[Rest Ex Definition PATCH 0/2] The definitions for EFI REST EX

[Rest Ex Definition PATCH 0/2] The definitions for EFI REST EX

[Abner Chang]

This is the commit of definitions required by EFI REST EX UEFI driver.

In patch (1/2), add the definitions of EFI REST EX Protocol according
to UEFI spec v2.8 Section 29.7.2 EFI REST EX Protocol.

In patch (2/2), add the definitions of structure PCD for Redfish Host
Interface EFI device path.

Signed-off-by: Abner Chang <abner.chang@hpe.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>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
Cc: Liming Gao <gaoliming@byosoft.com.cn>
Cc: Zhiguang Liu <zhiguang.liu@intel.com>


Abner Chang (2):
  MdePkg/Include: Definitions of EFI REST EX Protocol
  RedfishPkg/Include: PCD definitions of Host Interface EFI device path

 MdePkg/Include/Protocol/RestEx.h              | 388 ++++++++++++++++++
 MdePkg/MdePkg.dec                             |   7 +
 .../Include/Pcd/RestExServiceDevicePath.h     |  38 ++
 RedfishPkg/RedfishPkg.dec                     |   3 +
 4 files changed, 436 insertions(+)
 create mode 100644 MdePkg/Include/Protocol/RestEx.h
 create mode 100644 RedfishPkg/Include/Pcd/RestExServiceDevicePath.h

-- 
2.17.1

[Rest Ex Definition PATCH 1/2] MdePkg/Include: Definitions of EFI REST EX Protocol

[Abner Chang]

Add definitions of EFI REST EX Protocol according
to UEFI spec v2.8 Section 29.7.2 EFI REST EX Protocol.

Signed-off-by: Jiaxin Wu <jiaxin.wu@intel.com>
Signed-off-by: Siyuan Fu <siyuan.fu@intel.com>
Signed-off-by: Fan Wang <fan.wang@intel.com>
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: Jiewen Yao <jiewen.yao@intel.com>
Cc: Nickle Wang <nickle.wang@hpe.com>
---
 MdePkg/Include/Protocol/RestEx.h | 388 +++++++++++++++++++++++++++++++
 MdePkg/MdePkg.dec                |   7 +
 2 files changed, 395 insertions(+)
 create mode 100644 MdePkg/Include/Protocol/RestEx.h

