Reviewed-by: Nickle Wang <nick...@nvidia.com>
Regards,
Nickle
> -----Original Message-----
> From: abner.ch...@amd.com <abner.ch...@amd.com>
> Sent: Wednesday, March 22, 2023 10:49 AM
> To: devel@edk2.groups.io
> Cc: Liming Gao <gaolim...@byosoft.com.cn>; Isaac Oram
> <isaac.w.o...@intel.com>; Nate DeSimone <nathaniel.l.desim...@intel.com>;
> Nickle Wang <nick...@nvidia.com>; Igor Kulchytskyy <ig...@ami.com>; Abdul
> Lateef Attar <abdat...@amd.com>
> Subject: [PATCH v4 3/9] ManageabilityPkg: Add ManageabilityTransportLib
> header file
>
> External email: Use caution opening links or attachments
>
>
> From: Abner Chang <abner.ch...@amd.com>
>
> Add ManageabilityTransportLib header file to package.
>
> Signed-off-by: Abner Chang <abner.ch...@amd.com>
> Cc: Liming Gao <gaolim...@byosoft.com.cn>
> Cc: Isaac Oram <isaac.w.o...@intel.com>
> Cc: Nate DeSimone <nathaniel.l.desim...@intel.com>
> Cc: Nickle Wang <nick...@nvidia.com>
> Cc: Igor Kulchytskyy <ig...@ami.com>
> Cc: Abdul Lateef Attar <abdat...@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 (#101768): https://edk2.groups.io/g/devel/message/101768
Mute This Topic: https://groups.io/mt/97770709/21656
Group Owner: devel+ow...@edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [arch...@mail-archive.com]
-=-=-=-=-=-=-=-=-=-=-=-
