Re: [PATCH v4 3/9] ManageabilityPkg: Add ManageabilityTransportLib header file

["Attar, AbdulLateef (Abdul Lateef)" <AbdulLateef.Attar@amd.com>]

[AMD Official Use Only - General]

Some comments inline.

-----Original Message-----
From: Chang, Abner <Abner.Chang@amd.com>
Sent: 22 March 2023 08:19
To: devel@edk2.groups.io
Cc: Liming Gao <gaoliming@byosoft.com.cn>; Isaac Oram <isaac.w.oram@intel.com>; Nate DeSimone <nathaniel.l.desimone@intel.com>; Nickle Wang <nicklew@nvidia.com>; Igor Kulchytskyy <igork@ami.com>; Attar, AbdulLateef (Abdul Lateef) <AbdulLateef.Attar@amd.com>
Subject: [PATCH v4 3/9] ManageabilityPkg: Add ManageabilityTransportLib header file

From: Abner Chang <abner.chang@amd.com>

Add ManageabilityTransportLib header file to package.

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>
---
 .../ManageabilityPkg/ManageabilityPkg.dec     |   5 +
 .../Library/ManageabilityTransportLib.h       | 336 ++++++++++++++++++
 2 files changed, 341 insertions(+)
 create mode 100644 Features/ManageabilityPkg/Include/Library/ManageabilityTransportLib.h

diff --git a/Features/ManageabilityPkg/ManageabilityPkg.dec b/Features/ManageabilityPkg/ManageabilityPkg.dec
index 71bd8a0c80..92ba4538c0 100644
--- a/Features/ManageabilityPkg/ManageabilityPkg.dec
+++ b/Features/ManageabilityPkg/ManageabilityPkg.dec
@@ -17,5 +17,10 @@
 [Includes]
   Include

+[LibraryClasses]
+  ##  @libraryclass Manageability Transport Library
+  #   Manageability Transport Library definitions
+  ManageabilityTransportLib|Include/Library/ManageabilityTransportLib.h
+
 [Guids]
   gManageabilityPkgTokenSpaceGuid = { 0xBDEFFF48, 0x1C31, 0x49CD, { 0xA7, 0x6D, 0x92, 0x9E, 0x60, 0xDB, 0xB9, 0xF8 } } diff --git a/Features/ManageabilityPkg/Include/Library/ManageabilityTransportLib.h b/Features/ManageabilityPkg/Include/Library/ManageabilityTransportLib.h
