MdePkg/Include/Protocol/SpiHc.h

   1 /** @file
   2   This file defines the SPI Host Controller 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_HC_PROTOCOL_H__
  13 #define __SPI_HC_PROTOCOL_H__
  14
  15 #include <Protocol/SpiConfiguration.h>
  16 #include <Protocol/SpiIo.h>
  17
  18 ///
  19 /// Global ID for the SPI Host Controller Protocol
  20 ///
  21 #define EFI_SPI_HOST_GUID  \
  22   { 0xc74e5db2, 0xfa96, 0x4ae2,   \
  23     { 0xb3, 0x99, 0x15, 0x97, 0x7f, 0xe3, 0x0, 0x2d }}
  24
  25 ///
  26 /// EDK2-style name
  27 ///
  28 #define EFI_SPI_HC_PROTOCOL_GUID  EFI_SPI_HOST_GUID
  29
  30 typedef struct _EFI_SPI_HC_PROTOCOL EFI_SPI_HC_PROTOCOL;
  31
  32 /**
  33   Assert or deassert the SPI chip select.
  34
  35   This routine is called at TPL_NOTIFY.
  36   Update the value of the chip select line for a SPI peripheral. The SPI bus
  37   layer calls this routine either in the board layer or in the SPI controller
  38   to manipulate the chip select pin at the start and end of a SPI transaction.
  39
  40   @param[in] This           Pointer to an EFI_SPI_HC_PROTOCOL structure.
  41   @param[in] SpiPeripheral  The address of an EFI_SPI_PERIPHERAL data structure
  42                             describing the SPI peripheral whose chip select pin
  43                             is to be manipulated. The routine may access the
  44                             ChipSelectParameter field to gain sufficient
  45                             context to complete the operati on.
  46   @param[in] PinValue       The value to be applied to the chip select line of
  47                             the SPI peripheral.
  48
  49   @retval EFI_SUCCESS            The chip select was set as requested
  50   @retval EFI_NOT_READY          Support for the chip select is not properly
  51                                  initialized
  52   @retval EFI_INVALID_PARAMETER  The ChipSeLect value or its contents are
  53                                  invalid
  54
  55 **/
  56 typedef EFI_STATUS
  57 (EFIAPI *EFI_SPI_HC_PROTOCOL_CHIP_SELECT) (
  58   IN CONST EFI_SPI_HC_PROTOCOL  *This,
  59   IN CONST EFI_SPI_PERIPHERAL   *SpiPeripheral,
  60   IN BOOLEAN                    PinValue
  61   );
  62
  63 /**
  64   Set up the clock generator to produce the correct clock frequency, phase and
  65   polarity for a SPI chip.
  66
  67   This routine is called at TPL_NOTIFY.
  68   This routine updates the clock generator to generate the correct frequency
  69   and polarity for the SPI clock.
  70
  71   @param[in] This           Pointer to an EFI_SPI_HC_PROTOCOL structure.
  72   @param[in] SpiPeripheral  Pointer to a EFI_SPI_PERIPHERAL data structure from
  73                             which the routine can access the ClockParameter,
  74                             ClockPhase and ClockPolarity fields. The routine
  75                             also has access to the names for the SPI bus and
  76                             chip which can be used during debugging.
  77   @param[in] ClockHz        Pointer to the requested clock frequency. The SPI
  78                             host controller will choose a supported clock
  79                             frequency which is less then or equal to this
  80                             value. Specify zero to turn the clock generator
  81                             off. The actual clock frequency supported by the
  82                             SPI host controller will be returned.
  83
  84   @retval EFI_SUCCESS      The clock was set up successfully
  85   @retval EFI_UNSUPPORTED  The SPI controller was not able to support the
  86                            frequency requested by ClockHz
  87
  88 **/
  89 typedef EFI_STATUS
  90 (EFIAPI *EFI_SPI_HC_PROTOCOL_CLOCK) (
  91   IN CONST EFI_SPI_HC_PROTOCOL  *This,
  92   IN CONST EFI_SPI_PERIPHERAL   *SpiPeripheral,
  93   IN UINT32                      *ClockHz
  94   );
  95
  96 /**
  97   Perform the SPI transaction on the SPI peripheral using the SPI host
  98   controller.
  99
 100   This routine is called at TPL_NOTIFY.
 101   This routine synchronously returns EFI_SUCCESS indicating that the
 102   asynchronous SPI transaction was started. The routine then waits for
 103   completion of the SPI transaction prior to returning the final transaction
 104   status.
 105
 106   @param[in] This            Pointer to an EFI_SPI_HC_PROTOCOL structure.
 107   @param[in] BusTransaction  Pointer to a EFI_SPI_BUS_ TRANSACTION containing
 108                              the description of the SPI transaction to perform.
 109
 110   @retval EFI_SUCCESS          The transaction completed successfully
 111   @retval EFI_BAD_BUFFER_SIZE  The BusTransaction->WriteBytes value is invalid,
 112                                or the BusTransaction->ReadinBytes value is
 113                                invalid
 114   @retval EFI_UNSUPPORTED      The BusTransaction-> Transaction Type is
 115                                unsupported
 116
 117 **/
 118 typedef EFI_STATUS
 119 (EFIAPI *EFI_SPI_HC_PROTOCOL_TRANSACTION) (
 120   IN CONST EFI_SPI_HC_PROTOCOL  *This,
 121   IN EFI_SPI_BUS_TRANSACTION    *BusTransaction
 122   );
 123
 124 ///
 125 /// Support a SPI data transaction between the SPI controller and a SPI chip.
 126 ///
 127 struct _EFI_SPI_HC_PROTOCOL {
 128   ///
 129   /// Host control attributes, may have zero or more of the following set:
 130   /// * HC_SUPPORTS_WRITE_ONLY_OPERATIONS
 131   /// * HC_SUPPORTS_READ_ONLY_OPERATIONS
 132   /// * HC_SUPPORTS_WRITE_THEN_READ_OPERATIONS
 133   /// * HC_TX_FRAME_IN_MOST_SIGNIFICANT_BITS
 134   ///   - The SPI host controller requires the transmit frame to be in most
 135   ///     significant bits instead of least significant bits.The host driver
 136   ///     will adjust the frames if necessary.
 137   /// * HC_RX_FRAME_IN_MOST_SIGNIFICANT_BITS
 138   ///   - The SPI host controller places the receive frame to be in most
 139   ///     significant bits instead of least significant bits.The host driver
 140   ///     will adjust the frames to be in the least significant bits if
 141   ///     necessary.
 142   /// * HC_SUPPORTS_2_BIT_DATA_BUS_W1DTH
 143   ///   - The SPI controller supports a 2 - bit data bus
 144   /// * HC_SUPPORTS_4_B1T_DATA_BUS_WIDTH
 145   ///   - The SPI controller supports a 4 - bit data bus
 146   /// * HC_TRANSFER_SIZE_INCLUDES_OPCODE
 147   ///   - Transfer size includes the opcode byte
 148   /// * HC_TRANSFER_SIZE_INCLUDES_ADDRESS
 149   ///   - Transfer size includes the 3 address bytes
 150   /// The SPI host controller must support full - duplex (receive while
 151   /// sending) operation.The SPI host controller must support a 1 - bit bus
 152   /// width.
 153   ///
 154   UINT32                          Attributes;
 155
 156   ///
 157   /// Mask of frame sizes which the SPI host controller supports. Frame size of
 158   /// N-bits is supported when bit N-1 is set. The host controller must support
 159   /// a frame size of 8-bits.
 160   ///
 161   UINT32                          FrameSizeSupportMask;
 162
 163   ///
 164   /// Maximum transfer size in bytes: 1 - Oxffffffff
 165   ///
 166   UINT32                          MaximumTransferBytes;
 167
 168   ///
 169   /// Assert or deassert the SPI chip select.
 170   ///
 171   EFI_SPI_HC_PROTOCOL_CHIP_SELECT ChipSelect;
 172
 173   ///
 174   /// Set up the clock generator to produce the correct clock frequency, phase
 175   /// and polarity for a SPI chip.
 176   ///
 177   EFI_SPI_HC_PROTOCOL_CLOCK       Clock;
 178
 179   ///
 180   /// Perform the SPI transaction on the SPI peripheral using the SPI host
 181   /// controller.
 182   ///
 183   EFI_SPI_HC_PROTOCOL_TRANSACTION Transaction;
 184 };
 185
 186 extern EFI_GUID gEfiSpiHcProtocolGuid;
 187
 188 #endif // __SPI_HC_PROTOCOL_H__