Reviewed-by: Nickle Wang Thanks, Nickle ________________________________ From: abner.chang@amd.com Sent: Sunday, April 30, 2023 10:00 PM To: devel@edk2.groups.io Cc: Nickle Wang ; Igor Kulchytskyy Subject: [edk2-redfish-client][PATCH] RedfishClientPkg: Initial commit External email: Use caution opening links or attachments From: Abner Chang Initial commit of architecture diagrams and Readme.md Signed-off-by: Abner Chang Cc: Nickle Wang Cc: Igor Kulchytskyy --- RedfishClientPkg/Readme.md | 185 +++ .../Media/RedfishClientDriverStack.svg | 1068 +++++++++++++++++ 2 files changed, 1253 insertions(+) create mode 100644 RedfishClientPkg/Readme.md create mode 100644 RedfishClientPkg/Documents/Media/RedfishClientDriverStack.svg diff --git a/RedfishClientPkg/Readme.md b/RedfishClientPkg/Readme.md new file mode 100644 index 0000000000..9e56fb9039 --- /dev/null +++ b/RedfishClientPkg/Readme.md @@ -0,0 +1,185 @@ +# UEFI Redfish Client EDK2 Implementation + +## Introduction +UEFI Redfish Client EDK2 solution is implemented base on +[*EDK2 Redfish Foundation*](https://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Ftianocore%2Fedk2%2Fblob%2Fmaster%2FRedfishPkg%2FReadme.md&data=05%7C01%7Cnicklew%40nvidia.com%7C8de0ff8f50c246da729108db49835539%7C43083d15727340c1b7db39efd9ccc17a%7C0%7C0%7C638184600646325072%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=3fTcnyZX2vZ5ORBAVtENT8yxyhaXZQsoYBT9hD8NGss%3D&reserved=0), +the implementation utilizes the EFI protocols provided by EDK2 Redfish +Foundation to communicate with the Redfish service for creating, consuming, and +updating the Redfish properties which are managed by firmware. This solution +requests the instance of **EFI REST EX Protocol** through EFI Redfish Discover +Protocol and interacts with Redfish service using **EFI REST EX Protocol** later +on. The essential part of this implementation is to map the EDK2 HII options to +the corresponding Redfish properties that are already defined in the standard +Redfish schemas published by +[*DMTF Redfish working group*](https://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.dmtf.org%2Fstandards%2Fredfish&data=05%7C01%7Cnicklew%40nvidia.com%7C8de0ff8f50c246da729108db49835539%7C43083d15727340c1b7db39efd9ccc17a%7C0%7C0%7C638184600646325072%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=nrrH%2BA9VXIDC3YC%2B85jlBNdH2uHvz48d8TY37AfSaNs%3D&reserved=0). +The advantage of this design is to strengthen the interoperability among the +servers produced by different OEMs when configuring the platform through Redfish +service. Using the properties defined in Redfish standard schema for configuring +platform reduces the overhead of Redfish client tools to have different +implementations in order to compliant with OEM servers. The solution also +reduces OEM-defined proprietary BIOS Attributes that lead to the divergence of +platform configuration namings in Redfish BIOS Attribute Registry, however, +those different namings refer to the same platform functionality. + +## The Scope of UEFI Redfish Client EDK2 Implementation +- Platform Configurable settings + +This is the first stage of UEFI Redfish Client EDK2 Implementation. Associate +Redfish property with HII option. + +- Provisioning of Firmware Managed Platform Redfish Resource + +The current design of UEFI Redfish Client EDK2 Implementation can already +support the provisioning of firmware-owned platform Redfish resource, however, +this requires addtional support on edk2 HII. Therefore, provisioning of +firmware managed platform Redfish resource would be the second stage. + +Below are the block diagrams of UEFI Redfish Client EDK2 Implementation. + +## EDK2 Redfish Client Implementation Diagrams +![UEFI Redfish Client Implementation](https://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fchangab%2Fedk2-staging%2Fblob%2Fedk2-redfish-client%2FRedfishClientPkg%2FDocuments%2FMedia%2FRedfishClientDriverStack.svg%3Fraw%3Dtrue&data=05%7C01%7Cnicklew%40nvidia.com%7C8de0ff8f50c246da729108db49835539%7C43083d15727340c1b7db39efd9ccc17a%7C0%7C0%7C638184600646325072%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=u%2FET1d%2BA1lJoKk92ytJ%2FI1ZE7S6D1ioA%2Fbxubvz8ISE%3D&reserved=0) + +## EFI EDK2 Redfish Client Framework +The functionality of each block in the diagrams are described in belwo sections, + +### EDK2 Redfish Foundation ***[[1]](#[0])*** +EDK2 Redfish Redfish Foundation provides the facilities of communicating with +Redfish service. Such as the discovery of Redfish service, the credential to +access Redfish service, *EFI REST EX Protocol* instance which is the transport +layer to Redfish service, and so on. Please refer to +[*EDK2 Redfish Foundation*](https://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Ftianocore%2Fedk2%2Fblob%2Fmaster%2FRedfishPkg%2FReadme.md&data=05%7C01%7Cnicklew%40nvidia.com%7C8de0ff8f50c246da729108db49835539%7C43083d15727340c1b7db39efd9ccc17a%7C0%7C0%7C638184600646325072%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=3fTcnyZX2vZ5ORBAVtENT8yxyhaXZQsoYBT9hD8NGss%3D&reserved=0). + +### Redfish Profile Simulator ***[[2]](#[0])*** +Redfish Profile Simulator is an +[*open source project*](https://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2FDMTF%2FRedfish-Profile-Simulator&data=05%7C01%7Cnicklew%40nvidia.com%7C8de0ff8f50c246da729108db49835539%7C43083d15727340c1b7db39efd9ccc17a%7C0%7C0%7C638184600646325072%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=6yLfs7aHMnn4ERF9ih8NTOXrupmDT4hxgwSXiB2kf3g%3D&reserved=0) on +DMTF GitHub, which simulates the HTTP request methods (POST, PATCH, PUT, GET) on +Redfish resource maintained by Redfish Profile Simulator. EDK2 open source uses +this simulator for the use case when Redfish service has not been set up on the +platform, or for the quick Redfish firmware feature development. We clone this +project under RedfishClientPkg and maintain it by edk2 because this project has +currently been using and updating rarely. That is easier for edk2 to add +features to the simulator or modify the simulator to align with edk2 requirement +on Redfish service, such as ETAG and HTTP POST support.
+Another open source project of Redfish simulator is +[*Redfish Interface Emulator*](https://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2FDMTF%2FRedfish-Interface-Emulator&data=05%7C01%7Cnicklew%40nvidia.com%7C8de0ff8f50c246da729108db49835539%7C43083d15727340c1b7db39efd9ccc17a%7C0%7C0%7C638184600646325072%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=YFko4l8kiy5gZR9iaRFhrATZ2PXq1g8NwDFMzuliXFA%3D&reserved=0), +however, we don't pay much attention to this project because we have been +dedicating to Redfish Profile Simulator since we started the UEFI Redfish EDK2 +project. + +### EDK2 Redfish JSON Schema to C Structure Convertor ***[[3]](#[0])*** +This is the script auto-generated EDK2 drivers and libraries that provide the +Redfish schema naming based JSON to C structure and vise versa converters. C +structure is another representation of Redfish properties other than JSON and +CSDL(XML). The higher layer Redfish client application can deal with C structure +instead of using JSON library to manipulate Redfish properties. The script +[*Redfish Schema C Struct Generator*](https://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2FDMTF%2FRedfish-Schema-C-Struct-Generator&data=05%7C01%7Cnicklew%40nvidia.com%7C8de0ff8f50c246da729108db49835539%7C43083d15727340c1b7db39efd9ccc17a%7C0%7C0%7C638184600646325072%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=TfikAxceF8pMoAM6W4n0hi7hJgG1185n8IZpQkNqkgw%3D&reserved=0) +is still a private project on DMTF GitHub. Below is the reference of script +auto-generated +[*Redfish JSON C Struct Converter Lib*](https://nam11.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fchangab%2FRedfish-JSON-C-Struct-Converter-Lib&data=05%7C01%7Cnicklew%40nvidia.com%7C8de0ff8f50c246da729108db49835539%7C43083d15727340c1b7db39efd9ccc17a%7C0%7C0%7C638184600646325072%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=e3%2BgKfK5Nr3MPfsmDm2wmtHJnDzmb%2B0liABLnfmsao4%3D&reserved=0) +libraries. The converters generated by the script are followed +**EFI REST JSON Structure Protocol** defined in UEFI spec 2.8, section 29.7.3. + +### EDK2 Redfish Non-Collection ***[[4]](#[0])*** and Collection ***[[5]](#[0]) +*** Feature Drivers EDK2 Redfish feature driver is an intermediary driver that +sits between **JSON Schema to C Structure converters** and **EFI Platform +Configuration to Redfish Protocol**. The Redfish feature driver gets and sets +the platform configuration and incorporates it with Redfish JSON schema C +structure to manipulate Redfish JSON resources. Then applies the settings from +Redfish service to platform configurations, or vise versa to update platform +configurations to Redfish service. Both EDK2 Redfish Non-Collection and +Collection Feature drivers are script auto-generated base on Redfish schema +naming. The EDK2 Redfish Non-Collection feature driver manages the resource of +specific Resdifsh resource type, while the EDK2 Redfish Collection feature +driver manages the members which have the same resource type in collection +resource (e.g the ComputerSystem resource and ComputerSystemCollection resource) +. + +### EDKII Redfish Platform Config Protocol ***[[6]](#[0])*** +EDKII Redfish Platform Config Protocol is an abstract driver that abstracts the +platform configuration format and storage from EDK2 Redfish Feature driver. +This protocol provides the interfaces to get and set platform configuration with +the format and configuration storage agnostic to the Redfish feature driver. +The platform can provide its own EDKII Redfish Platform Config driver instance +to access platform-specific configuration format and storage. On EDK2 open +source, EDKII Redfish Platform Config Protocol accesses the platform +configuration in EDK2 HII defined format. + +Below is the prototype of **EDKII_REDFISH_PLATFORM_CONFIG_PROTOCOL**, + +```C +struct _EDKII_REDFISH_PLATFORM_CONFIG_PROTOCOL { + EDKII_REDFISH_PLATFORM_CONFIG_GET_VALUE GetValue; + EDKII_REDFISH_PLATFORM_CONFIG_SET_VALUE SetValue; + EDKII_REDFISH_PLATFORM_CONFIG_GET_CONFIG_LANG GetConfigureLang; + EDKII_REDFISH_PLATFORM_CONFIG_GET_SUPPORTED_SCHEMA GetSupportedSchema; +}; +``` + +### Other instances of EDKII Redfish Platform Config Protocol ***[[7]](#[0])*** +For those Non-EDK2 HII-based platform configuration formats, the driver instance +can provide its own implementation to get or set the platform configurations. + +### EDK2 HII VFR Form ***[[8]](#[0])*** +According to **UEFI spec 2.9 section 35.6 Form Browser Protocol**, +**EFI_HII_REST_STYLE_FORMSET_GUID** is used on HII form to indicate that HII +options declared in this form intend to interact with the REST architectural +style. On edk2 open source, the REST architectural style refers to the Redfish +service. Besides **EFI_HII_REST_STYLE_FORMSET_GUID** is defined in the form +scope, **EFI_IFR_FLAG_REST_STYLE** can be assigned to the HII options that +indicate those options intend to interact with the REST service. + +### EDK2 HII UNI file ***[[9]](#[0])*** +x-uefi-redfish Configure Language is used in UNI file to associate HII option +with the particular Redfish property. The Hii options interact with EDK2 Redfish +Feature driver if the string of HII option is assigned with x-uefi-redfish +Language as in below, + +```C +x-uefi-redfish-$(NAMESPACE) +where $(NAMESPACE) is the combination of Redfish ResourceTypeName and schema version. +``` +For example, if the HII option is mapped to the property in Processor.v1_0_0. +The x-uefi-redfish configure language is declared as below, +```C +x-uefi-redfish-Processor.v1_0_0 +``` +#### x-uefi-redfish Configure Language format: +- The string declared with x-uefi-redfish configure language is a path to the property +in Redfish resource +- The root of path is the Redfish resource type indicated in x-uefi-redfish configure +language +- The path is relative to root of Redfish resource type, not related to Redfish service +- root. + +#### Examples, +```C +Properties: + +#string STR_BOOT_SOURCE_OVERRIDE_ENABLED_PROMPT #language x_uefi_redfish_ComputerSystem.v1_0_0 "/Boot/BootSourceOverrideEnabled" +#string STR_BOOT_SOURCE_OVERRIDE_MODE_PROMPT #language x_uefi_redfish_ComputerSystem.v1_0_0 "/Boot/BootSourceOverrideMode" +#string STR_BOOT_SOURCE_OVERRIDE_TARGET_PROMPT #language x_uefi_redfish_ComputerSystem.v1_0_0 "/Boot/BootSourceOverrideTarget" +``` +```C +Properties in array object [NUM]: + +#string STR_BOOT_ORDER_1_PROMPT #language x_uefi_redfish_ComputerSystem.v1_11_0 "/Boot/BootOrder/[1]/Boot0001" +#string STR_BOOT_ORDER_2_PROMPT #language x_uefi_redfish_ComputerSystem.v1_11_0 "/Boot/BootOrder/[2]/Boot0002" +#string STR_BOOT_ORDER_3_PROMPT #language x_uefi_redfish_ComputerSystem.v1_11_0 "/Boot/BootOrder/[3]/Boot0003" +``` +```C +Properties in collection object {NUM}: + +#string STR_MEMORY_1_BASE_MODULE_TYPE_PROMPT #language x_uefi_redfish_Memory.v1_7_1 "/Memory/{1}/BaseModuleType" +#string STR_MEMORY_2_BASE_MODULE_TYPE_PROMPT #language x_uefi_redfish_Memory.v1_7_1 "/Memory/{2}/BaseModuleType" +#string STR_MEMORY_3_BASE_MODULE_TYPE_PROMPT #language x_uefi_redfish_Memory.v1_7_1 "/Memory/{3}/BaseModuleType" +``` + +### EDK2 Build Tool ***[[10]](#[0])*** +EDK2 Build is responsible to pull the necessary EDK2 Redfish JSON Schema to C +Structure Convertors and EDK2 Redfish Feature drivers into edk2 build process +according to the x-uefi-Redfish config language used in the HII VFR forms. + +## The Contributors +Chang, Abner \ +Wang, Nickle \ +Chen, Aaron diff --git a/RedfishClientPkg/Documents/Media/RedfishClientDriverStack.svg b/RedfishClientPkg/Documents/Media/RedfishClientDriverStack.svg new file mode 100644 index 0000000000..881d9647e5 --- /dev/null +++ b/RedfishClientPkg/Documents/Media/RedfishClientDriverStack.svg @@ -0,0 +1,1068 @@ + +"> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + VBackground-1 + + + Solid + + + + + + + + + + + Page-2 + + + + Rectangle.52 + + + + + + + + + + Can + Redfish Service + + Sheet.6 + + + + + + + + + + + + + Redfish Service + + + Sheet.8 + Redfish Profile Simulator On Network + + + + Redfish Profile Simulator On Network + + Sheet.10 + EFI REST EX + + + + EFI REST EX + + Rectangle + + + + + + + Rounded Rectangle.76 + + + + + + + + + + + + + + + + + + + + + + + + + Sheet.16 + EFI REST JSON to C Structure + + + + EFI REST JSON to C Structure + + Sheet.17 + EFI Network Stack + + + + EFI Network Stack + + Sheet.18 + EFI Redfish Discover Protocl + + + + EFI Redfish Discover Protocl + + Sheet.19 + EDKII Redfish Foundation + + + + EDKII Redfish Foundation + + Curve connect 1 + + + + + + + + + Sheet.21 + EDKII Redfish Client + + + + EDKII Redfish Client + + Sheet.24 + + + + Sheet.25 + + + + Sheet.26 + Script-generated Redfish JSON schema to C Structure convertor + + + + Script-generated Redfish JSON schema to C Structure convertor + + Sheet.28 + + + + Sheet.29 + + + + Sheet.30 + + + + Sheet.31 + ComputerSystem + + + + ComputerSystem + + Sheet.32 + BootOption + + + + BootOption + + Sheet.33 + Memory + + + + Memory + + Sheet.34 + + + + Sheet.35 + + + + Sheet.36 + Script-generated EDK2 Redfish Feature Driver + + + + Script-generated EDK2 Redfish Feature Driver + + Sheet.40 + ComputerSystem + + + + ComputerSystem + + Sheet.41 + BootOption + + + + BootOption + + Sheet.42 + Memory + + + + Memory + + Sheet.43 + + + + Sheet.46 + + + + Sheet.47 + + + + Sheet.48 + + + + Sheet.49 + ComputerSystemCollection + + + + ComputerSystemCollection + + Sheet.50 + BootOptionCollection + + + + BootOptionCollection + + Sheet.51 + MemoryCollection + + + + MemoryCollection + + Curve connect 2.56 + + + + + + + Sheet.57 + + + + 1-D double + + + + + + + Sheet.64 + EDKII REDFISH_PLATFORM_CONFIG_PROTOCOL + + + + + + + EDKII REDFISH_PLATFORM_CONFIG_PROTOCOL + + Sheet.65 + EDKII REDFISH_PLATFORM_CONFIG_PROTOCOL + + + + + + + EDKII REDFISH_PLATFORM_CONFIG_PROTOCOL + + Sheet.67 + Other Platform-specific Implementations + + + + Other Platform-specific Implementations + + + + + Can.71 + EFI Variable/ FW Storage + + Sheet.72 + + + + + + + + + + + + EFI Variable/ FW Storage + + + + + + Can.73 + Other Storage + + Sheet.74 + + + + + + + + + + + + Other Storage + + + 1-D double.76 + + + + + + + 1-D double.77 + + + + + + + Sheet.78 + + + + + + + + + + + + + + + Folded Corner + + + + + + + + Sheet.81 + + + + + + + + + + + + + + + + + + + + + + + Can.69 + EDK2 HII Database + + Sheet.83 + + + + + + + + + + + + EDK2 HII Database + + + Sheet.84 + EDKII REDFISH_PLATFORM_CONFIG_PROTOCOL + + + + + + + EDKII REDFISH_PLATFORM_CONFIG_PROTOCOL + + 1-D double.75 + + + + + + + 1-D double.68 + + + + + + + + + + Sheet.87 + EDK2 Open Source Implementation + + + + EDK2 Open Source Implementation + + 1-D double.88 + + + + + + + 1-D double.89 + + + + + + + Curve connect 1.61 + + + + + + + + + Curve connect 1.62 + + + + + + + + + Curve connect 2.54 + + + + + + + Sheet.96 + Script-generated EDK2 Redfish Collection Driver + + + + Script-generated EDK2 Redfish Collection Driver + + Rounded Rectangle.98 + EDK2 HII UNI file #string STR_OPTION_A #language x-uefi-redfi... + + + + + + + + + + + + + + + + + + + + + + EDK2 HII UNI file#string STR_OPTION_A #language x-uefi-redfish-SCHEMA.VERSION “/SCHEMA/PropertyA” #string STR_OPTION_B #language x-uefi-redfish-SCHEMA.VERSION “/SCHEMA/PropertyB”#string STR_OPTION_C #language x-uefi-redfish-SCHEMA.VERSION “/SCHEMA/PropertyC” + + Rounded Rectangle.100 + EDK2 HII VFR Form Option A Enabled Option B Disabled Option C... + + + + + + + + + + + + + + + + + + + + + + EDK2 HII VFR FormOption A EnabledOption B DisabledOption C 0x16 + + Rounded Rectangle.101 + EDK2 HII VFR Form Option A Enabled Option B Disabled Option C... + + + + + + + + + + + + + + + + + + + + + + EDK2 HII VFR FormOption A EnabledOption B DisabledOption C 0x16 + + Rounded Rectangle + EDK2 HII VFR Form Option A Enabled Option B Disabled Option C... + + + + + + + + + + + + + + + + + + + + + + EDK2 HII VFR FormOption A EnabledOption B DisabledOption C 0x16 + + Curve connect 1.110 + + + + + + + + + Sheet.122 + [1] + + + + [1] + + Sheet.123 + [2] + + + + [2] + + Sheet.124 + [3] + + + + [3] + + Sheet.125 + [4] + + + + [4] + + Sheet.126 + [5] + + + + [5] + + Sheet.127 + [6] + + + + [6] + + Sheet.128 + [8] + + + + [8] + + Sheet.129 + [9] + + + + [9] + + Curve connect 2.132 + + + + + + + Sheet.133 + Script-generated EDK2 Redfish client driver/library based on ... + + + + Script-generated EDK2 Redfish client driver/library based on the standard Redfish schemas published by DMTF + + Rectangle.134 + + + + + + + Sheet.135 + Script-generated code + + + + Script-generated code + + Rectangle.137 + + + + + + + Sheet.138 + UEFI/EDK2 open source + + + + UEFI/EDK2 open source + + Configure + + + + + + + + Side to top/bottom.145 + + + + + + + + Bottom to top fixed 2 + + + + + + + + + + + Side to top/bottom + + + + + + + + Sheet.152 + [10] + + + + [10] + + Sheet.153 + EDK2 Build Tool + + + + EDK2 Build Tool + + Curve connect 2 + + + + + + + Sheet.154 + [7] + + + + [7] + + Curve connect 1.155 + + + + + + + + + -- 2.37.1.windows.1