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

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

Add ManageabilityTransportLib header file to package.

Signed-off-by: Abner Chang <abner.chang@...>
Cc: Liming Gao <gaoliming@...>
Cc: Isaac Oram <isaac.w.oram@...>
Cc: Nate DeSimone <nathaniel.l.desimone@...>
Cc: Nickle Wang <nicklew@...>
Cc: Igor Kulchytskyy <igork@...>
Cc: Abdul Lateef Attar <abdattar@...>
---
.../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