MdePkg/Include/Protocol/SpiConfiguration.h

   1 /** @file
   2   This file defines the SPI Configuration 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_CONFIGURATION_PROTOCOL_H__
  19 #define __SPI_CONFIGURATION_PROTOCOL_H__
  20
  21 ///
  22 /// Global ID for the SPI Configuration Protocol
  23 ///
  24 #define EFI_SPI_CONFIGURATION_GUID  \
  25   { 0x85a6d3e6, 0xb65b, 0x4afc,     \
  26     { 0xb3, 0x8f, 0xc6, 0xd5, 0x4a, 0xf6, 0xdd, 0xc8 }}
  27
  28 ///
  29 /// Macros to easily specify frequencies in hertz, kilohertz and megahertz.
  30 ///
  31 #define Hz(Frequency)   (Frequency)
  32 #define KHz(Frequency)  (1000 * Hz (Frequency))
  33 #define MHz(Frequency)  (1000 * KHz (Frequency))
  34
  35 typedef struct _EFI_SPI_PERIPHERAL EFI_SPI_PERIPHERAL;
  36
  37 /**
  38   Manipulate the chip select for a SPI device.
  39
  40   This routine must be called at or below TPL_NOTIFY.
  41   Update the value of the chip select line for a SPI peripheral.
  42   The SPI bus layer calls this routine either in the board layer or in the SPI
  43   controller to manipulate the chip select pin at the start and end of a SPI
  44   transaction.
  45
  46   @param[in] SpiPeripheral  The address of an EFI_SPI_PERIPHERAL data structure
  47                             describing the SPI peripheral whose chip select pin
  48                             is to be manipulated. The routine may access the
  49                             ChipSelectParameter field to gain sufficient
  50                             context to complete the operation.
  51   @param[in] PinValue       The value to be applied to the chip select line of
  52                             the SPI peripheral.
  53
  54   @retval EFI_SUCCESS            The chip select was set successfully
  55   @retval EFI_NOT_READY          Support for the chip select is not properly
  56                                  initialized
  57   @retval EFI_INVALID_PARAMETER  The SpiPeripheral->ChipSelectParameter value
  58                                  is invalid
  59
  60 **/
  61 typedef
  62 EFI_STATUS
  63 (EFIAPI *EFI_SPI_CHIP_SELECT) (
  64   IN CONST EFI_SPI_PERIPHERAL  *SpiPeripheral,
  65   IN BOOLEAN                   PinValue
  66   );
  67
  68 /**
  69   Set up the clock generator to produce the correct clock frequency, phase and
  70   polarity for a SPI chip.
  71
  72   This routine must be called at or below TPL_NOTIFY.
  73   This routine updates the clock generator to generate the correct frequency
  74   and polarity for the SPI clock.
  75
  76   @param[in] SpiPeripheral  Pointer to a EFI_SPI_PERIPHERAL data structure from
  77                             which the routine can access the ClockParameter,
  78                             ClockPhase and ClockPolarity fields. The routine
  79                             also has access to the names for the SPI bus and
  80                             chip which can be used during debugging.
  81   @param[in] ClockHz        Pointer to the requested clock frequency. The clock
  82                             generator will choose a supported clock frequency
  83                             which is less then or equal to this value.
  84                             Specify zero to turn the clock generator off.
  85                             The actual clock frequency supported by the clock
  86                             generator will be returned.
  87
  88   @retval EFI_SUCCESS      The clock was set up successfully
  89   @retval EFI_UNSUPPORTED  The SPI controller was not able to support the
  90                            frequency requested by CLockHz
  91
  92 **/
  93 typedef EFI_STATUS
  94 (EFIAPI *EFI_SPI_CLOCK) (
  95   IN CONST EFI_SPI_PERIPHERAL  *SpiPeripheral,
  96   IN UINT32                    *ClockHz
  97   );
  98
  99 ///
 100 /// The EFI_SPI_PART data structure provides a description of a SPI part which
 101 /// is independent of the use on the board. This data is available directly
 102 /// from the part's datasheet and may be provided by the vendor.
 103 ///
 104 typedef struct _EFI_SPI_PART {
 105   ///
 106   /// A Unicode string specifying the SPI chip vendor.
 107   ///
 108   CONST CHAR16 *Vendor;
 109
 110   ///
 111   /// A Unicode string specifying the SPI chip part number.
 112   ///
 113   CONST CHAR16 *PartNumber;
 114
 115   ///
 116   /// The minimum SPI bus clock frequency used to access this chip. This value
 117   /// may be specified in the chip's datasheet. If not, use the value of zero.
 118   ///
 119   UINT32       MinClockHz;
 120
 121   ///
 122   /// The maximum SPI bus clock frequency used to access this chip. This value
 123   /// is found in the chip's datasheet.
 124   ///
 125   UINT32       MaxClockHz;
 126
 127   ///
 128   /// Specify the polarity of the chip select pin. This value can be found in
 129   /// the SPI chip's datasheet. Specify TRUE when a one asserts the chip select
 130   ///and FALSE when a zero asserts the chip select.
 131   ///
 132   BOOLEAN      ChipSelectPolarity;
 133 } EFI_SPI_PART;
 134
 135 ///
 136 /// The EFI_SPI_BUS data structure provides the connection details between the
 137 /// physical SPI bus and the EFI_SPI_HC_PROTOCOL instance which controls that
 138 /// SPI bus. This data structure also describes the details of how the clock is
 139 /// generated for that SPI bus. Finally this data structure provides the list
 140 /// of physical SPI devices which are attached to the SPI bus.
 141 ///
 142 typedef struct _EFI_SPI_BUS {
 143   ///
 144   /// A Unicode string describing the SPI bus
 145   ///
 146   CONST CHAR16                   *FriendlyName;
 147
 148   ///
 149   /// Address of the first EFI_SPI_PERIPHERAL data structure connected to this
 150   /// bus. Specify NULL if there are no SPI peripherals connected to this bus.
 151   ///
 152   CONST EFI_SPI_PERIPHERAL       *Peripherallist;
 153
 154   ///
 155   /// Address of an EFI_DEVICE_PATH_PROTOCOL data structure which uniquely
 156   /// describes the SPI controller.
 157   ///
 158   CONST EFI_DEVICE_PATH_PROTOCOL *ControllerPath;
 159
 160   ///
 161   /// Address of the routine which controls the clock used by the SPI bus for
 162   /// this SPI peripheral. The SPI host co ntroller's clock routine is called
 163   /// when this value is set to NULL.
 164   ///
 165   EFI_SPI_CLOCK                  Clock;
 166
 167   ///
 168   /// Address of a data structure containing the additional values which
 169   /// describe the necessary control for the clock. When Clock is NULL,
 170   /// the declaration for this data structure is provided by the vendor of the
 171   /// host's SPI controller driver. When Clock is not NULL, the declaration for
 172   /// this data structure is provided by the board layer.
 173   ///
 174   VOID                           *ClockParameter;
 175 } EFI_SPI_BUS;
 176
 177 ///
 178 /// The EFI_SPI_PERIPHERAL data structure describes how a specific block of
 179 /// logic which is connected to the SPI bus. This data structure also selects
 180 /// which upper level driver is used to manipulate this SPI device.
 181 /// The SpiPeripheraLDriverGuid is available from the vendor of the SPI
 182 /// peripheral driver.
 183 ///
 184 struct _EFI_SPI_PERIPHERAL {
 185   ///
 186   /// Address of the next EFI_SPI_PERIPHERAL data structure. Specify NULL if
 187   /// the current data structure is the last one on the SPI bus.
 188   ///
 189   CONST EFI_SPI_PERIPHERAL *NextSpiPeripheral;
 190
 191   ///
 192   /// A unicode string describing the function of the SPI part.
 193   ///
 194   CONST CHAR16             *FriendlyName;
 195
 196   ///
 197   /// Address of a GUID provided by the vendor of the SPI peripheral driver.
 198   /// Instead of using a " EFI_SPI_IO_PROTOCOL" GUID, the SPI bus driver uses
 199   /// this GUID to identify an EFI_SPI_IO_PROTOCOL data structure and to
 200   /// provide the connection points for the SPI peripheral drivers.
 201   /// This reduces the comparison logic in the SPI peripheral driver's
 202   /// Supported routine.
 203   ///
 204   CONST GUID               *SpiPeripheralDriverGuid;
 205
 206   ///
 207   /// The address of an EFI_SPI_PART data structure which describes this chip.
 208   ///
 209   CONST EFI_SPI_PART       *SpiPart;
 210
 211   ///
 212   /// The maximum clock frequency is specified in the EFI_SPI_P ART. When this
 213   /// this value is non-zero and less than the value in the EFI_SPI_PART then
 214   /// this value is used for the maximum clock frequency for the SPI part.
 215   ///
 216   UINT32                   MaxClockHz;
 217
 218   ///
 219   /// Specify the idle value of the clock as found in the datasheet.
 220   /// Use zero (0) if the clock'S idle value is low or one (1) if the the
 221   /// clock's idle value is high.
 222   ///
 223   BOOLEAN                  ClockPolarity;
 224
 225   ///
 226   /// Specify the clock delay after chip select. Specify zero (0) to delay an
 227   /// entire clock cycle or one (1) to delay only half a clock cycle.
 228   ///
 229   BOOLEAN                  ClockPhase;
 230
 231   ///
 232   /// SPI peripheral attributes, select zero or more of:
 233   /// * SPI_PART_SUPPORTS_2_B1T_DATA_BUS_W1DTH - The SPI peripheral is wired to
 234   ///   support a 2-bit data bus
 235   /// * SPI_PART_SUPPORTS_4_B1T_DATA_BUS_W1DTH - The SPI peripheral is wired to
 236   ///   support a 4-bit data bus
 237   ///
 238   UINT32                   Attributes;
 239
 240   ///
 241   /// Address of a vendor specific data structure containing additional board
 242   /// configuration details related to the SPI chip. The SPI peripheral layer
 243   /// uses this data structure when configuring the chip.
 244   ///
 245   CONST VOID               *ConfigurationData;
 246
 247   ///
 248   /// The address of an EFI_SPI_BUS data structure which describes the SPI bus
 249   /// to which this chip is connected.
 250   ///
 251   CONST EFI_SPI_BUS        *SpiBus;
 252
 253   ///
 254   /// Address of the routine which controls the chip select pin for this SPI
 255   /// peripheral. Call the SPI host controller's chip select routine when this
 256   /// value is set to NULL.
 257   ///
 258   EFI_SPI_CHIP_SELECT      ChipSelect;
 259
 260   ///
 261   /// Address of a data structure containing the additional values which
 262   /// describe the necessary control for the chip select. When ChipSelect is
 263   /// NULL, the declaration for this data structure is provided by the vendor
 264   /// of the host's SPI controller driver. The vendor's documentation specifies
 265   /// the necessary values to use for the chip select pin selection and
 266   /// control. When Chipselect is not NULL, the declaration for this data
 267   /// structure is provided by the board layer.
 268   ///
 269   VOID                     *ChipSelectParameter;
 270 };
 271
 272 ///
 273 /// Describe the details of the board's SPI busses to the SPI driver stack.
 274 /// The board layer uses the EFI_SPI_CONFIGURATION_PROTOCOL to expose the data
 275 /// tables which describe the board's SPI busses, The SPI bus layer uses these
 276 /// tables to configure the clock, chip select and manage the SPI transactions
 277 /// on the SPI controllers.
 278 ///
 279 typedef struct _EFI_SPI_CONFIGURATION_PROTOCOL {
 280   ///
 281   /// The number of SPI busses on the board.
 282   ///
 283   UINT32                          BusCount;
 284
 285   ///
 286   /// The address of an array of EFI_SPI_BUS data structure addresses.
 287   ///
 288   CONST EFI_SPI_BUS *CONST *CONST Buslist;
 289 } EFI_SPI_CONFIGURATION_PROTOCOL;
 290
 291 extern EFI_GUID gEfiSpiConfigurationProtocolGuid;
 292
 293 #endif // __SPI_CONFIGURATION_PROTOCOL_H__