diff --git a/MdePkg/Include/Protocol/RestEx.h b/MdePkg/Include/Protocol/RestEx.h
new file mode 100644
index 0000000000..c42096d14c
--- /dev/null
+++ b/MdePkg/Include/Protocol/RestEx.h
@@ -0,0 +1,388 @@
+/** @file
+  This file defines the EFI REST EX Protocol interface. It is
+  split into the following two main sections.
+
+  - REST EX Service Binding Protocol
+  - REST EX Protocol
+
+   Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
+  (C) Copyright 2020 Hewlett Packard Enterprise Development LP<BR>
+
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+
+**/
+
+#ifndef EFI_REST_EX_PROTOCOL_H_
+#define EFI_REST_EX_PROTOCOL_H_
+
+#include <Protocol/Http.h>
+
+//
+//GUID definitions
+//
+#define EFI_REST_EX_SERVICE_BINDING_PROTOCOL_GUID \
+  { \
+    0x456bbe01, 0x99d0, 0x45ea, {0xbb, 0x5f, 0x16, 0xd8, 0x4b, 0xed, 0xc5, 0x59 } \
+  }
+
+#define EFI_REST_EX_PROTOCOL_GUID \
+  { \
+    0x55648b91, 0xe7d, 0x40a3, {0xa9, 0xb3, 0xa8, 0x15, 0xd7, 0xea, 0xdf, 0x97 } \
+  }
+
+typedef struct _EFI_REST_EX_PROTOCOL EFI_REST_EX_PROTOCOL;
+
+//*******************************************************
+//EFI_REST_EX_SERVICE_INFO_VER
+//*******************************************************
+typedef struct {
+  UINT8  Major;
+  UINT8  Minor;
+} EFI_REST_EX_SERVICE_INFO_VER;
+
+//*******************************************************
+//EFI_REST_EX_SERVICE_INFO_HEADER
+//*******************************************************
+typedef struct {
+  UINT32                         Length;
+  EFI_REST_EX_SERVICE_INFO_VER   RestServiceInfoVer;
+} EFI_REST_EX_SERVICE_INFO_HEADER;
+
+//*******************************************************
+// EFI_REST_EX_SERVICE_TYPE
+//*******************************************************
+typedef enum {
+  EfiRestExServiceUnspecific = 1,
+  EfiRestExServiceRedfish,
+  EfiRestExServiceOdata,
+  EfiRestExServiceVendorSpecific = 0xff,
+  EfiRestExServiceTypeMax
+} EFI_REST_EX_SERVICE_TYPE;
+
+//*******************************************************
+// EFI_REST_EX_SERVICE_ACCESS_MODE
+//*******************************************************
+typedef enum {
+  EfiRestExServiceInBandAccess = 1,
+  EfiRestExServiceOutOfBandAccess = 2,
+  EfiRestExServiceModeMax
+} EFI_REST_EX_SERVICE_ACCESS_MODE;
+
+//*******************************************************
+// EFI_REST_EX_CONFIG_TYPE
+//*******************************************************
+typedef enum {
+  EfiRestExConfigHttp,
+  EfiRestExConfigUnspecific,
+  EfiRestExConfigTypeMax
+} EFI_REST_EX_CONFIG_TYPE;
+
+//*******************************************************
+//EFI_REST_EX_SERVICE_INFO v1.0
+//*******************************************************
+typedef struct {
+  EFI_REST_EX_SERVICE_INFO_HEADER  EfiRestExServiceInfoHeader;
+  EFI_REST_EX_SERVICE_TYPE         RestServiceType;
+  EFI_REST_EX_SERVICE_ACCESS_MODE  RestServiceAccessMode;
+  EFI_GUID                         VendorRestServiceName;
+  UINT32                           VendorSpecificDataLength;
+  UINT8                            *VendorSpecifcData;
+  EFI_REST_EX_CONFIG_TYPE          RestExConfigType;
+  UINT8                            RestExConfigDataLength;
+} EFI_REST_EX_SERVICE_INFO_V_1_0;
+
+//*******************************************************
+//EFI_REST_EX_SERVICE_INFO
+//*******************************************************
+typedef union {
+  EFI_REST_EX_SERVICE_INFO_HEADER EfiRestExServiceInfoHeader;
+  EFI_REST_EX_SERVICE_INFO_V_1_0  EfiRestExServiceInfoV10;
+} EFI_REST_EX_SERVICE_INFO;
+
+//*******************************************************
+// EFI_REST_EX_HTTP_CONFIG_DATA
+//*******************************************************
+typedef struct {
+  EFI_HTTP_CONFIG_DATA    HttpConfigData;
+  UINT32                  SendReceiveTimeout;
+} EFI_REST_EX_HTTP_CONFIG_DATA;
+
+//*******************************************************
+//EFI_REST_EX_CONFIG_DATA
+//*******************************************************
+typedef UINT8 *EFI_REST_EX_CONFIG_DATA;
+
+//*******************************************************
+//EFI_REST_EX_TOKEN
+//*******************************************************
+typedef struct {
+  EFI_EVENT         Event;
+  EFI_STATUS        Status;
+  EFI_HTTP_MESSAGE  *ResponseMessage;
+} EFI_REST_EX_TOKEN;
+
+/**
+  Provides a simple HTTP-like interface to send and receive resources from a REST service.
+
+  The SendReceive() function sends an HTTP request to this REST service, and returns a
+  response when the data is retrieved from the service. RequestMessage contains the HTTP
+  request to the REST resource identified by RequestMessage.Request.Url. The
+  ResponseMessage is the returned HTTP response for that request, including any HTTP
+  status.
+
+  @param[in]  This                Pointer to EFI_REST_EX_PROTOCOL instance for a particular
+                                  REST service.
+  @param[in]  RequestMessage      Pointer to the HTTP request data for this resource
+  @param[out] ResponseMessage     Pointer to the HTTP response data obtained for this requested.
+
+  @retval EFI_SUCCESS             operation succeeded.
+  @retval EFI_INVALID_PARAMETER   This, RequestMessage, or ResponseMessage are NULL.
+  @retval EFI_DEVICE_ERROR        An unexpected system or network error occurred.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_REST_SEND_RECEIVE)(
+  IN      EFI_REST_EX_PROTOCOL   *This,
+  IN      EFI_HTTP_MESSAGE       *RequestMessage,
+  OUT     EFI_HTTP_MESSAGE       *ResponseMessage
+  );
+
+/**
+  Obtain the current time from this REST service instance.
+
+  The GetServiceTime() function is an optional interface to obtain the current time from
+  this REST service instance. If this REST service does not support to retrieve the time,
+  this function returns EFI_UNSUPPORTED. This function must returns EFI_UNSUPPORTED if
+  EFI_REST_EX_SERVICE_TYPE returned in EFI_REST_EX_SERVICE_INFO from GetService() is
+  EFI_REST_EX_SERVICE_UNSPECIFIC.
+
+  @param[in]  This                Pointer to EFI_REST_EX_PROTOCOL instance for a particular
+                                  REST service.
+  @param[out] Time                A pointer to storage to receive a snapshot of the current time of
+                                  the REST service.
+
+  @retval EFI_SUCCESS             operation succeeded.
+  @retval EFI_INVALID_PARAMETER   This or Time are NULL.
+  @retval EFI_UNSUPPORTED         The RESTful service does not support returning the time.
+  @retval EFI_DEVICE_ERROR        An unexpected system or network error occurred.
+  @retval EFI_NOT_READY           The configuration of this instance is not set yet. Configure() must
+                                  be executed and returns successfully prior to invoke this function.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_REST_GET_TIME)(
+  IN      EFI_REST_EX_PROTOCOL   *This,
+  OUT     EFI_TIME               *Time
+  );
+
+/**
+  This function returns the information of REST service provided by this EFI REST EX driver instance.
+
+  The information such as the type of REST service and the access mode of REST EX driver instance
+  (In-band or Out-of-band) are described in EFI_REST_EX_SERVICE_INFO structure. For the vendor-specific
+  REST service, vendor-specific REST service information is returned in VendorSpecifcData.
+  REST EX driver designer is well know what REST service this REST EX driver instance intends to
+  communicate with. The designer also well know this driver instance is used to talk to BMC through
+  specific platform mechanism or talk to REST server through UEFI HTTP protocol. REST EX driver is
+  responsible to fill up the correct information in EFI_REST_EX_SERVICE_INFO. EFI_REST_EX_SERVICE_INFO
+  is referred by EFI REST clients to pickup the proper EFI REST EX driver instance to get and set resource.
+  GetService() is a basic and mandatory function which must be able to use even Configure() is not invoked
+  in previously.
+
+  @param[in]  This                Pointer to EFI_REST_EX_PROTOCOL instance for a particular
+                                  REST service.
+  @param[out] RestExServiceInfo   Pointer to receive a pointer to EFI_REST_EX_SERVICE_INFO structure. The
+                                  format of EFI_REST_EX_SERVICE_INFO is version controlled for the future
+                                  extension. The version of EFI_REST_EX_SERVICE_INFO structure is returned
+                                  in the header within this structure. EFI REST client refers to the correct
+                                  format of structure according to the version number. The pointer to
+                                  EFI_REST_EX_SERVICE_INFO is a memory block allocated by EFI REST EX driver
+                                  instance. That is caller's responsibility to free this memory when this
+                                  structure is no longer needed. Refer to Related Definitions below for the
+                                  definitions of EFI_REST_EX_SERVICE_INFO structure.
+
+  @retval EFI_SUCCESS             EFI_REST_EX_SERVICE_INFO is returned in RestExServiceInfo. This function
+                                  is not supported in this REST EX Protocol driver instance.
+  @retval EFI_UNSUPPORTED         This function is not supported in this REST EX Protocol driver instance.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_REST_EX_GET_SERVICE)(
+  IN   EFI_REST_EX_PROTOCOL      *This,
+  OUT  EFI_REST_EX_SERVICE_INFO  **RestExServiceInfo
+  );
+
+/**
+  This function returns operational configuration of current EFI REST EX child instance.
+
+  This function returns the current configuration of EFI REST EX child instance. The format of
+  operational configuration depends on the implementation of EFI REST EX driver instance. For
+  example, HTTP-aware EFI REST EX driver instance uses EFI HTTP protocol as the undying protocol
+  to communicate with REST service. In this case, the type of configuration is
+  EFI_REST_EX_CONFIG_TYPE_HTTP returned from GetService(). EFI_HTTP_CONFIG_DATA is used as EFI REST
+  EX configuration format and returned to EFI REST client. User has to type cast RestExConfigData
+  to EFI_HTTP_CONFIG_DATA. For those non HTTP-aware REST EX driver instances, the type of configuration
+  is EFI_REST_EX_CONFIG_TYPE_UNSPECIFIC returned from GetService(). In this case, the format of
+  returning data could be non industrial. Instead, the format of configuration data is system/platform
+  specific definition such as BMC mechanism used in EFI REST EX driver instance. EFI REST client and
+  EFI REST EX driver instance have to refer to the specific system /platform spec which is out of UEFI scope.
+
+  @param[in]  This                This is the EFI_REST_EX_PROTOCOL instance.
+  @param[out] RestExConfigData    Pointer to receive a pointer to EFI_REST_EX_CONFIG_DATA.
+                                  The memory allocated for configuration data should be freed
+                                  by caller. See Related Definitions for the details.
+
+  @retval EFI_SUCCESS             EFI_REST_EX_CONFIG_DATA is returned in successfully.
+  @retval EFI_UNSUPPORTED         This function is not supported in this REST EX Protocol driver instance.
+  @retval EFI_NOT_READY           The configuration of this instance is not set yet. Configure() must be
+                                  executed and returns successfully prior to invoke this function.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_REST_EX_GET_MODE_DATA)(
+  IN  EFI_REST_EX_PROTOCOL  *This,
+  OUT EFI_REST_EX_CONFIG_DATA *RestExConfigData
+  );
+
+/**
+  This function is used to configure EFI REST EX child instance.
+
+  This function is used to configure the setting of underlying protocol of REST EX child
+  instance. The type of configuration is according to the implementation of EFI REST EX
+  driver instance. For example, HTTP-aware EFI REST EX driver instance uses EFI HTTP protocol
+  as the undying protocol to communicate with REST service. The type of configuration is
+  EFI_REST_EX_CONFIG_TYPE_HTTP and RestExConfigData is the same format with EFI_HTTP_CONFIG_DATA.
+  Akin to HTTP configuration, REST EX child instance can be configure to use different HTTP
+  local access point for the data transmission. Multiple REST clients may use different
+  configuration of HTTP to distinguish themselves, such as to use the different TCP port.
+  For those non HTTP-aware REST EX driver instance, the type of configuration is
+  EFI_REST_EX_CONFIG_TYPE_UNSPECIFIC. RestExConfigData refers to the non industrial standard.
+  Instead, the format of configuration data is system/platform specific definition such as BMC.
+  In this case, EFI REST client and EFI REST EX driver instance have to refer to the specific
+  system/platform spec which is out of the UEFI scope. Besides GetService()function, no other
+  EFI REST EX functions can be executed by this instance until Configure()is executed and returns
+  successfully. All other functions must returns EFI_NOT_READY if this instance is not configured
+  yet. Set RestExConfigData to NULL means to put EFI REST EX child instance into the unconfigured
+  state.
+
+  @param[in]  This                This is the EFI_REST_EX_PROTOCOL instance.
+  @param[in]  RestExConfigData    Pointer to EFI_REST_EX_CONFIG_DATA. See Related Definitions in
+                                  GetModeData() protocol interface.
+
+  @retval EFI_SUCCESS             EFI_REST_EX_CONFIG_DATA is set in successfully.
+  @retval EFI_DEVICE_ERROR        Configuration for this REST EX child instance is failed with the given
+                                  EFI_REST_EX_CONFIG_DATA.
+  @retval EFI_UNSUPPORTED         This function is not supported in this REST EX Protocol driver instance.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_REST_EX_CONFIGURE)(
+  IN  EFI_REST_EX_PROTOCOL  *This,
+  IN  EFI_REST_EX_CONFIG_DATA RestExConfigData
+  );
+
+/**
+  This function sends REST request to REST service and signal caller's event asynchronously when
+  the final response is received by REST EX Protocol driver instance.
+
+  The essential design of this function is to handle asynchronous send/receive implicitly according
+  to REST service asynchronous request mechanism. Caller will get the notification once the response
+  is returned from REST service.
+
+  @param[in]  This                  This is the EFI_REST_EX_PROTOCOL instance.
+  @param[in]  RequestMessage        This is the HTTP request message sent to REST service. Set RequestMessage
+                                    to NULL to cancel the previous asynchronous request associated with the
+                                    corresponding RestExToken. See descriptions for the details.
+  @param[in]  RestExToken           REST EX token which REST EX Protocol instance uses to notify REST client
+                                    the status of response of asynchronous REST request. See related definition
+                                    of EFI_REST_EX_TOKEN.
+  @param[in]  TimeOutInMilliSeconds The pointer to the timeout in milliseconds which REST EX Protocol driver
+                                    instance refers as the duration to drop asynchronous REST request. NULL
+                                    pointer means no timeout for this REST request. REST EX Protocol driver
+                                    signals caller's event with EFI_STATUS set to EFI_TIMEOUT in RestExToken
+                                    if REST EX Protocol can't get the response from REST service within
+                                    TimeOutInMilliSeconds.
+
+  @retval EFI_SUCCESS               Asynchronous REST request is established.
+  @retval EFI_UNSUPPORTED           This REST EX Protocol driver instance doesn't support asynchronous request.
+  @retval EFI_TIMEOUT               Asynchronous REST request is not established and timeout is expired.
+  @retval EFI_ABORT                 Previous asynchronous REST request has been canceled.
+  @retval EFI_DEVICE_ERROR          Otherwise, returns EFI_DEVICE_ERROR for other errors according to HTTP Status Code.
+  @retval EFI_NOT_READY             The configuration of this instance is not set yet. Configure() must be executed
+                                    and returns successfully prior to invoke this function.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_REST_EX_ASYNC_SEND_RECEIVE)(
+  IN      EFI_REST_EX_PROTOCOL   *This,
+  IN      EFI_HTTP_MESSAGE       *RequestMessage OPTIONAL,
+  IN      EFI_REST_EX_TOKEN      *RestExToken,
+  IN      UINTN                  *TimeOutInMilliSeconds OPTIONAL
+  );
+
+/**
+  This function sends REST request to a REST Event service and signals caller's event
+  token asynchronously when the URI resource change event is received by REST EX
+  Protocol driver instance.
+
+  The essential design of this function is to monitor event implicitly according to
+  REST service event service mechanism. Caller will get the notification if certain
+  resource is changed.
+
+  @param[in]  This                  This is the EFI_REST_EX_PROTOCOL instance.
+  @param[in]  RequestMessage        This is the HTTP request message sent to REST service. Set RequestMessage
+                                    to NULL to cancel the previous event service associated with the corresponding
+                                    RestExToken. See descriptions for the details.
+  @param[in]  RestExToken           REST EX token which REST EX Protocol driver instance uses to notify REST client
+                                    the URI resource which monitored by REST client has been changed. See the related
+                                    definition of EFI_REST_EX_TOKEN in EFI_REST_EX_PROTOCOL.AsyncSendReceive().
+
+  @retval EFI_SUCCESS               Asynchronous REST request is established.
+  @retval EFI_UNSUPPORTED           This REST EX Protocol driver instance doesn't support asynchronous request.
+  @retval EFI_ABORT                 Previous asynchronous REST request has been canceled or event subscription has been
+                                    delete from service.
+  @retval EFI_DEVICE_ERROR          Otherwise, returns EFI_DEVICE_ERROR for other errors according to HTTP Status Code.
+  @retval EFI_NOT_READY             The configuration of this instance is not set yet. Configure() must be executed
+                                    and returns successfully prior to invoke this function.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_REST_EX_EVENT_SERVICE)(
+  IN      EFI_REST_EX_PROTOCOL   *This,
+  IN      EFI_HTTP_MESSAGE       *RequestMessage OPTIONAL,
+  IN      EFI_REST_EX_TOKEN      *RestExToken
+);
+
+///
+/// EFI REST(EX) protocols are designed to support REST communication between EFI REST client
+/// applications/drivers and REST services. EFI REST client tool uses EFI REST(EX) protocols
+/// to send/receive resources to/from REST service to manage systems, configure systems or
+/// manipulate resources on REST service. Due to HTTP protocol is commonly used to communicate
+/// with REST service in practice, EFI REST(EX) protocols adopt HTTP as the message format to
+/// send and receive REST service resource. EFI REST(EX) driver instance abstracts EFI REST
+/// client functionality and provides underlying interface to communicate with REST service.
+/// EFI REST(EX) driver instance knows how to communicate with REST service through certain
+/// interface after the corresponding configuration is initialized.
+///
+struct _EFI_REST_EX_PROTOCOL {
+  EFI_REST_SEND_RECEIVE          SendReceive;
+  EFI_REST_GET_TIME              GetServiceTime;
+  EFI_REST_EX_GET_SERVICE        GetService;
+  EFI_REST_EX_GET_MODE_DATA      GetModeData;
+  EFI_REST_EX_CONFIGURE          Configure;
+  EFI_REST_EX_ASYNC_SEND_RECEIVE AyncSendReceive;
+  EFI_REST_EX_EVENT_SERVICE      EventService;
+};
+
+extern EFI_GUID gEfiRestExServiceBindingProtocolGuid;
+extern EFI_GUID gEfiRestExProtocolGuid;
+
+#endif
diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec
index 812be75fb3..5205374d62 100644
--- a/MdePkg/MdePkg.dec
+++ b/MdePkg/MdePkg.dec
@@ -1848,6 +1848,13 @@
   ## Include/Protocol/NvdimmLabel.h
   gEfiNvdimmLabelProtocolGuid               = { 0xd40b6b80, 0x97d5, 0x4282, { 0xbb, 0x1d, 0x22, 0x3a, 0x16, 0x91, 0x80, 0x58 }}
 
+  #
+  # Protocols defined in UEFI2.8
+  #
+  ## Include/Protocol/RestEx.h
+  gEfiRestExProtocolGuid               = { 0x55648b91, 0xe7d, 0x40a3, { 0xa9, 0xb3, 0xa8, 0x15, 0xd7, 0xea, 0xdf, 0x97 }}
+  gEfiRestExServiceBindingProtocolGuid = { 0x456bbe01, 0x99d0, 0x45ea, { 0xbb, 0x5f, 0x16, 0xd8, 0x4b, 0xed, 0xc5, 0x59 }}
+
   #
   # Protocols defined in Shell2.0
   #
-- 
2.17.1

Re: [edk2-devel] [Rest Ex Definition PATCH 1/2] MdePkg/Include: Definitions of EFI REST EX Protocol

[Wu, Jiaxin]

Reviewed-by: Jiaxin Wu <jiaxin.wu@intel.com>



> -----Original Message-----
> From: devel@edk2.groups.io <devel@edk2.groups.io> On Behalf Of Abner
> Chang
> Sent: Monday, October 12, 2020 3:04 PM
> To: devel@edk2.groups.io
> Cc: Kinney, Michael D <michael.d.kinney@intel.com>; Liming Gao
> <gaoliming@byosoft.com.cn>; Liu, Zhiguang <zhiguang.liu@intel.com>; Yao,
> Jiewen <jiewen.yao@intel.com>; Nickle Wang <nickle.wang@hpe.com>
> Subject: [edk2-devel] [Rest Ex Definition PATCH 1/2] MdePkg/Include:
> Definitions of EFI REST EX Protocol
> 
> Add definitions of EFI REST EX Protocol according
> to UEFI spec v2.8 Section 29.7.2 EFI REST EX Protocol.
> 
> Signed-off-by: Jiaxin Wu <jiaxin.wu@intel.com>
> Signed-off-by: Siyuan Fu <siyuan.fu@intel.com>
> Signed-off-by: Fan Wang <fan.wang@intel.com>
> 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: Jiewen Yao <jiewen.yao@intel.com>
> Cc: Nickle Wang <nickle.wang@hpe.com>
> ---
>  MdePkg/Include/Protocol/RestEx.h | 388
> +++++++++++++++++++++++++++++++
>  MdePkg/MdePkg.dec                |   7 +
>  2 files changed, 395 insertions(+)
>  create mode 100644 MdePkg/Include/Protocol/RestEx.h
> 
> diff --git a/MdePkg/Include/Protocol/RestEx.h
> b/MdePkg/Include/Protocol/RestEx.h
> new file mode 100644
> index 0000000000..c42096d14c
> --- /dev/null
> +++ b/MdePkg/Include/Protocol/RestEx.h
> @@ -0,0 +1,388 @@
> +/** @file
> +  This file defines the EFI REST EX Protocol interface. It is
> +  split into the following two main sections.
> +
> +  - REST EX Service Binding Protocol
> +  - REST EX Protocol
> +
> +   Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
> +  (C) Copyright 2020 Hewlett Packard Enterprise Development LP<BR>
> +
> +  SPDX-License-Identifier: BSD-2-Clause-Patent
> +
> +
> +**/
> +
> +#ifndef EFI_REST_EX_PROTOCOL_H_
> +#define EFI_REST_EX_PROTOCOL_H_
> +
> +#include <Protocol/Http.h>
> +
> +//
> +//GUID definitions
> +//
> +#define EFI_REST_EX_SERVICE_BINDING_PROTOCOL_GUID \
> +  { \
> +    0x456bbe01, 0x99d0, 0x45ea, {0xbb, 0x5f, 0x16, 0xd8, 0x4b, 0xed, 0xc5,
> 0x59 } \
> +  }
> +
> +#define EFI_REST_EX_PROTOCOL_GUID \
> +  { \
> +    0x55648b91, 0xe7d, 0x40a3, {0xa9, 0xb3, 0xa8, 0x15, 0xd7, 0xea, 0xdf,
> 0x97 } \
> +  }
> +
> +typedef struct _EFI_REST_EX_PROTOCOL EFI_REST_EX_PROTOCOL;
> +
> +//*******************************************************
> +//EFI_REST_EX_SERVICE_INFO_VER
> +//*******************************************************
> +typedef struct {
> +  UINT8  Major;
> +  UINT8  Minor;
> +} EFI_REST_EX_SERVICE_INFO_VER;
> +
> +//*******************************************************
> +//EFI_REST_EX_SERVICE_INFO_HEADER
> +//*******************************************************
> +typedef struct {
> +  UINT32                         Length;
> +  EFI_REST_EX_SERVICE_INFO_VER   RestServiceInfoVer;
> +} EFI_REST_EX_SERVICE_INFO_HEADER;
> +
> +//*******************************************************
> +// EFI_REST_EX_SERVICE_TYPE
> +//*******************************************************
> +typedef enum {
> +  EfiRestExServiceUnspecific = 1,
> +  EfiRestExServiceRedfish,
> +  EfiRestExServiceOdata,
> +  EfiRestExServiceVendorSpecific = 0xff,
> +  EfiRestExServiceTypeMax
> +} EFI_REST_EX_SERVICE_TYPE;
> +
> +//*******************************************************
> +// EFI_REST_EX_SERVICE_ACCESS_MODE
> +//*******************************************************
> +typedef enum {
> +  EfiRestExServiceInBandAccess = 1,
> +  EfiRestExServiceOutOfBandAccess = 2,
> +  EfiRestExServiceModeMax
> +} EFI_REST_EX_SERVICE_ACCESS_MODE;
> +
> +//*******************************************************
> +// EFI_REST_EX_CONFIG_TYPE
> +//*******************************************************
> +typedef enum {
> +  EfiRestExConfigHttp,
> +  EfiRestExConfigUnspecific,
> +  EfiRestExConfigTypeMax
> +} EFI_REST_EX_CONFIG_TYPE;
> +
> +//*******************************************************
> +//EFI_REST_EX_SERVICE_INFO v1.0
> +//*******************************************************
> +typedef struct {
> +  EFI_REST_EX_SERVICE_INFO_HEADER  EfiRestExServiceInfoHeader;
> +  EFI_REST_EX_SERVICE_TYPE         RestServiceType;
> +  EFI_REST_EX_SERVICE_ACCESS_MODE  RestServiceAccessMode;
> +  EFI_GUID                         VendorRestServiceName;
> +  UINT32                           VendorSpecificDataLength;
> +  UINT8                            *VendorSpecifcData;
> +  EFI_REST_EX_CONFIG_TYPE          RestExConfigType;
> +  UINT8                            RestExConfigDataLength;
> +} EFI_REST_EX_SERVICE_INFO_V_1_0;
> +
> +//*******************************************************
> +//EFI_REST_EX_SERVICE_INFO
> +//*******************************************************
> +typedef union {
> +  EFI_REST_EX_SERVICE_INFO_HEADER EfiRestExServiceInfoHeader;
> +  EFI_REST_EX_SERVICE_INFO_V_1_0  EfiRestExServiceInfoV10;
> +} EFI_REST_EX_SERVICE_INFO;
> +
> +//*******************************************************
> +// EFI_REST_EX_HTTP_CONFIG_DATA
> +//*******************************************************
> +typedef struct {
> +  EFI_HTTP_CONFIG_DATA    HttpConfigData;
> +  UINT32                  SendReceiveTimeout;
> +} EFI_REST_EX_HTTP_CONFIG_DATA;
> +
> +//*******************************************************
> +//EFI_REST_EX_CONFIG_DATA
> +//*******************************************************
> +typedef UINT8 *EFI_REST_EX_CONFIG_DATA;
> +
> +//*******************************************************
> +//EFI_REST_EX_TOKEN
> +//*******************************************************
> +typedef struct {
> +  EFI_EVENT         Event;
> +  EFI_STATUS        Status;
> +  EFI_HTTP_MESSAGE  *ResponseMessage;
> +} EFI_REST_EX_TOKEN;
> +
> +/**
> +  Provides a simple HTTP-like interface to send and receive resources from a
> REST service.
> +
> +  The SendReceive() function sends an HTTP request to this REST service,
> and returns a
> +  response when the data is retrieved from the service. RequestMessage
> contains the HTTP
> +  request to the REST resource identified by RequestMessage.Request.Url.
> The
> +  ResponseMessage is the returned HTTP response for that request,
> including any HTTP
> +  status.
> +
> +  @param[in]  This                Pointer to EFI_REST_EX_PROTOCOL instance for a
> particular
> +                                  REST service.
> +  @param[in]  RequestMessage      Pointer to the HTTP request data for this
> resource
> +  @param[out] ResponseMessage     Pointer to the HTTP response data
> obtained for this requested.
> +
> +  @retval EFI_SUCCESS             operation succeeded.
> +  @retval EFI_INVALID_PARAMETER   This, RequestMessage, or
> ResponseMessage are NULL.
> +  @retval EFI_DEVICE_ERROR        An unexpected system or network error
> occurred.
> +
> +**/
> +typedef
> +EFI_STATUS
> +(EFIAPI *EFI_REST_SEND_RECEIVE)(
> +  IN      EFI_REST_EX_PROTOCOL   *This,
> +  IN      EFI_HTTP_MESSAGE       *RequestMessage,
> +  OUT     EFI_HTTP_MESSAGE       *ResponseMessage
> +  );
> +
> +/**
> +  Obtain the current time from this REST service instance.
> +
> +  The GetServiceTime() function is an optional interface to obtain the
> current time from
> +  this REST service instance. If this REST service does not support to retrieve
> the time,
> +  this function returns EFI_UNSUPPORTED. This function must returns
> EFI_UNSUPPORTED if
> +  EFI_REST_EX_SERVICE_TYPE returned in EFI_REST_EX_SERVICE_INFO from
> GetService() is
> +  EFI_REST_EX_SERVICE_UNSPECIFIC.
> +
> +  @param[in]  This                Pointer to EFI_REST_EX_PROTOCOL instance for a
> particular
> +                                  REST service.
> +  @param[out] Time                A pointer to storage to receive a snapshot of
> the current time of
> +                                  the REST service.
> +
> +  @retval EFI_SUCCESS             operation succeeded.
> +  @retval EFI_INVALID_PARAMETER   This or Time are NULL.
> +  @retval EFI_UNSUPPORTED         The RESTful service does not support
> returning the time.
> +  @retval EFI_DEVICE_ERROR        An unexpected system or network error
> occurred.
> +  @retval EFI_NOT_READY           The configuration of this instance is not set
> yet. Configure() must
> +                                  be executed and returns successfully prior to invoke this
> function.
> +
> +**/
> +typedef
> +EFI_STATUS
> +(EFIAPI *EFI_REST_GET_TIME)(
> +  IN      EFI_REST_EX_PROTOCOL   *This,
> +  OUT     EFI_TIME               *Time
> +  );
> +
> +/**
> +  This function returns the information of REST service provided by this EFI
> REST EX driver instance.
> +
> +  The information such as the type of REST service and the access mode of
> REST EX driver instance
> +  (In-band or Out-of-band) are described in EFI_REST_EX_SERVICE_INFO
> structure. For the vendor-specific
> +  REST service, vendor-specific REST service information is returned in
> VendorSpecifcData.
> +  REST EX driver designer is well know what REST service this REST EX driver
> instance intends to
> +  communicate with. The designer also well know this driver instance is used
> to talk to BMC through
> +  specific platform mechanism or talk to REST server through UEFI HTTP
> protocol. REST EX driver is
> +  responsible to fill up the correct information in
> EFI_REST_EX_SERVICE_INFO. EFI_REST_EX_SERVICE_INFO
> +  is referred by EFI REST clients to pickup the proper EFI REST EX driver
> instance to get and set resource.
> +  GetService() is a basic and mandatory function which must be able to use
> even Configure() is not invoked
> +  in previously.
> +
> +  @param[in]  This                Pointer to EFI_REST_EX_PROTOCOL instance for a
> particular
> +                                  REST service.
> +  @param[out] RestExServiceInfo   Pointer to receive a pointer to
> EFI_REST_EX_SERVICE_INFO structure. The
> +                                  format of EFI_REST_EX_SERVICE_INFO is version
> controlled for the future
> +                                  extension. The version of EFI_REST_EX_SERVICE_INFO
> structure is returned
> +                                  in the header within this structure. EFI REST client refers to
> the correct
> +                                  format of structure according to the version number. The
> pointer to
> +                                  EFI_REST_EX_SERVICE_INFO is a memory block allocated
> by EFI REST EX driver
> +                                  instance. That is caller's responsibility to free this memory
> when this
> +                                  structure is no longer needed. Refer to Related Definitions
> below for the
> +                                  definitions of EFI_REST_EX_SERVICE_INFO structure.
> +
> +  @retval EFI_SUCCESS             EFI_REST_EX_SERVICE_INFO is returned in
> RestExServiceInfo. This function
> +                                  is not supported in this REST EX Protocol driver instance.
> +  @retval EFI_UNSUPPORTED         This function is not supported in this REST
> EX Protocol driver instance.
> +
> +**/
> +typedef
> +EFI_STATUS
> +(EFIAPI *EFI_REST_EX_GET_SERVICE)(
> +  IN   EFI_REST_EX_PROTOCOL      *This,
> +  OUT  EFI_REST_EX_SERVICE_INFO  **RestExServiceInfo
> +  );
> +
> +/**
> +  This function returns operational configuration of current EFI REST EX child
> instance.
> +
> +  This function returns the current configuration of EFI REST EX child instance.
> The format of
> +  operational configuration depends on the implementation of EFI REST EX
> driver instance. For
> +  example, HTTP-aware EFI REST EX driver instance uses EFI HTTP protocol as
> the undying protocol
> +  to communicate with REST service. In this case, the type of configuration is
> +  EFI_REST_EX_CONFIG_TYPE_HTTP returned from GetService().
> EFI_HTTP_CONFIG_DATA is used as EFI REST
> +  EX configuration format and returned to EFI REST client. User has to type
> cast RestExConfigData
> +  to EFI_HTTP_CONFIG_DATA. For those non HTTP-aware REST EX driver
> instances, the type of configuration
> +  is EFI_REST_EX_CONFIG_TYPE_UNSPECIFIC returned from GetService(). In
> this case, the format of
> +  returning data could be non industrial. Instead, the format of configuration
> data is system/platform
> +  specific definition such as BMC mechanism used in EFI REST EX driver
> instance. EFI REST client and
> +  EFI REST EX driver instance have to refer to the specific system /platform
> spec which is out of UEFI scope.
> +
> +  @param[in]  This                This is the EFI_REST_EX_PROTOCOL instance.
> +  @param[out] RestExConfigData    Pointer to receive a pointer to
> EFI_REST_EX_CONFIG_DATA.
> +                                  The memory allocated for configuration data should be
> freed
> +                                  by caller. See Related Definitions for the details.
> +
> +  @retval EFI_SUCCESS             EFI_REST_EX_CONFIG_DATA is returned in
> successfully.
> +  @retval EFI_UNSUPPORTED         This function is not supported in this REST
> EX Protocol driver instance.
> +  @retval EFI_NOT_READY           The configuration of this instance is not set
> yet. Configure() must be
> +                                  executed and returns successfully prior to invoke this
> function.
> +
> +**/
> +typedef
> +EFI_STATUS
> +(EFIAPI *EFI_REST_EX_GET_MODE_DATA)(
> +  IN  EFI_REST_EX_PROTOCOL  *This,
> +  OUT EFI_REST_EX_CONFIG_DATA *RestExConfigData
> +  );
> +
> +/**
> +  This function is used to configure EFI REST EX child instance.
> +
> +  This function is used to configure the setting of underlying protocol of REST
> EX child
> +  instance. The type of configuration is according to the implementation of
> EFI REST EX
> +  driver instance. For example, HTTP-aware EFI REST EX driver instance uses
> EFI HTTP protocol
> +  as the undying protocol to communicate with REST service. The type of
> configuration is
> +  EFI_REST_EX_CONFIG_TYPE_HTTP and RestExConfigData is the same
> format with EFI_HTTP_CONFIG_DATA.
> +  Akin to HTTP configuration, REST EX child instance can be configure to use
> different HTTP
> +  local access point for the data transmission. Multiple REST clients may use
> different
> +  configuration of HTTP to distinguish themselves, such as to use the
> different TCP port.
> +  For those non HTTP-aware REST EX driver instance, the type of
> configuration is
> +  EFI_REST_EX_CONFIG_TYPE_UNSPECIFIC. RestExConfigData refers to the
> non industrial standard.
> +  Instead, the format of configuration data is system/platform specific
> definition such as BMC.
> +  In this case, EFI REST client and EFI REST EX driver instance have to refer to
> the specific
> +  system/platform spec which is out of the UEFI scope. Besides
> GetService()function, no other
> +  EFI REST EX functions can be executed by this instance until Configure()is
> executed and returns
> +  successfully. All other functions must returns EFI_NOT_READY if this
> instance is not configured
> +  yet. Set RestExConfigData to NULL means to put EFI REST EX child instance
> into the unconfigured
> +  state.
> +
> +  @param[in]  This                This is the EFI_REST_EX_PROTOCOL instance.
> +  @param[in]  RestExConfigData    Pointer to EFI_REST_EX_CONFIG_DATA.
> See Related Definitions in
> +                                  GetModeData() protocol interface.
> +
> +  @retval EFI_SUCCESS             EFI_REST_EX_CONFIG_DATA is set in
> successfully.
> +  @retval EFI_DEVICE_ERROR        Configuration for this REST EX child
> instance is failed with the given
> +                                  EFI_REST_EX_CONFIG_DATA.
> +  @retval EFI_UNSUPPORTED         This function is not supported in this REST
> EX Protocol driver instance.
> +
> +**/
> +typedef
> +EFI_STATUS
> +(EFIAPI *EFI_REST_EX_CONFIGURE)(
> +  IN  EFI_REST_EX_PROTOCOL  *This,
> +  IN  EFI_REST_EX_CONFIG_DATA RestExConfigData
> +  );
> +
> +/**
> +  This function sends REST request to REST service and signal caller's event
> asynchronously when
> +  the final response is received by REST EX Protocol driver instance.
> +
> +  The essential design of this function is to handle asynchronous
> send/receive implicitly according
> +  to REST service asynchronous request mechanism. Caller will get the
> notification once the response
> +  is returned from REST service.
> +
> +  @param[in]  This                  This is the EFI_REST_EX_PROTOCOL instance.
> +  @param[in]  RequestMessage        This is the HTTP request message sent
> to REST service. Set RequestMessage
> +                                    to NULL to cancel the previous asynchronous request
> associated with the
> +                                    corresponding RestExToken. See descriptions for the
> details.
> +  @param[in]  RestExToken           REST EX token which REST EX Protocol
> instance uses to notify REST client
> +                                    the status of response of asynchronous REST request. See
> related definition
> +                                    of EFI_REST_EX_TOKEN.
> +  @param[in]  TimeOutInMilliSeconds The pointer to the timeout in
> milliseconds which REST EX Protocol driver
> +                                    instance refers as the duration to drop asynchronous REST
> request. NULL
> +                                    pointer means no timeout for this REST request. REST EX
> Protocol driver
> +                                    signals caller's event with EFI_STATUS set to EFI_TIMEOUT
> in RestExToken
> +                                    if REST EX Protocol can't get the response from REST
> service within
> +                                    TimeOutInMilliSeconds.
> +
> +  @retval EFI_SUCCESS               Asynchronous REST request is established.
> +  @retval EFI_UNSUPPORTED           This REST EX Protocol driver instance
> doesn't support asynchronous request.
> +  @retval EFI_TIMEOUT               Asynchronous REST request is not
> established and timeout is expired.
> +  @retval EFI_ABORT                 Previous asynchronous REST request has been
> canceled.
> +  @retval EFI_DEVICE_ERROR          Otherwise, returns EFI_DEVICE_ERROR
> for other errors according to HTTP Status Code.
> +  @retval EFI_NOT_READY             The configuration of this instance is not set
> yet. Configure() must be executed
> +                                    and returns successfully prior to invoke this function.
> +
> +**/
> +typedef
> +EFI_STATUS
> +(EFIAPI *EFI_REST_EX_ASYNC_SEND_RECEIVE)(
> +  IN      EFI_REST_EX_PROTOCOL   *This,
> +  IN      EFI_HTTP_MESSAGE       *RequestMessage OPTIONAL,
> +  IN      EFI_REST_EX_TOKEN      *RestExToken,
> +  IN      UINTN                  *TimeOutInMilliSeconds OPTIONAL
> +  );
> +
> +/**
> +  This function sends REST request to a REST Event service and signals caller's
> event
> +  token asynchronously when the URI resource change event is received by
> REST EX
> +  Protocol driver instance.
> +
> +  The essential design of this function is to monitor event implicitly according
> to
> +  REST service event service mechanism. Caller will get the notification if
> certain
> +  resource is changed.
> +
> +  @param[in]  This                  This is the EFI_REST_EX_PROTOCOL instance.
> +  @param[in]  RequestMessage        This is the HTTP request message sent
> to REST service. Set RequestMessage
> +                                    to NULL to cancel the previous event service associated
> with the corresponding
> +                                    RestExToken. See descriptions for the details.
> +  @param[in]  RestExToken           REST EX token which REST EX Protocol
> driver instance uses to notify REST client
> +                                    the URI resource which monitored by REST client has
> been changed. See the related
> +                                    definition of EFI_REST_EX_TOKEN in
> EFI_REST_EX_PROTOCOL.AsyncSendReceive().
> +
> +  @retval EFI_SUCCESS               Asynchronous REST request is established.
> +  @retval EFI_UNSUPPORTED           This REST EX Protocol driver instance
> doesn't support asynchronous request.
> +  @retval EFI_ABORT                 Previous asynchronous REST request has been
> canceled or event subscription has been
> +                                    delete from service.
> +  @retval EFI_DEVICE_ERROR          Otherwise, returns EFI_DEVICE_ERROR
> for other errors according to HTTP Status Code.
> +  @retval EFI_NOT_READY             The configuration of this instance is not set
> yet. Configure() must be executed
> +                                    and returns successfully prior to invoke this function.
> +
> +**/
> +typedef
> +EFI_STATUS
> +(EFIAPI *EFI_REST_EX_EVENT_SERVICE)(
> +  IN      EFI_REST_EX_PROTOCOL   *This,
> +  IN      EFI_HTTP_MESSAGE       *RequestMessage OPTIONAL,
> +  IN      EFI_REST_EX_TOKEN      *RestExToken
> +);
> +
> +///
> +/// EFI REST(EX) protocols are designed to support REST communication
> between EFI REST client
> +/// applications/drivers and REST services. EFI REST client tool uses EFI
> REST(EX) protocols
> +/// to send/receive resources to/from REST service to manage systems,
> configure systems or
> +/// manipulate resources on REST service. Due to HTTP protocol is
> commonly used to communicate
> +/// with REST service in practice, EFI REST(EX) protocols adopt HTTP as the
> message format to
> +/// send and receive REST service resource. EFI REST(EX) driver instance
> abstracts EFI REST
> +/// client functionality and provides underlying interface to communicate
> with REST service.
> +/// EFI REST(EX) driver instance knows how to communicate with REST
> service through certain
> +/// interface after the corresponding configuration is initialized.
> +///
> +struct _EFI_REST_EX_PROTOCOL {
> +  EFI_REST_SEND_RECEIVE          SendReceive;
> +  EFI_REST_GET_TIME              GetServiceTime;
> +  EFI_REST_EX_GET_SERVICE        GetService;
> +  EFI_REST_EX_GET_MODE_DATA      GetModeData;
> +  EFI_REST_EX_CONFIGURE          Configure;
> +  EFI_REST_EX_ASYNC_SEND_RECEIVE AyncSendReceive;
> +  EFI_REST_EX_EVENT_SERVICE      EventService;
> +};
> +
> +extern EFI_GUID gEfiRestExServiceBindingProtocolGuid;
> +extern EFI_GUID gEfiRestExProtocolGuid;
> +
> +#endif
> diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec
> index 812be75fb3..5205374d62 100644
> --- a/MdePkg/MdePkg.dec
> +++ b/MdePkg/MdePkg.dec
> @@ -1848,6 +1848,13 @@
>    ## Include/Protocol/NvdimmLabel.h
>    gEfiNvdimmLabelProtocolGuid               = { 0xd40b6b80, 0x97d5, 0x4282,
> { 0xbb, 0x1d, 0x22, 0x3a, 0x16, 0x91, 0x80, 0x58 }}
> 
> +  #
> +  # Protocols defined in UEFI2.8
> +  #
> +  ## Include/Protocol/RestEx.h
> +  gEfiRestExProtocolGuid               = { 0x55648b91, 0xe7d, 0x40a3, { 0xa9, 0xb3,
> 0xa8, 0x15, 0xd7, 0xea, 0xdf, 0x97 }}
> +  gEfiRestExServiceBindingProtocolGuid = { 0x456bbe01, 0x99d0, 0x45ea,
> { 0xbb, 0x5f, 0x16, 0xd8, 0x4b, 0xed, 0xc5, 0x59 }}
> +
>    #
>    # Protocols defined in Shell2.0
>    #
> --
> 2.17.1
> 
> 
> 
> 
> 

