| # EDK2 Manageability Package | |
| edk2 ManageabilityPkg is introduced to provide edk2 drivers and | |
| libraries for industry platform management standards, such as PLDM (Platform | |
| Level Data Model), MCTP (Management Component Transfer Protocol), IPMI | |
| (Intelligent Platform Management Interface) and others. The framework of | |
| ManageabilityPkg is designed to flexibly support the transport interfaces for above | |
| industry standards, the transport interfaces such as KCS or I2C for IPMI, PCI VDM | |
| (Vendor Defined Message), I2C or KCS for MCTP, or the OEM proprietary transports. | |
| Below figure shows the driver stacks which are abstracted to support disparate | |
| transports for specifications of platform management. | |
|  | |
| ## Manageability Transport edk2 Driver Stack | |
| edk2 manageability transport library is designed to incorporated with disparate | |
| manageability protocols. In order to flexibly facilitating the transport | |
| functionalities, below functions must be provided by manageability transport | |
| library to compliant with the framework of ManageabilityPkg design. | |
| * ### ***AcquireTransportSession()*** | |
| edk2 manageability protocol driver invokes this function to acquire the | |
| transport session to transmit manageability packet. The implementation | |
| could reset the transport interface, initial the transport interface | |
| internal structure and the [Manageability Transport Function Structure](#manageability-transport-function-structure). | |
| The [Transport Token](#transfer-token) is returned to the caller for further manageability packet | |
| transmit and receive. | |
| * ### ***GetTransportCapability()*** | |
| edk2 Manageability protocol driver invokes this function to get the capabilities | |
| of transport interface. The implementation of manageability transport library | |
| can optionally support advanced features such as multi-sessions on transport | |
| interface or asynchronous transfer. | |
| * ### ***ReleaseTransportSession()*** | |
| edk2 manageability protocol driver invokes this function to release the transport | |
| session. | |
| ### **Manageability Transport Function Structure** | |
| Below is the function structure initiated by the manageability transport library and | |
| returned in the transport token when caller invokes [AcquireTransportSession](#acquiretransportsession) | |
| function. | |
| ***MANAGEABILITY_TRANSPORT_FUNCTION*** is declared as an union to accommodate | |
| different versions of transport function set. This allows the function added to | |
| support the new functionalities in the future and also keep the backward compatibility. | |
| Developers can not modify the previous version of function structure, instead | |
| developers can create a new function structure with the increased version number | |
| that includes the previous version of function set and new added functions. | |
| ``` | |
| typedef union { | |
| MANAGEABILITY_TRANSPORT_FUNCTION_V1_0 *Version1_0; | |
| } MANAGEABILITY_TRANSPORT_FUNCTION; | |
| struct _MANAGEABILITY_TRANSPORT_FUNCTION_V1_0 { | |
| MANAGEABILITY_TRANSPORT_INIT TransportInit; | |
| MANAGEABILITY_TRANSPORT_STATUS TransportStatus; | |
| MANAGEABILITY_TRANSPORT_RESET TransportReset; | |
| MANAGEABILITY_TRANSPORT_TRANSMIT_RECEIVE TransportTransmitReceive; | |
| }; | |
| ``` | |
| * ***TransportInit()*** | |
| Manageability protocol driver invokes this function to initial the transport | |
| interface with the optional hardware configuration of the transport interface. | |
| Whether the transport interface requires initialization or not depends on the | |
| transport interface characteristics. The hardware information is optional passed to | |
| this function if the manageability protocol driver would like to use the different | |
| hardware configuration of transport interface. For example, the different I/O | |
| address of KCS interface, or the memory mapped I/O KCS interface. The structure | |
| format of hardware information is created according to the hardware design of | |
| transport interface. | |
| * ***TransportStatus()*** | |
| Manageability protocol driver invokes this function to get the status of transport | |
| interface. How does this function report the status depends on the transport | |
| interface characteristics and the implementation of this function. | |
| * ***TransportReset()*** | |
| Manageability protocol driver can invoke this function to reset and recover the | |
| transport interface in case the error status is reported by the transport | |
| interface. Whether the transport interface can be reset or not depends on the | |
| transport interface characteristics and the implementation of this function. | |
| * ***TransportTransmitReceive()*** | |
| Manageability protocol driver invokes this function to transmit and/or receive the | |
| packet. Caller has to setup the [Transfer Token](#transfer-token) when invoke to | |
| this function. | |
| ### **Transfer Token** | |
| ``` | |
| struct _MANAGEABILITY_TRANSFER_TOKEN { | |
| EFI_EVENT ReceiveEvent; | |
| MANAGEABILITY_TRANSPORT_HEADER TransmitHeader; | |
| UINT16 TransmitHeaderSize; | |
| MANAGEABILITY_TRANSPORT_TRAILER TransmitTrailer; | |
| UINT16 TransmitTrailerSize; | |
| MANAGEABILITY_TRANSMIT_PACKAGE TransmitPackage; | |
| MANAGEABILITY_RECEIVE_PACKAGE ReceivePackage; | |
| EFI_STATUS TransferStatus; | |
| MANAGEABILITY_TRANSPORT_ADDITIONAL_STATUS TransportAdditionalStatus; | |
| }; | |
| ``` | |
| * ***ReceiveEvent*** | |
| The optional EFI event is created to wait for the signal of response data | |
| readiness. The parameter is valid only if the transport interface supports | |
| asynchronous transfer. MANAGEABILITY_TRANSPORT_CAPABILITY_ASYNCHRONOUS_TRANSFER bit | |
| must be set in the returned *TransportCapability* parameter in | |
| [GetTransportCapability()](#gettransportcapability) to indicate the | |
| transport interface is capable for asynchronous transfer. | |
| * ***TransmitHeader*** | |
| The transmit header is different according to the disparate transport interfaces | |
| for the manageability protocol. For example, the transmit header is different when | |
| MCTP packet is transmitted over I2C and KCS. Having this header abstracted from | |
| manageability transport library to make the transport implementation agnostic to the | |
| manageability protocol specification. | |
| * ***TransmitHeaderSize*** | |
| This indicates the size of TransmitHeader. | |
| * ***TransmitTrailer*** | |
| The transmit trailer may be different according to the disparate transport | |
| interface for the manageability protocol. Having this header abstracted from | |
| manageability transport library to make the transport implementation agnostic to the | |
| manageability protocol specification. | |
| * ***TransmitTrailerSize*** | |
| This indicates the size of TransmitTrailer. | |
| * ***TransmitPackage*** | |
| The buffer of packet to transmit, this could be a value of NULL if the manageability | |
| protocol is going to harvest the datagram sent by the management entity. | |
| * ***ReceivePackage*** | |
| The receive buffer, this could be a value of NULL if the manageability | |
| protocol is going to send the request to management endpoint which has no response | |
| required. | |
| * ***TransferStatus*** | |
| In order to support both synchronous and asynchronous transfer with a unified | |
| function, ***TransportTransmitReceive()*** is designed as a | |
| non return value function. Instead, the status of transmit/receive is returned | |
| in the transfer token. When the asynchronous transfer, manageability transport | |
| library has to set the status in transfer token before signal ***ReceiveEvent***. | |
| * ***TransportAdditionalStatus*** | |
| The additional transport status after the transfer. | |
| ## Industry Standard Manageability Protocol edk2 Driver Stack | |
| The edk2 implementation of industry manageability standards such as IpmiProtocol and | |
| MctpProtocol abstract the command layer and provide the unified protocol interface to | |
| build up the manageability packet for subordinate specifications. edk2 manageability | |
| protocol driver is linked with desired manageability transport library base on the | |
| platform design. | |
| ## Transport Implementation | |
| The manageability transport library could have the implementation in library or | |
| invoke the existing edk2 protocol which is defined in UEFI or PI specifications. | |
| This is the implementation decision made by the developer when introduce a new | |
| manageability transport library. |