Re: [edk2-devel] [PATCH v3 1/8] ManageabilityPkg: Add Readme file

["Leif Lindholm" <quic_llindhol@quicinc.com>]

Minor nit:

On Tue, Mar 21, 2023 at 11:21:06 +0800, Chang, Abner via groups.io wrote:
> From: Abner Chang <abner.chang@amd.com>
> 
> Add Readme file of edk2 platform ManageabilityPkg.
> 
> Signed-off-by: Abner Chang <abner.chang@amd.com>
> Cc: Liming Gao <gaoliming@byosoft.com.cn>
> Cc: Isaac Oram <isaac.w.oram@intel.com>
> Cc: Nate DeSimone <nathaniel.l.desimone@intel.com>
> Cc: Nickle Wang <nicklew@nvidia.com>
> Cc: Igor Kulchytskyy <igork@ami.com>
> Cc: Abdul Lateef Attar <abdattar@amd.com>
> Reviewed-by: Abdul Lateef Attar <AbdulLateef.Attar@amd.com>
> Reviewed-by: Nickle Wang <nicklew@nvidia.com>
> ---
>  Features/ManageabilityPkg/Readme.md           | 177 +++++
>  .../Media/ManageabilityDriverStack.svg        | 752 ++++++++++++++++++
>  2 files changed, 929 insertions(+)
>  create mode 100644 Features/ManageabilityPkg/Readme.md
>  create mode 100644 Features/ManageabilityPkg/Documents/Media/ManageabilityDriverStack.svg
> 
> diff --git a/Features/ManageabilityPkg/Readme.md b/Features/ManageabilityPkg/Readme.md
> new file mode 100644
> index 0000000000..b56ffb8a86
> --- /dev/null
> +++ b/Features/ManageabilityPkg/Readme.md
> @@ -0,0 +1,177 @@
> +# 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](https://github.com/tianocore/edk2-platforms/blob/master/Features/ManageabilityPkg/Documents/Media/ManageabilityDriverStack.svg)
> +
> +## 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;
> +      MANAGEABILITY_TRANSPORT_TRAILER            TransmitTrailer;
> +      MANAGEABILITY_TRANSMIT_PACKAGE             TransmitPackage;
> +      MANAGEABILITY_RECEIVE_PACKAGE              ReceivePackage;
> +      EFI_STATUS                                 TransferStatus;
> +      MANAGEABILITY_TRANSPORT_ADDITIONAL_STATUS  TransportAdditionalStatus;
> +};

indentation of curly brace.

/
    Leif