MdeModulePkg/Bus/Spi/SpiBus/SpiBus.h - edk2 - Git at Google

 /** @file

   SPI bus driver

   Copyright (C) 2024 Advanced Micro Devices, Inc. All rights reserved.<BR>
   SPDX-License-Identifier: BSD-2-Clause-Patent

 **/

 #ifndef SPI_BUS_H_
 #define SPI_BUS_H_

 #include <PiDxe.h>
 #include <Library/BaseLib.h>
 #include <Protocol/DevicePath.h>
 #include <Library/DevicePathLib.h>
 #include <Library/BaseMemoryLib.h>
 #include <Protocol/SpiIo.h>
 #include <Protocol/SpiHc.h>
 #include <Protocol/SpiConfiguration.h>

 #define SPI_IO_SIGNATURE  SIGNATURE_32 ('s', 'i', 'o', 'c')

 typedef struct {
   UINTN                             Signature;
   EFI_HANDLE                        Handle;
   EFI_SPI_IO_PROTOCOL               Protocol;
   EFI_SPI_BUS_TRANSACTION           BusTransaction;
   EFI_SPI_CONFIGURATION_PROTOCOL    *SpiConfig;
   EFI_SPI_HC_PROTOCOL               *SpiHc;
   EFI_SPI_BUS                       *SpiBus;
 } SPI_IO_CHIP;

 #define SPI_IO_CHIP_FROM_THIS(a) \
   CR (a, SPI_IO_CHIP, Protocol, \
       SPI_IO_SIGNATURE)

 /**
   Checks if two device paths are the same

   @param[in] DevicePath1        First device path to compare
   @param[in] DevicePath2        Second device path to compare

   @retval TRUE              The device paths share the same nodes and values
   @retval FALSE             The device paths differ
 **/
 BOOLEAN
 EFIAPI
 DevicePathsAreEqual (
   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath1,
   IN CONST EFI_DEVICE_PATH_PROTOCOL  *DevicePath2
   );

 /**
   Initiate a SPI transaction between the host and a SPI peripheral.

   This routine must be called at or below TPL_NOTIFY.
   This routine works with the SPI bus layer to pass the SPI transaction to the
   SPI controller for execution on the SPI bus. There are four types of
   supported transactions supported by this routine:
   * Full Duplex: WriteBuffer and ReadBuffer are the same size.
   * Write Only: WriteBuffer contains data for SPI peripheral, ReadBytes = 0
   * Read Only: ReadBuffer to receive data from SPI peripheral, WriteBytes = 0
   * Write Then Read: WriteBuffer contains control data to write to SPI
                      peripheral before data is placed into the ReadBuffer.
                      Both WriteBytes and ReadBytes must be non-zero.

   @param[in]  This              Pointer to an EFI_SPI_IO_PROTOCOL structure.
   @param[in]  TransactionType   Type of SPI transaction.
   @param[in]  DebugTransaction  Set TRUE only when debugging is desired.
                                 Debugging may be turned on for a single SPI
                                 transaction. Only this transaction will display
                                 debugging messages. All other transactions with
                                 this value set to FALSE will not display any
                                 debugging messages.
   @param[in]  ClockHz           Specify the ClockHz value as zero (0) to use
                                 the maximum clock frequency supported by the
                                 SPI controller and part. Specify a non-zero
                                 value only when a specific SPI transaction
                                 requires a reduced clock rate.
   @param[in]  BusWidth          Width of the SPI bus in bits: 1, 2, 4
   @param[in]  FrameSize         Frame size in bits, range: 1 - 32
   @param[in]  WriteBytes        The length of the WriteBuffer in bytes.
                                 Specify zero for read-only operations.
   @param[in]  WriteBuffer       The buffer containing data to be sent from the
                                 host to the SPI chip. Specify NULL for read
                                 only operations.
                                 * Frame sizes 1-8 bits: UINT8 (one byte) per
                                   frame
                                 * Frame sizes 7-16 bits: UINT16 (two bytes) per
                                   frame
                                 * Frame sizes 17-32 bits: UINT32 (four bytes)
                                   per frame The transmit frame is in the least
                                   significant N bits.
   @param[in]  ReadBytes         The length of the ReadBuffer in bytes.
                                 Specify zero for write-only operations.
   @param[out] ReadBuffer        The buffer to receeive data from the SPI chip
                                 during the transaction. Specify NULL for write
                                 only operations.
                                 * Frame sizes 1-8 bits: UINT8 (one byte) per
                                   frame
                                 * Frame sizes 7-16 bits: UINT16 (two bytes) per
                                   frame
                                 * Frame sizes 17-32 bits: UINT32 (four bytes)
                                   per frame The received frame is in the least
                                   significant N bits.

   @retval EFI_SUCCESS            The SPI transaction completed successfully
   @retval EFI_BAD_BUFFER_SIZE    The writeBytes value was invalid
   @retval EFI_BAD_BUFFER_SIZE    The ReadBytes value was invalid
   @retval EFI_INVALID_PARAMETER  TransactionType is not valid,
                                  or BusWidth not supported by SPI peripheral or
                                  SPI host controller,
                                  or WriteBytes non-zero and WriteBuffer is
                                  NULL,
                                  or ReadBytes non-zero and ReadBuffer is NULL,
                                  or ReadBuffer != WriteBuffer for full-duplex
                                  type,
                                  or WriteBuffer was NULL,
                                  or TPL is too high
   @retval EFI_OUT_OF_RESOURCES   Insufficient memory for SPI transaction
   @retval EFI_UNSUPPORTED        The FrameSize is not supported by the SPI bus
                                  layer or the SPI host controller
   @retval EFI_UNSUPPORTED        The SPI controller was not able to support

 **/
 EFI_STATUS
 EFIAPI
 Transaction (
   IN  CONST EFI_SPI_IO_PROTOCOL  *This,
   IN  EFI_SPI_TRANSACTION_TYPE   TransactionType,
   IN  BOOLEAN                    DebugTransaction,
   IN  UINT32                     ClockHz OPTIONAL,
   IN  UINT32                     BusWidth,
   IN  UINT32                     FrameSize,
   IN  UINT32                     WriteBytes,
   IN  UINT8                      *WriteBuffer,
   IN  UINT32                     ReadBytes,
   OUT UINT8                      *ReadBuffer
   );

 /**
   Update the SPI peripheral associated with this SPI 10 instance.

   Support socketed SPI parts by allowing the SPI peripheral driver to replace
   the SPI peripheral after the connection is made. An example use is socketed
   SPI NOR flash parts, where the size and parameters change depending upon
   device is in the socket.

   @param[in] This           Pointer to an EFI_SPI_IO_PROTOCOL structure.
   @param[in] SpiPeripheral  Pointer to an EFI_SPI_PERIPHERAL structure.

   @retval EFI_SUCCESS            The SPI peripheral was updated successfully
   @retval EFI_INVALID_PARAMETER  The SpiPeripheral value is NULL,
                                  or the SpiPeripheral->SpiBus is NULL,
                                  or the SpiPeripheral->SpiBus pointing at
                                  wrong bus, or the SpiPeripheral->SpiPart is NULL

 **/
 EFI_STATUS
 EFIAPI
 UpdateSpiPeripheral (
   IN CONST EFI_SPI_IO_PROTOCOL  *This,
   IN CONST EFI_SPI_PERIPHERAL   *SpiPeripheral
   );

 #endif //SPI_BUS_H_
	/** @file

	SPI bus driver

	Copyright (C) 2024 Advanced Micro Devices, Inc. All rights reserved.<BR>
	SPDX-License-Identifier: BSD-2-Clause-Patent

	**/

	#ifndef SPI_BUS_H_
	#define SPI_BUS_H_

	#include <PiDxe.h>
	#include <Library/BaseLib.h>
	#include <Protocol/DevicePath.h>
	#include <Library/DevicePathLib.h>
	#include <Library/BaseMemoryLib.h>
	#include <Protocol/SpiIo.h>
	#include <Protocol/SpiHc.h>
	#include <Protocol/SpiConfiguration.h>

	#define SPI_IO_SIGNATURE SIGNATURE_32 ('s', 'i', 'o', 'c')

	typedef struct {
	UINTN Signature;
	EFI_HANDLE Handle;
	EFI_SPI_IO_PROTOCOL Protocol;
	EFI_SPI_BUS_TRANSACTION BusTransaction;
	EFI_SPI_CONFIGURATION_PROTOCOL *SpiConfig;
	EFI_SPI_HC_PROTOCOL *SpiHc;
	EFI_SPI_BUS *SpiBus;
	} SPI_IO_CHIP;

	#define SPI_IO_CHIP_FROM_THIS(a) \
	CR (a, SPI_IO_CHIP, Protocol, \
	SPI_IO_SIGNATURE)

	/**
	Checks if two device paths are the same

	@param[in] DevicePath1 First device path to compare
	@param[in] DevicePath2 Second device path to compare

	@retval TRUE The device paths share the same nodes and values
	@retval FALSE The device paths differ
	**/
	BOOLEAN
	EFIAPI
	DevicePathsAreEqual (
	IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath1,
	IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath2
	);

	/**
	Initiate a SPI transaction between the host and a SPI peripheral.

	This routine must be called at or below TPL_NOTIFY.
	This routine works with the SPI bus layer to pass the SPI transaction to the
	SPI controller for execution on the SPI bus. There are four types of
	supported transactions supported by this routine:
	* Full Duplex: WriteBuffer and ReadBuffer are the same size.
	* Write Only: WriteBuffer contains data for SPI peripheral, ReadBytes = 0
	* Read Only: ReadBuffer to receive data from SPI peripheral, WriteBytes = 0
	* Write Then Read: WriteBuffer contains control data to write to SPI
	peripheral before data is placed into the ReadBuffer.
	Both WriteBytes and ReadBytes must be non-zero.

	@param[in] This Pointer to an EFI_SPI_IO_PROTOCOL structure.
	@param[in] TransactionType Type of SPI transaction.
	@param[in] DebugTransaction Set TRUE only when debugging is desired.
	Debugging may be turned on for a single SPI
	transaction. Only this transaction will display
	debugging messages. All other transactions with
	this value set to FALSE will not display any
	debugging messages.
	@param[in] ClockHz Specify the ClockHz value as zero (0) to use
	the maximum clock frequency supported by the
	SPI controller and part. Specify a non-zero
	value only when a specific SPI transaction
	requires a reduced clock rate.
	@param[in] BusWidth Width of the SPI bus in bits: 1, 2, 4
	@param[in] FrameSize Frame size in bits, range: 1 - 32
	@param[in] WriteBytes The length of the WriteBuffer in bytes.
	Specify zero for read-only operations.
	@param[in] WriteBuffer The buffer containing data to be sent from the
	host to the SPI chip. Specify NULL for read
	only operations.
	* Frame sizes 1-8 bits: UINT8 (one byte) per
	frame
	* Frame sizes 7-16 bits: UINT16 (two bytes) per
	frame
	* Frame sizes 17-32 bits: UINT32 (four bytes)
	per frame The transmit frame is in the least
	significant N bits.
	@param[in] ReadBytes The length of the ReadBuffer in bytes.
	Specify zero for write-only operations.
	@param[out] ReadBuffer The buffer to receeive data from the SPI chip
	during the transaction. Specify NULL for write
	only operations.
	* Frame sizes 1-8 bits: UINT8 (one byte) per
	frame
	* Frame sizes 7-16 bits: UINT16 (two bytes) per
	frame
	* Frame sizes 17-32 bits: UINT32 (four bytes)
	per frame The received frame is in the least
	significant N bits.

	@retval EFI_SUCCESS The SPI transaction completed successfully
	@retval EFI_BAD_BUFFER_SIZE The writeBytes value was invalid
	@retval EFI_BAD_BUFFER_SIZE The ReadBytes value was invalid
	@retval EFI_INVALID_PARAMETER TransactionType is not valid,
	or BusWidth not supported by SPI peripheral or
	SPI host controller,
	or WriteBytes non-zero and WriteBuffer is
	NULL,
	or ReadBytes non-zero and ReadBuffer is NULL,
	or ReadBuffer != WriteBuffer for full-duplex
	type,
	or WriteBuffer was NULL,
	or TPL is too high
	@retval EFI_OUT_OF_RESOURCES Insufficient memory for SPI transaction
	@retval EFI_UNSUPPORTED The FrameSize is not supported by the SPI bus
	layer or the SPI host controller
	@retval EFI_UNSUPPORTED The SPI controller was not able to support

	**/
	EFI_STATUS
	EFIAPI
	Transaction (
	IN CONST EFI_SPI_IO_PROTOCOL *This,
	IN EFI_SPI_TRANSACTION_TYPE TransactionType,
	IN BOOLEAN DebugTransaction,
	IN UINT32 ClockHz OPTIONAL,
	IN UINT32 BusWidth,
	IN UINT32 FrameSize,
	IN UINT32 WriteBytes,
	IN UINT8 *WriteBuffer,
	IN UINT32 ReadBytes,
	OUT UINT8 *ReadBuffer
	);

	/**
	Update the SPI peripheral associated with this SPI 10 instance.

	Support socketed SPI parts by allowing the SPI peripheral driver to replace
	the SPI peripheral after the connection is made. An example use is socketed
	SPI NOR flash parts, where the size and parameters change depending upon
	device is in the socket.

	@param[in] This Pointer to an EFI_SPI_IO_PROTOCOL structure.
	@param[in] SpiPeripheral Pointer to an EFI_SPI_PERIPHERAL structure.

	@retval EFI_SUCCESS The SPI peripheral was updated successfully
	@retval EFI_INVALID_PARAMETER The SpiPeripheral value is NULL,
	or the SpiPeripheral->SpiBus is NULL,
	or the SpiPeripheral->SpiBus pointing at
	wrong bus, or the SpiPeripheral->SpiPart is NULL

	**/
	EFI_STATUS
	EFIAPI
	UpdateSpiPeripheral (
	IN CONST EFI_SPI_IO_PROTOCOL *This,
	IN CONST EFI_SPI_PERIPHERAL *SpiPeripheral
	);

	#endif //SPI_BUS_H_