* [Rest Ex Definition PATCH 0/2] The definitions for EFI REST EX @ 2020-10-12 7:04 Abner Chang 2020-10-12 7:04 ` [Rest Ex Definition PATCH 1/2] MdePkg/Include: Definitions of EFI REST EX Protocol Abner Chang 2020-10-12 7:04 ` [Rest Ex Definition PATCH 2/2] RedfishPkg/Include: PCD definitions of Host Interface EFI device path Abner Chang 0 siblings, 2 replies; 9+ messages in thread From: Abner Chang @ 2020-10-12 7:04 UTC (permalink / raw) To: devel Cc: Jiaxin Wu, Siyuan Fu, Fan Wang, Jiewen Yao, Nickle Wang, Michael D Kinney, Liming Gao, Zhiguang Liu 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 ^ permalink raw reply [flat|nested] 9+ messages in thread
* [Rest Ex Definition PATCH 1/2] MdePkg/Include: Definitions of EFI REST EX Protocol 2020-10-12 7:04 [Rest Ex Definition PATCH 0/2] The definitions for EFI REST EX Abner Chang @ 2020-10-12 7:04 ` Abner Chang 2020-10-12 8:53 ` [edk2-devel] " Wu, Jiaxin 2020-10-12 7:04 ` [Rest Ex Definition PATCH 2/2] RedfishPkg/Include: PCD definitions of Host Interface EFI device path Abner Chang 1 sibling, 1 reply; 9+ messages in thread From: Abner Chang @ 2020-10-12 7:04 UTC (permalink / raw) To: devel; +Cc: Michael D Kinney, Liming Gao, Zhiguang Liu, Jiewen Yao, Nickle Wang 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 ^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [edk2-devel] [Rest Ex Definition PATCH 1/2] MdePkg/Include: Definitions of EFI REST EX Protocol 2020-10-12 7:04 ` [Rest Ex Definition PATCH 1/2] MdePkg/Include: Definitions of EFI REST EX Protocol Abner Chang @ 2020-10-12 8:53 ` Wu, Jiaxin 2020-10-14 5:36 ` 回复: " gaoliming 0 siblings, 1 reply; 9+ messages in thread From: Wu, Jiaxin @ 2020-10-12 8:53 UTC (permalink / raw) To: devel@edk2.groups.io, abner.chang@hpe.com Cc: Kinney, Michael D, Liming Gao, Liu, Zhiguang, Yao, Jiewen, Nickle Wang 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 > > > > > ^ permalink raw reply [flat|nested] 9+ messages in thread
* 回复: [edk2-devel] [Rest Ex Definition PATCH 1/2] MdePkg/Include: Definitions of EFI REST EX Protocol 2020-10-12 8:53 ` [edk2-devel] " Wu, Jiaxin @ 2020-10-14 5:36 ` gaoliming 2020-10-14 11:38 ` Abner Chang [not found] ` <163DD8E0887FF220.5123@groups.io> 0 siblings, 2 replies; 9+ messages in thread From: gaoliming @ 2020-10-14 5:36 UTC (permalink / raw) To: 'Wu, Jiaxin', devel, abner.chang Cc: 'Kinney, Michael D', 'Liu, Zhiguang', 'Yao, Jiewen', 'Nickle Wang' 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 > > > > > > > > > > ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [edk2-devel] [Rest Ex Definition PATCH 1/2] MdePkg/Include: Definitions of EFI REST EX Protocol 2020-10-14 5:36 ` 回复: " gaoliming @ 2020-10-14 11:38 ` Abner Chang [not found] ` <163DD8E0887FF220.5123@groups.io> 1 sibling, 0 replies; 9+ messages in thread From: Abner Chang @ 2020-10-14 11:38 UTC (permalink / raw) To: devel@edk2.groups.io, gaoliming@byosoft.com.cn, 'Wu, Jiaxin' Cc: 'Kinney, Michael D', 'Liu, Zhiguang', 'Yao, Jiewen', Wang, Nickle (HPS SW) 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 > > > > > > > > > > > > > > > > > > > > > > ^ permalink raw reply [flat|nested] 9+ messages in thread
[parent not found: <163DD8E0887FF220.5123@groups.io>]
* Re: [edk2-devel] [Rest Ex Definition PATCH 1/2] MdePkg/Include: Definitions of EFI REST EX Protocol [not found] ` <163DD8E0887FF220.5123@groups.io> @ 2020-10-15 1:12 ` Abner Chang 0 siblings, 0 replies; 9+ messages in thread From: Abner Chang @ 2020-10-15 1:12 UTC (permalink / raw) To: devel@edk2.groups.io, Chang, Abner (HPS SW/FW Technologist), gaoliming@byosoft.com.cn, 'Wu, Jiaxin' Cc: 'Kinney, Michael D', 'Liu, Zhiguang', 'Yao, Jiewen', Wang, Nickle (HPS SW) 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 > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > ^ permalink raw reply [flat|nested] 9+ messages in thread
* [Rest Ex Definition PATCH 2/2] RedfishPkg/Include: PCD definitions of Host Interface EFI device path 2020-10-12 7:04 [Rest Ex Definition PATCH 0/2] The definitions for EFI REST EX Abner Chang 2020-10-12 7:04 ` [Rest Ex Definition PATCH 1/2] MdePkg/Include: Definitions of EFI REST EX Protocol Abner Chang @ 2020-10-12 7:04 ` Abner Chang 2020-10-12 8:15 ` Nickle Wang 2020-10-12 8:54 ` [edk2-devel] " Wu, Jiaxin 1 sibling, 2 replies; 9+ messages in thread From: Abner Chang @ 2020-10-12 7:04 UTC (permalink / raw) To: devel; +Cc: Jiewen Yao, Nickle Wang 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 ^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [Rest Ex Definition PATCH 2/2] RedfishPkg/Include: PCD definitions of Host Interface EFI device path 2020-10-12 7:04 ` [Rest Ex Definition PATCH 2/2] RedfishPkg/Include: PCD definitions of Host Interface EFI device path Abner Chang @ 2020-10-12 8:15 ` Nickle Wang 2020-10-12 8:54 ` [edk2-devel] " Wu, Jiaxin 1 sibling, 0 replies; 9+ messages in thread From: Nickle Wang @ 2020-10-12 8:15 UTC (permalink / raw) To: Chang, Abner (HPS SW/FW Technologist), devel@edk2.groups.io; +Cc: Jiewen Yao 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 ^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [edk2-devel] [Rest Ex Definition PATCH 2/2] RedfishPkg/Include: PCD definitions of Host Interface EFI device path 2020-10-12 7:04 ` [Rest Ex Definition PATCH 2/2] RedfishPkg/Include: PCD definitions of Host Interface EFI device path Abner Chang 2020-10-12 8:15 ` Nickle Wang @ 2020-10-12 8:54 ` Wu, Jiaxin 1 sibling, 0 replies; 9+ messages in thread From: Wu, Jiaxin @ 2020-10-12 8:54 UTC (permalink / raw) To: devel@edk2.groups.io, abner.chang@hpe.com; +Cc: Yao, Jiewen, Nickle Wang 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 > > > > > ^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2020-10-15 1:13 UTC | newest] Thread overview: 9+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2020-10-12 7:04 [Rest Ex Definition PATCH 0/2] The definitions for EFI REST EX Abner Chang 2020-10-12 7:04 ` [Rest Ex Definition PATCH 1/2] MdePkg/Include: Definitions of EFI REST EX Protocol Abner Chang 2020-10-12 8:53 ` [edk2-devel] " Wu, Jiaxin 2020-10-14 5:36 ` 回复: " gaoliming 2020-10-14 11:38 ` Abner Chang [not found] ` <163DD8E0887FF220.5123@groups.io> 2020-10-15 1:12 ` Abner Chang 2020-10-12 7:04 ` [Rest Ex Definition PATCH 2/2] RedfishPkg/Include: PCD definitions of Host Interface EFI device path Abner Chang 2020-10-12 8:15 ` Nickle Wang 2020-10-12 8:54 ` [edk2-devel] " Wu, Jiaxin
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox