MdeModulePkg:BaseSpiHcPlatformLib: Adding NULL lib instance

Adding NULL SpiHcPlatformLib instance. This library is responsible for
handling the low level details of the SPI host controller. Since this is
platform specific this library will be dependent on OEM SPI
implementation. The SPI host controller layer will utilize this library
for SPI bus transactions.

Bugzilla #4753

Cc: Liming Gao <gaoliming@byosoft.com.cn>
Cc: Ray Ni <ray.ni@intel.com>
Cc: Abner Chang <abner.chang@amd.com>
Cc: Abdul Lateef Attar <AbdulLateef.Attar@amd.com>
Signed-off-by: Brit Chesley <brit.chesley@amd.com>
Acked-by: Abner Chang <abner.chang@amd.com>
Reviewed-by: Liming Gao <gaoliming@byosoft.com.cn>

6 files changed, 344 insertions, 0 deletions

diff --git a/MdeModulePkg/Include/Library/SpiHcPlatformLib.h b/MdeModulePkg/Include/Library/SpiHcPlatformLib.h
new file mode 100644
index 0000000000..c68f745537
--- /dev/null
+++ b/MdeModulePkg/Include/Library/SpiHcPlatformLib.h
@@ -0,0 +1,148 @@
+/** @file

+

+  Function declarations for SpiHcPlatformLib

+

+  Copyright (C) 2024 Advanced Micro Devices, Inc. All rights reserved.<BR>

+  SPDX-License-Identifier: BSD-2-Clause-Patent

+**/

+

+#ifndef PLATFORM_SPI_HC_H_

+#define PLATFORM_SPI_HC_H_

+

+#include <Uefi/UefiBaseType.h>

+#include <Protocol/SpiHc.h>

+#include <Protocol/SpiConfiguration.h>

+#include <Protocol/DevicePath.h>

+#include <Library/DevicePathLib.h>

+

+/**

+  This function reports the details of the SPI Host Controller to the SpiHc driver.

+

+  @param[out]     Attributes              The suported attributes of the SPI host controller

+  @param[out]     FrameSizeSupportMask    The suported FrameSizeSupportMask of the SPI host controller

+  @param[out]     MaximumTransferBytes    The suported MaximumTransferBytes of the SPI host controller

+

+  @retval EFI_SUCCESS             SPI_HOST_CONTROLLER_INSTANCE was allocated properly

+  @retval EFI_OUT_OF_RESOURCES    The SPI_HOST_CONTROLLER_INSTANCE could not be allocated

+*/

+EFI_STATUS

+EFIAPI

+GetPlatformSpiHcDetails (

+  OUT     UINT32  *Attributes,

+  OUT     UINT32  *FrameSizeSupportMask,

+  OUT     UINT32  *MaximumTransferBytes

+  );

+

+/**

+  This function reports the device path of SPI host controller. This is needed in order for the SpiBus

+  to match the correct SPI_BUS to the SPI host controller

+

+  @param[out] DevicePath The device path for this SPI HC is returned in this variable

+

+  @retval EFI_SUCCESS

+*/

+EFI_STATUS

+EFIAPI

+GetSpiHcDevicePath (

+  OUT EFI_DEVICE_PATH_PROTOCOL  **DevicePath

+  );

+

+/**

+  This is the platform specific Spi Chip select function.

+  Assert or deassert the SPI chip select.

+

+  This routine is called at TPL_NOTIFY.

+  Update the value of the chip select line for a SPI peripheral. The SPI bus

+  layer calls this routine either in the board layer or in the SPI controller

+  to manipulate the chip select pin at the start and end of a SPI transaction.

+

+  @param[in] This           Pointer to an EFI_SPI_HC_PROTOCOL structure.

+  @param[in] SpiPeripheral  The address of an EFI_SPI_PERIPHERAL data structure

+                            describing the SPI peripheral whose chip select pin

+                            is to be manipulated. The routine may access the

+                            ChipSelectParameter field to gain sufficient

+                            context to complete the operati on.

+  @param[in] PinValue       The value to be applied to the chip select line of

+                            the SPI peripheral.

+

+  @retval EFI_SUCCESS            The chip select was set as requested

+  @retval EFI_NOT_READY          Support for the chip select is not properly

+                                 initialized

+  @retval EFI_INVALID_PARAMETER  The ChipSeLect value or its contents are

+                                 invalid

+

+**/

+EFI_STATUS

+EFIAPI

+PlatformSpiHcChipSelect (

+  IN CONST EFI_SPI_HC_PROTOCOL  *This,

+  IN CONST EFI_SPI_PERIPHERAL   *SpiPeripheral,

+  IN BOOLEAN                    PinValue

+  );

