sravan/system76-edk2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

RedfishPkg: Update Readme.md

Browse Source 
Update readme.md and add figures to delineate the
relationship of edk2 Redfish, USB NIC and IPMI.

Signed-off-by: Abner Chang <abner.chang@amd.com>
Cc: Nickle Wang <nicklew@nvidia.com>
Cc: Igor Kulchytskyy <igork@ami.com>
Reviewed-by: Nickle Wang <nicklew@nvidia.com>
This commit is contained in:
Abner Chang
2023-01-07 23:23:37 +08:00
committed by mergify[bot]
parent f077bff840
commit b7a8264ae4
4 changed files with 1000 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

110
RedfishPkg/Readme.md
View File

@@ -50,12 +50,107 @@ The library is incorporated with RedfishLib ***[[13]](#[0])*** to encode and dec
* **RedfishPkg\Library\JsonLib** ***[[14]](#[0])***
This is the wrapper of open source project ***[Jansson](https://digip.org/jansson)***, which is the library that provides APIs to manipulate JSON payload.
## Platform Components for EDK2 EmulatorPkg:
* **RedfishPlatformCredentialLib**
the EDK2 Emulator platform implementation of acquiring credential to build up the communication between UEFI firmware and Redfish service. ***[[10]](#[0])***
## Platform Components
### **EDK2 EmulatorPkg**
![EDK2 EmulatorPkg Figure](https://github.com/tianocore/edk2/blob/master/RedfishPkg/Documents/Media/EmualtorPlatformLibrary.svg?raw=true)
* **RedfishPlatformHostInterfaceLib**
EDK2 Emulator platform implementation which provides the information of building up SMBIOS type 42h record. ***[[11]](#[0])***
* **RedfishPlatformCredentialLib** <br>
The EDK2 Emulator platform implementation of acquiring credential to build up the communication between
UEFI firmware and Redfish service. ***[[10]](#[0])***
The Redfish credential is hardcoded in the EmulatorPkg RedfishPlatformCredentialLib. The credential is
used to access to the Redfish service hosted by [Redfish Profile Simulator](https://github.com/DMTF/Redfish-Profile-Simulator).
* **RedfishPlatformHostInterfaceLib**<br>
EDK2 Emulator platform implementation which provides the information of building up SMBIOS type 42h
record. ***[[11]](#[0])***
EmulatorPkg RedfishPlatformHostInterfaceLib library consumes the EFI Variable which is created
by [RedfishPlatformConfig EFI application](https://github.com/tianocore/edk2/tree/master/EmulatorPkg/Application/RedfishPlatformConfig). RedfishPlatformConfig EFI application stores not all of SMBIOS
Type42 record information but the necessary network properties of Redfish Host Interface in EFI
Variable.
### **Platform with BMC and the BMC-Exposed USB Network Device**
![Platform with BMC Figure](https://github.com/tianocore/edk2/blob/master/RedfishPkg/Documents/Media/BmcExposedUsbNic.svg?raw=true)
Server platform with BMC as the server management entity may expose the [USB Network Interface Device (NIC)](https://www.usb.org/document-library/class-definitions-communication-devices-12)
to the platform, which is so called the in-band host-BMC transport interface. The USB NIC exposed by BMC is
usually a link-local network device which has two network endpoints at host and BMC ends. The endpoint at
host side is connected to the platform USB port, and it is enumerated by edk2 USB BUS driver. The edk2 USB
NIC driver then produces the **EFI Network Interface Identifier Protocol**
*(EFI_NETWORK_INTERFACE_IDENTIFIER_PROTOCOL_GUID_31)* and connected by EFI Simple
Network Protocol (SNP) driver and the upper layer edk2 network drivers. The applications can then utilize
the network stack built up on top of USB NIC to communicate with Redfish service hosted by BMC.<br>
BMC-exposed USB NIC is mainly designed for the communication between host and BMC-hosted Redfish service.
BMC-exposed USB NIC can be public to host through [Redfish Host Interface Specification](https://www.dmtf.org/sites/default/files/standards/documents/DSP0270_1.3.0.pdf) and discovered by edk2 Redfish discovery
driver. The [Redfish Host Interface Specification](https://www.dmtf.org/sites/default/files/standards/documents/DSP0270_1.3.0.pdf) describes the dedicated host interface between host and
BMC. The specification follows the [SMBIOS Type 42 format](https://www.dmtf.org/sites/default/files/standards/documents/DSP0134_3.6.0.pdf) and defines the host interface as:
- Network Host Interface type (40h)
- Redfish over IP Protocol (04h)
<br>
![Platform BMC Library Figure](https://github.com/tianocore/edk2/blob/master/RedfishPkg/Documents/Media/PlatformWihtBmcLibrary.svg?raw=true)
* **RedfishPlatformCredentialLib** <br>
RedfishPlatformCredentialLib library instance on the platform with BMC uses Redfish Credential
Bootstrapping IPMI commands defined in [Redfish Host Interface Specification](https://www.dmtf.org/sites/default/files/standards/documents/DSP0270_1.3.0.pdf) to acquire the Redfish credential from BMC. edk2
Redfish firmware then uses this credential to access to Redfish service hosted by BMC.
* **RedfishPlatformHostInterfaceLib** <br>
BMC-exposed USB NIC, a IPMI Message channel is reported by BMC as a "IPMB-1.0" protocol and "802.3 LAN"
medium channel. edk2 firmware can issue a series of IPMI commands to acquire the channel
application information (NetFn App), transport network properties (NetFn Transport) and other necessary
information to build up the SMBIOS type 42h record. <be>
In order to recognize the specific BMC-exposed USB NIC in case the platform has more than one USB NIC
devices attached, the MAC address specified in the EFI Device Path Protocol of SNP EFI handle is used to
match with the MAC address of IPMI message channel. Due to the network information such as the MAC
address, IP address, Subnet mask and Gateway are assigned by BMC, edk2 Redfish implementation needs a
programmatic way to recognize the BMC-exposed USB NIC.
* **MAC address:** Searching for the BMC-exposed USB NIC<br>
The last byte of host-end USB NIC MAC address is the last byte of BMC-end USB NIC MAC address minus 1.
RedfishPlatformHostInterfaceLib issues the NetFn Transport IPMI command to get the MAC address of each
channel and checks them with the MAC address specified in the EFI Device Path Protocol.<br>
**_For example:_**<br>
BMC-end USB NIC MAC address: 11-22-33-44-55-00<br>
Host-end USB NIC MAC address: 11-22-33-44-55-ff
* **IP Address:** Acquiring the host-end USB NIC IP Address<br>
The last byte of host-end USB NIC IPv4 address is the last byte of BMC-end USB NIC IPv4 address minus 1.
**_For example:_**<br>
BMC-end USB NIC IPv4 address: 165.10.0.10<br>
Host-end USB NIC IPv4 address: 165.10.0.9
* **Other Network Properties**: <br>
Due to the host-end USB NIC and BMC-end USB NIC is a link-local network. Both of them have the same
network properties such as subnet mask and gateway. RedfishPlatformHostInterfaceLib issues the NetFn
Transport IPMI command to get the network properties of BMC-end USB NIC and apply it on host-end USB
NIC.
* **IPMI Commands that Used to Build up Redfish Host Interface**
Standard IPMI commands those are used to build up the Redfish Host Interface for BMC-exposed USB NIC.
The USB NIC exposed by BMC must be reported as one of the message channels as 802.3 LAN/IPMB 1.0 message
channel.
| IPMI NetFn | IPMI Command| Purpose | Corresponding Host Interface Field|
|------------|-------------|---------|-----------------------------------|
| App<br>(0x06) | 0x42 | Check the message channel's medium type and protocol.<br>Medium: 802.3 LAN<br>Protocol: IPMB 1.0| None|
| Transport<br>(0x0C) | 0x02 | Get MAC address of message channel. Used to match with the MAC address populated in EFI Device Path of network device| None|
| Group Ext<br>(0x2C) | Group Extension ID: 0x52<br>Command: 0x02 | Check if Redfish bootstrap credential is supported or not.| In Device Descriptor Data, Credential Bootstrapping Handle|
| Transport<br>(0x0C) | Command: 0x02<br>Parameter: 0x04 | Get BMC-end message channel IP address source| In Protocol Specific Record Data<br>- Host IP Assignment Type<br>- Redfish Service IP Discovery Type<br>- Generate the Host-side IP address|.
| Transport<br>(0x0C) | Command: 0x02<br>Parameter: 0x03 | Get BMC-end message channel IPv4 address| In Protocol Specific Record Data<br>- Host IP Address Format<br>- Host IP Address|
| Transport<br>(0x0C) | Command: 0x02<br>Parameter: 0x06 | Get BMC-end message channel IPv4 subnet mask| In Protocol Specific Record Data<br>- Host IP Mask<br>- Redfish Service IP Mask|
| Transport<br>(0x0C) | Command: 0x02<br>Parameter: 0x12 | Get BMC-end message channel gateway IP address| None, used to configure edk2 network configuration|
| Transport<br>(0x0C) | Command: 0x02<br>Parameter: 0x14 | Get BMC-end message channel VLAN ID| In Protocol Specific Record Data<br> Redfish Service VLAN ID|
**__NOTE__**
```
Current RedfishPlatformHostInterfaceLib implementation of BMC-exposed USB NIC can only support IPv4 address format.
```
## Miscellaneous:
@@ -65,7 +160,6 @@ The library is incorporated with RedfishLib ***[[13]](#[0])*** to encode and dec
For example, run shell command "RedfishPlatformConfig.efi -s 192.168.10.101 255.255.255.0 192.168.10.123 255.255.255.0", which means
the source IP address is 192.168.10.101, and the Redfish Server IP address is 192.168.10.123.
```
* **Redfish Profile Simulator**
Refer to [Redfish Profile Simulator](https://github.com/DMTF/Redfish-Profile-Simulator) to set up the Redfish service.
We are also in the progress to contribute bug fixes and enhancements to the mainstream Redfish Profile Simulator in order to incorporate with EDK2 Redfish solution.
@@ -121,7 +215,9 @@ The library is incorporated with RedfishLib ***[[13]](#[0])*** to encode and dec
1. [DSP0270](https://www.dmtf.org/sites/default/files/standards/documents/DSP0270_1.3.0.pdf) - Redfish Host Interface Specification, 1.3.0
2. [DSP0266](https://www.dmtf.org/sites/default/files/standards/documents/DSP0266_1.12.0.pdf) - Redfish Specification, 1.12.0
3. Redfish Schemas - https://redfish.dmtf.org/schemas/v1/
4. UEFI Specification - http://uefi.org/specifications
4. SMBIOS - https://www.dmtf.org/sites/default/files/standards/documents/DSP0134_3.6.0.pdf
5. USB CDC - https://www.usb.org/document-library/class-definitions-communication-devices-12
6. UEFI Specification - http://uefi.org/specifications
## The Contributors
Thanks to the below predecessors who contributed to the UEFI EDK2 Redfish Prove of Concept code.\