MdePkg/Include/Protocol/SpiIo.h

   1 /** @file
   2   This file defines the SPI I/O Protocol.
   3
   4   Copyright (c) 2017, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7   @par Revision Reference:
   8     This Protocol was introduced in UEFI PI Specification 1.6.
   9
  10 **/
  11
  12 #ifndef __SPI_IO_PROTOCOL_H__
  13 #define __SPI_IO_PROTOCOL_H__
  14
  15 #include <Protocol/LegacySpiController.h>
  16 #include <Protocol/SpiConfiguration.h>
  17
  18 typedef struct _EFI_SPI_IO_PROTOCOL EFI_SPI_IO_PROTOCOL;
  19
  20 ///
  21 /// Note: The UEFI PI 1.6 specification does not specify values for the
  22 ///       members below. The order matches the specification.
  23 ///
  24 typedef enum {
  25   ///
  26   /// Data flowing in both direction between the host and
  27   /// SPI peripheral.ReadBytes must equal WriteBytes and both ReadBuffer and
  28   /// WriteBuffer must be provided.
  29   ///
  30   SPI_TRANSACTION_FULL_DUPLEX,
  31
  32   ///
  33   /// Data flowing from the host to the SPI peripheral.ReadBytes must be
  34   /// zero.WriteBytes must be non - zero and WriteBuffer must be provided.
  35   ///
  36   SPI_TRANSACTION_WRITE_ONLY,
  37
  38   ///
  39   /// Data flowing from the SPI peripheral to the host.WriteBytes must be
  40   /// zero.ReadBytes must be non - zero and ReadBuffer must be provided.
  41   ///
  42   SPI_TRANSACTION_READ_ONLY,
  43
  44   ///
  45   /// Data first flowing from the host to the SPI peripheral and then data
  46   /// flows from the SPI peripheral to the host.These types of operations get
  47   /// used for SPI flash devices when control data (opcode, address) must be
  48   /// passed to the SPI peripheral to specify the data to be read.
  49   ///
  50   SPI_TRANSACTION_WRITE_THEN_READ
  51 } EFI_SPI_TRANSACTION_TYPE;
  52
  53 /**
  54   Initiate a SPI transaction between the host and a SPI peripheral.
  55
  56   This routine must be called at or below TPL_NOTIFY.
  57   This routine works with the SPI bus layer to pass the SPI transaction to the
  58   SPI controller for execution on the SPI bus. There are four types of
  59   supported transactions supported by this routine:
  60   * Full Duplex: WriteBuffer and ReadBuffer are the same size.
  61   * Write Only: WriteBuffer contains data for SPI peripheral, ReadBytes = 0
  62   * Read Only: ReadBuffer to receive data from SPI peripheral, WriteBytes = 0
  63   * Write Then Read: WriteBuffer contains control data to write to SPI
  64                      peripheral before data is placed into the ReadBuffer.
  65                      Both WriteBytes and ReadBytes must be non-zero.
  66
  67   @param[in]  This              Pointer to an EFI_SPI_IO_PROTOCOL structure.
  68   @param[in]  TransactionType   Type of SPI transaction.
  69   @param[in]  DebugTransaction  Set TRUE only when debugging is desired.
  70                                 Debugging may be turned on for a single SPI
  71                                 transaction. Only this transaction will display
  72                                 debugging messages. All other transactions with
  73                                 this value set to FALSE will not display any
  74                                 debugging messages.
  75   @param[in]  ClockHz           Specify the ClockHz value as zero (0) to use
  76                                 the maximum clock frequency supported by the
  77                                 SPI controller and part. Specify a non-zero
  78                                 value only when a specific SPI transaction
  79                                 requires a reduced clock rate.
  80   @param[in]  BusWidth          Width of the SPI bus in bits: 1, 2, 4
  81   @param[in]  FrameSize         Frame size in bits, range: 1 - 32
  82   @param[in]  WriteBytes        The length of the WriteBuffer in bytes.
  83                                 Specify zero for read-only operations.
  84   @param[in]  WriteBuffer       The buffer containing data to be sent from the
  85                                 host to the SPI chip. Specify NULL for read
  86                                 only operations.
  87                                 * Frame sizes 1-8 bits: UINT8 (one byte) per
  88                                   frame
  89                                 * Frame sizes 7-16 bits: UINT16 (two bytes) per
  90                                   frame
  91                                 * Frame sizes 17-32 bits: UINT32 (four bytes)
  92                                   per frame The transmit frame is in the least
  93                                   significant N bits.
  94   @param[in]  ReadBytes         The length of the ReadBuffer in bytes.
  95                                 Specify zero for write-only operations.
  96   @param[out] ReadBuffer        The buffer to receeive data from the SPI chip
  97                                 during the transaction. Specify NULL for write
  98                                 only operations.
  99                                 * Frame sizes 1-8 bits: UINT8 (one byte) per
 100                                   frame
 101                                 * Frame sizes 7-16 bits: UINT16 (two bytes) per
 102                                   frame
 103                                 * Frame sizes 17-32 bits: UINT32 (four bytes)
 104                                   per frame The received frame is in the least
 105                                   significant N bits.
 106
 107   @retval EFI_SUCCESS            The SPI transaction completed successfully
 108   @retval EFI_BAD_BUFFER_SIZE    The writeBytes value was invalid
 109   @retval EFI_BAD_BUFFER_SIZE    The ReadBytes value was invalid
 110   @retval EFI_INVALID_PARAMETER  TransactionType is not valid,
 111                                  or BusWidth not supported by SPI peripheral or
 112                                  SPI host controller,
 113                                  or WriteBytes non-zero and WriteBuffer is
 114                                  NULL,
 115                                  or ReadBytes non-zero and ReadBuffer is NULL,
 116                                  or ReadBuffer != WriteBuffer for full-duplex
 117                                  type,
 118                                  or WriteBuffer was NULL,
 119                                  or TPL is too high
 120   @retval EFI_OUT_OF_RESOURCES   Insufficient memory for SPI transaction
 121   @retval EFI_UNSUPPORTED        The FrameSize is not supported by the SPI bus
 122                                  layer or the SPI host controller
 123   @retval EFI_UNSUPPORTED        The SPI controller was not able to support
 124
 125 **/
 126 typedef
 127 EFI_STATUS
 128 (EFIAPI *EFI_SPI_IO_PROTOCOL_TRANSACTION)(
 129   IN  CONST EFI_SPI_IO_PROTOCOL  *This,
 130   IN  EFI_SPI_TRANSACTION_TYPE   TransactionType,
 131   IN  BOOLEAN                    DebugTransaction,
 132   IN  UINT32                     ClockHz OPTIONAL,
 133   IN  UINT32                     BusWidth,
 134   IN  UINT32                     FrameSize,
 135   IN  UINT32                     WriteBytes,
 136   IN  UINT8                      *WriteBuffer,
 137   IN  UINT32                     ReadBytes,
 138   OUT UINT8                      *ReadBuffer
 139   );
 140
 141 /**
 142   Update the SPI peripheral associated with this SPI 10 instance.
 143
 144   Support socketed SPI parts by allowing the SPI peripheral driver to replace
 145   the SPI peripheral after the connection is made. An example use is socketed
 146   SPI NOR flash parts, where the size and parameters change depending upon
 147   device is in the socket.
 148
 149   @param[in] This           Pointer to an EFI_SPI_IO_PROTOCOL structure.
 150   @param[in] SpiPeripheral  Pointer to an EFI_SPI_PERIPHERAL structure.
 151
 152   @retval EFI_SUCCESS            The SPI peripheral was updated successfully
 153   @retval EFI_INVALID_PARAMETER  The SpiPeripheral value is NULL,
 154                                  or the SpiPeripheral->SpiBus is NULL,
 155                                  or the SpiP eripheral - >SpiBus pointing at
 156                                  wrong bus,
 157                                  or the SpiP eripheral - >SpiPart is NULL
 158
 159 **/
 160 typedef EFI_STATUS
 161 (EFIAPI *EFI_SPI_IO_PROTOCOL_UPDATE_SPI_PERIPHERAL)(
 162   IN CONST EFI_SPI_IO_PROTOCOL  *This,
 163   IN CONST EFI_SPI_PERIPHERAL   *SpiPeripheral
 164   );
 165
 166 ///
 167 /// The EFI_SPI_BUS_ TRANSACTION data structure contains the description of the
 168 /// SPI transaction to perform on the host controller.
 169 ///
 170 typedef struct _EFI_SPI_BUS_TRANSACTION {
 171   ///
 172   /// Pointer to the SPI peripheral being manipulated.
 173   ///
 174   CONST EFI_SPI_PERIPHERAL    *SpiPeripheral;
 175
 176   ///
 177   /// Type of transaction specified by one of the EFI_SPI_TRANSACTION_TYPE
 178   /// values.
 179   ///
 180   EFI_SPI_TRANSACTION_TYPE    TransactionType;
 181
 182   ///
 183   /// TRUE if the transaction is being debugged. Debugging may be turned on for
 184   /// a single SPI transaction. Only this transaction will display debugging
 185   /// messages. All other transactions with this value set to FALSE will not
 186   /// display any debugging messages.
 187   ///
 188   BOOLEAN                     DebugTransaction;
 189
 190   ///
 191   /// SPI bus width in bits: 1, 2, 4
 192   ///
 193   UINT32                      BusWidth;
 194
 195   ///
 196   /// Frame size in bits, range: 1 - 32
 197   ///
 198   UINT32                      FrameSize;
 199
 200   ///
 201   /// Length of the write buffer in bytes
 202   ///
 203   UINT32                      WriteBytes;
 204
 205   ///
 206   /// Buffer containing data to send to the SPI peripheral
 207   /// Frame sizes 1 - 8 bits: UINT8 (one byte) per frame
 208   /// Frame sizes 7 - 16 bits : UINT16 (two bytes) per frame
 209   ///
 210   UINT8                       *WriteBuffer;
 211
 212   ///
 213   /// Length of the read buffer in bytes
 214   ///
 215   UINT32                      ReadBytes;
 216
 217   ///
 218   /// Buffer to receive the data from the SPI peripheral
 219   /// * Frame sizes 1 - 8 bits: UINT8 (one byte) per frame
 220   /// * Frame sizes 7 - 16 bits : UINT16 (two bytes) per frame
 221   /// * Frame sizes 17 - 32 bits : UINT32 (four bytes) per frame
 222   ///
 223   UINT8                       *ReadBuffer;
 224 } EFI_SPI_BUS_TRANSACTION;
 225
 226 ///
 227 /// Support managed SPI data transactions between the SPI controller and a SPI
 228 /// chip.
 229 ///
 230 struct _EFI_SPI_IO_PROTOCOL {
 231   ///
 232   /// Address of an EFI_SPI_PERIPHERAL data structure associated with this
 233   /// protocol instance.
 234   ///
 235   CONST EFI_SPI_PERIPHERAL    *SpiPeripheral;
 236
 237   ///
 238   /// Address of the original EFI_SPI_PERIPHERAL data structure associated with
 239   /// this protocol instance.
 240   ///
 241   CONST EFI_SPI_PERIPHERAL    *OriginalSpiPeripheral;
 242
 243   ///
 244   /// Mask of frame sizes which the SPI 10 layer supports. Frame size of N-bits
 245   /// is supported when bit N-1 is set. The host controller must support a
 246   /// frame size of 8-bits. Frame sizes of 16, 24 and 32-bits are converted to
 247   /// 8-bit frame sizes by the SPI bus layer if the frame size is not supported
 248   /// by the SPI host controller.
 249   ///
 250   UINT32    FrameSizeSupportMask;
 251
 252   ///
 253   /// Maximum transfer size in bytes: 1 - Oxffffffff
 254   ///
 255   UINT32    MaximumTransferBytes;
 256
 257   ///
 258   /// Transaction attributes: One or more from:
 259   /// * SPI_10_SUPPORTS_2_B1T_DATA_BUS_W1DTH
 260   ///   - The SPI host and peripheral supports a 2-bit data bus
 261   /// * SPI_IO_SUPPORTS_4_BIT_DATA_BUS_W1DTH
 262   ///   - The SPI host and peripheral supports a 4-bit data bus
 263   /// * SPI_IO_TRANSFER_SIZE_INCLUDES_OPCODE
 264   ///   - Transfer size includes the opcode byte
 265   /// * SPI_IO_TRANSFER_SIZE_INCLUDES_ADDRESS
 266   ///   - Transfer size includes the 3 address bytes
 267   ///
 268   UINT32                                       Attributes;
 269
 270   ///
 271   /// Pointer to legacy SPI controller protocol
 272   ///
 273   CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL     *LegacySpiProtocol;
 274
 275   ///
 276   /// Initiate a SPI transaction between the host and a SPI peripheral.
 277   ///
 278   EFI_SPI_IO_PROTOCOL_TRANSACTION              Transaction;
 279
 280   ///
 281   /// Update the SPI peripheral associated with this SPI 10 instance.
 282   ///
 283   EFI_SPI_IO_PROTOCOL_UPDATE_SPI_PERIPHERAL    UpdateSpiPeripheral;
 284 };
 285
 286 #endif // __SPI_IO_PROTOCOL_H__