回复: [edk2-devel] [Rest Ex Definition PATCH 1/2] MdePkg/Include: Definitions of EFI REST EX Protocol

[gaoliming]

Abner:
  In the file header, please describe this definition is from which version
UEFI spec. With this change, Reviewed-by: Liming Gao <gaoliming@byosoft.com.
cn>

Thanks
Liming
> -----邮件原件-----
> 发件人: Wu, Jiaxin <jiaxin.wu@intel.com>
> 发送时间: 2020年10月12日 16:54
> 收件人: devel@edk2.groups.io; abner.chang@hpe.com
> 抄送: Kinney, Michael D <michael.d.kinney@intel.com>; Liming Gao
> <gaoliming@byosoft.com.cn>; Liu, Zhiguang <zhiguang.liu@intel.com>; Yao,
> Jiewen <jiewen.yao@intel.com>; Nickle Wang <nickle.wang@hpe.com>
> 主题: RE: [edk2-devel] [Rest Ex Definition PATCH 1/2] MdePkg/Include:
> Definitions of EFI REST EX Protocol
> 
> Reviewed-by: Jiaxin Wu <jiaxin.wu@intel.com>
> 
> 
> 
> > -----Original Message-----
> > From: devel@edk2.groups.io <devel@edk2.groups.io> On Behalf Of Abner
> > Chang
> > Sent: Monday, October 12, 2020 3:04 PM
> > To: devel@edk2.groups.io
> > Cc: Kinney, Michael D <michael.d.kinney@intel.com>; Liming Gao
> > <gaoliming@byosoft.com.cn>; Liu, Zhiguang <zhiguang.liu@intel.com>; Yao,
> > Jiewen <jiewen.yao@intel.com>; Nickle Wang <nickle.wang@hpe.com>
> > Subject: [edk2-devel] [Rest Ex Definition PATCH 1/2] MdePkg/Include:
> > Definitions of EFI REST EX Protocol
> >
> > Add definitions of EFI REST EX Protocol according
> > to UEFI spec v2.8 Section 29.7.2 EFI REST EX Protocol.
> >
> > Signed-off-by: Jiaxin Wu <jiaxin.wu@intel.com>
> > Signed-off-by: Siyuan Fu <siyuan.fu@intel.com>
> > Signed-off-by: Fan Wang <fan.wang@intel.com>
> > 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: Jiewen Yao <jiewen.yao@intel.com>
> > Cc: Nickle Wang <nickle.wang@hpe.com>
> > ---
> >  MdePkg/Include/Protocol/RestEx.h | 388
> > +++++++++++++++++++++++++++++++
> >  MdePkg/MdePkg.dec                |   7 +
> >  2 files changed, 395 insertions(+)
> >  create mode 100644 MdePkg/Include/Protocol/RestEx.h
> >
> > diff --git a/MdePkg/Include/Protocol/RestEx.h
> > b/MdePkg/Include/Protocol/RestEx.h
> > new file mode 100644
> > index 0000000000..c42096d14c
> > --- /dev/null
> > +++ b/MdePkg/Include/Protocol/RestEx.h
> > @@ -0,0 +1,388 @@
> > +/** @file
> > +  This file defines the EFI REST EX Protocol interface. It is
> > +  split into the following two main sections.
> > +
> > +  - REST EX Service Binding Protocol
> > +  - REST EX Protocol
> > +
> > +   Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
> > +  (C) Copyright 2020 Hewlett Packard Enterprise Development LP<BR>
> > +
> > +  SPDX-License-Identifier: BSD-2-Clause-Patent
> > +
> > +
> > +**/
> > +
> > +#ifndef EFI_REST_EX_PROTOCOL_H_
> > +#define EFI_REST_EX_PROTOCOL_H_
> > +
> > +#include <Protocol/Http.h>
> > +
> > +//
> > +//GUID definitions
> > +//
> > +#define EFI_REST_EX_SERVICE_BINDING_PROTOCOL_GUID \
> > +  { \
> > +    0x456bbe01, 0x99d0, 0x45ea, {0xbb, 0x5f, 0x16, 0xd8, 0x4b, 0xed,
> 0xc5,
> > 0x59 } \
> > +  }
> > +
> > +#define EFI_REST_EX_PROTOCOL_GUID \
> > +  { \
> > +    0x55648b91, 0xe7d, 0x40a3, {0xa9, 0xb3, 0xa8, 0x15, 0xd7, 0xea,
0xdf,
> > 0x97 } \
> > +  }
> > +
> > +typedef struct _EFI_REST_EX_PROTOCOL EFI_REST_EX_PROTOCOL;
> > +
> > +//*******************************************************
> > +//EFI_REST_EX_SERVICE_INFO_VER
> > +//*******************************************************
> > +typedef struct {
> > +  UINT8  Major;
> > +  UINT8  Minor;
> > +} EFI_REST_EX_SERVICE_INFO_VER;
> > +
> > +//*******************************************************
> > +//EFI_REST_EX_SERVICE_INFO_HEADER
> > +//*******************************************************
> > +typedef struct {
> > +  UINT32                         Length;
> > +  EFI_REST_EX_SERVICE_INFO_VER   RestServiceInfoVer;
> > +} EFI_REST_EX_SERVICE_INFO_HEADER;
> > +
> > +//*******************************************************
> > +// EFI_REST_EX_SERVICE_TYPE
> > +//*******************************************************
> > +typedef enum {
> > +  EfiRestExServiceUnspecific = 1,
> > +  EfiRestExServiceRedfish,
> > +  EfiRestExServiceOdata,
> > +  EfiRestExServiceVendorSpecific = 0xff,
> > +  EfiRestExServiceTypeMax
> > +} EFI_REST_EX_SERVICE_TYPE;
> > +
> > +//*******************************************************
> > +// EFI_REST_EX_SERVICE_ACCESS_MODE
> > +//*******************************************************
> > +typedef enum {
> > +  EfiRestExServiceInBandAccess = 1,
> > +  EfiRestExServiceOutOfBandAccess = 2,
> > +  EfiRestExServiceModeMax
> > +} EFI_REST_EX_SERVICE_ACCESS_MODE;
> > +
> > +//*******************************************************
> > +// EFI_REST_EX_CONFIG_TYPE
> > +//*******************************************************
> > +typedef enum {
> > +  EfiRestExConfigHttp,
> > +  EfiRestExConfigUnspecific,
> > +  EfiRestExConfigTypeMax
> > +} EFI_REST_EX_CONFIG_TYPE;
> > +
> > +//*******************************************************
> > +//EFI_REST_EX_SERVICE_INFO v1.0
> > +//*******************************************************
> > +typedef struct {
> > +  EFI_REST_EX_SERVICE_INFO_HEADER  EfiRestExServiceInfoHeader;
> > +  EFI_REST_EX_SERVICE_TYPE         RestServiceType;
> > +  EFI_REST_EX_SERVICE_ACCESS_MODE  RestServiceAccessMode;
> > +  EFI_GUID                         VendorRestServiceName;
> > +  UINT32                           VendorSpecificDataLength;
> > +  UINT8                            *VendorSpecifcData;
> > +  EFI_REST_EX_CONFIG_TYPE          RestExConfigType;
> > +  UINT8                            RestExConfigDataLength;
> > +} EFI_REST_EX_SERVICE_INFO_V_1_0;
> > +
> > +//*******************************************************
> > +//EFI_REST_EX_SERVICE_INFO
> > +//*******************************************************
> > +typedef union {
> > +  EFI_REST_EX_SERVICE_INFO_HEADER EfiRestExServiceInfoHeader;
> > +  EFI_REST_EX_SERVICE_INFO_V_1_0  EfiRestExServiceInfoV10;
> > +} EFI_REST_EX_SERVICE_INFO;
> > +
> > +//*******************************************************
> > +// EFI_REST_EX_HTTP_CONFIG_DATA
> > +//*******************************************************
> > +typedef struct {
> > +  EFI_HTTP_CONFIG_DATA    HttpConfigData;
> > +  UINT32                  SendReceiveTimeout;
> > +} EFI_REST_EX_HTTP_CONFIG_DATA;
> > +
> > +//*******************************************************
> > +//EFI_REST_EX_CONFIG_DATA
> > +//*******************************************************
> > +typedef UINT8 *EFI_REST_EX_CONFIG_DATA;
> > +
> > +//*******************************************************
> > +//EFI_REST_EX_TOKEN
> > +//*******************************************************
> > +typedef struct {
> > +  EFI_EVENT         Event;
> > +  EFI_STATUS        Status;
> > +  EFI_HTTP_MESSAGE  *ResponseMessage;
> > +} EFI_REST_EX_TOKEN;
> > +
> > +/**
> > +  Provides a simple HTTP-like interface to send and receive resources
> from a
> > REST service.
> > +
> > +  The SendReceive() function sends an HTTP request to this REST
service,
> > and returns a
> > +  response when the data is retrieved from the service. RequestMessage
> > contains the HTTP
> > +  request to the REST resource identified by
> RequestMessage.Request.Url.
> > The
> > +  ResponseMessage is the returned HTTP response for that request,
> > including any HTTP
> > +  status.
> > +
> > +  @param[in]  This                Pointer to
> EFI_REST_EX_PROTOCOL instance for a
> > particular
> > +                                  REST service.
> > +  @param[in]  RequestMessage      Pointer to the HTTP request data
> for this
> > resource
> > +  @param[out] ResponseMessage     Pointer to the HTTP response
> data
> > obtained for this requested.
> > +
> > +  @retval EFI_SUCCESS             operation succeeded.
> > +  @retval EFI_INVALID_PARAMETER   This, RequestMessage, or
> > ResponseMessage are NULL.
> > +  @retval EFI_DEVICE_ERROR        An unexpected system or
> network error
> > occurred.
> > +
> > +**/
> > +typedef
> > +EFI_STATUS
> > +(EFIAPI *EFI_REST_SEND_RECEIVE)(
> > +  IN      EFI_REST_EX_PROTOCOL   *This,
> > +  IN      EFI_HTTP_MESSAGE       *RequestMessage,
> > +  OUT     EFI_HTTP_MESSAGE       *ResponseMessage
> > +  );
> > +
> > +/**
> > +  Obtain the current time from this REST service instance.
> > +
> > +  The GetServiceTime() function is an optional interface to obtain the
> > current time from
> > +  this REST service instance. If this REST service does not support to
> retrieve
> > the time,
> > +  this function returns EFI_UNSUPPORTED. This function must returns
> > EFI_UNSUPPORTED if
> > +  EFI_REST_EX_SERVICE_TYPE returned in EFI_REST_EX_SERVICE_INFO
> from
> > GetService() is
> > +  EFI_REST_EX_SERVICE_UNSPECIFIC.
> > +
> > +  @param[in]  This                Pointer to
> EFI_REST_EX_PROTOCOL instance for a
> > particular
> > +                                  REST service.
> > +  @param[out] Time                A pointer to storage to receive a
> snapshot of
> > the current time of
> > +                                  the REST service.
> > +
> > +  @retval EFI_SUCCESS             operation succeeded.
> > +  @retval EFI_INVALID_PARAMETER   This or Time are NULL.
> > +  @retval EFI_UNSUPPORTED         The RESTful service does not
> support
> > returning the time.
> > +  @retval EFI_DEVICE_ERROR        An unexpected system or
> network error
> > occurred.
> > +  @retval EFI_NOT_READY           The configuration of this instance
> is not set
> > yet. Configure() must
> > +                                  be executed and returns
> successfully prior to invoke this
> > function.
> > +
> > +**/
> > +typedef
> > +EFI_STATUS
> > +(EFIAPI *EFI_REST_GET_TIME)(
> > +  IN      EFI_REST_EX_PROTOCOL   *This,
> > +  OUT     EFI_TIME               *Time
> > +  );
> > +
> > +/**
> > +  This function returns the information of REST service provided by
this EFI
> > REST EX driver instance.
> > +
> > +  The information such as the type of REST service and the access mode
> of
> > REST EX driver instance
> > +  (In-band or Out-of-band) are described in EFI_REST_EX_SERVICE_INFO
> > structure. For the vendor-specific
> > +  REST service, vendor-specific REST service information is returned in
> > VendorSpecifcData.
> > +  REST EX driver designer is well know what REST service this REST EX
> driver
> > instance intends to
> > +  communicate with. The designer also well know this driver instance is
> used
> > to talk to BMC through
> > +  specific platform mechanism or talk to REST server through UEFI HTTP
> > protocol. REST EX driver is
> > +  responsible to fill up the correct information in
> > EFI_REST_EX_SERVICE_INFO. EFI_REST_EX_SERVICE_INFO
> > +  is referred by EFI REST clients to pickup the proper EFI REST EX
driver
> > instance to get and set resource.
> > +  GetService() is a basic and mandatory function which must be able to
> use
> > even Configure() is not invoked
> > +  in previously.
> > +
> > +  @param[in]  This                Pointer to
> EFI_REST_EX_PROTOCOL instance for a
> > particular
> > +                                  REST service.
> > +  @param[out] RestExServiceInfo   Pointer to receive a pointer to
> > EFI_REST_EX_SERVICE_INFO structure. The
> > +                                  format of
> EFI_REST_EX_SERVICE_INFO is version
> > controlled for the future
> > +                                  extension. The version of
> EFI_REST_EX_SERVICE_INFO
> > structure is returned
> > +                                  in the header within this
> structure. EFI REST client refers to
> > the correct
> > +                                  format of structure according to
> the version number. The
> > pointer to
> > +                                  EFI_REST_EX_SERVICE_INFO is
> a memory block allocated
> > by EFI REST EX driver
> > +                                  instance. That is caller's
> responsibility to free this memory
> > when this
> > +                                  structure is no longer needed.
> Refer to Related Definitions
> > below for the
> > +                                  definitions of
> EFI_REST_EX_SERVICE_INFO structure.
> > +
> > +  @retval EFI_SUCCESS             EFI_REST_EX_SERVICE_INFO is
> returned in
> > RestExServiceInfo. This function
> > +                                  is not supported in this REST EX
> Protocol driver instance.
> > +  @retval EFI_UNSUPPORTED         This function is not supported in
> this REST
> > EX Protocol driver instance.
> > +
> > +**/
> > +typedef
> > +EFI_STATUS
> > +(EFIAPI *EFI_REST_EX_GET_SERVICE)(
> > +  IN   EFI_REST_EX_PROTOCOL      *This,
> > +  OUT  EFI_REST_EX_SERVICE_INFO  **RestExServiceInfo
> > +  );
> > +
> > +/**
> > +  This function returns operational configuration of current EFI REST
EX
> child
> > instance.
> > +
> > +  This function returns the current configuration of EFI REST EX child
> instance.
> > The format of
> > +  operational configuration depends on the implementation of EFI REST
EX
> > driver instance. For
> > +  example, HTTP-aware EFI REST EX driver instance uses EFI HTTP
> protocol as
> > the undying protocol
> > +  to communicate with REST service. In this case, the type of
configuration
> is
> > +  EFI_REST_EX_CONFIG_TYPE_HTTP returned from GetService().
> > EFI_HTTP_CONFIG_DATA is used as EFI REST
> > +  EX configuration format and returned to EFI REST client. User has to
type
> > cast RestExConfigData
> > +  to EFI_HTTP_CONFIG_DATA. For those non HTTP-aware REST EX driver
> > instances, the type of configuration
> > +  is EFI_REST_EX_CONFIG_TYPE_UNSPECIFIC returned from GetService().
> In
> > this case, the format of
> > +  returning data could be non industrial. Instead, the format of
> configuration
> > data is system/platform
> > +  specific definition such as BMC mechanism used in EFI REST EX driver
> > instance. EFI REST client and
> > +  EFI REST EX driver instance have to refer to the specific system
> /platform
> > spec which is out of UEFI scope.
> > +
> > +  @param[in]  This                This is the
> EFI_REST_EX_PROTOCOL instance.
> > +  @param[out] RestExConfigData    Pointer to receive a pointer to
> > EFI_REST_EX_CONFIG_DATA.
> > +                                  The memory allocated for
> configuration data should be
> > freed
> > +                                  by caller. See Related Definitions
> for the details.
> > +
> > +  @retval EFI_SUCCESS             EFI_REST_EX_CONFIG_DATA is
> returned in
> > successfully.
> > +  @retval EFI_UNSUPPORTED         This function is not supported in
> this REST
> > EX Protocol driver instance.
> > +  @retval EFI_NOT_READY           The configuration of this instance
> is not set
> > yet. Configure() must be
> > +                                  executed and returns
> successfully prior to invoke this
> > function.
> > +
> > +**/
> > +typedef
> > +EFI_STATUS
> > +(EFIAPI *EFI_REST_EX_GET_MODE_DATA)(
> > +  IN  EFI_REST_EX_PROTOCOL  *This,
> > +  OUT EFI_REST_EX_CONFIG_DATA *RestExConfigData
> > +  );
> > +
> > +/**
> > +  This function is used to configure EFI REST EX child instance.
> > +
> > +  This function is used to configure the setting of underlying protocol
of
> REST
> > EX child
> > +  instance. The type of configuration is according to the
implementation of
> > EFI REST EX
> > +  driver instance. For example, HTTP-aware EFI REST EX driver instance
> uses
> > EFI HTTP protocol
> > +  as the undying protocol to communicate with REST service. The type of
> > configuration is
> > +  EFI_REST_EX_CONFIG_TYPE_HTTP and RestExConfigData is the same
> > format with EFI_HTTP_CONFIG_DATA.
> > +  Akin to HTTP configuration, REST EX child instance can be configure
to
> use
> > different HTTP
> > +  local access point for the data transmission. Multiple REST clients
may
> use
> > different
> > +  configuration of HTTP to distinguish themselves, such as to use the
> > different TCP port.
> > +  For those non HTTP-aware REST EX driver instance, the type of
> > configuration is
> > +  EFI_REST_EX_CONFIG_TYPE_UNSPECIFIC. RestExConfigData refers to
> the
> > non industrial standard.
> > +  Instead, the format of configuration data is system/platform specific
> > definition such as BMC.
> > +  In this case, EFI REST client and EFI REST EX driver instance have to
refer
> to
> > the specific
> > +  system/platform spec which is out of the UEFI scope. Besides
> > GetService()function, no other
> > +  EFI REST EX functions can be executed by this instance until
Configure()is
> > executed and returns
> > +  successfully. All other functions must returns EFI_NOT_READY if this
> > instance is not configured
> > +  yet. Set RestExConfigData to NULL means to put EFI REST EX child
> instance
> > into the unconfigured
> > +  state.
> > +
> > +  @param[in]  This                This is the
> EFI_REST_EX_PROTOCOL instance.
> > +  @param[in]  RestExConfigData    Pointer to
> EFI_REST_EX_CONFIG_DATA.
> > See Related Definitions in
> > +                                  GetModeData() protocol
> interface.
> > +
> > +  @retval EFI_SUCCESS             EFI_REST_EX_CONFIG_DATA is
> set in
> > successfully.
> > +  @retval EFI_DEVICE_ERROR        Configuration for this REST EX
> child
> > instance is failed with the given
> > +                                  EFI_REST_EX_CONFIG_DATA.
> > +  @retval EFI_UNSUPPORTED         This function is not supported in
> this REST
> > EX Protocol driver instance.
> > +
> > +**/
> > +typedef
> > +EFI_STATUS
> > +(EFIAPI *EFI_REST_EX_CONFIGURE)(
> > +  IN  EFI_REST_EX_PROTOCOL  *This,
> > +  IN  EFI_REST_EX_CONFIG_DATA RestExConfigData
> > +  );
> > +
> > +/**
> > +  This function sends REST request to REST service and signal caller's
> event
> > asynchronously when
> > +  the final response is received by REST EX Protocol driver instance.
> > +
> > +  The essential design of this function is to handle asynchronous
> > send/receive implicitly according
> > +  to REST service asynchronous request mechanism. Caller will get the
> > notification once the response
> > +  is returned from REST service.
> > +
> > +  @param[in]  This                  This is the
> EFI_REST_EX_PROTOCOL instance.
> > +  @param[in]  RequestMessage        This is the HTTP request
> message sent
> > to REST service. Set RequestMessage
> > +                                    to NULL to cancel the
> previous asynchronous request
> > associated with the
> > +                                    corresponding RestExToken.
> See descriptions for the
> > details.
> > +  @param[in]  RestExToken           REST EX token which REST EX
> Protocol
> > instance uses to notify REST client
> > +                                    the status of response of
> asynchronous REST request. See
> > related definition
> > +                                    of EFI_REST_EX_TOKEN.
> > +  @param[in]  TimeOutInMilliSeconds The pointer to the timeout in
> > milliseconds which REST EX Protocol driver
> > +                                    instance refers as the
> duration to drop asynchronous REST
> > request. NULL
> > +                                    pointer means no timeout for
> this REST request. REST EX
> > Protocol driver
> > +                                    signals caller's event with
> EFI_STATUS set to EFI_TIMEOUT
> > in RestExToken
> > +                                    if REST EX Protocol can't get
> the response from REST
> > service within
> > +                                    TimeOutInMilliSeconds.
> > +
> > +  @retval EFI_SUCCESS               Asynchronous REST request is
> established.
> > +  @retval EFI_UNSUPPORTED           This REST EX Protocol driver
> instance
> > doesn't support asynchronous request.
> > +  @retval EFI_TIMEOUT               Asynchronous REST request is
> not
> > established and timeout is expired.
> > +  @retval EFI_ABORT                 Previous asynchronous REST
> request has been
> > canceled.
> > +  @retval EFI_DEVICE_ERROR          Otherwise, returns
> EFI_DEVICE_ERROR
> > for other errors according to HTTP Status Code.
> > +  @retval EFI_NOT_READY             The configuration of this
> instance is not set
> > yet. Configure() must be executed
> > +                                    and returns successfully prior
> to invoke this function.
> > +
> > +**/
> > +typedef
> > +EFI_STATUS
> > +(EFIAPI *EFI_REST_EX_ASYNC_SEND_RECEIVE)(
> > +  IN      EFI_REST_EX_PROTOCOL   *This,
> > +  IN      EFI_HTTP_MESSAGE       *RequestMessage OPTIONAL,
> > +  IN      EFI_REST_EX_TOKEN      *RestExToken,
> > +  IN      UINTN                  *TimeOutInMilliSeconds
> OPTIONAL
> > +  );
> > +
> > +/**
> > +  This function sends REST request to a REST Event service and signals
> caller's
> > event
> > +  token asynchronously when the URI resource change event is received
> by
> > REST EX
> > +  Protocol driver instance.
> > +
> > +  The essential design of this function is to monitor event implicitly
> according
> > to
> > +  REST service event service mechanism. Caller will get the
notification if
> > certain
> > +  resource is changed.
> > +
> > +  @param[in]  This                  This is the
> EFI_REST_EX_PROTOCOL instance.
> > +  @param[in]  RequestMessage        This is the HTTP request
> message sent
> > to REST service. Set RequestMessage
> > +                                    to NULL to cancel the
> previous event service associated
> > with the corresponding
> > +                                    RestExToken. See
> descriptions for the details.
> > +  @param[in]  RestExToken           REST EX token which REST EX
> Protocol
> > driver instance uses to notify REST client
> > +                                    the URI resource which
> monitored by REST client has
> > been changed. See the related
> > +                                    definition of
> EFI_REST_EX_TOKEN in
> > EFI_REST_EX_PROTOCOL.AsyncSendReceive().
> > +
> > +  @retval EFI_SUCCESS               Asynchronous REST request is
> established.
> > +  @retval EFI_UNSUPPORTED           This REST EX Protocol driver
> instance
> > doesn't support asynchronous request.
> > +  @retval EFI_ABORT                 Previous asynchronous REST
> request has been
> > canceled or event subscription has been
> > +                                    delete from service.
> > +  @retval EFI_DEVICE_ERROR          Otherwise, returns
> EFI_DEVICE_ERROR
> > for other errors according to HTTP Status Code.
> > +  @retval EFI_NOT_READY             The configuration of this
> instance is not set
> > yet. Configure() must be executed
> > +                                    and returns successfully prior
> to invoke this function.
> > +
> > +**/
> > +typedef
> > +EFI_STATUS
> > +(EFIAPI *EFI_REST_EX_EVENT_SERVICE)(
> > +  IN      EFI_REST_EX_PROTOCOL   *This,
> > +  IN      EFI_HTTP_MESSAGE       *RequestMessage OPTIONAL,
> > +  IN      EFI_REST_EX_TOKEN      *RestExToken
> > +);
> > +
> > +///
> > +/// EFI REST(EX) protocols are designed to support REST communication
> > between EFI REST client
> > +/// applications/drivers and REST services. EFI REST client tool uses
EFI
> > REST(EX) protocols
> > +/// to send/receive resources to/from REST service to manage systems,
> > configure systems or
> > +/// manipulate resources on REST service. Due to HTTP protocol is
> > commonly used to communicate
> > +/// with REST service in practice, EFI REST(EX) protocols adopt HTTP as
the
> > message format to
> > +/// send and receive REST service resource. EFI REST(EX) driver
instance
> > abstracts EFI REST
> > +/// client functionality and provides underlying interface to
communicate
> > with REST service.
> > +/// EFI REST(EX) driver instance knows how to communicate with REST
> > service through certain
> > +/// interface after the corresponding configuration is initialized.
> > +///
> > +struct _EFI_REST_EX_PROTOCOL {
> > +  EFI_REST_SEND_RECEIVE          SendReceive;
> > +  EFI_REST_GET_TIME              GetServiceTime;
> > +  EFI_REST_EX_GET_SERVICE        GetService;
> > +  EFI_REST_EX_GET_MODE_DATA      GetModeData;
> > +  EFI_REST_EX_CONFIGURE          Configure;
> > +  EFI_REST_EX_ASYNC_SEND_RECEIVE AyncSendReceive;
> > +  EFI_REST_EX_EVENT_SERVICE      EventService;
> > +};
> > +
> > +extern EFI_GUID gEfiRestExServiceBindingProtocolGuid;
> > +extern EFI_GUID gEfiRestExProtocolGuid;
> > +
> > +#endif
> > diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec
> > index 812be75fb3..5205374d62 100644
> > --- a/MdePkg/MdePkg.dec
> > +++ b/MdePkg/MdePkg.dec
> > @@ -1848,6 +1848,13 @@
> >    ## Include/Protocol/NvdimmLabel.h
> >    gEfiNvdimmLabelProtocolGuid               = { 0xd40b6b80,
> 0x97d5, 0x4282,
> > { 0xbb, 0x1d, 0x22, 0x3a, 0x16, 0x91, 0x80, 0x58 }}
> >
> > +  #
> > +  # Protocols defined in UEFI2.8
> > +  #
> > +  ## Include/Protocol/RestEx.h
> > +  gEfiRestExProtocolGuid               = { 0x55648b91, 0xe7d,
> 0x40a3, { 0xa9, 0xb3,
> > 0xa8, 0x15, 0xd7, 0xea, 0xdf, 0x97 }}
> > +  gEfiRestExServiceBindingProtocolGuid = { 0x456bbe01, 0x99d0, 0x45ea,
> > { 0xbb, 0x5f, 0x16, 0xd8, 0x4b, 0xed, 0xc5, 0x59 }}
> > +
> >    #
> >    # Protocols defined in Shell2.0
> >    #
> > --
> > 2.17.1
> >
> >
> >
> > 
> >