+

+/**

+  This function is the platform specific SPI clock function.

+  Set up the clock generator to produce the correct clock frequency, phase and

+  polarity for a SPI chip.

+

+  This routine is called at TPL_NOTIFY.

+  This routine updates the clock generator to generate the correct frequency

+  and polarity for the SPI clock.

+

+  @param[in] This           Pointer to an EFI_SPI_HC_PROTOCOL structure.

+  @param[in] SpiPeripheral  Pointer to a EFI_SPI_PERIPHERAL data structure from

+                            which the routine can access the ClockParameter,

+                            ClockPhase and ClockPolarity fields. The routine

+                            also has access to the names for the SPI bus and

+                            chip which can be used during debugging.

+  @param[in] ClockHz        Pointer to the requested clock frequency. The SPI

+                            host controller will choose a supported clock

+                            frequency which is less then or equal to this

+                            value. Specify zero to turn the clock generator

+                            off. The actual clock frequency supported by the

+                            SPI host controller will be returned.

+

+  @retval EFI_SUCCESS      The clock was set up successfully

+  @retval EFI_UNSUPPORTED  The SPI controller was not able to support the

+                           frequency requested by ClockHz

+

+**/

+EFI_STATUS

+EFIAPI

+PlatformSpiHcClock (

+  IN CONST EFI_SPI_HC_PROTOCOL  *This,

+  IN CONST EFI_SPI_PERIPHERAL   *SpiPeripheral,

+  IN UINT32                     *ClockHz

+  );

+

+/**

+  This function is the platform specific SPI transaction function

+  Perform the SPI transaction on the SPI peripheral using the SPI host

+  controller.

+

+  This routine is called at TPL_NOTIFY.

+  This routine synchronously returns EFI_SUCCESS indicating that the

+  asynchronous SPI transaction was started. The routine then waits for

+  completion of the SPI transaction prior to returning the final transaction

+  status.

+

+  @param[in] This            Pointer to an EFI_SPI_HC_PROTOCOL structure.

+  @param[in] BusTransaction  Pointer to a EFI_SPI_BUS_ TRANSACTION containing

+                             the description of the SPI transaction to perform.

+

+  @retval EFI_SUCCESS          The transaction completed successfully

+  @retval EFI_BAD_BUFFER_SIZE  The BusTransaction->WriteBytes value is invalid,

+                               or the BusTransaction->ReadinBytes value is

+                               invalid

+  @retval EFI_UNSUPPORTED      The BusTransaction-> Transaction Type is

+                               unsupported

+

+**/

+EFI_STATUS

+EFIAPI

+PlatformSpiHcTransaction (

+  IN CONST EFI_SPI_HC_PROTOCOL  *This,

+  IN EFI_SPI_BUS_TRANSACTION    *BusTransaction

+  );

+

+#endif // PLATFORM_SPI_HC_SMM_PROTOCOL_H_

diff --git a/MdeModulePkg/Library/BaseSpiHcPlatformLibNull/BaseSpiHcPlatformLibNull.c b/MdeModulePkg/Library/BaseSpiHcPlatformLibNull/BaseSpiHcPlatformLibNull.c
new file mode 100644
index 0000000000..2926e9e248
--- /dev/null
+++ b/MdeModulePkg/Library/BaseSpiHcPlatformLibNull/BaseSpiHcPlatformLibNull.c
@@ -0,0 +1,145 @@
+/** @file

+

+  Null implementation of SpiHcPlatformLib

+

+  Copyright (C) 2024 Advanced Micro Devices, Inc. All rights reserved.<BR>

+  SPDX-License-Identifier: BSD-2-Clause-Patent

+

+**/

+#include <PiDxe.h>

+#include <Protocol/DevicePath.h>

+#include <Protocol/SpiHc.h>

+#include <Library/SpiHcPlatformLib.h>

+

+/**

+  This function reports the details of the SPI Host Controller to the SpiHc driver.

+

+  @param[out]     Attributes              The suported attributes of the SPI host controller

+  @param[out]     FrameSizeSupportMask    The suported FrameSizeSupportMask of the SPI host controller

+  @param[out]     MaximumTransferBytes    The suported MaximumTransferBytes of the SPI host controller

+

+  @retval EFI_UNSUPPORTED

+**/

+EFI_STATUS

+EFIAPI

+GetPlatformSpiHcDetails (

+  OUT     UINT32  *Attributes,

+  OUT     UINT32  *FrameSizeSupportMask,

+  OUT     UINT32  *MaximumTransferBytes

+  )

+{

+  return EFI_UNSUPPORTED;

+}

+

