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