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