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