new file mode 100644
index 0000000000..c022b4ac5c
--- /dev/null
+++ b/Features/ManageabilityPkg/Include/Library/ManageabilityTransportLi
+++ b.h
@@ -0,0 +1,336 @@
+/** @file
+
+  This file defines the manageability transport interface library and functions.
+
+  Copyright (C) 2023 Advanced Micro Devices, Inc. All rights
+reserved.<BR>
+  SPDX-License-Identifier: BSD-2-Clause-Patent **/
+
+#ifndef MANAGEABILITY_TRANSPORT_LIB_H_
+#define MANAGEABILITY_TRANSPORT_LIB_H_
+
+#define MANAGEABILITY_TRANSPORT_TOKEN_VERSION_MAJOR  1 #define
+MANAGEABILITY_TRANSPORT_TOKEN_VERSION_MINOR  0
+#define MANAGEABILITY_TRANSPORT_TOKEN_VERSION        ((MANAGEABILITY_TRANSPORT_TOKEN_VERSION_MAJOR << 8) |\
+
+MANAGEABILITY_TRANSPORT_TOKEN_VERSION_MINOR)
+
+typedef struct  _MANAGEABILITY_TRANSPORT_FUNCTION_V1_0  MANAGEABILITY_TRANSPORT_FUNCTION_V1_0;
+typedef struct  _MANAGEABILITY_TRANSPORT                MANAGEABILITY_TRANSPORT;
+typedef struct  _MANAGEABILITY_TRANSPORT_TOKEN          MANAGEABILITY_TRANSPORT_TOKEN;
+typedef struct  _MANAGEABILITY_TRANSFER_TOKEN           MANAGEABILITY_TRANSFER_TOKEN;
+
+///
+/// Optional transport header and trailer required /// for the
+transport interface.
+///
+typedef VOID  *MANAGEABILITY_TRANSPORT_HEADER; typedef VOID
+*MANAGEABILITY_TRANSPORT_TRAILER;
+
+///
+/// The transport interface specific hardware information.
+///
+
+typedef union {
+  UINT16    IoAddress16;
+  UINT32    IoAddress32;
+} MANAGEABILITY_TRANSPORT_HARDWARE_IO;
+
+///
+/// Manageability KCS protocol interface hardware information.
+///
+typedef struct {
+  BOOLEAN                                MemoryMap;
+  MANAGEABILITY_TRANSPORT_HARDWARE_IO    IoBaseAddress;
+  MANAGEABILITY_TRANSPORT_HARDWARE_IO    IoDataInAddress;
+  MANAGEABILITY_TRANSPORT_HARDWARE_IO    IoDataOutAddress;
+  MANAGEABILITY_TRANSPORT_HARDWARE_IO    IoCommandAddress;
+  MANAGEABILITY_TRANSPORT_HARDWARE_IO    IoStatusAddress;
+} MANAGEABILITY_TRANSPORT_KCS_HARDWARE_INFO;
+#define MANAGEABILITY_TRANSPORT_KCS_IO_MAP_IO      FALSE
+#define MANAGEABILITY_TRANSPORT_KCS_MEMORY_MAP_IO  TRUE
+
+typedef union {
+  VOID                                         *Pointer;
+  MANAGEABILITY_TRANSPORT_KCS_HARDWARE_INFO    *Kcs;
+} MANAGEABILITY_TRANSPORT_HARDWARE_INFORMATION;
+
+///
+/// Additional transport interface status.
+///
+typedef UINT32 MANAGEABILITY_TRANSPORT_ADDITIONAL_STATUS;
+#define MANAGEABILITY_TRANSPORT_ADDITIONAL_STATUS_NO_ERRORS      0x00000000
+#define MANAGEABILITY_TRANSPORT_ADDITIONAL_STATUS_ERROR          0x00000001
+#define MANAGEABILITY_TRANSPORT_ADDITIONAL_STATUS_BUSY_IN_READ   0x00000002
+#define MANAGEABILITY_TRANSPORT_ADDITIONAL_STATUS_BUSY_IN_WRITE
+0x00000004 #define
+MANAGEABILITY_TRANSPORT_ADDITIONAL_STATUS_NOT_AVAILABLE  0xffffffff
+
+///
+/// Additional transport interface features.
+///
+typedef UINT32 MANAGEABILITY_TRANSPORT_CAPABILITY;
+#define MANAGEABILITY_TRANSPORT_CAPABILITY_MULTIPLE_TRANSFER_TOKENS  0x00000001
+#define MANAGEABILITY_TRANSPORT_CAPABILITY_ASYNCHRONOUS_TRANSFER     0x00000002
+
+///
+/// Definitions of Manageability transport interface functions.
+/// This is a union that can accommodate the new functions ///
+introduced to the Manageability transport library in the future.
+/// The new added function must has its own
+MANAGEABILITY_TRANSPORT_FUNCTION /// structure with the incremental version number.
+///   e.g., MANAGEABILITY_TRANSPORT_FUNCTION_V1_1.
+///
+/// The new function must be added base on the last version of ///
+MANAGEABILITY_TRANSPORT_FUNCTION to keep the backward compatability.
+///
+typedef union {
+  MANAGEABILITY_TRANSPORT_FUNCTION_V1_0    *Version1_0;
+} MANAGEABILITY_TRANSPORT_FUNCTION;
+
+///
+/// Manageability specification GUID/Name table structure /// typedef
+struct {
+  EFI_GUID    *SpecificationGuid;
+  CHAR16      *SpecificationName;
+} MANAGEABILITY_SPECIFICATION_NAME;
+
+///
+/// Definitions of Transmit/Receive package /// typedef struct {
+  UINT8     *TransmitPayload;
+  UINT32    TransmitSizeInByte;
+  UINT32    TransmitTimeoutInMillisecond;
+} MANAGEABILITY_TRANSMIT_PACKAGE;
+
+typedef struct {
+  UINT8     *ReceiveBuffer;
+  UINT32    ReceiveSizeInByte;
+  UINT32    TransmitTimeoutInMillisecond;
+} MANAGEABILITY_RECEIVE_PACKAGE;
+
+///
+/// Definitions of Manageability transport interface.
+///
+struct _MANAGEABILITY_TRANSPORT {
+  EFI_GUID                            *ManageabilityTransportSpecification; ///< The Manageability Transport Interface spec.
+  UINT16                              TransportVersion;                     ///< The version of transport interface
+                                                                            ///< function that indicates which version
+                                                                            ///< of MANAGEABILITY_TRANSPORT_FUNCTION
+                                                                            ///< is unsupported by this library.
+  CHAR16                              *TransportName;                       ///< Human readable string of
+                                                                            ///< this transport interface.
+  MANAGEABILITY_TRANSPORT_FUNCTION    Function;                             ///< Transport functions
+};
+
+///
+/// Definitions of Manageability transport token.
+///
+struct _MANAGEABILITY_TRANSPORT_TOKEN {
+  EFI_GUID                   *ManageabilityProtocolSpecification; ///< The Manageability Protocol spec.
+  MANAGEABILITY_TRANSPORT    *Transport;
+};
+
+#define MANAGEABILITY_TRANSPORT_NO_TIMEOUT  0
+
+///
+/// The Manageability transport receive token used to receive /// the
+response from transport interface after transmitting the /// request.
+///
+struct _MANAGEABILITY_TRANSFER_TOKEN {
+  EFI_EVENT    ReceiveEvent;                                              ///< The EFI event is created to
+                                                                          ///< wait the signal for the readiness
+                                                                          ///< of response data.
+                                                                          ///< If NULL, transport library should
+                                                                          ///< just return the response data in
+                                                                          ///< ReceiveBuffer then the process returns
+                                                                          ///< to caller. Otherwise the transport
+                                                                          ///< library can signal event when the
+                                                                          ///< response is ready for caller. That
+                                                                          ///< means the transport library can
+                                                                          ///< optionally implement the asynchronous
+                                                                          ///< transfer mechanism or when the multiple
+                                                                          ///< transport sessions are acquired.
+  MANAGEABILITY_TRANSPORT_HEADER               TransmitHeader;            ///< This is the transport-specific header
+                                                                          ///< which is sent discretely of payload.
+                                                                          ///< This field can be NULL if the transport
+                                                                          ///< doesn't require this.
+  MANAGEABILITY_TRANSPORT_TRAILER              TransmitTrailer;           ///< This is the transport-specific trailer
+                                                                          ///< which is sent discretely of payload.
+                                                                          ///< This field can be NULL if the transport
+                                                                          ///< doesn't require this.
+  MANAGEABILITY_TRANSMIT_PACKAGE               TransmitPackage;           ///< The payload sent to transport interface.
+  MANAGEABILITY_RECEIVE_PACKAGE                ReceivePackage;            ///< The buffer to receive the response.
+  EFI_STATUS                                   TransferStatus;            ///< The EFI Status of the transfer.
+  MANAGEABILITY_TRANSPORT_ADDITIONAL_STATUS    TransportAdditionalStatus; ///< The additional status of transport
+                                                                          ///< interface.
+};
+
+/**
+  This function acquires to create a transport session to transmit
+manageability
+  packet. A transport token is returned to caller for the follow up operations.
+
+  @param [in]   ManageabilityProtocolSpec  The protocol spec the transport interface is acquired for.
+  @param [out]  TransportToken             The pointer to receive the transport token created by
+                                           the target transport interface library.
+  @retval       EFI_SUCCESS                Token is created successfully.
+  @retval       EFI_OUT_OF_RESOURCES       Out of resource to create a new transport session.
+  @retval       EFI_UNSUPPORTED            Protocol is not supported on this transport interface.
+  @retval       Otherwise                  Other errors.
+
+**/
+EFI_STATUS
[Abdul] EFIAPI is missing.
+AcquireTransportSession (
+  IN  EFI_GUID                       *ManageabilityProtocolSpec,
+  OUT MANAGEABILITY_TRANSPORT_TOKEN  **TransportToken
+  );
+
+/**
+  This function returns the transport capabilities.
+
+  @param [out]  TransportFeature        Pointer to receive transport capabilities.
+                                        See the definitions of
+                                        MANAGEABILITY_TRANSPORT_CAPABILITY.
+
+**/
+VOID
[Abdul] EFIAPI is missing.
+GetTransportCapability (
+  OUT MANAGEABILITY_TRANSPORT_CAPABILITY  *TransportCapability
+  );
+
+/**
+  This function releases the manageability transport session.
+
+  @param [in]  TransportToken   The transport token acquired through
+                                AcquireTransportSession.
+  @retval      EFI_SUCCESS      Token is released successfully.
+  @retval      EFI_INVALID_PARAMETER  Invalid TransportToken.
+  @retval      Otherwise        Other errors.
+
+**/
+EFI_STATUS
[Abdul] EFIAPI is missing.
+ReleaseTransportSession (
+  IN MANAGEABILITY_TRANSPORT_TOKEN  *TransportToken
+  );
+
+/**
+  This function initializes the transport interface.
+
+  @param [in]  TransportToken           The transport token acquired through
+                                        AcquireTransportSession function.
+  @param [in]  HardwareInfo             This is the optional hardware information
+                                        assigned to this transport interface.
+
+  @retval      EFI_SUCCESS              Transport interface is initialized
+                                        successfully.
+  @retval      EFI_INVALID_PARAMETER    The invalid transport token.
+  @retval      EFI_NOT_READY            The transport interface works fine but
+  @retval                               is not ready.
+  @retval      EFI_DEVICE_ERROR         The transport interface has problems.
+  @retval      EFI_ALREADY_STARTED      Teh protocol interface has already initialized.
+  @retval      Otherwise                Other errors.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *MANAGEABILITY_TRANSPORT_INIT)(
+  IN  MANAGEABILITY_TRANSPORT_TOKEN                 *TransportToken,
+  IN  MANAGEABILITY_TRANSPORT_HARDWARE_INFORMATION  HardwareInfo
+OPTIONAL
+  );
+
+/**
+  This function returns the transport interface status.
+  The generic EFI_STATUS is returned to caller directly, The additional
+  information of transport interface could be optionally returned in
+  TransportAdditionalStatus to describes the status that can't be
+  described obviously through EFI_STATUS.
+  See the definition of MANAGEABILITY_TRANSPORT_STATUS.
+
+  @param [in]   TransportToken             The transport token acquired through
+                                           AcquireTransportSession function.
+  @param [out]  TransportAdditionalStatus  The additional status of transport
+                                           interface.
+                                           NULL means no additional status of this
+                                           transport interface.
+
+  @retval      EFI_SUCCESS              Transport interface status is returned.
+  @retval      EFI_INVALID_PARAMETER    The invalid transport token.
+  @retval      EFI_DEVICE_ERROR         The transport interface has problems to return
+  @retval                               status.
+               Otherwise                Other errors.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *MANAGEABILITY_TRANSPORT_STATUS)(
+  IN  MANAGEABILITY_TRANSPORT_TOKEN               *TransportToken,
+  OUT MANAGEABILITY_TRANSPORT_ADDITIONAL_STATUS   *TransportAdditionalStatus OPTIONAL
+  );
+
+/**
+  This function resets the transport interface.
+  The generic EFI_STATUS is returned to caller directly after reseting
+transport
+  interface. The additional information of transport interface could be
+optionally
+  returned in TransportAdditionalStatus to describes the status that
+can't be
+  described obviously through EFI_STATUS.
+  See the definition of MANAGEABILITY_TRANSPORT_ADDITIONAL_STATUS.
+
+  @param [in]   TransportToken             The transport token acquired through
+                                           AcquireTransportSession function.
+  @param [out]  TransportAdditionalStatus  The additional status of specific transport
+                                           interface after the reset.
+                                           NULL means no additional status of this
+                                           transport interface.
+
+  @retval      EFI_SUCCESS              Transport interface status is returned.
+  @retval      EFI_INVALID_PARAMETER    The invalid transport token.
+  @retval      EFI_TIMEOUT              The reset process is time out.
+  @retval      EFI_DEVICE_ERROR         The transport interface has problems to return
+                                        status.
+               Otherwise                Other errors.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *MANAGEABILITY_TRANSPORT_RESET)(
+  IN  MANAGEABILITY_TRANSPORT_TOKEN              *TransportToken,
+  OUT MANAGEABILITY_TRANSPORT_ADDITIONAL_STATUS
+*TransportAdditionalStatus OPTIONAL
+  );
+
+/**
+  This function transmit the request over target transport interface.
+  The generic EFI_STATUS is returned to caller directly after reseting
+transport
+  interface. The additional information of transport interface could be
+optionally
+  returned in TransportAdditionalStatus to describes the status that
+can't be
+  described obviously through EFI_STATUS.
+  See the definition of MANAGEABILITY_TRANSPORT_ADDITIONAL_STATUS.
+
+  @param [in]  TransportToken           The transport token acquired through
+                                        AcquireTransportSession function.
+  @param [in]  TransferToken            The transfer token, see the definition of
+                                        MANAGEABILITY_TRANSFER_TOKEN.
+
+  @retval      The EFI status is returned in MANAGEABILITY_TRANSFER_TOKEN.
+
+**/
+typedef
+VOID
+(EFIAPI *MANAGEABILITY_TRANSPORT_TRANSMIT_RECEIVE)(
+  IN  MANAGEABILITY_TRANSPORT_TOKEN       *TransportToken,
+  IN  MANAGEABILITY_TRANSFER_TOKEN        *TransferToken
+  );
+
+///
+/// The first version of Manageability transport interface function.
+///
+struct _MANAGEABILITY_TRANSPORT_FUNCTION_V1_0 {
+  MANAGEABILITY_TRANSPORT_INIT                TransportInit;            ///< Initial the transport.
+  MANAGEABILITY_TRANSPORT_STATUS              TransportStatus;          ///< Get the transport status.
+  MANAGEABILITY_TRANSPORT_RESET               TransportReset;           ///< Reset the transport.
+  MANAGEABILITY_TRANSPORT_TRANSMIT_RECEIVE    TransportTransmitReceive; ///< Transmit the packet over
+                                                                        ///< transport and get the
+                                                                        ///< response back.
+};
+
+#endif
--
2.37.1.windows.1