RedfishClientPkg: Redfish task service support

RedfishClientPkg/Include/Protocol/EdkIIRedfishTaskProtocol.h

@@ -0,0 +1,218 @@
+/** @file
+  This file defines the EDKII_REDFISH_TASK_PROTOCOL interface.
+
+  Copyright (c) 2023, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#ifndef EDKII_REDFISH_TASK_PROTOCOL_H_
+#define EDKII_REDFISH_TASK_PROTOCOL_H_
+
+#include <Uefi.h>
+#include <Protocol/Http.h>
+#include <Library/RedfishMessageLib.h>
+
+typedef struct _EDKII_REDFISH_TASK_PROTOCOL EDKII_REDFISH_TASK_PROTOCOL;
+
+///
+/// Definition of REDFISH_TASK_STATE.
+///
+typedef enum {
+  RedfishTaskStateNew = 0x0,
+  RedfishTaskStateStarting,
+  RedfishTaskStateRunning,
+  RedfishTaskStateSuspended,
+  RedfishTaskStateInterrupted,
+  RedfishTaskStatePending,
+  RedfishTaskStateStopping,
+  RedfishTaskStateCompleted,
+  RedfishTaskStateKilled,
+  RedfishTaskStateException,
+  RedfishTaskStateService,
+  RedfishTaskStateCancelling,
+  RedfishTaskStateCancelled,
+  RedfishTaskStateMax
+} REDFISH_TASK_STATE;
+
+///
+/// Definition of REDFISH_TASK_STATUS.
+///
+typedef enum {
+  RedfishTaskStatusOk = 0x0,
+  RedfishTaskStatusWarning,
+  RedfishTaskStatusCritical,
+  RedfishTaskStatusMax
+} REDFISH_TASK_STATUS;
+
+///
+/// Definition of REDFISH_TASK_RESULT.
+///
+typedef struct {
+  REDFISH_TASK_STATE     TaskState;
+  REDFISH_TASK_STATUS    TaskStatus;
+} REDFISH_TASK_RESULT;
+
+///
+/// Definition of REDFISH_TASK_PAYLOAD.
+///
+typedef struct {
+  EFI_HTTP_METHOD    HttpOperation;
+  EFI_HTTP_HEADER    *Headers;
+  UINTN              HeaderCount;
+  CHAR8              *JsonBody;
+  CHAR8              *TargetUri;
+} REDFISH_TASK_PAYLOAD;
+
+/**
+  The callback function provided by Redfish feature driver.
+
+  @param[in]     TaskId              The Task ID.
+  @param[in]     JsonText            The context of task resource in JSON format.
+  @param[in]     Context             The context of Redfish feature driver.
+  @param[in,out] Result              The pointer to REDFISH_TASK_RESULT.
+                                     On input, it is "TaskState" and "TaskStatus" in task resource.
+                                     On ouput, it is "TaskState" and "TaskStatus" that will be update
+                                     to task resource.
+
+  @retval EFI_SUCCESS              Redfish feature driver callback is executed successfully.
+  @retval Others                   Some errors happened.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *REDFISH_TASK_CALLBACK)(
+  IN     UINTN                       TaskId,
+  IN     CHAR8                       *JsonText,
+  IN     VOID                        *Context,
+  IN OUT REDFISH_TASK_RESULT         *Result
+  );
+
+/**
+  The registration function for the Redfish Feature driver.
+
+  @param[in]   This                Pointer to EDKII_REDFISH_TASK_PROTOCOL instance.
+  @param[in]   ListenTaskUri       The URI in "Payload.TargetUri" from task resource that
+                                   feature driver likes to listen. If the ListenTaskUri is
+                                   matched in any of task resource, the corresponding Callback
+                                   is called to serve this task in feature driver.
+  @param[in]   PartialMatch        When PartialMatch is TRUE, StrStr() is used to do string matching.
+                                   When PartialMatch is FALSE, StrCmp() is used to do string matching.
+  @param[in]   Callback            Callback routine associated with this registration that
+                                   provided by Redfish feature driver to execute the action
+                                   on Redfish resource which is managed by this Redfish
+                                   feature driver.
+  @param[in]   Context             The context of the registering feature driver. The pointer
+                                   to the context is delivered through callback function.
+
+  @retval EFI_SUCCESS              Redfish feature driver is registered successfully.
+  @retval Others                   Some error happened.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *REDFISH_TASK_REGISTER)(
+  IN     EDKII_REDFISH_TASK_PROTOCOL  *This,
+  IN     EFI_STRING                   ListenTaskUri,
+  IN     BOOLEAN                      PartialMatch,
+  IN     REDFISH_TASK_CALLBACK        Callback,
+  IN     VOID                         *Context  OPTIONAL
+  );
+
+/**
+  The unregistration function for the Redfish Feature driver.
+
+  @param[in]   This                Pointer to EDKII_REDFISH_TASK_PROTOCOL instance.
+  @param[in]   ListenTaskUri       The URI in "Payload.TargetUri" from task resource that
+                                   feature driver likes to listen.
+  @param[in]   Context             The context used for the previous feature driver
+                                   registration.
+
+  @retval EFI_SUCCESS              Redfish feature driver is registered successfully.
+  @retval Others                   Some error happened.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *REDFISH_TASK_UNREGISTER)(
+  IN     EDKII_REDFISH_TASK_PROTOCOL  *This,
+  IN     EFI_STRING                   ListenTaskUri,
+  IN     VOID                         *Context OPTIONAL
+  );
+
+/**
+  The report message function to report information about task.
+
+  @param[in]   This                Pointer to EDKII_REDFISH_TASK_PROTOCOL instance.
+  @param[in]   TaskId              The Task ID.
+  @param[in]   Message             String message attached to give task.
+  @param[in]   MessageSeverity     Message severity.
+
+  @retval EFI_SUCCESS              Redfish feature driver is registered successfully.
+  @retval Others                   Some error happened.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *REDFISH_TASK_REPORT_MESSAGE)(
+  IN     EDKII_REDFISH_TASK_PROTOCOL  *This,
+  IN     UINTN                        TaskId,
+  IN     CHAR8                        *Message,
+  IN     REDFISH_MESSAGE_SEVERITY     MessageSeverity
+  );
+
+/**
+  This function read input JsonText and generate payload information in REDFISH_TASK_PAYLOAD.
+  It's call responsibility to release returned Payload by calling FreePayload().
+
+  @param[in]   This                Pointer to EDKII_REDFISH_TASK_PROTOCOL instance.
+  @param[in]   JsonText            The context of task resource in JSON format.
+  @param[out]  Payload             Returned payload information.
+
+  @retval EFI_SUCCESS              Task payload is returned successfully.
+  @retval Others                   Some error happened.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *REDFISH_TASK_GET_PAYLOAD)(
+  IN     EDKII_REDFISH_TASK_PROTOCOL  *This,
+  IN     CHAR8                       *JsonText,
+  OUT    REDFISH_TASK_PAYLOAD        **Payload
+  );
+
+/**
+  This function release Payload resource which is returned by GetPayload().
+
+  @param[in]   This                Pointer to EDKII_REDFISH_TASK_PROTOCOL instance.
+  @param[in]   Payload             The payload to release.
+
+  @retval EFI_SUCCESS              Payload is released successfully.
+  @retval Others                   Some error happened.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *REDFISH_TASK_FREE_PAYLOAD)(
+  IN     EDKII_REDFISH_TASK_PROTOCOL  *This,
+  IN     REDFISH_TASK_PAYLOAD         *Payload
+  );
+
+///
+/// Definition of _EDKII_REDFISH_TASK_PROTOCOL.
+///
+struct _EDKII_REDFISH_TASK_PROTOCOL {
+  UINT32                         Version;
+  REDFISH_TASK_REGISTER          Register;
+  REDFISH_TASK_UNREGISTER        Unregister;
+  REDFISH_TASK_REPORT_MESSAGE    ReportMessage;
+  REDFISH_TASK_GET_PAYLOAD       GetPayload;
+  REDFISH_TASK_FREE_PAYLOAD      FreePayload;
+};
+
+#define EDKII_REDFISH_TASK_PROTOCOL_REVISION  0x00001000
+
+extern EFI_GUID  gEdkIIRedfishTaskProtocolGuid;
+
+#endif

RedfishClientPkg/Readme.md

@@ -509,8 +509,40 @@ collection resource, and also for triggering the Redfish action. For the Redfish
 as loading the BIOS default and Secure boot certification enrollment.<br>
 HTTP DELETE operation is triggered by BIOS to delete a member in the Redfish collection.
 
-### Redfish Task design
-TBD.
+### Redfish Task
+Redfish task service driver handles Redfish task resources at `/redfish/v1/TaskService/Tasks` and dispatch the task
+resource to registered Redfish feature driver. Redfish feature driver utilizes Redfish task protocol to get data
+from registered Redfish task, and perform corresponding action specified by the Redfish task. After job is finished,
+Redfish task service reports task result back to BMC. So user can check task state to see if issued task is done
+successfully or not.
+
+Redfish task is handled before any other Redfish resource because the action requested by Redfish task may change host configuration.
+
+There are several interfaces supported by Redfish task protocol:
+```C
+struct _EDKII_REDFISH_TASK_PROTOCOL {
+  UINT32                         Version;
+  REDFISH_TASK_REGISTER          Register;
+  REDFISH_TASK_UNREGISTER        Unregister;
+  REDFISH_TASK_REPORT_MESSAGE    ReportMessage;
+  REDFISH_TASK_GET_PAYLOAD       GetPayload;
+  REDFISH_TASK_FREE_PAYLOAD      FreePayload;
+};
+```
+- Register()
+  - Redfish feature driver register its callback function and provide the task URI which is wants to handle. `PartialMatch` parameter allows feature driver to handle the task URI when certain keyword is presented.
+- Unregister()
+  - Redfish feature driver unregister itself and Redfish task service won't notify it anymore.
+- ReportMessage()
+  - When Redfish feature driver perform task given job and there is message that driver wants to send to user, feature driver calls this function and Redfish task service will send these messages to BMC. Typical use case is when there is error happens and task is failing, feature driver provides the reason why task is failing by calling this function.
+- GetPayload()
+  - Feature driver calls this function to get Redfish payload attached to this task resource.
+- FreePayload()
+  - The function that helps feature driver to release Redfish payload that is returned by GetPayload().
+
+**Redfish task library**
+
+Redfish task service reads Redfish tasks on  `/redfish/v1/TaskService/Tasks`. However, the URI for host firmware to update task results and state are not defined in any specification. As the result, platform BMC may have different implementation of updating task result. This makes the interface of updating Redfish task to be platform dependent. Redfish task library is introduced for platform owner to implement this path.
 
 ## The Contributors
 Chang, Abner <[email protected]>\

RedfishClientPkg/RedfishClientPkg.dec

@@ -48,6 +48,8 @@
   gEdkiiRedfishOverrideProtocolGuid         = { 0xb55bef20, 0xf7c8, 0x4ae9, { 0xa7, 0xca, 0x8b, 0xba, 0x9f, 0x7b, 0xbf, 0x9c } }
   ## Include/Protocol/EdkIIRedfishResourceConfig2Protocol.h
   gEdkIIRedfishResourceConfig2ProtocolGuid  = { 0xe9bef87f, 0xbff4, 0x4872, { 0xa9, 0xa4, 0x16, 0x59, 0xbe, 0xd9, 0x1c, 0xf4 } }
+  ## Include/Protocol/EdkIIRedfishTaskProtocol.h
+  gEdkIIRedfishTaskProtocolGuid             = { 0x3a94e53e, 0x3f30, 0x4386, { 0x84, 0x9b, 0xbc, 0x5a, 0x87, 0x09, 0x3b, 0x1f } }
 
 [Guids]
   ## Include/Guid/RedfishClientPkgTokenSpace.h