From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail02.groups.io (mail02.groups.io [66.175.222.108]) by spool.mail.gandi.net (Postfix) with ESMTPS id CD403D8086D for ; Mon, 5 Feb 2024 08:34:37 +0000 (UTC) DKIM-Signature: a=rsa-sha256; bh=B4jhqeh6V1uHDfX5dYR0TgJZyzov6qSEYJ8wSuHnocc=; c=relaxed/simple; d=groups.io; h=ARC-Seal:ARC-Message-Signature:ARC-Authentication-Results:Received-SPF:From:To:CC:Subject:Date:Message-ID:MIME-Version:Precedence:List-Subscribe:List-Help:Sender:List-Id:Mailing-List:Delivered-To:Reply-To:List-Unsubscribe-Post:List-Unsubscribe:Content-Transfer-Encoding:Content-Type; s=20140610; t=1707122076; v=1; b=EMCg2axLbCNQtPOyUqUo4JHxgExuxUvJhppNKy9ERLRibMmGaPrJQ02fe6Lm/U6by03VV7Td lV6KK2MiUTKB0OJrq+wiYpkoRoAWtWtGmlRyoQM07mAojHptwpQLWrPoQFx6Kedl1dah+fA5I/E qNW1aJbSE/kd/4VQUKbiWM24= X-Received: by 127.0.0.2 with SMTP id CXnBYY7687511xH2P3Mubf7b; Mon, 05 Feb 2024 00:34:36 -0800 X-Received: from NAM10-BN7-obe.outbound.protection.outlook.com (NAM10-BN7-obe.outbound.protection.outlook.com [40.107.92.85]) by mx.groups.io with SMTP id smtpd.web10.58982.1707122075433233345 for ; Mon, 05 Feb 2024 00:34:35 -0800 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=T4fDaoLbYRfaB1IjM62nV1yrgGwcjlivdmT9+2TkA79ilCLhMc9wiE3Lzop233CgYhK+9MJJDPTK1N+BZ97x09ZyHQ/JJ6BxEuLudnxSID3V/9MVWYWEguOGLsHx+AgenTXEj3XxlKn+F81Jk84R5GsEOXgqgIh8E2LNNNSfy2BDEED5aRjL90EjTPybKf3FL3FQo4M1ifztOby/YXNL45XxkaKKXrsH+v/jvTtR1m7zrxHL10EkQSvaOJD9Rl+bUYlMmwGRNlw638tyALJY7iJFNN51Qaf2mLHM+p6wNnMBxzCIxWY+qYGTpbobflp1C/Qp/euj7dW1ukcqNh8utw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=X5NXuC46iw0W5rXpCq8O9IQIoUSCA4SbccPCi94Y1rM=; b=aZgqQKpoXfh1k1K5CA0YN7rm/fHBU58AjPiYzCY1FM+UmRGRvxeb4U1wMQ9nnGmkCZTopxU6WV/F3/pa0u06VlXJLHM1/xQg6e413MAK2oC4MFR/ZZB9JTqPrk64xxhPwRx2MzC5pNKuQifIT3QT7YCEqwsLpTRlBuVY3tV7THEegqIXh4bQ8DIpL+uWvnRGZ3jDC9UA57pjJ5OC+QsT8phkmQxx8W4x6Bu0d41x5x2r2ofdG0x3vWkWiFeL/1XVBGYr2p3UPs545CZF6ymnr4ZQBAzpsfbCmeMxwtSNm6nWDWdcIcd7G38RjWOcOTs4OKB1nCjJkHImgkfFuGlHag== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass (sender ip is 165.204.84.17) smtp.rcpttodomain=edk2.groups.io smtp.mailfrom=amd.com; dmarc=pass (p=quarantine sp=quarantine pct=100) action=none header.from=amd.com; dkim=none (message not signed); arc=none (0) X-Received: from BYAPR07CA0064.namprd07.prod.outlook.com (2603:10b6:a03:60::41) by PH8PR12MB6699.namprd12.prod.outlook.com (2603:10b6:510:1ce::17) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.7270.15; Mon, 5 Feb 2024 08:34:32 +0000 X-Received: from SJ5PEPF000001D2.namprd05.prod.outlook.com (2603:10b6:a03:60:cafe::26) by BYAPR07CA0064.outlook.office365.com (2603:10b6:a03:60::41) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.7249.34 via Frontend Transport; Mon, 5 Feb 2024 08:34:32 +0000 X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 165.204.84.17) smtp.mailfrom=amd.com; dkim=none (message not signed) header.d=none;dmarc=pass action=none header.from=amd.com; Received-SPF: Pass (protection.outlook.com: domain of amd.com designates 165.204.84.17 as permitted sender) receiver=protection.outlook.com; client-ip=165.204.84.17; helo=SATLEXMB04.amd.com; pr=C X-Received: from SATLEXMB04.amd.com (165.204.84.17) by SJ5PEPF000001D2.mail.protection.outlook.com (10.167.242.54) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.20.7202.16 via Frontend Transport; Mon, 5 Feb 2024 08:34:32 +0000 X-Received: from TPE-L1-ABNCHANG.amd.com (10.180.168.240) by SATLEXMB04.amd.com (10.181.40.145) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.34; Mon, 5 Feb 2024 02:34:30 -0600 From: "Chang, Abner via groups.io" To: CC: Nickle Wang , Igor Kulchytskyy Subject: [edk2-devel] [edk2-redfish-client][PATCH V3] RedfishClientPkg: Readme.md update Date: Mon, 5 Feb 2024 16:34:20 +0800 Message-ID: <20240205083420.1047-1-abner.chang@amd.com> MIME-Version: 1.0 X-Originating-IP: [10.180.168.240] X-ClientProxiedBy: SATLEXMB03.amd.com (10.181.40.144) To SATLEXMB04.amd.com (10.181.40.145) X-EOPAttributedMessage: 0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: SJ5PEPF000001D2:EE_|PH8PR12MB6699:EE_ X-MS-Office365-Filtering-Correlation-Id: b05e9882-afa3-437c-497a-08dc262546fd X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam-Message-Info: VDoOJUB8yFkNRBkrUnsdkLQd4qIF3GaU2BCRGXkHdZOvmR4zaXq2WxJfSgec7bbcs0ackiZ/RVhvIr5P4joMN5yTI4s3obCUtDahqSsCTRBk7ena65+NRlD7nm52lClfbewTaH3peKE7RR98QdTZhQ5Oy3DPH7jbFXiqxgKL/XicK80Amr9WwBdrKyParLUOAmYbqwwogxm0NAkpeTauSJXkbWhCPFeziXo1JBW7TjVMaHOeWTq47xBiCH7DqvcnnPnwtieoKRv1lfTjEOjet00Yl7L7Sfa+09VqyXBkXkxR81d8cmiHMq90G5hx25BNx2LAJLfyoBAlo2ctrHZYM3qWGOF9fq3UB/qbz+tTtgPehFrde/dqPEwLDh5M78ACOcpVRYTWZom+HSKcqL7vbEZFLC4T7s5/+mnQOD2XfdP4PrSN9QwmtvcGWlZixhRvpV3Yx5fOOBHfMeJODNbPVoZE9zj47/cGIZzirjy832Fi1ASzXrpdA64ip6LuYpuv1sYNC2XzuZacEpme0cuIVAPkrc0oaKZ7Kwi0Yt2KlncMlUA2S69QokPnBn/cOQh6r+x6PyWpyVljB2+Hy8IoCyJwcD+FR2qi9C+lZvhZs6un4U62d/dfvS29u2ovOB6owC41F1Ntr34RvH5OIhSFVBCbL7XdRVJGUGvOKLfQYxlb4Ua+x1aczW9eVJYpaNqwA/ckGzg378o5LXuWHKwnbRnjln/ZeI06oJaaaljVTtRIYj8WhYnGcsD2R6+xDFYj8V6mzWQp62scJexTvUCtAZUmhQdgjWqwNQpqytXmdRA= X-OriginatorOrg: amd.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 05 Feb 2024 08:34:32.5323 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: b05e9882-afa3-437c-497a-08dc262546fd X-MS-Exchange-CrossTenant-Id: 3dd8961f-e488-4e60-8e11-a82d994e183d X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=3dd8961f-e488-4e60-8e11-a82d994e183d;Ip=[165.204.84.17];Helo=[SATLEXMB04.amd.com] X-MS-Exchange-CrossTenant-AuthSource: SJ5PEPF000001D2.namprd05.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: PH8PR12MB6699 Precedence: Bulk List-Subscribe: List-Help: Sender: devel@edk2.groups.io List-Id: Mailing-List: list devel@edk2.groups.io; contact devel+owner@edk2.groups.io Reply-To: devel@edk2.groups.io,abner.chang@amd.com List-Unsubscribe-Post: List-Unsubscribe=One-Click List-Unsubscribe: X-Gm-Message-State: NEjmlsSka527Kh0VSnNuCuQgx7686176AA= Content-Transfer-Encoding: quoted-printable Content-Type: text/plain X-GND-Status: LEGIT Authentication-Results: spool.mail.gandi.net; dkim=pass header.d=groups.io header.s=20140610 header.b=EMCg2axL; spf=pass (spool.mail.gandi.net: domain of bounce@groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce@groups.io; dmarc=none; arc=reject ("signature check failed: fail, {[1] = sig:microsoft.com:reject}") From: Abner Chang Update Readme file to align with Redfish Client implementation. Signed-off-by: Abner Chang Cc: Nickle Wang Cc: Igor Kulchytskyy --- RedfishClientPkg/Readme.md | 175 +++++++++++++++++++++++++++++++++---- 1 file changed, 160 insertions(+), 15 deletions(-) diff --git a/RedfishClientPkg/Readme.md b/RedfishClientPkg/Readme.md index edef2ec23b..82cb9c8c99 100644 --- a/RedfishClientPkg/Readme.md +++ b/RedfishClientPkg/Readme.md @@ -294,7 +294,7 @@ PCD is set to `TRUE`. The purpose of Redfish feature driver is to do the synchronization job bet= ween Redfish service and BIOS. The operation of synchronization can be simp= ly divided into two types: =20 #### Provisioning resource -Below is the flow diagram of provisioning platform configuration to Redfis= h service at Bios resource. With the x-uefi-redfish +Below is the flow diagram of provisioning platform configuration to Redfis= h service at BIOS resource. With the x-uefi-redfish configure language described in above section, Redfish feature driver coll= ect all BIOS attributes from HII database and populated them to Redfish service. ![provisioning](https://github.com/tianocore/edk2-redfish-client/blob/main= /RedfishClientPkg/Documents/Media/redfish-call-flow-provisioning.svg?raw=3D= true) @@ -311,7 +311,7 @@ job. Several interfaces defined in EDKII Redfish Resource Config Protocol work = together to support Redfish synchronization: - Identify() - This function is used to check if the given Redfish resource is the on= e the feature driver wants to manage. A platform - library `RedfishReesourceIdentifyLib` is introduced for platform to im= plement its own policy to identify Redfish resource. + library `RedfishResourceIdentifyLib` is introduced for platform to imp= lement its own policy to identify Redfish resource. - Check() - This function is used to check the attribute status on Redfish service= . If all attributes the feature driver manages are presented in Redfish service, feature driver must provision them a= lready. Otherwise, Provisioning() will be called @@ -338,19 +338,164 @@ struct _EDKII_REDFISH_RESOURCE_ADDENDUM_PROTOCOL { }; ``` =20 -#### Redfish service implementation -The idea of Redfish synchronization design is to manage Redfish resource d= irectly by platform firmware. To do this, Redfish -synchronization functions have to work with Redfish service implementation= in BMC firmware. This is because the interface -between platform firmware and BMC firmware is not defined in any specifica= tion. -Several prerequisites must be satisfied: -- Platform firmware has permission to manage Redfish resource. BMC has abi= lity to tell the difference between platform request - and out-of-band user. This can normally be done by identifying the boots= trap account in HTTP request. The bootstrap account is - described in Host Interface specification 1.3.0 section 9. -- The ability to tell if there is an user who changes to Redfish resource = or not. Redfish feature drivers can only be executed at - POST time. So the modification to BIOS managed resource is an asynchrono= us operation. Thus, we need below supports in Redfish service: - - ETAG support in HTTP header. - - Setting resource support (defined in Redfish specification 1.18 sectio= n 9.10). - - Redfish Task support to POST and DELETE operation made by user in Redf= ish collection resource and Redfish actions. +### Redfish Service Implementation that Incorporates with EDK2 Redfish +The idea of Redfish synchronization design is to manage Redfish resource d= irectly by platform host +firmware. To do this, Redfish synchronization functions have to work with = Redfish service implementation +in BMC firmware. This is because the mechanism between platform host firmw= are and BMC firmware is not +defined in any specification. Several prerequisites must be satisfied and = listed below: + +**BIOS Redfish Credential** + +- Platform host firmware has the permission to manage Redfish resource. BM= C has ability to distinguish +the in-band platform host firmware and out-of-band user, this can normally= be done by identifying the bootstrap account in HTTP request. The bootstra= p account is described in Host Interface specification 1.3.0 section 9. If = the Redfish client uses bootstrap account for HTTP actions, BMC must consid= er the Redfish +client is BIOS and give the write permission to BIOS for updating BIOS man= aged Redfish properties even the +properties are declared as "ReadOnly" in the Redfish schema. + +**BIOS Managed Redfish Resource Provisioning** +- The Default Empty BIOS Managed Redfish Resource
+ The BIOS managed Redfish properties may not covering the entire resource= but just manages some properties + in the resource or a subset of resource. For example, the "Boot" propert= y in ComputerSystem. BIOS is not able to use HTTP PUT to replace a resource= that is not entirely managed by BIOS. The HTTP PATCH is the only method to= provision the BIOS managed properties. This is a requirement the BIOS mana= ged properties + in the resource must have either a default value or an empty property, w= ith this BIOS can have a HTTP + PATCH to update the value.

+ For the example in ComputerSystem resource below,
+ The "BootOrder" property is exist in ComputerSystem, however the values = is left as empty. With the + existence of "BootOrder", BIOS can provision the valid values using HTTP= PATCH with out error. + +```C +In Redfish Computer System resource: +{ + "Boot": { + "AutomaticRetryAttempts": 3, + "BootOrder": [] + } +} +``` + +- Computer System Bios resource
+The "Bios" property in Computer System resource usually has a "@odata.id" = property that is an +URI points to the BIOS Redfish resource. The "Bios" property must exist in= the computer system +resource and the URI of "Bios" property is required to be provided by BMC = as the default value. +With this, BIOS knows where to provision the BIOS resource. + +```C +In Redfish Computer System resource: +{ + "Bios": { + "@odata.id": "/redfish/v1/Systems/system/Bios" + } +} +``` + +- BIOS AttributeRegistry
+The "AttributeRegistry" is a property in "Bios" resource, which is the res= ource ID of +message registry file that has the system-specific information about a BIO= S resource. +"AttributeRegistry" must exist in "Bios" resource and the value can't be e= mpty if the the +platform support system-specific information BIOS resource. In order to pr= ovision the BIOS +attribute registry resource, BIOS attribute registry must be defined as a = collection member +in the service root "Registries" collection property. The value of "Id" pr= operty in +MessageFileRegistry must be as the same as "AttributeRegistry" value in BI= OS resource. +Also, the "Languages" and "Location" array property must be predefined in = the Redfish message +file. The location URI of message registry file can be determined by BMC. = With this, BIOS can get the resource ID from "AttributeRegistry" property a= nd look for the same ID defined in the +Message File Registry collection for provisioning the entire BIOS Attribut= eRegistry resource. + +```C +In Redfish Computer System Bios resource: +{ + "AttributeRegistry": "BiosAttributeRegistry" +} + +In Service Root Registries resource: +{ + "Members": [ + { + "@odata.id": "/redfish/v1/Registries/BiosAttributeRegistry" + } + ] +} + +In /redfish/v1/Registries/BiosAttributeRegistry: +{ + "Id": "BiosAttributeRegistry", + "Languages": [ + "en" + ], + "Languages@odata.count": 1, + "Location": [ + { + "Language": "en", + "Uri": "/redfish/v1/Registries/Bios" + } + ] +} + +The URI "/redfish/v1/Registries/Bios" is where BIOS to put the BIOS attrib= ute registry resource. +``` + +**BIOS Managed Redfish Resource Consumption** + +The ability to tell if there are the changes on BIOS managed Redfish resou= rce. The modifications to BIOS managed resource is considered as an asynchr= onous operation because the Redfish feature drivers can only be +executed at the platform host firmware POST time. With the above constrain= t, we need the below requirements +on BMC Redfish service. + - ETAG Support in HTTP Header
+ To reduce the unnecessary HTTP GET for the unchanged Redfish resource th= at leads to increase the platform + boot time, ETAG is leveraged to tell BIOS if BIOS has to get the entire = resource as there were some + changes made on the resource. Although ETAG support in HTTP response hea= der is not mandatory by edk2 + Redfish design, it is still a strong recommendation if the platform boot= time is a concern.
+ Below PCD is used to configure the BMC Redfish service supports ETAG. + +```C + gEfiRedfishClientPkgTokenSpaceGuid.PcdRedfishServiceEtagSupported +``` + + - HTTP Query Head Support
+ In order to retrieve the HTTP response headers only to reduce the unnece= ssary HTTP GET for the entire + Redfish resource. HTTP Query Head support on Redfish service is mandator= y if the system boot time is a + concern. + + - Redfish Setting Annotation Support (defined in Redfish specification 1= .18 section 9.10).
+ @Redfish.Settings annotation represents the future state of resource. Th= e future state of BIOS managed + properties will be consume in the next time platform boot, no matter it = is a reset cycle or power cycle.
+ This is a requirement for BMC Redfish service having @Redfish.Settings f= or the changed properties made by + remote user. With the @Redfish.Settings annotation in the resource, BIOS= can identify which Redfish + properties were changed. BIOS can then only consume these changes and a= pply those to BIOS platform + configurations. Without providing @Redfish.Settings for the changes, BIO= S can just consume all of the + BIOS managed properties on Redfish service even the properties weren't c= hanged. + + - ETAG Support in Redfish Setting Annotation
+ ETAG in @Redfish.Settings resource is also required. As @Redfish.Setting= s annotation may not be deleted by + BMC after it has been consumed, the out of date @Redfish.Settings may st= ill leave in the Redfish + resource. With ETAG is provided in @Redfish.Settings, BIOS is able to te= ll if @Redfish.Settings is fresh + or stale.

+ Below is the example of @Redfish.Settings for BIOS attribute change, + +```C + "@Redfish.Settings": { + "@odata.type": "#Settings.v1_3_3.Settings", + "SettingsObject": { + "@odata.id": "/redfish/v1/Systems/1/Bios", + "@odata.etag": "W/\"ABCDEFG\"", + "Attributes": { + "BootMode": "Uefi" + } + } + } +``` + +**Redfish HTTP Content Encoding**
+For the performance consideration when BIOS HTTP POST, PUT and PATCH the r= esource, HTTP Content-Encoding +header is leverage to compress the resource to reduce the payload size wit= h BMC Redfish support. Below PCD string is introduced for platform develope= r to set the encoding method supported by BMC Redfish, currently +only "None" and "gzip" are supported. + +```C + gEfiRedfishPkgTokenSpaceGuid.PcdRedfishServiceContentEncoding|["None"]["= gzip"] +``` + +**BIOS Redfish Action** +- Redfish supports the HTTP POST and DELETE operation
+HTTP POST operation is triggered by BIOS to create a Redfish collection me= mber in the Redfish +collection resource, and also for triggering the Redfish action. For the R= edfish action, such +as loading the BIOS default and Secure boot certification enrollment.
+HTTP DELETE operation is triggered by BIOS to delete a member in the Redfi= sh collection. =20 ### Redfish Task design TBD. --=20 2.37.1.windows.1 -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#115107): https://edk2.groups.io/g/devel/message/115107 Mute This Topic: https://groups.io/mt/104172431/7686176 Group Owner: devel+owner@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [rebecca@openfw.io] -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-