+/**

+  This function reports the device path of SPI host controller. This is needed in order for the SpiBus

+  to match the correct SPI_BUS to the SPI host controller

+

+  @param[out] DevicePath The device path for this SPI HC is returned in this variable

+

+  @retval EFI_UNSUPPORTED

+**/

+EFI_STATUS

+EFIAPI

+GetSpiHcDevicePath (

+  OUT EFI_DEVICE_PATH_PROTOCOL  **DevicePath

+  )

+{

+  return EFI_UNSUPPORTED;

+}

+

+/**

+  This is the platform specific Spi Chip select function.

+  Assert or deassert the SPI chip select.

+

+  This routine is called at TPL_NOTIFY.

+  Update the value of the chip select line for a SPI peripheral. The SPI bus

+  layer calls this routine either in the board layer or in the SPI controller

+  to manipulate the chip select pin at the start and end of a SPI transaction.

+

+  @param[in] This           Pointer to an EFI_SPI_HC_PROTOCOL structure.

+  @param[in] SpiPeripheral  The address of an EFI_SPI_PERIPHERAL data structure

+                            describing the SPI peripheral whose chip select pin

+                            is to be manipulated. The routine may access the

+                            ChipSelectParameter field to gain sufficient

+                            context to complete the operati on.

+  @param[in] PinValue       The value to be applied to the chip select line of

+                            the SPI peripheral.

+

+  @retval EFI_UNSUPPORTED

+

+**/

+EFI_STATUS

+EFIAPI

+PlatformSpiHcChipSelect (

+  IN CONST EFI_SPI_HC_PROTOCOL  *This,

+  IN CONST EFI_SPI_PERIPHERAL   *SpiPeripheral,

+  IN BOOLEAN                    PinValue

+  )

+{

+  return EFI_UNSUPPORTED;

+}

+

+/**

+  This function is the platform specific SPI clock function.

+  Set up the clock generator to produce the correct clock frequency, phase and

+  polarity for a SPI chip.

+

+  This routine is called at TPL_NOTIFY.

+  This routine updates the clock generator to generate the correct frequency

+  and polarity for the SPI clock.

+

+  @param[in] This           Pointer to an EFI_SPI_HC_PROTOCOL structure.

+  @param[in] SpiPeripheral  Pointer to a EFI_SPI_PERIPHERAL data structure from

+                            which the routine can access the ClockParameter,

+                            ClockPhase and ClockPolarity fields. The routine

+                            also has access to the names for the SPI bus and

+                            chip which can be used during debugging.

+  @param[in] ClockHz        Pointer to the requested clock frequency. The SPI

+                            host controller will choose a supported clock

+                            frequency which is less then or equal to this

+                            value. Specify zero to turn the clock generator

+                            off. The actual clock frequency supported by the

+                            SPI host controller will be returned.

+

+  @retval EFI_UNSUPPORTED

+

+**/

+EFI_STATUS

+EFIAPI

+PlatformSpiHcClock (

+  IN CONST EFI_SPI_HC_PROTOCOL  *This,

+  IN CONST EFI_SPI_PERIPHERAL   *SpiPeripheral,

+  IN UINT32                     *ClockHz

+  )

+{

+  return EFI_UNSUPPORTED;

+}

+

+/**

+  This function is the platform specific SPI transaction function

+  Perform the SPI transaction on the SPI peripheral using the SPI host

+  controller.

+

+  This routine is called at TPL_NOTIFY.

+  This routine synchronously returns EFI_SUCCESS indicating that the

+  asynchronous SPI transaction was started. The routine then waits for

+  completion of the SPI transaction prior to returning the final transaction

+  status.

+

+  @param[in] This            Pointer to an EFI_SPI_HC_PROTOCOL structure.

+  @param[in] BusTransaction  Pointer to a EFI_SPI_BUS_ TRANSACTION containing

+                             the description of the SPI transaction to perform.

+

+  @retval EFI_UNSUPPORTED

+

+**/

+EFI_STATUS

+EFIAPI

+PlatformSpiHcTransaction (

+  IN CONST EFI_SPI_HC_PROTOCOL  *This,

+  IN EFI_SPI_BUS_TRANSACTION    *BusTransaction

+  )

+{

+  return EFI_UNSUPPORTED;

+}

diff --git a/MdeModulePkg/Library/BaseSpiHcPlatformLibNull/BaseSpiHcPlatformLibNull.inf b/MdeModulePkg/Library/BaseSpiHcPlatformLibNull/BaseSpiHcPlatformLibNull.inf
new file mode 100644
index 0000000000..805f50b895
--- /dev/null
+++ b/MdeModulePkg/Library/BaseSpiHcPlatformLibNull/BaseSpiHcPlatformLibNull.inf
@@ -0,0 +1,33 @@
+## @file

