[edk2-devel] [PATCH v4 3/9] ManageabilityPkg: Add ManageabilityTransportLib header file
Chang, Abner via groups.io
abner.chang=amd.com at groups.io
Wed Mar 22 02:48:34 UTC 2023
From: Abner Chang <abner.chang at amd.com>
Add ManageabilityTransportLib header file to package.
Signed-off-by: Abner Chang <abner.chang at amd.com>
Cc: Liming Gao <gaoliming at byosoft.com.cn>
Cc: Isaac Oram <isaac.w.oram at intel.com>
Cc: Nate DeSimone <nathaniel.l.desimone at intel.com>
Cc: Nickle Wang <nicklew at nvidia.com>
Cc: Igor Kulchytskyy <igork at ami.com>
Cc: Abdul Lateef Attar <abdattar at 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/ManageabilityTransportLib.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
+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
+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
+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
-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#101545): https://edk2.groups.io/g/devel/message/101545
Mute This Topic: https://groups.io/mt/97770709/1813853
Group Owner: devel+owner at edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [edk2-devel-archive at redhat.com]
-=-=-=-=-=-=-=-=-=-=-=-
More information about the edk2-devel-archive
mailing list