Ronak Kanabar | 1ae366f | 2023-06-07 01:21:56 +0530 | [diff] [blame^] | 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__ |