Re: [edk2-devel] [PATCH v2 1/6] RedfishPkg: introduce Redfish HTTP protocol

["Igor Kulchytskyy via groups.io" <igork=ami.com@groups.io>]

Reviewed-by: Igor Kulchytskyy <igork@ami.com>

-----Original Message-----
From: Nickle Wang <nicklew@nvidia.com>
Sent: Thursday, February 22, 2024 4:11 AM
To: devel@edk2.groups.io
Cc: Igor Kulchytskyy <igork@ami.com>; Abner Chang <abner.chang@amd.com>; Nick Ramirez <nramirez@nvidia.com>
Subject: [EXTERNAL] [PATCH v2 1/6] RedfishPkg: introduce Redfish HTTP protocol


**CAUTION: The e-mail below is from an external source. Please exercise caution before opening attachments, clicking links, or following guidance.**

Introduce Redfish HTTP protocol to improve Redfish performance
and communication stability between BIOS and Redfish service.
- Feature drivers often query same Redfish resource multiple
times for different purpose. Implement HTTP cache mechanism to
improve HTTP GET performance. "UseCache" parameter is provided
if application likes to send HTTP GET request to Redfish service
without using cache data.
- This driver will retire stale cache data automatically when
application modify Redfish resource at service side.
- PCD PcdHttpCacheDisabled is used to disable cache mechanism in
this driver for debugging purpose.
- PCD PcdRedfishServiceContentEncoding is used to enable content
encoding while sending data to Redfish service.
- Redfish HTTP protocol also implement retry mechanism to retry
HTTP request when BIOS receive unexpected response from Redfish service.
This function helps BIOS Redfish to finish its job as much as possible.
- PCDs are defined to control how many times BIOS will retry the
request and how many time BIOS will wait between retries.

Signed-off-by: Nickle Wang <nicklew@nvidia.com>
Co-authored-by: Igor Kulchytskyy <igork@ami.com>
Cc: Abner Chang <abner.chang@amd.com>
Cc: Igor Kulchytskyy <igork@ami.com>
Cc: Nick Ramirez <nramirez@nvidia.com>
Reviewed-by: Abner Chang <abner.chang@amd.com>
---
 RedfishPkg/RedfishPkg.dec                     |  24 +-
 .../Protocol/EdkIIRedfishHttpProtocol.h       | 308 ++++++++++++++++++
 RedfishPkg/Include/RedfishServiceData.h       |  43 +++
 3 files changed, 374 insertions(+), 1 deletion(-)
 create mode 100644 RedfishPkg/Include/Protocol/EdkIIRedfishHttpProtocol.h
 create mode 100644 RedfishPkg/Include/RedfishServiceData.h

diff --git a/RedfishPkg/RedfishPkg.dec b/RedfishPkg/RedfishPkg.dec
index 3ea9ff3ef7..9b424efdf3 100644
--- a/RedfishPkg/RedfishPkg.dec
+++ b/RedfishPkg/RedfishPkg.dec
@@ -4,7 +4,7 @@
 # Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
 # (C) Copyright 2021 Hewlett Packard Enterprise Development LP<BR>
 # Copyright (c) 2023, American Megatrends International LLC.
-# Copyright (c) 2023, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# Copyright (c) 2023-2024, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 #
 # SPDX-License-Identifier: BSD-2-Clause-Patent
 ##
@@ -93,6 +93,9 @@
   # Redfish Host Interface ready notification protocol
   gEdkIIRedfishHostInterfaceReadyProtocolGuid = { 0xC3F6D062, 0x3D38, 0x4EA4, { 0x92, 0xB1, 0xE8, 0xF8, 0x02, 0x27, 0x63, 0xDF } }

+  ## Include/Protocol/EdkIIRedfishHttpProtocol.h
+  gEdkIIRedfishHttpProtocolGuid = { 0x58a0f47e, 0xf45f, 0x4d44, { 0x89, 0x5b, 0x2a, 0xfe, 0xb0, 0x80, 0x15, 0xe2 } }
+
 [Guids]
   gEfiRedfishPkgTokenSpaceGuid      = { 0x4fdbccb7, 0xe829, 0x4b4c, { 0x88, 0x87, 0xb2, 0x3f, 0xd7, 0x25, 0x4b, 0x85 }}

@@ -154,3 +157,22 @@
   # set to EFI_REST_EX_PROTOCOL.
   #
   gEfiRedfishPkgTokenSpaceGuid.PcdRedfishSendReceiveTimeout|5000|UINT32|0x00001009
