Re: [edk2-devel] [RestJsonStructureDxe PATCH 1/2] MdePkg/Include: Definitions of EFI REST JSON Structure Protocol

["Abner Chang" <abner.chang@hpe.com>]

> -----Original Message-----
> From: gaoliming [mailto:gaoliming@byosoft.com.cn]
> Sent: Wednesday, October 14, 2020 1:42 PM
> To: devel@edk2.groups.io; Chang, Abner (HPS SW/FW Technologist)
> <abner.chang@hpe.com>
> Cc: 'Michael D Kinney' <michael.d.kinney@intel.com>; 'Zhiguang Liu'
> <zhiguang.liu@intel.com>; 'Jiaxin Wu' <jiaxin.wu@intel.com>; 'Siyuan Fu'
> <siyuan.fu@intel.com>; 'Fan Wang' <fan.wang@intel.com>; 'Jiewen Yao'
> <jiewen.yao@intel.com>; Wang, Nickle (HPS SW) <nickle.wang@hpe.com>
> Subject: 回复: [edk2-devel] [RestJsonStructureDxe PATCH 1/2]
> MdePkg/Include: Definitions of EFI REST JSON Structure Protocol
> 
> Abner:
> 
> > -----邮件原件-----
> > 发件人: bounce+27952+66030+4905953+8761045@groups.io
> > <bounce+27952+66030+4905953+8761045@groups.io> 代表 Abner Chang
> > 发送时间: 2020年10月8日 23:11
> > 收件人: devel@edk2.groups.io
> > 抄送: Michael D Kinney <michael.d.kinney@intel.com>; Liming Gao
> > <gaoliming@byosoft.com.cn>; Zhiguang Liu <zhiguang.liu@intel.com>;
> > Jiaxin Wu <jiaxin.wu@intel.com>; Siyuan Fu <siyuan.fu@intel.com>; Fan
> > Wang <fan.wang@intel.com>; Jiewen Yao <jiewen.yao@intel.com>; Nickle
> > Wang <nickle.wang@hpe.com>
> > 主题: [edk2-devel] [RestJsonStructureDxe PATCH 1/2] MdePkg/Include:
> > Definitions of EFI REST JSON Structure Protocol
> >
> > Add definitions of EFI REST JSON Structure according to UEFI spec
> > 2.8 Section 29.7.3 EFI REST JSON Resource to C Structure Converter.
> >
> > Signed-off-by: Abner Chang <abner.chang@hpe.com>
> >
> > Cc: Michael D Kinney <michael.d.kinney@intel.com>
> > Cc: Liming Gao <gaoliming@byosoft.com.cn>
> > Cc: Zhiguang Liu <zhiguang.liu@intel.com>
> > Cc: Jiaxin Wu <jiaxin.wu@intel.com>
> > Cc: Siyuan Fu <siyuan.fu@intel.com>
> > Cc: Fan Wang <fan.wang@intel.com>
> > Cc: Jiewen Yao <jiewen.yao@intel.com>
> > Cc: Nickle Wang <nickle.wang@hpe.com>
> > ---
> >  MdePkg/Include/Protocol/RestJsonStructure.h | 160
> > ++++++++++++++++++++
> >  MdePkg/MdePkg.dec                           |   6 +
> >  2 files changed, 166 insertions(+)
> >  create mode 100644 MdePkg/Include/Protocol/RestJsonStructure.h
> >
> > diff --git a/MdePkg/Include/Protocol/RestJsonStructure.h
> > b/MdePkg/Include/Protocol/RestJsonStructure.h
> > new file mode 100644
> > index 0000000000..5e4fef8cff
> > --- /dev/null
> > +++ b/MdePkg/Include/Protocol/RestJsonStructure.h
> > @@ -0,0 +1,160 @@
> > +/** @file
> > +  This file defines the EFI REST JSON Structure Protocol interface.
> > +
> 
> Please also specify UEFI spec version.
> 
> > +  (C) Copyright 2020 Hewlett Packard Enterprise Development LP<BR>
> > +
> > +  SPDX-License-Identifier: BSD-2-Clause-Patent
> > +
> > +**/
> > +
> > +#ifndef EFI_REST_JSON_STRUCTURE_PROTOCOL_H_
> > +#define EFI_REST_JSON_STRUCTURE_PROTOCOL_H_
> > +
> > +#include <Uefi.h>
> > +
> 
> Uefi.h is not required. The module will include this header file.
> 
> > +//
> > +// GUID definitions
> > +//
> > +#define EFI_REST_JSON_STRUCTURE_PROTOCOL_GUID \
> > +  { \
> > +    0xa9a048f6, 0x48a0, 0x4714, {0xb7, 0xda, 0xa9, 0xad,0x87, 0xd4,
> > +0xda,
> > 0xc9 } \
> > +  }
> > +
> > +typedef struct _EFI_REST_JSON_STRUCTURE_PROTOCOL
> > EFI_REST_JSON_STRUCTURE_PROTOCOL;
> > +typedef CHAR8 * EFI_REST_JSON_RESOURCE_TYPE_DATATYPE;
> > +typedef CHAR8 * EFI_REST_RESOURCE_RELATIVE_PATH;
> EFI_REST_RESOURCE_RELATIVE_PATH is not in UEFI spec. Can you confirm it?
Good catch. We don’t use this anymore.
> 
> > +
> > +/** Structure defintions of resource name space.
> > +  *
> > +  * The fields declared in this structure define the
> > +  * name and revision of payload delievered throught
> > +  * REST API.
> > +**/
> 
> Structure comments start with /// or //. /**/ style is for the function.
> Please update them.
> 
> > +typedef struct _EFI_REST_JSON_RESOURCE_TYPE_NAMESPACE {
> > +  CHAR8 *ResourceTypeName;   ///< Resource type name
> > +  CHAR8 *MajorVersion;       ///< Resource major version
> > +  CHAR8 *MinorVersion;       ///< Resource minor version
> > +  CHAR8 *ErrataVersion;      ///< Resource errata version
> > +} EFI_REST_JSON_RESOURCE_TYPE_NAMESPACE;
> > +
> > +/** REST resource type identifier
> > +  *
> > +  * REST resource type consists of name space and data type.
> > +**/
> > +typedef struct _EFI_REST_JSON_RESOURCE_TYPE_IDENTIFIER {
> > +  EFI_REST_JSON_RESOURCE_TYPE_NAMESPACE NameSpace; ///<
> > Namespace of this resource type.
> > +  EFI_REST_JSON_RESOURCE_TYPE_DATATYPE DataType;   ///< Name of
> > data type declared in this
> > +                                                   ///<
> > resource type.
> > +} EFI_REST_JSON_RESOURCE_TYPE_IDENTIFIER;
> > +
> > +/** List of JSON to C structure conversions which this convertor
> supports.
> > +  *
> > +**/
> > +typedef struct _EFI_REST_JSON_STRUCTURE_SUPPORTED {
> > +  LIST_ENTRY NextSupportedRsrcInterp;                        ///<
> > Linklist to next supported conversion.
> > +  EFI_REST_JSON_RESOURCE_TYPE_IDENTIFIER RestResourceInterp; ///<
> > JSON resource type this convertor supports.
> > +} EFI_REST_JSON_STRUCTURE_SUPPORTED;
> > +
> > +/** The header file of JSON C structure
> > +  *
> > +**/
> > +typedef struct _EFI_REST_JSON_STRUCTURE_HEADER {
> > +  EFI_REST_JSON_RESOURCE_TYPE_IDENTIFIER    JsonRsrcIdentifier;
> > ///< Resource identifier which use to
> > +
> > ///< choice the proper interpreter.
> > +  ///< Follow by a pointer points to JSON structure, the content in
> > + the  ///< JSON structure is implementation-specific according to
> > + converter
> > producer.
> > +  ///
> > +  VOID  *JsonStructurePointer;
> > +}  EFI_REST_JSON_STRUCTURE_HEADER;
> > +
> > +/**
> > +  JSON-IN C Structure-OUT function. Convert the given REST JSON
> > +resource
> > into structure.
> > +
> > +  @param[in]    This                This is the
> > EFI_REST_JSON_STRUCTURE_PROTOCOL instance.
> > +  @param[in]    JsonRsrcIdentifier  This indicates the resource type and
> > version is given in
> > +                                    ResourceJsonText.
> > +  @param[in]    ResourceJsonText    REST JSON resource in text
> > format.
> > +  @param[out]   JsonStructure       Pointer to receive the pointer to
> > EFI_REST_JSON_STRUCTURE_HEADER
> > +
> > +  @retval EFI_SUCCESS
> > +  @retval Others
> > +--*/
> > +typedef
> > +EFI_STATUS
> > +(EFIAPI *EFI_REST_JSON_STRUCTURE_TO_STRUCTURE)(
> > +  IN  EFI_REST_JSON_STRUCTURE_PROTOCOL        *This,
> > +  IN  EFI_REST_JSON_RESOURCE_TYPE_IDENTIFIER *JsonRsrcIdentifier
> > OPTIONAL,
> > +  IN  CHAR8
> > *ResourceJsonText,
> > +  OUT  EFI_REST_JSON_STRUCTURE_HEADER         **JsonStructure
> > +);
> > +
> > +/**
> > +  Convert the given REST JSON structure into JSON text.
> > +
> > +  @param[in]    This                 This is the
> > EFI_REST_JSON_STRUCTURE_PROTOCOL instance.
> > +  @param[in]    JsonStructureHeader  The point to
> > EFI_REST_JSON_STRUCTURE_HEADER  structure.
> > +  @param[out]   ResourceJsonText     Pointer to receive REST JSON
> > resource in text format.
> > +
> > +  @retval EFI_SUCCESS
> > +  @retval Others
> > +
> > +--*/
> > +typedef
> > +EFI_STATUS
> > +(EFIAPI *EFI_REST_JSON_STRUCTURE_TO_JSON)(
> > +  IN EFI_REST_JSON_STRUCTURE_PROTOCOL     *This,
> > +  IN EFI_REST_JSON_STRUCTURE_HEADER       *JsonStructureHeader,
> > +  OUT CHAR8                               **ResourceJsonText
> > +);
> > +
> > +/**
> > +  This function destroys the REST JSON structure.
> > +
> > +  @param[in]    This                 This is the
> > EFI_REST_JSON_STRUCTURE_PROTOCOL instance.
> > +  @param[in]    JsonStructureHeader  JSON structure to destroy.
> > +
> > +  @retval EFI_SUCCESS
> > +  @retval Others
> > +
> > +--*/
> > +typedef
> > +EFI_STATUS
> > +(EFIAPI *EFI_REST_JSON_STRUCTURE_DESTORY_STRUCTURE)(
> > +  IN EFI_REST_JSON_STRUCTURE_PROTOCOL   *This,
> > +  IN EFI_REST_JSON_STRUCTURE_HEADER     *JsonStructureHeader
> > +);
> > +/**
> > +  This function provides REST JSON resource to structure converter
> > registration.
> > +
> > +  @param[in]    This                     This is the
> > EFI_REST_JSON_STRUCTURE_PROTOCOL instance.
> > +  @param[in]    JsonStructureSupported   The type and version of REST
> > JSON resource which this converter
> > +                                         supports.
> > +  @param[in]    ToStructure              The function to convert
> > REST JSON resource to structure.
> > +  @param[in]    ToJson                   The function to convert
> > REST JSON structure to JSON in text format.
> > +  @param[out]   DestroyStructure         Destroy REST JSON
> > structure returned in ToStructure()  function.
> > +
> > +  @retval EFI_SUCCESS             Register successfully.
> > +  @retval Others                  Fail to register.
> > +
> > +--*/
> > +typedef
> > +EFI_STATUS
> > +(EFIAPI *EFI_REST_JSON_STRUCTURE_REGISTER)(
> > +  IN EFI_REST_JSON_STRUCTURE_PROTOCOL       *This,
> > +  IN EFI_REST_JSON_STRUCTURE_SUPPORTED
> > *JsonStructureSupported,
> > +  IN EFI_REST_JSON_STRUCTURE_TO_STRUCTURE   ToStructure,
> > +  IN EFI_REST_JSON_STRUCTURE_TO_JSON        ToJson,
> > +  IN EFI_REST_JSON_STRUCTURE_DESTORY_STRUCTURE
> DestroyStructure );
> > +
> > +/** EFI REST JSON to C structure protocol definition.
> > +  *
> > +**/
> > +typedef struct _EFI_REST_JSON_STRUCTURE_PROTOCOL {
> > +  EFI_REST_JSON_STRUCTURE_REGISTER           Register;
> > ///< Register JSON to C structure convertor
> > +  EFI_REST_JSON_STRUCTURE_TO_STRUCTURE       ToStructure;
> > ///< The function to convert JSON to C structure
> > +  EFI_REST_JSON_STRUCTURE_TO_JSON            ToJson;
> > ///< The function to convert C structure to JSON
> > +  EFI_REST_JSON_STRUCTURE_DESTORY_STRUCTURE  DestoryStructure;
> > ///< Destory C structure.
> > +} EFI_REST_JSON_STRUCTURE_PROTOCOL;
> 
> Here, typedef is not required, because
> EFI_REST_JSON_STRUCTURE_PROTOCOL has been defined in the begin of
> this file.
> 
All comments were addressed, v2 was sent.
Thanks.

> Thanks
> Liming
> > +
> > +#endif
> > diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec index
> > 812be75fb3..0943816825 100644
> > --- a/MdePkg/MdePkg.dec
> > +++ b/MdePkg/MdePkg.dec
> > @@ -1848,6 +1848,12 @@
> >    ## Include/Protocol/NvdimmLabel.h
> >    gEfiNvdimmLabelProtocolGuid               = { 0xd40b6b80, 0x97d5,
> > 0x4282, { 0xbb, 0x1d, 0x22, 0x3a, 0x16, 0x91, 0x80, 0x58 }}
> >
> > +  #
> > +  # Protocols defined in UEFI2.8
> > +  #
> > +  ## Include/Protocol/RestJsonStructure.h
> > +  gEfiRestJsonStructureProtocolGuid  = { 0xa9a048f6, 0x48a0, 0x4714,
> > {0xb7, 0xda, 0xa9, 0xad,0x87, 0xd4, 0xda, 0xc9 }}
> > +
> >    #
> >    # Protocols defined in Shell2.0
> >    #
> > --
> > 2.17.1
> >
> >
> >
> > 
> >
> 
>