Re: [edk2-devel] [Rest Ex Definition PATCH 1/2] MdePkg/Include: Definitions of EFI REST EX Protocol

[Abner Chang]

Thanks Liming, v2 patch sent.

CI test passed on PR:  https://github.com/tianocore/edk2/pull/1012


> -----Original Message-----
> From: devel@edk2.groups.io [mailto:devel@edk2.groups.io] On Behalf Of
> gaoliming
> Sent: Wednesday, October 14, 2020 1:37 PM
> To: 'Wu, Jiaxin' <jiaxin.wu@intel.com>; devel@edk2.groups.io; Chang, Abner
> (HPS SW/FW Technologist) <abner.chang@hpe.com>
> Cc: 'Kinney, Michael D' <michael.d.kinney@intel.com>; 'Liu, Zhiguang'
> <zhiguang.liu@intel.com>; 'Yao, Jiewen' <jiewen.yao@intel.com>; Wang,
> Nickle (HPS SW) <nickle.wang@hpe.com>
> Subject: 回复: [edk2-devel] [Rest Ex Definition PATCH 1/2] MdePkg/Include:
> Definitions of EFI REST EX Protocol
> 
> Abner:
>   In the file header, please describe this definition is from which version UEFI
> spec. With this change, Reviewed-by: Liming Gao <gaoliming@byosoft.com.
> cn>
> 
> Thanks
> Liming
> > -----邮件原件-----
> > 发件人: Wu, Jiaxin <jiaxin.wu@intel.com>
> > 发送时间: 2020年10月12日 16:54
> > 收件人: devel@edk2.groups.io; abner.chang@hpe.com
> > 抄送: Kinney, Michael D <michael.d.kinney@intel.com>; Liming Gao
> > <gaoliming@byosoft.com.cn>; Liu, Zhiguang <zhiguang.liu@intel.com>;
> > Yao, Jiewen <jiewen.yao@intel.com>; Nickle Wang
> <nickle.wang@hpe.com>
> > 主题: RE: [edk2-devel] [Rest Ex Definition PATCH 1/2] MdePkg/Include:
> > Definitions of EFI REST EX Protocol
> >
> > Reviewed-by: Jiaxin Wu <jiaxin.wu@intel.com>
> >
> >
> >
> > > -----Original Message-----
> > > From: devel@edk2.groups.io <devel@edk2.groups.io> On Behalf Of
> Abner
> > > Chang
> > > Sent: Monday, October 12, 2020 3:04 PM
> > > To: devel@edk2.groups.io
> > > Cc: Kinney, Michael D <michael.d.kinney@intel.com>; Liming Gao
> > > <gaoliming@byosoft.com.cn>; Liu, Zhiguang <zhiguang.liu@intel.com>;
> > > Yao, Jiewen <jiewen.yao@intel.com>; Nickle Wang
> > > <nickle.wang@hpe.com>
> > > Subject: [edk2-devel] [Rest Ex Definition PATCH 1/2] MdePkg/Include:
> > > Definitions of EFI REST EX Protocol
> > >
> > > Add definitions of EFI REST EX Protocol according to UEFI spec v2.8
> > > Section 29.7.2 EFI REST EX Protocol.
> > >
> > > Signed-off-by: Jiaxin Wu <jiaxin.wu@intel.com>
> > > Signed-off-by: Siyuan Fu <siyuan.fu@intel.com>
> > > Signed-off-by: Fan Wang <fan.wang@intel.com>
> > > 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: Jiewen Yao <jiewen.yao@intel.com>
> > > Cc: Nickle Wang <nickle.wang@hpe.com>
> > > ---
> > >  MdePkg/Include/Protocol/RestEx.h | 388
> > > +++++++++++++++++++++++++++++++
> > >  MdePkg/MdePkg.dec                |   7 +
> > >  2 files changed, 395 insertions(+)
> > >  create mode 100644 MdePkg/Include/Protocol/RestEx.h
> > >
> > > diff --git a/MdePkg/Include/Protocol/RestEx.h
> > > b/MdePkg/Include/Protocol/RestEx.h
> > > new file mode 100644
> > > index 0000000000..c42096d14c
> > > --- /dev/null
> > > +++ b/MdePkg/Include/Protocol/RestEx.h
> > > @@ -0,0 +1,388 @@
> > > +/** @file
> > > +  This file defines the EFI REST EX Protocol interface. It is
> > > +  split into the following two main sections.
> > > +
> > > +  - REST EX Service Binding Protocol
> > > +  - REST EX Protocol
> > > +
> > > +   Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
> > > +  (C) Copyright 2020 Hewlett Packard Enterprise Development LP<BR>
> > > +
> > > +  SPDX-License-Identifier: BSD-2-Clause-Patent
> > > +
> > > +
> > > +**/
> > > +
> > > +#ifndef EFI_REST_EX_PROTOCOL_H_
> > > +#define EFI_REST_EX_PROTOCOL_H_
> > > +
> > > +#include <Protocol/Http.h>
> > > +
> > > +//
> > > +//GUID definitions
> > > +//
> > > +#define EFI_REST_EX_SERVICE_BINDING_PROTOCOL_GUID \
> > > +  { \
> > > +    0x456bbe01, 0x99d0, 0x45ea, {0xbb, 0x5f, 0x16, 0xd8, 0x4b,
> > > +0xed,
> > 0xc5,
> > > 0x59 } \
> > > +  }
> > > +
> > > +#define EFI_REST_EX_PROTOCOL_GUID \
> > > +  { \
> > > +    0x55648b91, 0xe7d, 0x40a3, {0xa9, 0xb3, 0xa8, 0x15, 0xd7, 0xea,
> 0xdf,
> > > 0x97 } \
> > > +  }
> > > +
> > > +typedef struct _EFI_REST_EX_PROTOCOL EFI_REST_EX_PROTOCOL;
> > > +
> > >
> +//*******************************************************
> > > +//EFI_REST_EX_SERVICE_INFO_VER
> > >
> +//*******************************************************
> > > +typedef struct {
> > > +  UINT8  Major;
> > > +  UINT8  Minor;
> > > +} EFI_REST_EX_SERVICE_INFO_VER;
> > > +
> > >
> +//*******************************************************
> > > +//EFI_REST_EX_SERVICE_INFO_HEADER
> > >
> +//*******************************************************
> > > +typedef struct {
> > > +  UINT32                         Length;
> > > +  EFI_REST_EX_SERVICE_INFO_VER   RestServiceInfoVer;
> > > +} EFI_REST_EX_SERVICE_INFO_HEADER;
> > > +
> > >
> +//*******************************************************
> > > +// EFI_REST_EX_SERVICE_TYPE
> > >
> +//*******************************************************
> > > +typedef enum {
> > > +  EfiRestExServiceUnspecific = 1,
> > > +  EfiRestExServiceRedfish,
> > > +  EfiRestExServiceOdata,
> > > +  EfiRestExServiceVendorSpecific = 0xff,
> > > +  EfiRestExServiceTypeMax
> > > +} EFI_REST_EX_SERVICE_TYPE;
> > > +
> > >
> +//*******************************************************
> > > +// EFI_REST_EX_SERVICE_ACCESS_MODE
> > >
> +//*******************************************************
> > > +typedef enum {
> > > +  EfiRestExServiceInBandAccess = 1,
> > > +  EfiRestExServiceOutOfBandAccess = 2,
> > > +  EfiRestExServiceModeMax
> > > +} EFI_REST_EX_SERVICE_ACCESS_MODE;
> > > +
> > >
> +//*******************************************************
> > > +// EFI_REST_EX_CONFIG_TYPE
> > >
> +//*******************************************************
> > > +typedef enum {
> > > +  EfiRestExConfigHttp,
> > > +  EfiRestExConfigUnspecific,
> > > +  EfiRestExConfigTypeMax
> > > +} EFI_REST_EX_CONFIG_TYPE;
> > > +
> > >
> +//*******************************************************
> > > +//EFI_REST_EX_SERVICE_INFO v1.0
> > >
> +//*******************************************************
> > > +typedef struct {
> > > +  EFI_REST_EX_SERVICE_INFO_HEADER  EfiRestExServiceInfoHeader;
> > > +  EFI_REST_EX_SERVICE_TYPE         RestServiceType;
> > > +  EFI_REST_EX_SERVICE_ACCESS_MODE  RestServiceAccessMode;
> > > +  EFI_GUID                         VendorRestServiceName;
> > > +  UINT32                           VendorSpecificDataLength;
> > > +  UINT8                            *VendorSpecifcData;
> > > +  EFI_REST_EX_CONFIG_TYPE          RestExConfigType;
> > > +  UINT8                            RestExConfigDataLength;
> > > +} EFI_REST_EX_SERVICE_INFO_V_1_0;
> > > +
> > >
> +//*******************************************************
> > > +//EFI_REST_EX_SERVICE_INFO
> > >
> +//*******************************************************
> > > +typedef union {
> > > +  EFI_REST_EX_SERVICE_INFO_HEADER EfiRestExServiceInfoHeader;
> > > +  EFI_REST_EX_SERVICE_INFO_V_1_0  EfiRestExServiceInfoV10; }
> > > +EFI_REST_EX_SERVICE_INFO;
> > > +
> > >
> +//*******************************************************
> > > +// EFI_REST_EX_HTTP_CONFIG_DATA
> > >
> +//*******************************************************
> > > +typedef struct {
> > > +  EFI_HTTP_CONFIG_DATA    HttpConfigData;
> > > +  UINT32                  SendReceiveTimeout;
> > > +} EFI_REST_EX_HTTP_CONFIG_DATA;
> > > +
> > >
> +//*******************************************************
> > > +//EFI_REST_EX_CONFIG_DATA
> > >
> +//*******************************************************
> > > +typedef UINT8 *EFI_REST_EX_CONFIG_DATA;
> > > +
> > >
> +//*******************************************************
> > > +//EFI_REST_EX_TOKEN
> > >
> +//*******************************************************
> > > +typedef struct {
> > > +  EFI_EVENT         Event;
> > > +  EFI_STATUS        Status;
> > > +  EFI_HTTP_MESSAGE  *ResponseMessage; } EFI_REST_EX_TOKEN;
> > > +
> > > +/**
> > > +  Provides a simple HTTP-like interface to send and receive
> > > +resources
> > from a
> > > REST service.
> > > +
> > > +  The SendReceive() function sends an HTTP request to this REST
> service,
> > > and returns a
> > > +  response when the data is retrieved from the service.
> > > + RequestMessage
> > > contains the HTTP
> > > +  request to the REST resource identified by
> > RequestMessage.Request.Url.
> > > The
> > > +  ResponseMessage is the returned HTTP response for that request,
> > > including any HTTP
> > > +  status.
> > > +
> > > +  @param[in]  This                Pointer to
> > EFI_REST_EX_PROTOCOL instance for a
> > > particular
> > > +                                  REST service.
> > > +  @param[in]  RequestMessage      Pointer to the HTTP request data
> > for this
> > > resource
> > > +  @param[out] ResponseMessage     Pointer to the HTTP response
> > data
> > > obtained for this requested.
> > > +
> > > +  @retval EFI_SUCCESS             operation succeeded.
> > > +  @retval EFI_INVALID_PARAMETER   This, RequestMessage, or
> > > ResponseMessage are NULL.
> > > +  @retval EFI_DEVICE_ERROR        An unexpected system or
> > network error
> > > occurred.
> > > +
> > > +**/
> > > +typedef
> > > +EFI_STATUS
> > > +(EFIAPI *EFI_REST_SEND_RECEIVE)(
> > > +  IN      EFI_REST_EX_PROTOCOL   *This,
> > > +  IN      EFI_HTTP_MESSAGE       *RequestMessage,
> > > +  OUT     EFI_HTTP_MESSAGE       *ResponseMessage
> > > +  );
> > > +
> > > +/**
> > > +  Obtain the current time from this REST service instance.
> > > +
> > > +  The GetServiceTime() function is an optional interface to obtain
> > > + the
> > > current time from
> > > +  this REST service instance. If this REST service does not support
> > > + to
> > retrieve
> > > the time,
> > > +  this function returns EFI_UNSUPPORTED. This function must returns
> > > EFI_UNSUPPORTED if
> > > +  EFI_REST_EX_SERVICE_TYPE returned in EFI_REST_EX_SERVICE_INFO
> > from
> > > GetService() is
> > > +  EFI_REST_EX_SERVICE_UNSPECIFIC.
> > > +
> > > +  @param[in]  This                Pointer to
> > EFI_REST_EX_PROTOCOL instance for a
> > > particular
> > > +                                  REST service.
> > > +  @param[out] Time                A pointer to storage to receive a
> > snapshot of
> > > the current time of
> > > +                                  the REST service.
> > > +
> > > +  @retval EFI_SUCCESS             operation succeeded.
> > > +  @retval EFI_INVALID_PARAMETER   This or Time are NULL.
> > > +  @retval EFI_UNSUPPORTED         The RESTful service does not
> > support
> > > returning the time.
> > > +  @retval EFI_DEVICE_ERROR        An unexpected system or
> > network error
> > > occurred.
> > > +  @retval EFI_NOT_READY           The configuration of this instance
> > is not set
> > > yet. Configure() must
> > > +                                  be executed and returns
> > successfully prior to invoke this
> > > function.
> > > +
> > > +**/
> > > +typedef
> > > +EFI_STATUS
> > > +(EFIAPI *EFI_REST_GET_TIME)(
> > > +  IN      EFI_REST_EX_PROTOCOL   *This,
> > > +  OUT     EFI_TIME               *Time
> > > +  );
> > > +
> > > +/**
> > > +  This function returns the information of REST service provided by
> this EFI
> > > REST EX driver instance.
> > > +
> > > +  The information such as the type of REST service and the access
> > > + mode
> > of
> > > REST EX driver instance
> > > +  (In-band or Out-of-band) are described in
> > > + EFI_REST_EX_SERVICE_INFO
> > > structure. For the vendor-specific
> > > +  REST service, vendor-specific REST service information is
> > > + returned in
> > > VendorSpecifcData.
> > > +  REST EX driver designer is well know what REST service this REST
> > > + EX
> > driver
> > > instance intends to
> > > +  communicate with. The designer also well know this driver
> > > + instance is
> > used
> > > to talk to BMC through
> > > +  specific platform mechanism or talk to REST server through UEFI
> > > + HTTP
> > > protocol. REST EX driver is
> > > +  responsible to fill up the correct information in
> > > EFI_REST_EX_SERVICE_INFO. EFI_REST_EX_SERVICE_INFO
> > > +  is referred by EFI REST clients to pickup the proper EFI REST EX
> driver
> > > instance to get and set resource.
> > > +  GetService() is a basic and mandatory function which must be able
> > > + to
> > use
> > > even Configure() is not invoked
> > > +  in previously.
> > > +
> > > +  @param[in]  This                Pointer to
> > EFI_REST_EX_PROTOCOL instance for a
> > > particular
> > > +                                  REST service.
> > > +  @param[out] RestExServiceInfo   Pointer to receive a pointer to
> > > EFI_REST_EX_SERVICE_INFO structure. The
> > > +                                  format of
> > EFI_REST_EX_SERVICE_INFO is version
> > > controlled for the future
> > > +                                  extension. The version of
> > EFI_REST_EX_SERVICE_INFO
> > > structure is returned
> > > +                                  in the header within this
> > structure. EFI REST client refers to
> > > the correct
> > > +                                  format of structure according to
> > the version number. The
> > > pointer to
> > > +                                  EFI_REST_EX_SERVICE_INFO is
> > a memory block allocated
> > > by EFI REST EX driver
> > > +                                  instance. That is caller's
> > responsibility to free this memory
> > > when this
> > > +                                  structure is no longer needed.
> > Refer to Related Definitions
> > > below for the
> > > +                                  definitions of
> > EFI_REST_EX_SERVICE_INFO structure.
> > > +
> > > +  @retval EFI_SUCCESS             EFI_REST_EX_SERVICE_INFO is
> > returned in
> > > RestExServiceInfo. This function
> > > +                                  is not supported in this REST EX
> > Protocol driver instance.
> > > +  @retval EFI_UNSUPPORTED         This function is not supported in
> > this REST
> > > EX Protocol driver instance.
> > > +
> > > +**/
> > > +typedef
> > > +EFI_STATUS
> > > +(EFIAPI *EFI_REST_EX_GET_SERVICE)(
> > > +  IN   EFI_REST_EX_PROTOCOL      *This,
> > > +  OUT  EFI_REST_EX_SERVICE_INFO  **RestExServiceInfo
> > > +  );
> > > +
> > > +/**
> > > +  This function returns operational configuration of current EFI
> > > +REST
> EX
> > child
> > > instance.
> > > +
> > > +  This function returns the current configuration of EFI REST EX
> > > + child
> > instance.
> > > The format of
> > > +  operational configuration depends on the implementation of EFI
> > > + REST
> EX
> > > driver instance. For
> > > +  example, HTTP-aware EFI REST EX driver instance uses EFI HTTP
> > protocol as
> > > the undying protocol
> > > +  to communicate with REST service. In this case, the type of
> configuration
> > is
> > > +  EFI_REST_EX_CONFIG_TYPE_HTTP returned from GetService().
> > > EFI_HTTP_CONFIG_DATA is used as EFI REST
> > > +  EX configuration format and returned to EFI REST client. User has
> > > + to
> type
> > > cast RestExConfigData
> > > +  to EFI_HTTP_CONFIG_DATA. For those non HTTP-aware REST EX driver
> > > instances, the type of configuration
> > > +  is EFI_REST_EX_CONFIG_TYPE_UNSPECIFIC returned from
> GetService().
> > In
> > > this case, the format of
> > > +  returning data could be non industrial. Instead, the format of
> > configuration
> > > data is system/platform
> > > +  specific definition such as BMC mechanism used in EFI REST EX
> > > + driver
> > > instance. EFI REST client and
> > > +  EFI REST EX driver instance have to refer to the specific system
> > /platform
> > > spec which is out of UEFI scope.
> > > +
> > > +  @param[in]  This                This is the
> > EFI_REST_EX_PROTOCOL instance.
> > > +  @param[out] RestExConfigData    Pointer to receive a pointer to
> > > EFI_REST_EX_CONFIG_DATA.
> > > +                                  The memory allocated for
> > configuration data should be
> > > freed
> > > +                                  by caller. See Related
> > > + Definitions
> > for the details.
> > > +
> > > +  @retval EFI_SUCCESS             EFI_REST_EX_CONFIG_DATA is
> > returned in
> > > successfully.
> > > +  @retval EFI_UNSUPPORTED         This function is not supported in
> > this REST
> > > EX Protocol driver instance.
> > > +  @retval EFI_NOT_READY           The configuration of this instance
> > is not set
> > > yet. Configure() must be
> > > +                                  executed and returns
> > successfully prior to invoke this
> > > function.
> > > +
> > > +**/
> > > +typedef
> > > +EFI_STATUS
> > > +(EFIAPI *EFI_REST_EX_GET_MODE_DATA)(
> > > +  IN  EFI_REST_EX_PROTOCOL  *This,
> > > +  OUT EFI_REST_EX_CONFIG_DATA *RestExConfigData
> > > +  );
> > > +
> > > +/**
> > > +  This function is used to configure EFI REST EX child instance.
> > > +
> > > +  This function is used to configure the setting of underlying
> > > + protocol
> of
> > REST
> > > EX child
> > > +  instance. The type of configuration is according to the
> implementation of
> > > EFI REST EX
> > > +  driver instance. For example, HTTP-aware EFI REST EX driver
> > > + instance
> > uses
> > > EFI HTTP protocol
> > > +  as the undying protocol to communicate with REST service. The
> > > + type of
> > > configuration is
> > > +  EFI_REST_EX_CONFIG_TYPE_HTTP and RestExConfigData is the same
> > > format with EFI_HTTP_CONFIG_DATA.
> > > +  Akin to HTTP configuration, REST EX child instance can be
> > > + configure
> to
> > use
> > > different HTTP
> > > +  local access point for the data transmission. Multiple REST
> > > + clients
> may
> > use
> > > different
> > > +  configuration of HTTP to distinguish themselves, such as to use
> > > + the
> > > different TCP port.
> > > +  For those non HTTP-aware REST EX driver instance, the type of
> > > configuration is
> > > +  EFI_REST_EX_CONFIG_TYPE_UNSPECIFIC. RestExConfigData refers to
> > the
> > > non industrial standard.
> > > +  Instead, the format of configuration data is system/platform
> > > + specific
> > > definition such as BMC.
> > > +  In this case, EFI REST client and EFI REST EX driver instance
> > > + have to
> refer
> > to
> > > the specific
> > > +  system/platform spec which is out of the UEFI scope. Besides
> > > GetService()function, no other
> > > +  EFI REST EX functions can be executed by this instance until
> Configure()is
> > > executed and returns
> > > +  successfully. All other functions must returns EFI_NOT_READY if
> > > + this
> > > instance is not configured
> > > +  yet. Set RestExConfigData to NULL means to put EFI REST EX child
> > instance
> > > into the unconfigured
> > > +  state.
> > > +
> > > +  @param[in]  This                This is the
> > EFI_REST_EX_PROTOCOL instance.
> > > +  @param[in]  RestExConfigData    Pointer to
> > EFI_REST_EX_CONFIG_DATA.
> > > See Related Definitions in
> > > +                                  GetModeData() protocol
> > interface.
> > > +
> > > +  @retval EFI_SUCCESS             EFI_REST_EX_CONFIG_DATA is
> > set in
> > > successfully.
> > > +  @retval EFI_DEVICE_ERROR        Configuration for this REST EX
> > child
> > > instance is failed with the given
> > > +                                  EFI_REST_EX_CONFIG_DATA.
> > > +  @retval EFI_UNSUPPORTED         This function is not supported in
> > this REST
> > > EX Protocol driver instance.
> > > +
> > > +**/
> > > +typedef
> > > +EFI_STATUS
> > > +(EFIAPI *EFI_REST_EX_CONFIGURE)(
> > > +  IN  EFI_REST_EX_PROTOCOL  *This,
> > > +  IN  EFI_REST_EX_CONFIG_DATA RestExConfigData
> > > +  );
> > > +
> > > +/**
> > > +  This function sends REST request to REST service and signal
> > > +caller's
> > event
> > > asynchronously when
> > > +  the final response is received by REST EX Protocol driver instance.
> > > +
> > > +  The essential design of this function is to handle asynchronous
> > > send/receive implicitly according
> > > +  to REST service asynchronous request mechanism. Caller will get
> > > + the
> > > notification once the response
> > > +  is returned from REST service.
> > > +
> > > +  @param[in]  This                  This is the
> > EFI_REST_EX_PROTOCOL instance.
> > > +  @param[in]  RequestMessage        This is the HTTP request
> > message sent
> > > to REST service. Set RequestMessage
> > > +                                    to NULL to cancel the
> > previous asynchronous request
> > > associated with the
> > > +                                    corresponding RestExToken.
> > See descriptions for the
> > > details.
> > > +  @param[in]  RestExToken           REST EX token which REST EX
> > Protocol
> > > instance uses to notify REST client
> > > +                                    the status of response of
> > asynchronous REST request. See
> > > related definition
> > > +                                    of EFI_REST_EX_TOKEN.
> > > +  @param[in]  TimeOutInMilliSeconds The pointer to the timeout in
> > > milliseconds which REST EX Protocol driver
> > > +                                    instance refers as the
> > duration to drop asynchronous REST
> > > request. NULL
> > > +                                    pointer means no timeout for
> > this REST request. REST EX
> > > Protocol driver
> > > +                                    signals caller's event with
> > EFI_STATUS set to EFI_TIMEOUT
> > > in RestExToken
> > > +                                    if REST EX Protocol can't get
> > the response from REST
> > > service within
> > > +                                    TimeOutInMilliSeconds.
> > > +
> > > +  @retval EFI_SUCCESS               Asynchronous REST request is
> > established.
> > > +  @retval EFI_UNSUPPORTED           This REST EX Protocol driver
> > instance
> > > doesn't support asynchronous request.
> > > +  @retval EFI_TIMEOUT               Asynchronous REST request is
> > not
> > > established and timeout is expired.
> > > +  @retval EFI_ABORT                 Previous asynchronous REST
> > request has been
> > > canceled.
> > > +  @retval EFI_DEVICE_ERROR          Otherwise, returns
> > EFI_DEVICE_ERROR
> > > for other errors according to HTTP Status Code.
> > > +  @retval EFI_NOT_READY             The configuration of this
> > instance is not set
> > > yet. Configure() must be executed
> > > +                                    and returns successfully prior
> > to invoke this function.
> > > +
> > > +**/
> > > +typedef
> > > +EFI_STATUS
> > > +(EFIAPI *EFI_REST_EX_ASYNC_SEND_RECEIVE)(
> > > +  IN      EFI_REST_EX_PROTOCOL   *This,
> > > +  IN      EFI_HTTP_MESSAGE       *RequestMessage OPTIONAL,
> > > +  IN      EFI_REST_EX_TOKEN      *RestExToken,
> > > +  IN      UINTN                  *TimeOutInMilliSeconds
> > OPTIONAL
> > > +  );
> > > +
> > > +/**
> > > +  This function sends REST request to a REST Event service and
> > > +signals
> > caller's
> > > event
> > > +  token asynchronously when the URI resource change event is
> > > + received
> > by
> > > REST EX
> > > +  Protocol driver instance.
> > > +
> > > +  The essential design of this function is to monitor event
> > > + implicitly
> > according
> > > to
> > > +  REST service event service mechanism. Caller will get the
> notification if
> > > certain
> > > +  resource is changed.
> > > +
> > > +  @param[in]  This                  This is the
> > EFI_REST_EX_PROTOCOL instance.
> > > +  @param[in]  RequestMessage        This is the HTTP request
> > message sent
> > > to REST service. Set RequestMessage
> > > +                                    to NULL to cancel the
> > previous event service associated
> > > with the corresponding
> > > +                                    RestExToken. See
> > descriptions for the details.
> > > +  @param[in]  RestExToken           REST EX token which REST EX
> > Protocol
> > > driver instance uses to notify REST client
> > > +                                    the URI resource which
> > monitored by REST client has
> > > been changed. See the related
> > > +                                    definition of
> > EFI_REST_EX_TOKEN in
> > > EFI_REST_EX_PROTOCOL.AsyncSendReceive().
> > > +
> > > +  @retval EFI_SUCCESS               Asynchronous REST request is
> > established.
> > > +  @retval EFI_UNSUPPORTED           This REST EX Protocol driver
> > instance
> > > doesn't support asynchronous request.
> > > +  @retval EFI_ABORT                 Previous asynchronous REST
> > request has been
> > > canceled or event subscription has been
> > > +                                    delete from service.
> > > +  @retval EFI_DEVICE_ERROR          Otherwise, returns
> > EFI_DEVICE_ERROR
> > > for other errors according to HTTP Status Code.
> > > +  @retval EFI_NOT_READY             The configuration of this
> > instance is not set
> > > yet. Configure() must be executed
> > > +                                    and returns successfully prior
> > to invoke this function.
> > > +
> > > +**/
> > > +typedef
> > > +EFI_STATUS
> > > +(EFIAPI *EFI_REST_EX_EVENT_SERVICE)(
> > > +  IN      EFI_REST_EX_PROTOCOL   *This,
> > > +  IN      EFI_HTTP_MESSAGE       *RequestMessage OPTIONAL,
> > > +  IN      EFI_REST_EX_TOKEN      *RestExToken
> > > +);
> > > +
> > > +///
> > > +/// EFI REST(EX) protocols are designed to support REST
> > > +communication
> > > between EFI REST client
> > > +/// applications/drivers and REST services. EFI REST client tool
> > > +uses
> EFI
> > > REST(EX) protocols
> > > +/// to send/receive resources to/from REST service to manage
> > > +systems,
> > > configure systems or
> > > +/// manipulate resources on REST service. Due to HTTP protocol is
> > > commonly used to communicate
> > > +/// with REST service in practice, EFI REST(EX) protocols adopt
> > > +HTTP as
> the
> > > message format to
> > > +/// send and receive REST service resource. EFI REST(EX) driver
> instance
> > > abstracts EFI REST
> > > +/// client functionality and provides underlying interface to
> communicate
> > > with REST service.
> > > +/// EFI REST(EX) driver instance knows how to communicate with REST
> > > service through certain
> > > +/// interface after the corresponding configuration is initialized.
> > > +///
> > > +struct _EFI_REST_EX_PROTOCOL {
> > > +  EFI_REST_SEND_RECEIVE          SendReceive;
> > > +  EFI_REST_GET_TIME              GetServiceTime;
> > > +  EFI_REST_EX_GET_SERVICE        GetService;
> > > +  EFI_REST_EX_GET_MODE_DATA      GetModeData;
> > > +  EFI_REST_EX_CONFIGURE          Configure;
> > > +  EFI_REST_EX_ASYNC_SEND_RECEIVE AyncSendReceive;
> > > +  EFI_REST_EX_EVENT_SERVICE      EventService;
> > > +};
> > > +
> > > +extern EFI_GUID gEfiRestExServiceBindingProtocolGuid;
> > > +extern EFI_GUID gEfiRestExProtocolGuid;
> > > +
> > > +#endif
> > > diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec index
> > > 812be75fb3..5205374d62 100644
> > > --- a/MdePkg/MdePkg.dec
> > > +++ b/MdePkg/MdePkg.dec
> > > @@ -1848,6 +1848,13 @@
> > >    ## Include/Protocol/NvdimmLabel.h
> > >    gEfiNvdimmLabelProtocolGuid               = { 0xd40b6b80,
> > 0x97d5, 0x4282,
> > > { 0xbb, 0x1d, 0x22, 0x3a, 0x16, 0x91, 0x80, 0x58 }}
> > >
> > > +  #
> > > +  # Protocols defined in UEFI2.8
> > > +  #
> > > +  ## Include/Protocol/RestEx.h
> > > +  gEfiRestExProtocolGuid               = { 0x55648b91, 0xe7d,
> > 0x40a3, { 0xa9, 0xb3,
> > > 0xa8, 0x15, 0xd7, 0xea, 0xdf, 0x97 }}
> > > +  gEfiRestExServiceBindingProtocolGuid = { 0x456bbe01, 0x99d0,
> > > + 0x45ea,
> > > { 0xbb, 0x5f, 0x16, 0xd8, 0x4b, 0xed, 0xc5, 0x59 }}
> > > +
> > >    #
> > >    # Protocols defined in Shell2.0
> > >    #
> > > --
> > > 2.17.1
> > >
> > >
> > >
> > >
> > >
> 
> 
> 
> 
> 
> 
> 

