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 D61F6AC0D9B for ; Mon, 5 Feb 2024 07:49:31 +0000 (UTC) DKIM-Signature: a=rsa-sha256; bh=WHtvgkNmSzrVyA/Qsc+p5V4U72AG52qvYHMi47MX240=; 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=1707119370; v=1; b=HYkeSOB6Ftx8Uj7jQurrvskLZ6R4FLShS4NddP5xT1CFLNrWTK41kIvMijP7jskwm/SRUnEj Ov3eHqx3eEwNkzM5pWvBgFZIOHbmSUqTAmYgFv4MR62h562aQf4gUv3kH2pLyAt1+4/H0MvTYTc C55xM4ymoIgqdf13Y3QGHzz4= X-Received: by 127.0.0.2 with SMTP id PRIKYY7687511xOuVk6ZkWHl; Sun, 04 Feb 2024 23:49:30 -0800 X-Received: from NAM10-MW2-obe.outbound.protection.outlook.com (NAM10-MW2-obe.outbound.protection.outlook.com [40.107.94.53]) by mx.groups.io with SMTP id smtpd.web10.58556.1707119369725723728 for ; Sun, 04 Feb 2024 23:49:30 -0800 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=kDRS/Bhxv0KIgZ8dk5ffYlmN3kDEW2qsrb/sVcctyzt3wCbMXg/qJYfKt+gw47DfSmsM0DruDZqUcOesmCTATGU2vKi2Sivy/BRum25ok0uXTnoVX/XVaXsdzc4YImvwHQERWTn6BKXxeAui2KDhHEzRkDrCYmCmGDJqmuZmHeaNTwcW5plV+y5MFpKe6FAv36fFWA73tDE1ShWqKGfuYqAYQF0VYLndIk+VDqdcBhgcflJNWizX1bIVURYlqVwBRbp8kXcOD23Q1mv00I1VpcHaqnTwl3MfrwLjwzs2ACjUhwoha/pflDJgH28IGPCm9tJl2N+gyiYFQ7Hia8cDNQ== 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=d7evOZK/aEYxgrd3wjeKsgk96z1rp6cGTeh2YhcdbpQ=; b=jT2oqesCNfC0epdB6kOl6cbMhs/IqEcGCInrPpiqdj3qxOJnXhQL45zn/sUx8PP5mDNRTREkhUvzrQRHGtFRU+1rlQAxslK7fPvXcRnJHbW9BnKl/PGctypcLOdFyFNjTTGSL8rrvF4abuXpNTEQ+JL2wmjIvpUDGZpM56qg0ZCCYlZfFUyMVRmxiGuwNWped9/9PxeL/KoRFCDmjIht0TxcN/SB92IwJwULnmPDyJryTuHaq715tsNA0TXLa5VST1cfMst/QBEvziTP3kt0q2S6d9z77gY/sS67JnEBrgCy7Mnax4T1TDL3ef5Ote3FlozXUeorVwp4gc3ZqgfkcA== 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 SA0PR11CA0056.namprd11.prod.outlook.com (2603:10b6:806:d0::31) by SA3PR12MB7807.namprd12.prod.outlook.com (2603:10b6:806:304::22) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.7270.17; Mon, 5 Feb 2024 07:49:27 +0000 X-Received: from SN1PEPF00026369.namprd02.prod.outlook.com (2603:10b6:806:d0:cafe::6b) by SA0PR11CA0056.outlook.office365.com (2603:10b6:806:d0::31) 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 07:49:27 +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 SN1PEPF00026369.mail.protection.outlook.com (10.167.241.134) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.20.7249.19 via Frontend Transport; Mon, 5 Feb 2024 07:49:27 +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 01:49:25 -0600 From: "Chang, Abner via groups.io" To: CC: Nickle Wang , Igor Kulchytskyy Subject: [edk2-devel] [edk2-redfish-client][PATCH V2] RedfishClientPkg: Readme.md update Date: Mon, 5 Feb 2024 15:49:14 +0800 Message-ID: <20240205074914.1571-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: SN1PEPF00026369:EE_|SA3PR12MB7807:EE_ X-MS-Office365-Filtering-Correlation-Id: b8618364-4b53-47b5-6fe6-08dc261efa5c X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam-Message-Info: 1AC8CVKIKalICUrTU1Fq8YIY5HrPN0OG5P59mBOmH+Oav9ooADRMSCiEPA+tI6ZDQg+scdgh0G7rQVS9/Ilg9AzaC1YtpOZeuGsVD9pg08mjCQqobGkcnYk78t8GXMQ06m/9gRI2DxzoHzpnTNTMqvfpsO9Zbl23iYToU+VbubBFo6EfDnRrIhJRBYadeBRwTvGxu6hlhKRkh+UJC6KGUz7SKvi/hrFV2DxgXAbUUR+rsZAcLFanWBHqnlDLb9rU5cQkF5+fCDDZ7GOrdRPNrgBRfkU9IaEBalMYHtB01ZDoJOtQuk5CHF5BAwYdl3A5v8DEzJT0hV67Thtlcp2dlwrs7LcMXK0PhDUa6quIjhCqcm6Dhyxc21p737LzY8AAFtOKOnyRWulzZPh3KKbGc46tewDw9VA1ZCm7R/KKxj7fPId1PrxcFs3WQ6MECxdntIkbnb3SVsxAHl6hE4DsSCs1lWEKxXYz2gIDxaGcFbd3vCX95i5DSdFMAJJnymmFdAnfQdOH3+3xHWYpHuEJT/2jBUYMHo2z4seU6+77X7mKnZLju/smO83bLBPT8HhcHnAJ7deRYx6S6WsHTNqxEKqYavz7dLU/ATToyYZDiDr5KHOC1i83GFnp+y8bkPFIIgiVD9ubVnQYCRwN3XxDm9JK+rfLuen1alOVJK+LTWQSgN0wgXdxIG0ivEMIho/tgEVe3qHCod17EPiky4OZCbINaEFQSjfLThv36glE52eO91DiO2MojqbwQHeuDlYOp/2v6dJz1cSTgfspOi9yeg== X-OriginatorOrg: amd.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 05 Feb 2024 07:49:27.0379 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: b8618364-4b53-47b5-6fe6-08dc261efa5c 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: SN1PEPF00026369.namprd02.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: SA3PR12MB7807 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: ReLpviVudnbNaKUvVbeB0Kkax7686176AA= 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=HYkeSOB6; arc=reject ("signature check failed: fail, {[1] = sig:microsoft.com:reject}"); dmarc=none; spf=pass (spool.mail.gandi.net: domain of bounce@groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce@groups.io 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 | 171 +++++++++++++++++++++++++++++++++---- 1 file changed, 156 insertions(+), 15 deletions(-) diff --git a/RedfishClientPkg/Readme.md b/RedfishClientPkg/Readme.md index edef2ec23b..23ca160a5a 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,160 @@ 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 Task support to POST and DELETE operation made by user in Redfi= sh collection resource and Redfish actions. =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 (#115101): https://edk2.groups.io/g/devel/message/115101 Mute This Topic: https://groups.io/mt/104172106/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-