Abner Chang d34cfa0d0e ManageabilityPkg: Add IpmiProtocol to Manageability Package 1 year ago
..
Documents 4a0ab22de6 ManageabilityPkg: Add Readme file 1 year ago
Include d34cfa0d0e ManageabilityPkg: Add IpmiProtocol to Manageability Package 1 year ago
Library 12aa3bd76a ManageabilityPkg/ManageabilityTransportKcsLib 1 year ago
Universal d34cfa0d0e ManageabilityPkg: Add IpmiProtocol to Manageability Package 1 year ago
ManageabilityPkg.dec 2844929d73 ManageabilityPkg: Add ManageabilityTransportHelperLib 1 year ago
ManageabilityPkg.dsc 12aa3bd76a ManageabilityPkg/ManageabilityTransportKcsLib 1 year ago
Readme.md 4a0ab22de6 ManageabilityPkg: Add Readme file 1 year ago

Readme.md

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 Package Driver Stack

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. The Transport 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 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 when invoke to this function.

### Transfer Token

    struct _MANAGEABILITY_TRANSFER_TOKEN {
      EFI_EVENT                                  ReceiveEvent;
      MANAGEABILITY_TRANSPORT_HEADER             TransmitHeader;
      MANAGEABILITY_TRANSPORT_TRAILER            TransmitTrailer;
      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() 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.

  • 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.

  • 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.

Build the Manageability Package

In order to use the modules provided by ManageabilityPkg, PACKAGES_PATH must contains the path to point to edk2-platform Features:

$ export PACKAGES_PATH=$PWD/edk2:$PWD/edk2-platforms:$PWD/edk2-platforms/Features