+#  NULL library for platform SPI Host controller, which should be provided

+#  by the OEM.

+#

+#  Copyright (C) 2024 Advanced Micro Devices, Inc. All rights reserved.<BR>

+#

+#  SPDX-License-Identifier: BSD-2-Clause-Patent

+##

+[Defines]

+  INF_VERSION               = 1.27

+  BASE_NAME                 = BaseSpiHcPlatformLibNull

+  FILE_GUID                 = 3C230948-6DF5-4802-8177-967A190579CF

+  MODULE_TYPE               = BASE

+  VERSION_STRING            = 0.1

+  PI_SPECIFICATION_VERSION  = 0x0001000A

+  LIBRARY_CLASS             = SpiHcPlatformLib

+

+[Packages]

+  MdePkg/MdePkg.dec

+  MdeModulePkg/MdeModulePkg.dec

+

+[LibraryClasses]

+  DevicePathLib

+  UefiLib

+

+[Sources]

+  BaseSpiHcPlatformLibNull.c

+

+[Depex]

+  TRUE

+

+[UserExtensions.TianoCore."ExtraFiles"]

+  BaseSpiHcPlatformLibNull.uni

diff --git a/MdeModulePkg/Library/BaseSpiHcPlatformLibNull/BaseSpiHcPlatformLibNull.uni b/MdeModulePkg/Library/BaseSpiHcPlatformLibNull/BaseSpiHcPlatformLibNull.uni
new file mode 100644
index 0000000000..82fa02c31d
--- /dev/null
+++ b/MdeModulePkg/Library/BaseSpiHcPlatformLibNull/BaseSpiHcPlatformLibNull.uni
@@ -0,0 +1,11 @@
+

+// /** @file

+//

+// Copyright (C) 2024 Advanced Micro Devices, Inc. All rights reserved.<BR>

+//

+// SPDX-License-Identifier: BSD-2-Clause-Patent

+//

+// **/

+

+#string STR_PROPERTIES_MODULE_NAME

+#language en-US   "Null SPI Host controller library"

diff --git a/MdeModulePkg/MdeModulePkg.dec b/MdeModulePkg/MdeModulePkg.dec
index dba6fbe642..f7339f0aec 100644
--- a/MdeModulePkg/MdeModulePkg.dec
+++ b/MdeModulePkg/MdeModulePkg.dec
@@ -169,6 +169,11 @@
   #

   ImagePropertiesRecordLib|Include/Library/ImagePropertiesRecordLib.h

 

+  ##  @libraryclass   Platform SPI Host Controller library which provides low-level

+  #                   control over the SPI hardware

+  #

+  SpiHcPlatformLib|Include/Library/SpiHcPlatformLib.h

+

 [Guids]

   ## MdeModule package token space guid

   # Include/Guid/MdeModulePkgTokenSpace.h

diff --git a/MdeModulePkg/MdeModulePkg.dsc b/MdeModulePkg/MdeModulePkg.dsc
index 33d6f4a1f6..177128bdfd 100644
--- a/MdeModulePkg/MdeModulePkg.dsc
+++ b/MdeModulePkg/MdeModulePkg.dsc
@@ -107,6 +107,7 @@
   MmUnblockMemoryLib|MdePkg/Library/MmUnblockMemoryLib/MmUnblockMemoryLibNull.inf

   VariableFlashInfoLib|MdeModulePkg/Library/BaseVariableFlashInfoLib/BaseVariableFlashInfoLib.inf

   IpmiCommandLib|MdeModulePkg/Library/BaseIpmiCommandLibNull/BaseIpmiCommandLibNull.inf

+  SpiHcPlatformLib|MdeModulePkg/Library/BaseSpiHcPlatformLibNull/BaseSpiHcPlatformLibNull.inf

 

 [LibraryClasses.EBC.PEIM]

   IoLib|MdePkg/Library/PeiIoLibCpuIo/PeiIoLibCpuIo.inf

@@ -528,6 +529,7 @@
   MdeModulePkg/Library/TraceHubDebugSysTLib/BaseTraceHubDebugSysTLib.inf

   MdeModulePkg/Library/TraceHubDebugSysTLib/PeiTraceHubDebugSysTLib.inf

   MdeModulePkg/Library/TraceHubDebugSysTLib/DxeSmmTraceHubDebugSysTLib.inf

+  MdeModulePkg/Library/BaseSpiHcPlatformLibNull/BaseSpiHcPlatformLibNull.inf

 

 [Components.X64]

   MdeModulePkg/Universal/CapsulePei/CapsuleX64.inf