Re: [edk2-devel] [Rest Ex Definition PATCH 1/2] MdePkg/Include: Definitions of EFI REST EX Protocol

[Abner Chang]

Patches were merged @b9b7406c43e9d29bde3e9679c1b039cb91109097

> -----Original Message-----
> From: devel@edk2.groups.io [mailto:devel@edk2.groups.io] On Behalf Of
> Abner Chang
> Sent: Wednesday, October 14, 2020 7:38 PM
> To: devel@edk2.groups.io; gaoliming@byosoft.com.cn; 'Wu, Jiaxin'
> <jiaxin.wu@intel.com>
> Cc: 'Kinney, Michael D' <michael.d.kinney@intel.com>; 'Liu, Zhiguang'
> <zhiguang.liu@intel.com>; 'Yao, Jiewen' <jiewen.yao@intel.com>; Wang,
> Nickle (HPS SW) <nickle.wang@hpe.com>
> Subject: Re: [edk2-devel] [Rest Ex Definition PATCH 1/2] MdePkg/Include:
> Definitions of EFI REST EX Protocol
> 
> Thanks Liming, v2 patch sent.
> 
> CI test passed on PR:  https://github.com/tianocore/edk2/pull/1012
> 
> 
> > -----Original Message-----
> > From: devel@edk2.groups.io [mailto:devel@edk2.groups.io] On Behalf Of
> > gaoliming
> > Sent: Wednesday, October 14, 2020 1:37 PM
> > To: 'Wu, Jiaxin' <jiaxin.wu@intel.com>; devel@edk2.groups.io; Chang,
> > Abner (HPS SW/FW Technologist) <abner.chang@hpe.com>
> > Cc: 'Kinney, Michael D' <michael.d.kinney@intel.com>; 'Liu, Zhiguang'
> > <zhiguang.liu@intel.com>; 'Yao, Jiewen' <jiewen.yao@intel.com>; Wang,
> > Nickle (HPS SW) <nickle.wang@hpe.com>
> > Subject: 回复: [edk2-devel] [Rest Ex Definition PATCH 1/2]
> MdePkg/Include:
> > Definitions of EFI REST EX Protocol
> >
> > Abner:
> >   In the file header, please describe this definition is from which
> > version UEFI spec. With this change, Reviewed-by: Liming Gao
> <gaoliming@byosoft.com.
> > cn>
> >
> > Thanks
> > Liming
> > > -----邮件原件-----
> > > 发件人: Wu, Jiaxin <jiaxin.wu@intel.com>
> > > 发送时间: 2020年10月12日 16:54
> > > 收件人: devel@edk2.groups.io; abner.chang@hpe.com
> > > 抄送: Kinney, Michael D <michael.d.kinney@intel.com>; Liming Gao
> > > <gaoliming@byosoft.com.cn>; Liu, Zhiguang <zhiguang.liu@intel.com>;
> > > Yao, Jiewen <jiewen.yao@intel.com>; Nickle Wang
> > <nickle.wang@hpe.com>
> > > 主题: RE: [edk2-devel] [Rest Ex Definition PATCH 1/2] MdePkg/Include:
> > > Definitions of EFI REST EX Protocol
> > >
> > > Reviewed-by: Jiaxin Wu <jiaxin.wu@intel.com>
> > >
> > >
> > >
> > > > -----Original Message-----
> > > > From: devel@edk2.groups.io <devel@edk2.groups.io> On Behalf Of
> > Abner
> > > > Chang
> > > > Sent: Monday, October 12, 2020 3:04 PM
> > > > To: devel@edk2.groups.io
> > > > Cc: Kinney, Michael D <michael.d.kinney@intel.com>; Liming Gao
> > > > <gaoliming@byosoft.com.cn>; Liu, Zhiguang
> > > > <zhiguang.liu@intel.com>; Yao, Jiewen <jiewen.yao@intel.com>;
> > > > Nickle Wang <nickle.wang@hpe.com>
> > > > Subject: [edk2-devel] [Rest Ex Definition PATCH 1/2] MdePkg/Include:
> > > > Definitions of EFI REST EX Protocol
> > > >
> > > > Add definitions of EFI REST EX Protocol according to UEFI spec
> > > > v2.8 Section 29.7.2 EFI REST EX Protocol.
> > > >
> > > > Signed-off-by: Jiaxin Wu <jiaxin.wu@intel.com>
> > > > Signed-off-by: Siyuan Fu <siyuan.fu@intel.com>
> > > > Signed-off-by: Fan Wang <fan.wang@intel.com>
> > > > 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: Jiewen Yao <jiewen.yao@intel.com>
> > > > Cc: Nickle Wang <nickle.wang@hpe.com>
> > > > ---
> > > >  MdePkg/Include/Protocol/RestEx.h | 388
> > > > +++++++++++++++++++++++++++++++
> > > >  MdePkg/MdePkg.dec                |   7 +
> > > >  2 files changed, 395 insertions(+)  create mode 100644
> > > > MdePkg/Include/Protocol/RestEx.h
> > > >
> > > > diff --git a/MdePkg/Include/Protocol/RestEx.h
> > > > b/MdePkg/Include/Protocol/RestEx.h
> > > > new file mode 100644
> > > > index 0000000000..c42096d14c
> > > > --- /dev/null
> > > > +++ b/MdePkg/Include/Protocol/RestEx.h
> > > > @@ -0,0 +1,388 @@
> > > > +/** @file
> > > > +  This file defines the EFI REST EX Protocol interface. It is
> > > > +  split into the following two main sections.
> > > > +
> > > > +  - REST EX Service Binding Protocol
> > > > +  - REST EX Protocol
> > > > +
> > > > +   Copyright (c) 2019, Intel Corporation. All rights
> > > > + reserved.<BR>
> > > > +  (C) Copyright 2020 Hewlett Packard Enterprise Development
> > > > + LP<BR>
> > > > +
> > > > +  SPDX-License-Identifier: BSD-2-Clause-Patent
> > > > +
> > > > +
> > > > +**/
> > > > +
> > > > +#ifndef EFI_REST_EX_PROTOCOL_H_
> > > > +#define EFI_REST_EX_PROTOCOL_H_
> > > > +
> > > > +#include <Protocol/Http.h>
> > > > +
> > > > +//
> > > > +//GUID definitions
> > > > +//
> > > > +#define EFI_REST_EX_SERVICE_BINDING_PROTOCOL_GUID \
> > > > +  { \
> > > > +    0x456bbe01, 0x99d0, 0x45ea, {0xbb, 0x5f, 0x16, 0xd8, 0x4b,
> > > > +0xed,
> > > 0xc5,
> > > > 0x59 } \
> > > > +  }
> > > > +
> > > > +#define EFI_REST_EX_PROTOCOL_GUID \
> > > > +  { \
> > > > +    0x55648b91, 0xe7d, 0x40a3, {0xa9, 0xb3, 0xa8, 0x15, 0xd7,
> > > > +0xea,
> > 0xdf,
> > > > 0x97 } \
> > > > +  }
> > > > +
> > > > +typedef struct _EFI_REST_EX_PROTOCOL EFI_REST_EX_PROTOCOL;
> > > > +
> > > >
> >
> +//*******************************************************
> > > > +//EFI_REST_EX_SERVICE_INFO_VER
> > > >
> >
> +//*******************************************************
> > > > +typedef struct {
> > > > +  UINT8  Major;
> > > > +  UINT8  Minor;
> > > > +} EFI_REST_EX_SERVICE_INFO_VER;
> > > > +
> > > >
> >
> +//*******************************************************
> > > > +//EFI_REST_EX_SERVICE_INFO_HEADER
> > > >
> >
> +//*******************************************************
> > > > +typedef struct {
> > > > +  UINT32                         Length;
> > > > +  EFI_REST_EX_SERVICE_INFO_VER   RestServiceInfoVer;
> > > > +} EFI_REST_EX_SERVICE_INFO_HEADER;
> > > > +
> > > >
> >
> +//*******************************************************
> > > > +// EFI_REST_EX_SERVICE_TYPE
> > > >
> >
> +//*******************************************************
> > > > +typedef enum {
> > > > +  EfiRestExServiceUnspecific = 1,
> > > > +  EfiRestExServiceRedfish,
> > > > +  EfiRestExServiceOdata,
> > > > +  EfiRestExServiceVendorSpecific = 0xff,
> > > > +  EfiRestExServiceTypeMax
> > > > +} EFI_REST_EX_SERVICE_TYPE;
> > > > +
> > > >
> >
> +//*******************************************************
> > > > +// EFI_REST_EX_SERVICE_ACCESS_MODE
> > > >
> >
> +//*******************************************************
> > > > +typedef enum {
> > > > +  EfiRestExServiceInBandAccess = 1,
> > > > +  EfiRestExServiceOutOfBandAccess = 2,
> > > > +  EfiRestExServiceModeMax
> > > > +} EFI_REST_EX_SERVICE_ACCESS_MODE;
> > > > +
> > > >
> >
> +//*******************************************************
> > > > +// EFI_REST_EX_CONFIG_TYPE
> > > >
> >
> +//*******************************************************
> > > > +typedef enum {
> > > > +  EfiRestExConfigHttp,
> > > > +  EfiRestExConfigUnspecific,
> > > > +  EfiRestExConfigTypeMax
> > > > +} EFI_REST_EX_CONFIG_TYPE;
> > > > +
> > > >
> >
> +//*******************************************************
> > > > +//EFI_REST_EX_SERVICE_INFO v1.0
> > > >
> >
> +//*******************************************************
> > > > +typedef struct {
> > > > +  EFI_REST_EX_SERVICE_INFO_HEADER  EfiRestExServiceInfoHeader;
> > > > +  EFI_REST_EX_SERVICE_TYPE         RestServiceType;
> > > > +  EFI_REST_EX_SERVICE_ACCESS_MODE  RestServiceAccessMode;
> > > > +  EFI_GUID                         VendorRestServiceName;
> > > > +  UINT32                           VendorSpecificDataLength;
> > > > +  UINT8                            *VendorSpecifcData;
> > > > +  EFI_REST_EX_CONFIG_TYPE          RestExConfigType;
> > > > +  UINT8                            RestExConfigDataLength;
> > > > +} EFI_REST_EX_SERVICE_INFO_V_1_0;
> > > > +
> > > >
> >
> +//*******************************************************
> > > > +//EFI_REST_EX_SERVICE_INFO
> > > >
> >
> +//*******************************************************
> > > > +typedef union {
> > > > +  EFI_REST_EX_SERVICE_INFO_HEADER EfiRestExServiceInfoHeader;
> > > > +  EFI_REST_EX_SERVICE_INFO_V_1_0  EfiRestExServiceInfoV10; }
> > > > +EFI_REST_EX_SERVICE_INFO;
> > > > +
> > > >
> >
> +//*******************************************************
> > > > +// EFI_REST_EX_HTTP_CONFIG_DATA
> > > >
> >
> +//*******************************************************
> > > > +typedef struct {
> > > > +  EFI_HTTP_CONFIG_DATA    HttpConfigData;
> > > > +  UINT32                  SendReceiveTimeout;
> > > > +} EFI_REST_EX_HTTP_CONFIG_DATA;
> > > > +
> > > >
> >
> +//*******************************************************
> > > > +//EFI_REST_EX_CONFIG_DATA
> > > >
> >
> +//*******************************************************
> > > > +typedef UINT8 *EFI_REST_EX_CONFIG_DATA;
> > > > +
> > > >
> >
> +//*******************************************************
> > > > +//EFI_REST_EX_TOKEN
> > > >
> >
> +//*******************************************************
> > > > +typedef struct {
> > > > +  EFI_EVENT         Event;
> > > > +  EFI_STATUS        Status;
> > > > +  EFI_HTTP_MESSAGE  *ResponseMessage; } EFI_REST_EX_TOKEN;
> > > > +
> > > > +/**
> > > > +  Provides a simple HTTP-like interface to send and receive
> > > > +resources
> > > from a
> > > > REST service.
> > > > +
> > > > +  The SendReceive() function sends an HTTP request to this REST
> > service,
> > > > and returns a
> > > > +  response when the data is retrieved from the service.
> > > > + RequestMessage
> > > > contains the HTTP
> > > > +  request to the REST resource identified by
> > > RequestMessage.Request.Url.
> > > > The
> > > > +  ResponseMessage is the returned HTTP response for that request,
> > > > including any HTTP
> > > > +  status.
> > > > +
> > > > +  @param[in]  This                Pointer to
> > > EFI_REST_EX_PROTOCOL instance for a
> > > > particular
> > > > +                                  REST service.
> > > > +  @param[in]  RequestMessage      Pointer to the HTTP request data
> > > for this
> > > > resource
> > > > +  @param[out] ResponseMessage     Pointer to the HTTP response
> > > data
> > > > obtained for this requested.
> > > > +
> > > > +  @retval EFI_SUCCESS             operation succeeded.
> > > > +  @retval EFI_INVALID_PARAMETER   This, RequestMessage, or
> > > > ResponseMessage are NULL.
> > > > +  @retval EFI_DEVICE_ERROR        An unexpected system or
> > > network error
> > > > occurred.
> > > > +
> > > > +**/
> > > > +typedef
> > > > +EFI_STATUS
> > > > +(EFIAPI *EFI_REST_SEND_RECEIVE)(
> > > > +  IN      EFI_REST_EX_PROTOCOL   *This,
> > > > +  IN      EFI_HTTP_MESSAGE       *RequestMessage,
> > > > +  OUT     EFI_HTTP_MESSAGE       *ResponseMessage
> > > > +  );
> > > > +
> > > > +/**
> > > > +  Obtain the current time from this REST service instance.
> > > > +
> > > > +  The GetServiceTime() function is an optional interface to
> > > > + obtain the
> > > > current time from
> > > > +  this REST service instance. If this REST service does not
> > > > + support to
> > > retrieve
> > > > the time,
> > > > +  this function returns EFI_UNSUPPORTED. This function must
> > > > + returns
> > > > EFI_UNSUPPORTED if
> > > > +  EFI_REST_EX_SERVICE_TYPE returned in EFI_REST_EX_SERVICE_INFO
> > > from
> > > > GetService() is
> > > > +  EFI_REST_EX_SERVICE_UNSPECIFIC.
> > > > +
> > > > +  @param[in]  This                Pointer to
> > > EFI_REST_EX_PROTOCOL instance for a
> > > > particular
> > > > +                                  REST service.
> > > > +  @param[out] Time                A pointer to storage to receive a
> > > snapshot of
> > > > the current time of
> > > > +                                  the REST service.
> > > > +
> > > > +  @retval EFI_SUCCESS             operation succeeded.
> > > > +  @retval EFI_INVALID_PARAMETER   This or Time are NULL.
> > > > +  @retval EFI_UNSUPPORTED         The RESTful service does not
> > > support
> > > > returning the time.
> > > > +  @retval EFI_DEVICE_ERROR        An unexpected system or
> > > network error
> > > > occurred.
> > > > +  @retval EFI_NOT_READY           The configuration of this instance
> > > is not set
> > > > yet. Configure() must
> > > > +                                  be executed and returns
> > > successfully prior to invoke this
> > > > function.
> > > > +
> > > > +**/
> > > > +typedef
> > > > +EFI_STATUS
> > > > +(EFIAPI *EFI_REST_GET_TIME)(
> > > > +  IN      EFI_REST_EX_PROTOCOL   *This,
> > > > +  OUT     EFI_TIME               *Time
> > > > +  );
> > > > +
> > > > +/**
> > > > +  This function returns the information of REST service provided
> > > > +by
> > this EFI
> > > > REST EX driver instance.
> > > > +
> > > > +  The information such as the type of REST service and the access
> > > > + mode
> > > of
> > > > REST EX driver instance
> > > > +  (In-band or Out-of-band) are described in
> > > > + EFI_REST_EX_SERVICE_INFO
> > > > structure. For the vendor-specific
> > > > +  REST service, vendor-specific REST service information is
> > > > + returned in
> > > > VendorSpecifcData.
> > > > +  REST EX driver designer is well know what REST service this
> > > > + REST EX
> > > driver
> > > > instance intends to
> > > > +  communicate with. The designer also well know this driver
> > > > + instance is
> > > used
> > > > to talk to BMC through
> > > > +  specific platform mechanism or talk to REST server through UEFI
> > > > + HTTP
> > > > protocol. REST EX driver is
> > > > +  responsible to fill up the correct information in
> > > > EFI_REST_EX_SERVICE_INFO. EFI_REST_EX_SERVICE_INFO
> > > > +  is referred by EFI REST clients to pickup the proper EFI REST
> > > > + EX
> > driver
> > > > instance to get and set resource.
> > > > +  GetService() is a basic and mandatory function which must be
> > > > + able to
> > > use
> > > > even Configure() is not invoked
> > > > +  in previously.
> > > > +
> > > > +  @param[in]  This                Pointer to
> > > EFI_REST_EX_PROTOCOL instance for a
> > > > particular
> > > > +                                  REST service.
> > > > +  @param[out] RestExServiceInfo   Pointer to receive a pointer to
> > > > EFI_REST_EX_SERVICE_INFO structure. The
> > > > +                                  format of
> > > EFI_REST_EX_SERVICE_INFO is version
> > > > controlled for the future
> > > > +                                  extension. The version of
> > > EFI_REST_EX_SERVICE_INFO
> > > > structure is returned
> > > > +                                  in the header within this
> > > structure. EFI REST client refers to
> > > > the correct
> > > > +                                  format of structure according
> > > > + to
> > > the version number. The
> > > > pointer to
> > > > +                                  EFI_REST_EX_SERVICE_INFO is
> > > a memory block allocated
> > > > by EFI REST EX driver
> > > > +                                  instance. That is caller's
> > > responsibility to free this memory
> > > > when this
> > > > +                                  structure is no longer needed.
> > > Refer to Related Definitions
> > > > below for the
> > > > +                                  definitions of
> > > EFI_REST_EX_SERVICE_INFO structure.
> > > > +
> > > > +  @retval EFI_SUCCESS             EFI_REST_EX_SERVICE_INFO is
> > > returned in
> > > > RestExServiceInfo. This function
> > > > +                                  is not supported in this REST
> > > > + EX
> > > Protocol driver instance.
> > > > +  @retval EFI_UNSUPPORTED         This function is not supported in
> > > this REST
> > > > EX Protocol driver instance.
> > > > +
> > > > +**/
> > > > +typedef
> > > > +EFI_STATUS
> > > > +(EFIAPI *EFI_REST_EX_GET_SERVICE)(
> > > > +  IN   EFI_REST_EX_PROTOCOL      *This,
> > > > +  OUT  EFI_REST_EX_SERVICE_INFO  **RestExServiceInfo
> > > > +  );
> > > > +
> > > > +/**
> > > > +  This function returns operational configuration of current EFI
> > > > +REST
> > EX
> > > child
> > > > instance.
> > > > +
> > > > +  This function returns the current configuration of EFI REST EX
> > > > + child
> > > instance.
> > > > The format of
> > > > +  operational configuration depends on the implementation of EFI
> > > > + REST
> > EX
> > > > driver instance. For
> > > > +  example, HTTP-aware EFI REST EX driver instance uses EFI HTTP
> > > protocol as
> > > > the undying protocol
> > > > +  to communicate with REST service. In this case, the type of
> > configuration
> > > is
> > > > +  EFI_REST_EX_CONFIG_TYPE_HTTP returned from GetService().
> > > > EFI_HTTP_CONFIG_DATA is used as EFI REST
> > > > +  EX configuration format and returned to EFI REST client. User
> > > > + has to
> > type
> > > > cast RestExConfigData
> > > > +  to EFI_HTTP_CONFIG_DATA. For those non HTTP-aware REST EX
> > > > + driver
> > > > instances, the type of configuration
> > > > +  is EFI_REST_EX_CONFIG_TYPE_UNSPECIFIC returned from
> > GetService().
> > > In
> > > > this case, the format of
> > > > +  returning data could be non industrial. Instead, the format of
> > > configuration
> > > > data is system/platform
> > > > +  specific definition such as BMC mechanism used in EFI REST EX
> > > > + driver
> > > > instance. EFI REST client and
> > > > +  EFI REST EX driver instance have to refer to the specific
> > > > + system
> > > /platform
> > > > spec which is out of UEFI scope.
> > > > +
> > > > +  @param[in]  This                This is the
> > > EFI_REST_EX_PROTOCOL instance.
> > > > +  @param[out] RestExConfigData    Pointer to receive a pointer to
> > > > EFI_REST_EX_CONFIG_DATA.
> > > > +                                  The memory allocated for
> > > configuration data should be
> > > > freed
> > > > +                                  by caller. See Related
> > > > + Definitions
> > > for the details.
> > > > +
> > > > +  @retval EFI_SUCCESS             EFI_REST_EX_CONFIG_DATA is
> > > returned in
> > > > successfully.
> > > > +  @retval EFI_UNSUPPORTED         This function is not supported in
> > > this REST
> > > > EX Protocol driver instance.
> > > > +  @retval EFI_NOT_READY           The configuration of this instance
> > > is not set
> > > > yet. Configure() must be
> > > > +                                  executed and returns
> > > successfully prior to invoke this
> > > > function.
> > > > +
> > > > +**/
> > > > +typedef
> > > > +EFI_STATUS
> > > > +(EFIAPI *EFI_REST_EX_GET_MODE_DATA)(
> > > > +  IN  EFI_REST_EX_PROTOCOL  *This,
> > > > +  OUT EFI_REST_EX_CONFIG_DATA *RestExConfigData
> > > > +  );
> > > > +
> > > > +/**
> > > > +  This function is used to configure EFI REST EX child instance.
> > > > +
> > > > +  This function is used to configure the setting of underlying
> > > > + protocol
> > of
> > > REST
> > > > EX child
> > > > +  instance. The type of configuration is according to the
> > implementation of
> > > > EFI REST EX
> > > > +  driver instance. For example, HTTP-aware EFI REST EX driver
> > > > + instance
> > > uses
> > > > EFI HTTP protocol
> > > > +  as the undying protocol to communicate with REST service. The
> > > > + type of
> > > > configuration is
> > > > +  EFI_REST_EX_CONFIG_TYPE_HTTP and RestExConfigData is the same
> > > > format with EFI_HTTP_CONFIG_DATA.
> > > > +  Akin to HTTP configuration, REST EX child instance can be
> > > > + configure
> > to
> > > use
> > > > different HTTP
> > > > +  local access point for the data transmission. Multiple REST
> > > > + clients
> > may
> > > use
> > > > different
> > > > +  configuration of HTTP to distinguish themselves, such as to use
> > > > + the
> > > > different TCP port.
> > > > +  For those non HTTP-aware REST EX driver instance, the type of
> > > > configuration is
> > > > +  EFI_REST_EX_CONFIG_TYPE_UNSPECIFIC. RestExConfigData refers
> to
> > > the
> > > > non industrial standard.
> > > > +  Instead, the format of configuration data is system/platform
> > > > + specific
> > > > definition such as BMC.
> > > > +  In this case, EFI REST client and EFI REST EX driver instance
> > > > + have to
> > refer
> > > to
> > > > the specific
> > > > +  system/platform spec which is out of the UEFI scope. Besides
> > > > GetService()function, no other
> > > > +  EFI REST EX functions can be executed by this instance until
> > Configure()is
> > > > executed and returns
> > > > +  successfully. All other functions must returns EFI_NOT_READY if
> > > > + this
> > > > instance is not configured
> > > > +  yet. Set RestExConfigData to NULL means to put EFI REST EX
> > > > + child
> > > instance
> > > > into the unconfigured
> > > > +  state.
> > > > +
> > > > +  @param[in]  This                This is the
> > > EFI_REST_EX_PROTOCOL instance.
> > > > +  @param[in]  RestExConfigData    Pointer to
> > > EFI_REST_EX_CONFIG_DATA.
> > > > See Related Definitions in
> > > > +                                  GetModeData() protocol
> > > interface.
> > > > +
> > > > +  @retval EFI_SUCCESS             EFI_REST_EX_CONFIG_DATA is
> > > set in
> > > > successfully.
> > > > +  @retval EFI_DEVICE_ERROR        Configuration for this REST EX
> > > child
> > > > instance is failed with the given
> > > > +                                  EFI_REST_EX_CONFIG_DATA.
> > > > +  @retval EFI_UNSUPPORTED         This function is not supported in
> > > this REST
> > > > EX Protocol driver instance.
> > > > +
> > > > +**/
> > > > +typedef
> > > > +EFI_STATUS
> > > > +(EFIAPI *EFI_REST_EX_CONFIGURE)(
> > > > +  IN  EFI_REST_EX_PROTOCOL  *This,
> > > > +  IN  EFI_REST_EX_CONFIG_DATA RestExConfigData
> > > > +  );
> > > > +
> > > > +/**
> > > > +  This function sends REST request to REST service and signal
> > > > +caller's
> > > event
> > > > asynchronously when
> > > > +  the final response is received by REST EX Protocol driver instance.
> > > > +
> > > > +  The essential design of this function is to handle asynchronous
> > > > send/receive implicitly according
> > > > +  to REST service asynchronous request mechanism. Caller will get
> > > > + the
> > > > notification once the response
> > > > +  is returned from REST service.
> > > > +
> > > > +  @param[in]  This                  This is the
> > > EFI_REST_EX_PROTOCOL instance.
> > > > +  @param[in]  RequestMessage        This is the HTTP request
> > > message sent
> > > > to REST service. Set RequestMessage
> > > > +                                    to NULL to cancel the
> > > previous asynchronous request
> > > > associated with the
> > > > +                                    corresponding RestExToken.
> > > See descriptions for the
> > > > details.
> > > > +  @param[in]  RestExToken           REST EX token which REST EX
> > > Protocol
> > > > instance uses to notify REST client
> > > > +                                    the status of response of
> > > asynchronous REST request. See
> > > > related definition
> > > > +                                    of EFI_REST_EX_TOKEN.
> > > > +  @param[in]  TimeOutInMilliSeconds The pointer to the timeout in
> > > > milliseconds which REST EX Protocol driver
> > > > +                                    instance refers as the
> > > duration to drop asynchronous REST
> > > > request. NULL
> > > > +                                    pointer means no timeout for
> > > this REST request. REST EX
> > > > Protocol driver
> > > > +                                    signals caller's event with
> > > EFI_STATUS set to EFI_TIMEOUT
> > > > in RestExToken
> > > > +                                    if REST EX Protocol can't get
> > > the response from REST
> > > > service within
> > > > +                                    TimeOutInMilliSeconds.
> > > > +
> > > > +  @retval EFI_SUCCESS               Asynchronous REST request is
> > > established.
> > > > +  @retval EFI_UNSUPPORTED           This REST EX Protocol driver
> > > instance
> > > > doesn't support asynchronous request.
> > > > +  @retval EFI_TIMEOUT               Asynchronous REST request is
> > > not
> > > > established and timeout is expired.
> > > > +  @retval EFI_ABORT                 Previous asynchronous REST
> > > request has been
> > > > canceled.
> > > > +  @retval EFI_DEVICE_ERROR          Otherwise, returns
> > > EFI_DEVICE_ERROR
> > > > for other errors according to HTTP Status Code.
> > > > +  @retval EFI_NOT_READY             The configuration of this
> > > instance is not set
> > > > yet. Configure() must be executed
> > > > +                                    and returns successfully
> > > > + prior
> > > to invoke this function.
> > > > +
> > > > +**/
> > > > +typedef
> > > > +EFI_STATUS
> > > > +(EFIAPI *EFI_REST_EX_ASYNC_SEND_RECEIVE)(
> > > > +  IN      EFI_REST_EX_PROTOCOL   *This,
> > > > +  IN      EFI_HTTP_MESSAGE       *RequestMessage OPTIONAL,
> > > > +  IN      EFI_REST_EX_TOKEN      *RestExToken,
> > > > +  IN      UINTN                  *TimeOutInMilliSeconds
> > > OPTIONAL
> > > > +  );
> > > > +
> > > > +/**
> > > > +  This function sends REST request to a REST Event service and
> > > > +signals
> > > caller's
> > > > event
> > > > +  token asynchronously when the URI resource change event is
> > > > + received
> > > by
> > > > REST EX
> > > > +  Protocol driver instance.
> > > > +
> > > > +  The essential design of this function is to monitor event
> > > > + implicitly
> > > according
> > > > to
> > > > +  REST service event service mechanism. Caller will get the
> > notification if
> > > > certain
> > > > +  resource is changed.
> > > > +
> > > > +  @param[in]  This                  This is the
> > > EFI_REST_EX_PROTOCOL instance.
> > > > +  @param[in]  RequestMessage        This is the HTTP request
> > > message sent
> > > > to REST service. Set RequestMessage
> > > > +                                    to NULL to cancel the
> > > previous event service associated
> > > > with the corresponding
> > > > +                                    RestExToken. See
> > > descriptions for the details.
> > > > +  @param[in]  RestExToken           REST EX token which REST EX
> > > Protocol
> > > > driver instance uses to notify REST client
> > > > +                                    the URI resource which
> > > monitored by REST client has
> > > > been changed. See the related
> > > > +                                    definition of
> > > EFI_REST_EX_TOKEN in
> > > > EFI_REST_EX_PROTOCOL.AsyncSendReceive().
> > > > +
> > > > +  @retval EFI_SUCCESS               Asynchronous REST request is
> > > established.
> > > > +  @retval EFI_UNSUPPORTED           This REST EX Protocol driver
> > > instance
> > > > doesn't support asynchronous request.
> > > > +  @retval EFI_ABORT                 Previous asynchronous REST
> > > request has been
> > > > canceled or event subscription has been
> > > > +                                    delete from service.
> > > > +  @retval EFI_DEVICE_ERROR          Otherwise, returns
> > > EFI_DEVICE_ERROR
> > > > for other errors according to HTTP Status Code.
> > > > +  @retval EFI_NOT_READY             The configuration of this
> > > instance is not set
> > > > yet. Configure() must be executed
> > > > +                                    and returns successfully
> > > > + prior
> > > to invoke this function.
> > > > +
> > > > +**/
> > > > +typedef
> > > > +EFI_STATUS
> > > > +(EFIAPI *EFI_REST_EX_EVENT_SERVICE)(
> > > > +  IN      EFI_REST_EX_PROTOCOL   *This,
> > > > +  IN      EFI_HTTP_MESSAGE       *RequestMessage OPTIONAL,
> > > > +  IN      EFI_REST_EX_TOKEN      *RestExToken
> > > > +);
> > > > +
> > > > +///
> > > > +/// EFI REST(EX) protocols are designed to support REST
> > > > +communication
> > > > between EFI REST client
> > > > +/// applications/drivers and REST services. EFI REST client tool
> > > > +uses
> > EFI
> > > > REST(EX) protocols
> > > > +/// to send/receive resources to/from REST service to manage
> > > > +systems,
> > > > configure systems or
> > > > +/// manipulate resources on REST service. Due to HTTP protocol is
> > > > commonly used to communicate
> > > > +/// with REST service in practice, EFI REST(EX) protocols adopt
> > > > +HTTP as
> > the
> > > > message format to
> > > > +/// send and receive REST service resource. EFI REST(EX) driver
> > instance
> > > > abstracts EFI REST
> > > > +/// client functionality and provides underlying interface to
> > communicate
> > > > with REST service.
> > > > +/// EFI REST(EX) driver instance knows how to communicate with
> > > > +REST
> > > > service through certain
> > > > +/// interface after the corresponding configuration is initialized.
> > > > +///
> > > > +struct _EFI_REST_EX_PROTOCOL {
> > > > +  EFI_REST_SEND_RECEIVE          SendReceive;
> > > > +  EFI_REST_GET_TIME              GetServiceTime;
> > > > +  EFI_REST_EX_GET_SERVICE        GetService;
> > > > +  EFI_REST_EX_GET_MODE_DATA      GetModeData;
> > > > +  EFI_REST_EX_CONFIGURE          Configure;
> > > > +  EFI_REST_EX_ASYNC_SEND_RECEIVE AyncSendReceive;
> > > > +  EFI_REST_EX_EVENT_SERVICE      EventService;
> > > > +};
> > > > +
> > > > +extern EFI_GUID gEfiRestExServiceBindingProtocolGuid;
> > > > +extern EFI_GUID gEfiRestExProtocolGuid;
> > > > +
> > > > +#endif
> > > > diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec index
> > > > 812be75fb3..5205374d62 100644
> > > > --- a/MdePkg/MdePkg.dec
> > > > +++ b/MdePkg/MdePkg.dec
> > > > @@ -1848,6 +1848,13 @@
> > > >    ## Include/Protocol/NvdimmLabel.h
> > > >    gEfiNvdimmLabelProtocolGuid               = { 0xd40b6b80,
> > > 0x97d5, 0x4282,
> > > > { 0xbb, 0x1d, 0x22, 0x3a, 0x16, 0x91, 0x80, 0x58 }}
> > > >
> > > > +  #
> > > > +  # Protocols defined in UEFI2.8
> > > > +  #
> > > > +  ## Include/Protocol/RestEx.h
> > > > +  gEfiRestExProtocolGuid               = { 0x55648b91, 0xe7d,
> > > 0x40a3, { 0xa9, 0xb3,
> > > > 0xa8, 0x15, 0xd7, 0xea, 0xdf, 0x97 }}
> > > > +  gEfiRestExServiceBindingProtocolGuid = { 0x456bbe01, 0x99d0,
> > > > + 0x45ea,
> > > > { 0xbb, 0x5f, 0x16, 0xd8, 0x4b, 0xed, 0xc5, 0x59 }}
> > > > +
> > > >    #
> > > >    # Protocols defined in Shell2.0
> > > >    #
> > > > --
> > > > 2.17.1
> > > >
> > > >
> > > >
> > > >
> > > >
> >
> >
> >
> >
> >
> >
> >
> 
> 
> 
> 
> 

