RedfishPkg: Update Readme.md

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>

1 files changed, 104 insertions, 8 deletions

diff --git a/RedfishPkg/Readme.md b/RedfishPkg/Readme.md
index a0e9f0892c..7defe78eb1 100644
--- a/RedfishPkg/Readme.md
+++ b/RedfishPkg/Readme.md
@@ -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])***

-

-  * **RedfishPlatformHostInterfaceLib**

-  EDK2 Emulator platform implementation which provides the information of building up SMBIOS type 42h record. ***[[11]](#[0])***

+## Platform Components

+### **EDK2 EmulatorPkg**

+![EDK2 EmulatorPkg Figure](https://github.com/tianocore/edk2/blob/master/RedfishPkg/Documents/Media/EmualtorPlatformLibrary.svg?raw=true)

+

+  * **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.\