+  ## This is used to enable HTTP content encoding on Redfish communication.
+  gEfiRedfishPkgTokenSpaceGuid.PcdRedfishServiceContentEncoding|TRUE|BOOLEAN|0x0000100A
+  #
+  # Use below PCDs to control Redfhs HTTP protocol.
+  #
+  ## The number of retry when HTTP GET request failed. If the value is 0, there is no retry enabled.
+  gEfiRedfishPkgTokenSpaceGuid.PcdHttpGetRetry|0|UINT16|0x0000100B
+  ## The number of retry when HTTP PUT request failed. If the value is 0, there is no retry enabled.
+  gEfiRedfishPkgTokenSpaceGuid.PcdHttpPutRetry|0|UINT16|0x0000100C
+  ## The number of retry when HTTP PATCH request failed. If the value is 0, there is no retry enabled.
+  gEfiRedfishPkgTokenSpaceGuid.PcdHttpPatchRetry|0|UINT16|0x0000100D
+  ## The number of retry when HTTP POST request failed. If the value is 0, there is no retry enabled.
+  gEfiRedfishPkgTokenSpaceGuid.PcdHttpPostRetry|0|UINT16|0x0000100E
+  ## The number of retry when HTTP DELETE request failed. If the value is 0, there is no retry enabled.
+  gEfiRedfishPkgTokenSpaceGuid.PcdHttpDeleteRetry|0|UINT16|0x0000100F
+  ## The number of second to wait before driver retry HTTP request. If the value is 0, there is no wait before next retry.
+  gEfiRedfishPkgTokenSpaceGuid.PcdHttpRetryWaitInSecond|1|UINT16|0x00001010
+  ## This is used to disable Redfish HTTP cache function and every request will be sent to Redfish service.
+  gEfiRedfishPkgTokenSpaceGuid.PcdHttpCacheDisabled|FALSE|BOOLEAN|0x00001011
diff --git a/RedfishPkg/Include/Protocol/EdkIIRedfishHttpProtocol.h b/RedfishPkg/Include/Protocol/EdkIIRedfishHttpProtocol.h
new file mode 100644
index 0000000000..fef365730d
--- /dev/null
+++ b/RedfishPkg/Include/Protocol/EdkIIRedfishHttpProtocol.h
@@ -0,0 +1,308 @@
+/** @file
+  This file defines the EDKII_REDFISH_HTTP_PROTOCOL interface.
+
+  Copyright (c) 2023-2024, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#ifndef EDKII_REDFISH_HTTP_PROTOCOL_H_
+#define EDKII_REDFISH_HTTP_PROTOCOL_H_
+
+#include <RedfishServiceData.h>
+#include <Library/JsonLib.h>
+#include <Protocol/EdkIIRedfishConfigHandler.h>
+
+typedef struct _EDKII_REDFISH_HTTP_PROTOCOL EDKII_REDFISH_HTTP_PROTOCOL;
+
+/**
+  This function create Redfish service. It's caller's responsibility to free returned
+  Redfish service by calling FreeService ().
+
+  @param[in]  This                       Pointer to EDKII_REDFISH_HTTP_PROTOCOL instance.
+  @param[in]  RedfishConfigServiceInfo   Redfish config service information.
+
+  @retval     REDFISH_SERVICE  Redfish service is created.
+  @retval     NULL             Errors occur.
+
+**/
+typedef
+REDFISH_SERVICE
+(EFIAPI *REDFISH_HTTP_CREATE_SERVICE)(
+  IN  EDKII_REDFISH_HTTP_PROTOCOL         *This,
+  IN  REDFISH_CONFIG_SERVICE_INFORMATION  *RedfishConfigServiceInfo
+  );
+
+/**
+  This function free resources in Redfish service. RedfishService is no longer available
+  after this function returns successfully.
+
+  @param[in]  This            Pointer to EDKII_REDFISH_HTTP_PROTOCOL instance.
+  @param[in]  RedfishService  Pointer to Redfish service to be released.
+
+  @retval     EFI_SUCCESS     Resrouce is released successfully.
+  @retval     Others          Errors occur.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *REDFISH_HTTP_FREE_SERVICE)(
+  IN  EDKII_REDFISH_HTTP_PROTOCOL         *This,
+  IN  REDFISH_SERVICE                     RedfishService
+  );
+
+/**
+  This function returns JSON value in given RedfishPayload. Returned JSON value
+  is a reference to the JSON value in RedfishPayload. Any modification to returned
+  JSON value will change JSON value in RedfishPayload.
+
+  @param[in]  This            Pointer to EDKII_REDFISH_HTTP_PROTOCOL instance.
+  @param[in]  RedfishPayload  Pointer to Redfish payload.
+
+  @retval     EDKII_JSON_VALUE   JSON value is returned.
+  @retval     NULL               Errors occur.
+
+**/
+typedef
+EDKII_JSON_VALUE
+(EFIAPI *REDFISH_HTTP_JSON_IN_PAYLOAD)(
+  IN  EDKII_REDFISH_HTTP_PROTOCOL         *This,
+  IN  REDFISH_PAYLOAD                     RedfishPayload
+  );
+
+/**
+  This function free resources in Request. Request is no longer available
+  after this function returns successfully.
+
+  @param[in]  This         Pointer to EDKII_REDFISH_HTTP_PROTOCOL instance.
+  @param[in]  Request      HTTP request to be released.
+
+  @retval     EFI_SUCCESS     Resrouce is released successfully.
+  @retval     Others          Errors occur.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *REDFISH_HTTP_FREE_REQUEST)(
+  IN  EDKII_REDFISH_HTTP_PROTOCOL *This,
+  IN  REDFISH_REQUEST             *Request
+  );
+
+/**
+  This function free resources in Response. Response is no longer available
+  after this function returns successfully.
+
+  @param[in]  This         Pointer to EDKII_REDFISH_HTTP_PROTOCOL instance.
+  @param[in]  Response     HTTP response to be released.
+
+  @retval     EFI_SUCCESS     Resrouce is released successfully.
+  @retval     Others          Errors occur.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *REDFISH_HTTP_FREE_RESPONSE)(
+  IN  EDKII_REDFISH_HTTP_PROTOCOL *This,
+  IN  REDFISH_RESPONSE            *Response
+  );
+
+/**
+  This function expire the cached response of given URI.
+
+  @param[in]  This         Pointer to EDKII_REDFISH_HTTP_PROTOCOL instance.
+  @param[in]  Uri          Target response of URI.
+
+  @retval     EFI_SUCCESS     Target response is expired successfully.
+  @retval     Others          Errors occur.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *REDFISH_HTTP_EXPIRE_RESPONSE)(
+  IN  EDKII_REDFISH_HTTP_PROTOCOL *This,
+  IN  EFI_STRING                  Uri
+  );
+
+/**
+  Perform HTTP GET to Get redfish resource from given resource URI with
+  cache mechanism supported. It's caller's responsibility to free Response
+  by calling FreeResponse ().
+
+  @param[in]  This          Pointer to EDKII_REDFISH_HTTP_PROTOCOL instance.
+  @param[in]  Service       Redfish service instance to perform HTTP GET.
+  @param[in]  Uri           Target resource URI.
+  @param[in]  Request       Additional request context. This is optional.
+  @param[out] Response      HTTP response from redfish service.
+  @param[in]  UseCache      If it is TRUE, this function will search for
+                            cache first. If it is FALSE, this function
+                            will query Redfish URI directly.
+
+  @retval     EFI_SUCCESS     Resrouce is returned successfully.
+  @retval     Others          Errors occur.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *REDFISH_HTTP_GET_RESOURCE)(
+  IN  EDKII_REDFISH_HTTP_PROTOCOL *This,
+  IN  REDFISH_SERVICE             Service,
+  IN  EFI_STRING                  Uri,
+  IN  REDFISH_REQUEST             *Request OPTIONAL,
+  OUT REDFISH_RESPONSE            *Response,
+  IN  BOOLEAN                     UseCache
+  );
+
+/**
+  Perform HTTP PATCH to send redfish resource to given resource URI.
+  It's caller's responsibility to free Response by calling FreeResponse ().
+
+  @param[in]  This          Pointer to EDKII_REDFISH_HTTP_PROTOCOL instance.
+  @param[in]  Service       Redfish service instance to perform HTTP PATCH.
+  @param[in]  Uri           Target resource URI.
+  @param[in]  Content       Data to patch.
+  @param[in]  ContentSize   Size of the Content to be send to Redfish service.
+                            This is optional. When ContentSize is 0, ContentSize
+                            is the size of Content.
+  @param[in]  ContentType   Type of the Content to be send to Redfish service.
+                            This is optional. When ContentType is NULL, content
+                            type HTTP_CONTENT_TYPE_APP_JSON will be used.
+  @param[out] Response      HTTP response from redfish service.
+
+  @retval     EFI_SUCCESS     Resrouce is returned successfully.
+  @retval     Others          Errors occur.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *REDFISH_HTTP_PATCH_RESOURCE)(
+  IN  EDKII_REDFISH_HTTP_PROTOCOL  *This,
+  IN  REDFISH_SERVICE              Service,
+  IN  EFI_STRING                   Uri,
+  IN  CHAR8                        *Content,
+  IN  UINTN                        ContentSize OPTIONAL,
+  IN  CHAR8                        *ContentType OPTIONAL,
+  OUT REDFISH_RESPONSE             *Response
+  );
+
+/**
+  Perform HTTP PUT to send redfish resource to given resource URI.
+  It's caller's responsibility to free Response by calling FreeResponse ().
+
+  @param[in]  This          Pointer to EDKII_REDFISH_HTTP_PROTOCOL instance.
+  @param[in]  Service       Redfish service instance to perform HTTP PUT.
+  @param[in]  Uri           Target resource URI.
+  @param[in]  Content       Data to put.
+  @param[in]  ContentSize   Size of the Content to be send to Redfish service.
+                            This is optional. When ContentSize is 0, ContentSize
+                            is the size of Content.
+  @param[in]  ContentType   Type of the Content to be send to Redfish service.
+                            This is optional. When ContentType is NULL, content
+                            type HTTP_CONTENT_TYPE_APP_JSON will be used.
+  @param[out] Response      HTTP response from redfish service.
+
+  @retval     EFI_SUCCESS     Resrouce is returned successfully.
+  @retval     Others          Errors occur.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *REDFISH_HTTP_PUT_RESOURCE)(
+  IN  EDKII_REDFISH_HTTP_PROTOCOL  *This,
+  IN  REDFISH_SERVICE              Service,
+  IN  EFI_STRING                   Uri,
+  IN  CHAR8                        *Content,
+  IN  UINTN                        ContentSize OPTIONAL,
+  IN  CHAR8                        *ContentType OPTIONAL,
+  OUT REDFISH_RESPONSE             *Response
+  );
+
+/**
+  Perform HTTP POST to send redfish resource to given resource URI.
+  It's caller's responsibility to free Response by calling FreeResponse ().
+
+  @param[in]  This          Pointer to EDKII_REDFISH_HTTP_PROTOCOL instance.
+  @param[in]  Service       Redfish service instance to perform HTTP POST.
+  @param[in]  Uri           Target resource URI.
+  @param[in]  Content       Data to post.
+  @param[in]  ContentSize   Size of the Content to be send to Redfish service.
+                            This is optional. When ContentSize is 0, ContentSize
+                            is the size of Content.
+  @param[in]  ContentType   Type of the Content to be send to Redfish service.
+                            This is optional. When ContentType is NULL, content
+                            type HTTP_CONTENT_TYPE_APP_JSON will be used.
+  @param[out] Response      HTTP response from redfish service.
+
+  @retval     EFI_SUCCESS     Resrouce is returned successfully.
+  @retval     Others          Errors occur.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *REDFISH_HTTP_POST_RESOURCE)(
+  IN  EDKII_REDFISH_HTTP_PROTOCOL  *This,
+  IN  REDFISH_SERVICE              Service,
+  IN  EFI_STRING                   Uri,
+  IN  CHAR8                        *Content,
+  IN  UINTN                        ContentSize OPTIONAL,
+  IN  CHAR8                        *ContentType OPTIONAL,
+  OUT REDFISH_RESPONSE             *Response
+  );
+
+/**
+  Perform HTTP DELETE to delete redfish resource on given resource URI.
+  It's caller's responsibility to free Response by calling FreeResponse ().
+
+  @param[in]  This          Pointer to EDKII_REDFISH_HTTP_PROTOCOL instance.
+  @param[in]  Service       Redfish service instance to perform HTTP DELETE.
+  @param[in]  Uri           Target resource URI.
+  @param[in]  Content       JSON represented properties to be deleted. This is
+                            optional.
+  @param[in]  ContentSize   Size of the Content to be send to Redfish service.
+                            This is optional. When ContentSize is 0, ContentSize
+                            is the size of Content if Content is not NULL.
+  @param[in]  ContentType   Type of the Content to be send to Redfish service.
+                            This is optional. When Content is not NULL and
+                            ContentType is NULL, content type HTTP_CONTENT_TYPE_APP_JSON
+                            will be used.
+  @param[out] Response      HTTP response from redfish service.
+
+  @retval     EFI_SUCCESS     Resrouce is returned successfully.
+  @retval     Others          Errors occur.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *REDFISH_HTTP_DELETE_RESOURCE)(
+  IN  EDKII_REDFISH_HTTP_PROTOCOL  *This,
+  IN  REDFISH_SERVICE              Service,
+  IN  EFI_STRING                   Uri,
+  IN  CHAR8                        *Content OPTIONAL,
+  IN  UINTN                        ContentSize OPTIONAL,
+  IN  CHAR8                        *ContentType OPTIONAL,
+  OUT REDFISH_RESPONSE             *Response
+  );
+
+///
+/// Definition of _EDKII_REDFISH_HTTP_PROTOCOL.
+///
+struct _EDKII_REDFISH_HTTP_PROTOCOL {
+  UINT32                          Version;
+  REDFISH_HTTP_CREATE_SERVICE     CreateService;
+  REDFISH_HTTP_FREE_SERVICE       FreeService;
+  REDFISH_HTTP_JSON_IN_PAYLOAD    JsonInPayload;
+  REDFISH_HTTP_GET_RESOURCE       GetResource;
+  REDFISH_HTTP_PATCH_RESOURCE     PatchResource;
+  REDFISH_HTTP_PUT_RESOURCE       PutResource;
+  REDFISH_HTTP_POST_RESOURCE      PostResource;
+  REDFISH_HTTP_DELETE_RESOURCE    DeleteResource;
+  REDFISH_HTTP_FREE_REQUEST       FreeRequest;
+  REDFISH_HTTP_FREE_RESPONSE      FreeResponse;
+  REDFISH_HTTP_EXPIRE_RESPONSE    ExpireResponse;
+};
+
+#define EDKII_REDFISH_HTTP_PROTOCOL_REVISION  0x00001000
+
+extern EFI_GUID  gEdkIIRedfishHttpProtocolGuid;
+
+#endif
diff --git a/RedfishPkg/Include/RedfishServiceData.h b/RedfishPkg/Include/RedfishServiceData.h
new file mode 100644
index 0000000000..bcaa12ba27
--- /dev/null
+++ b/RedfishPkg/Include/RedfishServiceData.h
@@ -0,0 +1,43 @@
+/** @file
+  This header file defines Redfish service and Redfish data structures that
+  are used to communicate with Redfish Ex Protocol.
+
+  Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
+  (C) Copyright 2021 Hewlett Packard Enterprise Development LP<BR>
+  Copyright (c) 2023-2024, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+
+    SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#ifndef REDFISH_SERVICE_DATA_H_
+#define REDFISH_SERVICE_DATA_H_
+
+#include <Uefi.h>
+#include <Protocol/Http.h>
+
+typedef  VOID  *REDFISH_SERVICE;
+typedef  VOID  *REDFISH_PAYLOAD;
+
+///
+/// REDFISH_REQUEST definition.
+///
+typedef struct {
+  UINTN              HeaderCount;
+  EFI_HTTP_HEADER    *Headers;
+  CHAR8              *Content;
+  CHAR8              *ContentType;
+  UINTN              ContentLength;
+} REDFISH_REQUEST;
+
+///
+/// REDFISH_REQUEST definition.
+///
+typedef struct {
+  EFI_HTTP_STATUS_CODE    *StatusCode;
+  UINTN                   HeaderCount;
+  EFI_HTTP_HEADER         *Headers;
+  REDFISH_PAYLOAD         Payload;
+} REDFISH_RESPONSE;
+
+#endif
--
2.34.1

-The information contained in this message may be confidential and proprietary to American Megatrends (AMI). This communication is intended to be read only by the individual or entity to whom it is addressed or by their designee. If the reader of this message is not the intended recipient, you are on notice that any distribution of this message, in any form, is strictly prohibited. Please promptly notify the sender by reply e-mail or by telephone at 770-246-8600, and then delete or destroy all copies of the transmission.


-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#115818): https://edk2.groups.io/g/devel/message/115818
Mute This Topic: https://groups.io/mt/104505402/7686176
Group Owner: devel+owner@edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [rebecca@openfw.io]
-=-=-=-=-=-=-=-=-=-=-=-