[Rest Ex Definition PATCH 2/2] RedfishPkg/Include: PCD definitions of Host Interface EFI device path

[Abner Chang]

The definitions of Host Interface EFI device path structure PCD.

Signed-off-by: Jiaxin Wu <jiaxin.wu@intel.com>
Signed-off-by: Siyuan Fu <siyuan.fu@intel.com>
Signed-off-by: Fan Wang <fan.wang@intel.com>
Signed-off-by: Abner Chang <abner.chang@hpe.com>

Cc: Jiewen Yao <jiewen.yao@intel.com>
Cc: Nickle Wang <nickle.wang@hpe.com>
---
 .../Include/Pcd/RestExServiceDevicePath.h     | 38 +++++++++++++++++++
 RedfishPkg/RedfishPkg.dec                     |  3 ++
 2 files changed, 41 insertions(+)
 create mode 100644 RedfishPkg/Include/Pcd/RestExServiceDevicePath.h

diff --git a/RedfishPkg/Include/Pcd/RestExServiceDevicePath.h b/RedfishPkg/Include/Pcd/RestExServiceDevicePath.h
new file mode 100644
index 0000000000..89de3b1a21
--- /dev/null
+++ b/RedfishPkg/Include/Pcd/RestExServiceDevicePath.h
@@ -0,0 +1,38 @@
+/** @file
+  This library defines the UEFI device path data of network device for REST
+  service to decide which should be used as the Redfish host interface.
+
+  Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
+  (C) Copyright 2020 Hewlett Packard Enterprise Development LP<BR>
+
+    SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#ifndef REST_EX_SERVICE_DEVICE_PATH_H_
+#define REST_EX_SERVICE_DEVICE_PATH_H_
+
+#include <Protocol/DevicePath.h>
+
+typedef enum {
+  DEVICE_PATH_MATCH_MAC_NODE = 1,
+  DEVICE_PATH_MATCH_PCI_NODE = 2,
+  DEVICE_PATH_MATCH_MODE_MAX
+} DEVICE_PATH_MATCH_MODE;
+
+typedef struct {
+  UINT32 DevicePathMatchMode;
+  UINT32 DevicePathNum;
+  //
+  // Example:
+  //   {DEVICE_PATH("PciRoot(0)/Pci(0,0)/MAC(005056C00002,0x1)")}
+  // DevicePath will be parsed as below:
+  //   {0x02,0x01,0x0c,0x00,0xd0,0x41,0x03,0x0a,0x00,0x00,0x00,0x00,
+  //    0x01,0x01,0x06,0x00,0x00,0x00,
+  //    0x03,0x0b,0x25,0x00,0x00,0x50,0x56,0xc0,0x00,0x02,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x01,
+  //    0x7f,0xff,0x04,0x00}
+  //
+  EFI_DEVICE_PATH_PROTOCOL      DevicePath[];
+} REST_EX_SERVICE_DEVICE_PATH_DATA;
+
+#endif
diff --git a/RedfishPkg/RedfishPkg.dec b/RedfishPkg/RedfishPkg.dec
index e95ec5fe10..de3611252e 100644
--- a/RedfishPkg/RedfishPkg.dec
+++ b/RedfishPkg/RedfishPkg.dec
@@ -13,6 +13,9 @@
   PACKAGE_GUID      = c432b76e-5232-11e7-9010-005056c00008
   PACKAGE_VERSION   = 1.0
 
+[Includes]
+  Include
+
 [Guids]
   gEfiRedfishPkgTokenSpaceGuid      = { 0x4fdbccb7, 0xe829, 0x4b4c, { 0x88, 0x87, 0xb2, 0x3f, 0xd7, 0x25, 0x4b, 0x85 }}
 
-- 
2.17.1

Re: [Rest Ex Definition PATCH 2/2] RedfishPkg/Include: PCD definitions of Host Interface EFI device path

[Nickle Wang]

Reviewed-by: Nickle Wang <nickle.wang@hpe.com>

-----Original Message-----
From: Chang, Abner (HPS SW/FW Technologist) <abner.chang@hpe.com> 
Sent: Monday, October 12, 2020 3:04 PM
To: devel@edk2.groups.io
Cc: Jiewen Yao <jiewen.yao@intel.com>; Wang, Nickle (HPS SW) <nickle.wang@hpe.com>
Subject: [Rest Ex Definition PATCH 2/2] RedfishPkg/Include: PCD definitions of Host Interface EFI device path

The definitions of Host Interface EFI device path structure PCD.

Signed-off-by: Jiaxin Wu <jiaxin.wu@intel.com>
Signed-off-by: Siyuan Fu <siyuan.fu@intel.com>
Signed-off-by: Fan Wang <fan.wang@intel.com>
Signed-off-by: Abner Chang <abner.chang@hpe.com>

Cc: Jiewen Yao <jiewen.yao@intel.com>
Cc: Nickle Wang <nickle.wang@hpe.com>
---
 .../Include/Pcd/RestExServiceDevicePath.h     | 38 +++++++++++++++++++
 RedfishPkg/RedfishPkg.dec                     |  3 ++
 2 files changed, 41 insertions(+)
 create mode 100644 RedfishPkg/Include/Pcd/RestExServiceDevicePath.h

diff --git a/RedfishPkg/Include/Pcd/RestExServiceDevicePath.h b/RedfishPkg/Include/Pcd/RestExServiceDevicePath.h
new file mode 100644
index 0000000000..89de3b1a21
--- /dev/null
+++ b/RedfishPkg/Include/Pcd/RestExServiceDevicePath.h
@@ -0,0 +1,38 @@
+/** @file
+  This library defines the UEFI device path data of network device for 
+REST
+  service to decide which should be used as the Redfish host interface.
+
+  Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
+  (C) Copyright 2020 Hewlett Packard Enterprise Development LP<BR>
+
+    SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#ifndef REST_EX_SERVICE_DEVICE_PATH_H_
+#define REST_EX_SERVICE_DEVICE_PATH_H_
+
+#include <Protocol/DevicePath.h>
+
+typedef enum {
+  DEVICE_PATH_MATCH_MAC_NODE = 1,
+  DEVICE_PATH_MATCH_PCI_NODE = 2,
+  DEVICE_PATH_MATCH_MODE_MAX
+} DEVICE_PATH_MATCH_MODE;
+
+typedef struct {
+  UINT32 DevicePathMatchMode;
+  UINT32 DevicePathNum;
+  //
+  // Example:
+  //   {DEVICE_PATH("PciRoot(0)/Pci(0,0)/MAC(005056C00002,0x1)")}
+  // DevicePath will be parsed as below:
+  //   {0x02,0x01,0x0c,0x00,0xd0,0x41,0x03,0x0a,0x00,0x00,0x00,0x00,
+  //    0x01,0x01,0x06,0x00,0x00,0x00,
+  //    0x03,0x0b,0x25,0x00,0x00,0x50,0x56,0xc0,0x00,0x02,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x01,
+  //    0x7f,0xff,0x04,0x00}
+  //
+  EFI_DEVICE_PATH_PROTOCOL      DevicePath[];
+} REST_EX_SERVICE_DEVICE_PATH_DATA;
+
+#endif
diff --git a/RedfishPkg/RedfishPkg.dec b/RedfishPkg/RedfishPkg.dec index e95ec5fe10..de3611252e 100644
--- a/RedfishPkg/RedfishPkg.dec
+++ b/RedfishPkg/RedfishPkg.dec
@@ -13,6 +13,9 @@
   PACKAGE_GUID      = c432b76e-5232-11e7-9010-005056c00008
   PACKAGE_VERSION   = 1.0
 
+[Includes]
+  Include
+
 [Guids]
   gEfiRedfishPkgTokenSpaceGuid      = { 0x4fdbccb7, 0xe829, 0x4b4c, { 0x88, 0x87, 0xb2, 0x3f, 0xd7, 0x25, 0x4b, 0x85 }}
 
--
2.17.1

Re: [edk2-devel] [Rest Ex Definition PATCH 2/2] RedfishPkg/Include: PCD definitions of Host Interface EFI device path

[Wu, Jiaxin]

Reviewed-by: Jiaxin Wu <jiaxin.wu@intel.com>



> -----Original Message-----
> From: devel@edk2.groups.io <devel@edk2.groups.io> On Behalf Of Abner
> Chang
> Sent: Monday, October 12, 2020 3:04 PM
> To: devel@edk2.groups.io
> Cc: Yao, Jiewen <jiewen.yao@intel.com>; Nickle Wang
> <nickle.wang@hpe.com>
> Subject: [edk2-devel] [Rest Ex Definition PATCH 2/2] RedfishPkg/Include:
> PCD definitions of Host Interface EFI device path
> 
> The definitions of Host Interface EFI device path structure PCD.
> 
> Signed-off-by: Jiaxin Wu <jiaxin.wu@intel.com>
> Signed-off-by: Siyuan Fu <siyuan.fu@intel.com>
> Signed-off-by: Fan Wang <fan.wang@intel.com>
> Signed-off-by: Abner Chang <abner.chang@hpe.com>
> 
> Cc: Jiewen Yao <jiewen.yao@intel.com>
> Cc: Nickle Wang <nickle.wang@hpe.com>
> ---
>  .../Include/Pcd/RestExServiceDevicePath.h     | 38 +++++++++++++++++++
>  RedfishPkg/RedfishPkg.dec                     |  3 ++
>  2 files changed, 41 insertions(+)
>  create mode 100644 RedfishPkg/Include/Pcd/RestExServiceDevicePath.h
> 
> diff --git a/RedfishPkg/Include/Pcd/RestExServiceDevicePath.h
> b/RedfishPkg/Include/Pcd/RestExServiceDevicePath.h
> new file mode 100644
> index 0000000000..89de3b1a21
> --- /dev/null
> +++ b/RedfishPkg/Include/Pcd/RestExServiceDevicePath.h
> @@ -0,0 +1,38 @@
> +/** @file
> +  This library defines the UEFI device path data of network device for REST
> +  service to decide which should be used as the Redfish host interface.
> +
> +  Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
> +  (C) Copyright 2020 Hewlett Packard Enterprise Development LP<BR>
> +
> +    SPDX-License-Identifier: BSD-2-Clause-Patent
> +
> +**/
> +
> +#ifndef REST_EX_SERVICE_DEVICE_PATH_H_
> +#define REST_EX_SERVICE_DEVICE_PATH_H_
> +
> +#include <Protocol/DevicePath.h>
> +
> +typedef enum {
> +  DEVICE_PATH_MATCH_MAC_NODE = 1,
> +  DEVICE_PATH_MATCH_PCI_NODE = 2,
> +  DEVICE_PATH_MATCH_MODE_MAX
> +} DEVICE_PATH_MATCH_MODE;
> +
> +typedef struct {
> +  UINT32 DevicePathMatchMode;
> +  UINT32 DevicePathNum;
> +  //
> +  // Example:
> +  //   {DEVICE_PATH("PciRoot(0)/Pci(0,0)/MAC(005056C00002,0x1)")}
> +  // DevicePath will be parsed as below:
> +  //   {0x02,0x01,0x0c,0x00,0xd0,0x41,0x03,0x0a,0x00,0x00,0x00,0x00,
> +  //    0x01,0x01,0x06,0x00,0x00,0x00,
> +  //
> 0x03,0x0b,0x25,0x00,0x00,0x50,0x56,0xc0,0x00,0x02,0x00,0x00,0x00,0x00,0x0
> 0,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0
> x00,0x00,0x00,0x00,0x00,0x00,0x00,0x01,
> +  //    0x7f,0xff,0x04,0x00}
> +  //
> +  EFI_DEVICE_PATH_PROTOCOL      DevicePath[];
> +} REST_EX_SERVICE_DEVICE_PATH_DATA;
> +
> +#endif
> diff --git a/RedfishPkg/RedfishPkg.dec b/RedfishPkg/RedfishPkg.dec
> index e95ec5fe10..de3611252e 100644
> --- a/RedfishPkg/RedfishPkg.dec
> +++ b/RedfishPkg/RedfishPkg.dec
> @@ -13,6 +13,9 @@
>    PACKAGE_GUID      = c432b76e-5232-11e7-9010-005056c00008
>    PACKAGE_VERSION   = 1.0
> 
> +[Includes]
> +  Include
> +
>  [Guids]
>    gEfiRedfishPkgTokenSpaceGuid      = { 0x4fdbccb7, 0xe829, 0x4b4c, { 0x88,
> 0x87, 0xb2, 0x3f, 0xd7, 0x25, 0x4b, 0x85 }}
> 
> --
> 2.17.1
> 
> 
> 
> 
>