+/** @file\r
+ This file defines the SPI I/O Protocol.\r
+\r
+ Copyright (c) 2017, Intel Corporation. All rights reserved.<BR>\r
+ This program and the accompanying materials\r
+ are licensed and made available under the terms and conditions of the BSD\r
+ License which accompanies this distribution. The full text of the license may\r
+ be found at http://opensource.org/licenses/bsd-license.php\r
+\r
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+\r
+ @par Revision Reference:\r
+ This Protocol was introduced in UEFI PI Specification 1.6.\r
+\r
+**/\r
+\r
+#ifndef __SPI_IO_PROTOCOL_H__\r
+#define __SPI_IO_PROTOCOL_H__\r
+\r
+#include <Protocol/LegacySpiController.h>\r
+#include <Protocol/SpiConfiguration.h>\r
+\r
+typedef struct _EFI_SPI_IO_PROTOCOL EFI_SPI_IO_PROTOCOL;\r
+\r
+///\r
+/// Note: The UEFI PI 1.6 specification does not specify values for the\r
+/// members below. The order matches the specification.\r
+///\r
+typedef enum {\r
+ ///\r
+ /// Data flowing in both direction between the host and\r
+ /// SPI peripheral.ReadBytes must equal WriteBytes and both ReadBuffer and\r
+ /// WriteBuffer must be provided.\r
+ ///\r
+ SPI_TRANSACTION_FULL_DUPLEX,\r
+\r
+ ///\r
+ /// Data flowing from the host to the SPI peripheral.ReadBytes must be\r
+ /// zero.WriteBytes must be non - zero and WriteBuffer must be provided.\r
+ ///\r
+ SPI_TRANSACTION_WRITE_ONLY,\r
+\r
+ ///\r
+ /// Data flowing from the SPI peripheral to the host.WriteBytes must be\r
+ /// zero.ReadBytes must be non - zero and ReadBuffer must be provided.\r
+ ///\r
+ SPI_TRANSACTION_READ_ONLY,\r
+\r
+ ///\r
+ /// Data first flowing from the host to the SPI peripheral and then data\r
+ /// flows from the SPI peripheral to the host.These types of operations get\r
+ /// used for SPI flash devices when control data (opcode, address) must be\r
+ /// passed to the SPI peripheral to specify the data to be read.\r
+ ///\r
+ SPI_TRANSACTION_WRITE_THEN_READ\r
+} EFI_SPI_TRANSACTION_TYPE;\r
+\r
+/**\r
+ Initiate a SPI transaction between the host and a SPI peripheral.\r
+\r
+ This routine must be called at or below TPL_NOTIFY.\r
+ This routine works with the SPI bus layer to pass the SPI transaction to the\r
+ SPI controller for execution on the SPI bus. There are four types of\r
+ supported transactions supported by this routine:\r
+ * Full Duplex: WriteBuffer and ReadBuffer are the same size.\r
+ * Write Only: WriteBuffer contains data for SPI peripheral, ReadBytes = 0\r
+ * Read Only: ReadBuffer to receive data from SPI peripheral, WriteBytes = 0\r
+ * Write Then Read: WriteBuffer contains control data to write to SPI\r
+ peripheral before data is placed into the ReadBuffer.\r
+ Both WriteBytes and ReadBytes must be non-zero.\r
+\r
+ @param[in] This Pointer to an EFI_SPI_IO_PROTOCOL structure.\r
+ @param[in] TransactionType Type of SPI transaction.\r
+ @param[in] DebugTransaction Set TRUE only when debugging is desired.\r
+ Debugging may be turned on for a single SPI\r
+ transaction. Only this transaction will display\r
+ debugging messages. All other transactions with\r
+ this value set to FALSE will not display any\r
+ debugging messages.\r
+ @param[in] ClockHz Specify the ClockHz value as zero (0) to use\r
+ the maximum clock frequency supported by the\r
+ SPI controller and part. Specify a non-zero\r
+ value only when a specific SPI transaction\r
+ requires a reduced clock rate.\r
+ @param[in] BusWidth Width of the SPI bus in bits: 1, 2, 4\r
+ @param[in] FrameSize Frame size in bits, range: 1 - 32\r
+ @param[in] WriteBytes The length of the WriteBuffer in bytes.\r
+ Specify zero for read-only operations.\r
+ @param[in] WriteBuffer The buffer containing data to be sent from the\r
+ host to the SPI chip. Specify NULL for read\r
+ only operations.\r
+ * Frame sizes 1-8 bits: UINT8 (one byte) per\r
+ frame\r
+ * Frame sizes 7-16 bits: UINT16 (two bytes) per\r
+ frame\r
+ * Frame sizes 17-32 bits: UINT32 (four bytes)\r
+ per frame The transmit frame is in the least\r
+ significant N bits.\r
+ @param[in] ReadBytes The length of the ReadBuffer in bytes.\r
+ Specify zero for write-only operations.\r
+ @param[out] ReadBuffer The buffer to receeive data from the SPI chip\r
+ during the transaction. Specify NULL for write\r
+ only operations.\r
+ * Frame sizes 1-8 bits: UINT8 (one byte) per\r
+ frame\r
+ * Frame sizes 7-16 bits: UINT16 (two bytes) per\r
+ frame\r
+ * Frame sizes 17-32 bits: UINT32 (four bytes)\r
+ per frame The received frame is in the least\r
+ significant N bits.\r
+\r
+ @retval EFI_SUCCESS The SPI transaction completed successfully\r
+ @retval EFI_BAD_BUFFER_SIZE The writeBytes value was invalid\r
+ @retval EFI_BAD_BUFFER_SIZE The ReadBytes value was invalid\r
+ @retval EFI_INVALID_PARAMETER TransactionType is not valid,\r
+ or BusWidth not supported by SPI peripheral or\r
+ SPI host controller,\r
+ or WriteBytes non-zero and WriteBuffer is\r
+ NULL,\r
+ or ReadBytes non-zero and ReadBuffer is NULL,\r
+ or ReadBuffer != WriteBuffer for full-duplex\r
+ type,\r
+ or WriteBuffer was NULL,\r
+ or TPL is too high\r
+ @retval EFI_OUT_OF_RESOURCES Insufficient memory for SPI transaction\r
+ @retval EFI_UNSUPPORTED The FrameSize is not supported by the SPI bus\r
+ layer or the SPI host controller\r
+ @retval EFI_UNSUPPORTED The SPI controller was not able to support\r
+\r
+**/\r
+typedef\r
+EFI_STATUS\r
+(EFIAPI *EFI_SPI_IO_PROTOCOL_TRANSACTION) (\r
+ IN CONST EFI_SPI_IO_PROTOCOL *This,\r
+ IN EFI_SPI_TRANSACTION_TYPE TransactionType,\r
+ IN BOOLEAN DebugTransaction,\r
+ IN UINT32 ClockHz OPTIONAL,\r
+ IN UINT32 BusWidth,\r
+ IN UINT32 FrameSize,\r
+ IN UINT32 WriteBytes,\r
+ IN UINT8 *WriteBuffer,\r
+ IN UINT32 ReadBytes,\r
+ OUT UINT8 *ReadBuffer\r
+ );\r
+\r
+/**\r
+ Update the SPI peripheral associated with this SPI 10 instance.\r
+\r
+ Support socketed SPI parts by allowing the SPI peripheral driver to replace\r
+ the SPI peripheral after the connection is made. An example use is socketed\r
+ SPI NOR flash parts, where the size and parameters change depending upon\r
+ device is in the socket.\r
+\r
+ @param[in] This Pointer to an EFI_SPI_IO_PROTOCOL structure.\r
+ @param[in] SpiPeripheral Pointer to an EFI_SPI_PERIPHERAL structure.\r
+\r
+ @retval EFI_SUCCESS The SPI peripheral was updated successfully\r
+ @retval EFI_INVALID_PARAMETER The SpiPeripheral value is NULL,\r
+ or the SpiPeripheral->SpiBus is NULL,\r
+ or the SpiP eripheral - >SpiBus pointing at\r
+ wrong bus,\r
+ or the SpiP eripheral - >SpiPart is NULL\r
+\r
+**/\r
+typedef EFI_STATUS\r
+(EFIAPI *EFI_SPI_IO_PROTOCOL_UPDATE_SPI_PERIPHERAL) (\r
+ IN CONST EFI_SPI_IO_PROTOCOL *This,\r
+ IN CONST EFI_SPI_PERIPHERAL *SpiPeripheral\r
+ );\r
+\r
+///\r
+/// The EFI_SPI_BUS_ TRANSACTION data structure contains the description of the\r
+/// SPI transaction to perform on the host controller.\r
+///\r
+typedef struct _EFI_SPI_BUS_TRANSACTION {\r
+ ///\r
+ /// Pointer to the SPI peripheral being manipulated.\r
+ ///\r
+ CONST EFI_SPI_PERIPHERAL *SpiPeripheral;\r
+\r
+ ///\r
+ /// Type of transaction specified by one of the EFI_SPI_TRANSACTION_TYPE\r
+ /// values.\r
+ ///\r
+ EFI_SPI_TRANSACTION_TYPE TransactionType;\r
+\r
+ ///\r
+ /// TRUE if the transaction is being debugged. Debugging may be turned on for\r
+ /// a single SPI transaction. Only this transaction will display debugging\r
+ /// messages. All other transactions with this value set to FALSE will not\r
+ /// display any debugging messages.\r
+ ///\r
+ BOOLEAN DebugTransaction;\r
+\r
+ ///\r
+ /// SPI bus width in bits: 1, 2, 4\r
+ ///\r
+ UINT32 BusWidth;\r
+\r
+ ///\r
+ /// Frame size in bits, range: 1 - 32\r
+ ///\r
+ UINT32 FrameSize;\r
+\r
+ ///\r
+ /// Length of the write buffer in bytes\r
+ ///\r
+ UINT32 WriteBytes;\r
+\r
+ ///\r
+ /// Buffer containing data to send to the SPI peripheral\r
+ /// Frame sizes 1 - 8 bits: UINT8 (one byte) per frame\r
+ /// Frame sizes 7 - 16 bits : UINT16 (two bytes) per frame\r
+ ///\r
+ UINT8 *WriteBuffer;\r
+\r
+ ///\r
+ /// Length of the read buffer in bytes\r
+ ///\r
+ UINT32 ReadBytes;\r
+\r
+ ///\r
+ /// Buffer to receive the data from the SPI peripheral\r
+ /// * Frame sizes 1 - 8 bits: UINT8 (one byte) per frame\r
+ /// * Frame sizes 7 - 16 bits : UINT16 (two bytes) per frame\r
+ /// * Frame sizes 17 - 32 bits : UINT32 (four bytes) per frame\r
+ ///\r
+ UINT8 *ReadBuffer;\r
+} EFI_SPI_BUS_TRANSACTION;\r
+\r
+///\r
+/// Support managed SPI data transactions between the SPI controller and a SPI\r
+/// chip.\r
+///\r
+struct _EFI_SPI_IO_PROTOCOL {\r
+ ///\r
+ /// Address of an EFI_SPI_PERIPHERAL data structure associated with this\r
+ /// protocol instance.\r
+ ///\r
+ CONST EFI_SPI_PERIPHERAL *SpiPeripheral;\r
+\r
+ ///\r
+ /// Address of the original EFI_SPI_PERIPHERAL data structure associated with\r
+ /// this protocol instance.\r
+ ///\r
+ CONST EFI_SPI_PERIPHERAL *OriginalSpiPeripheral;\r
+\r
+ ///\r
+ /// Mask of frame sizes which the SPI 10 layer supports. Frame size of N-bits\r
+ /// is supported when bit N-1 is set. The host controller must support a\r
+ /// frame size of 8-bits. Frame sizes of 16, 24 and 32-bits are converted to\r
+ /// 8-bit frame sizes by the SPI bus layer if the frame size is not supported\r
+ /// by the SPI host controller.\r
+ ///\r
+ UINT32 FrameSizeSupportMask;\r
+\r
+ ///\r
+ /// Maximum transfer size in bytes: 1 - Oxffffffff\r
+ ///\r
+ UINT32 MaximumTransferBytes;\r
+\r
+ ///\r
+ /// Transaction attributes: One or more from:\r
+ /// * SPI_10_SUPPORTS_2_B1T_DATA_BUS_W1DTH\r
+ /// - The SPI host and peripheral supports a 2-bit data bus\r
+ /// * SPI_IO_SUPPORTS_4_BIT_DATA_BUS_W1DTH\r
+ /// - The SPI host and peripheral supports a 4-bit data bus\r
+ /// * SPI_IO_TRANSFER_SIZE_INCLUDES_OPCODE\r
+ /// - Transfer size includes the opcode byte\r
+ /// * SPI_IO_TRANSFER_SIZE_INCLUDES_ADDRESS\r
+ /// - Transfer size includes the 3 address bytes\r
+ ///\r
+ UINT32 Attributes;\r
+\r
+ ///\r
+ /// Pointer to legacy SPI controller protocol\r
+ ///\r
+ CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *LegacySpiProtocol;\r
+\r
+ ///\r
+ /// Initiate a SPI transaction between the host and a SPI peripheral.\r
+ ///\r
+ EFI_SPI_IO_PROTOCOL_TRANSACTION Transaction;\r
+\r
+ ///\r
+ /// Update the SPI peripheral associated with this SPI 10 instance.\r
+ ///\r
+ EFI_SPI_IO_PROTOCOL_UPDATE_SPI_PERIPHERAL UpdateSpiPeripheral;\r
+};\r
+\r
+#endif // __SPI_IO_PROTOCOL_H__\r
projects / mirror_edk2.git / commitdiff