diff options
Diffstat (limited to 'src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/SpiConfiguration.h')
| -rw-r--r-- | src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/SpiConfiguration.h | 293 |
1 files changed, 293 insertions, 0 deletions
diff --git a/src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/SpiConfiguration.h b/src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/SpiConfiguration.h new file mode 100644 index 0000000000..4c5c8a16d8 --- /dev/null +++ b/src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/SpiConfiguration.h @@ -0,0 +1,293 @@ +/** @file + This file defines the SPI Configuration Protocol. + + Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> + This program and the accompanying materials + are licensed and made available under the terms and conditions of the BSD + License which accompanies this distribution. The full text of the license may + be found at http://opensource.org/licenses/bsd-license.php + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + + @par Revision Reference: + This Protocol was introduced in UEFI PI Specification 1.6. + +**/ + +#ifndef __SPI_CONFIGURATION_PROTOCOL_H__ +#define __SPI_CONFIGURATION_PROTOCOL_H__ + +/// +/// Global ID for the SPI Configuration Protocol +/// +#define EFI_SPI_CONFIGURATION_GUID \ + { 0x85a6d3e6, 0xb65b, 0x4afc, \ + { 0xb3, 0x8f, 0xc6, 0xd5, 0x4a, 0xf6, 0xdd, 0xc8 }} + +/// +/// Macros to easily specify frequencies in hertz, kilohertz and megahertz. +/// +#define Hz(Frequency) (Frequency) +#define KHz(Frequency) (1000 * Hz (Frequency)) +#define MHz(Frequency) (1000 * KHz (Frequency)) + +typedef struct _EFI_SPI_PERIPHERAL EFI_SPI_PERIPHERAL; + +/** + Manipulate the chip select for a SPI device. + + This routine must be called at or below TPL_NOTIFY. + Update the value of the chip select line for a SPI peripheral. + The SPI bus layer calls this routine either in the board layer or in the SPI + controller to manipulate the chip select pin at the start and end of a SPI + transaction. + + @param[in] SpiPeripheral The address of an EFI_SPI_PERIPHERAL data structure + describing the SPI peripheral whose chip select pin + is to be manipulated. The routine may access the + ChipSelectParameter field to gain sufficient + context to complete the operation. + @param[in] PinValue The value to be applied to the chip select line of + the SPI peripheral. + + @retval EFI_SUCCESS The chip select was set successfully + @retval EFI_NOT_READY Support for the chip select is not properly + initialized + @retval EFI_INVALID_PARAMETER The SpiPeripheral->ChipSelectParameter value + is invalid + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_SPI_CHIP_SELECT) ( + IN CONST EFI_SPI_PERIPHERAL *SpiPeripheral, + IN BOOLEAN PinValue + ); + +/** + Set up the clock generator to produce the correct clock frequency, phase and + polarity for a SPI chip. + + This routine must be called at or below TPL_NOTIFY. + This routine updates the clock generator to generate the correct frequency + and polarity for the SPI clock. + + @param[in] SpiPeripheral Pointer to a EFI_SPI_PERIPHERAL data structure from + which the routine can access the ClockParameter, + ClockPhase and ClockPolarity fields. The routine + also has access to the names for the SPI bus and + chip which can be used during debugging. + @param[in] ClockHz Pointer to the requested clock frequency. The clock + generator will choose a supported clock frequency + which is less then or equal to this value. + Specify zero to turn the clock generator off. + The actual clock frequency supported by the clock + generator will be returned. + + @retval EFI_SUCCESS The clock was set up successfully + @retval EFI_UNSUPPORTED The SPI controller was not able to support the + frequency requested by CLockHz + +**/ +typedef EFI_STATUS +(EFIAPI *EFI_SPI_CLOCK) ( + IN CONST EFI_SPI_PERIPHERAL *SpiPeripheral, + IN UINT32 *ClockHz + ); + +/// +/// The EFI_SPI_PART data structure provides a description of a SPI part which +/// is independent of the use on the board. This data is available directly +/// from the part's datasheet and may be provided by the vendor. +/// +typedef struct _EFI_SPI_PART { + /// + /// A Unicode string specifying the SPI chip vendor. + /// + CONST CHAR16 *Vendor; + + /// + /// A Unicode string specifying the SPI chip part number. + /// + CONST CHAR16 *PartNumber; + + /// + /// The minimum SPI bus clock frequency used to access this chip. This value + /// may be specified in the chip's datasheet. If not, use the value of zero. + /// + UINT32 MinClockHz; + + /// + /// The maximum SPI bus clock frequency used to access this chip. This value + /// is found in the chip's datasheet. + /// + UINT32 MaxClockHz; + + /// + /// Specify the polarity of the chip select pin. This value can be found in + /// the SPI chip's datasheet. Specify TRUE when a one asserts the chip select + ///and FALSE when a zero asserts the chip select. + /// + BOOLEAN ChipSelectPolarity; +} EFI_SPI_PART; + +/// +/// The EFI_SPI_BUS data structure provides the connection details between the +/// physical SPI bus and the EFI_SPI_HC_PROTOCOL instance which controls that +/// SPI bus. This data structure also describes the details of how the clock is +/// generated for that SPI bus. Finally this data structure provides the list +/// of physical SPI devices which are attached to the SPI bus. +/// +typedef struct _EFI_SPI_BUS { + /// + /// A Unicode string describing the SPI bus + /// + CONST CHAR16 *FriendlyName; + + /// + /// Address of the first EFI_SPI_PERIPHERAL data structure connected to this + /// bus. Specify NULL if there are no SPI peripherals connected to this bus. + /// + CONST EFI_SPI_PERIPHERAL *Peripherallist; + + /// + /// Address of an EFI_DEVICE_PATH_PROTOCOL data structure which uniquely + /// describes the SPI controller. + /// + CONST EFI_DEVICE_PATH_PROTOCOL *ControllerPath; + + /// + /// Address of the routine which controls the clock used by the SPI bus for + /// this SPI peripheral. The SPI host co ntroller's clock routine is called + /// when this value is set to NULL. + /// + EFI_SPI_CLOCK Clock; + + /// + /// Address of a data structure containing the additional values which + /// describe the necessary control for the clock. When Clock is NULL, + /// the declaration for this data structure is provided by the vendor of the + /// host's SPI controller driver. When Clock is not NULL, the declaration for + /// this data structure is provided by the board layer. + /// + VOID *ClockParameter; +} EFI_SPI_BUS; + +/// +/// The EFI_SPI_PERIPHERAL data structure describes how a specific block of +/// logic which is connected to the SPI bus. This data structure also selects +/// which upper level driver is used to manipulate this SPI device. +/// The SpiPeripheraLDriverGuid is available from the vendor of the SPI +/// peripheral driver. +/// +struct _EFI_SPI_PERIPHERAL { + /// + /// Address of the next EFI_SPI_PERIPHERAL data structure. Specify NULL if + /// the current data structure is the last one on the SPI bus. + /// + CONST EFI_SPI_PERIPHERAL *NextSpiPeripheral; + + /// + /// A unicode string describing the function of the SPI part. + /// + CONST CHAR16 *FriendlyName; + + /// + /// Address of a GUID provided by the vendor of the SPI peripheral driver. + /// Instead of using a " EFI_SPI_IO_PROTOCOL" GUID, the SPI bus driver uses + /// this GUID to identify an EFI_SPI_IO_PROTOCOL data structure and to + /// provide the connection points for the SPI peripheral drivers. + /// This reduces the comparison logic in the SPI peripheral driver's + /// Supported routine. + /// + CONST GUID *SpiPeripheralDriverGuid; + + /// + /// The address of an EFI_SPI_PART data structure which describes this chip. + /// + CONST EFI_SPI_PART *SpiPart; + + /// + /// The maximum clock frequency is specified in the EFI_SPI_P ART. When this + /// this value is non-zero and less than the value in the EFI_SPI_PART then + /// this value is used for the maximum clock frequency for the SPI part. + /// + UINT32 MaxClockHz; + + /// + /// Specify the idle value of the clock as found in the datasheet. + /// Use zero (0) if the clock'S idle value is low or one (1) if the the + /// clock's idle value is high. + /// + BOOLEAN ClockPolarity; + + /// + /// Specify the clock delay after chip select. Specify zero (0) to delay an + /// entire clock cycle or one (1) to delay only half a clock cycle. + /// + BOOLEAN ClockPhase; + + /// + /// SPI peripheral attributes, select zero or more of: + /// * SPI_PART_SUPPORTS_2_B1T_DATA_BUS_W1DTH - The SPI peripheral is wired to + /// support a 2-bit data bus + /// * SPI_PART_SUPPORTS_4_B1T_DATA_BUS_W1DTH - The SPI peripheral is wired to + /// support a 4-bit data bus + /// + UINT32 Attributes; + + /// + /// Address of a vendor specific data structure containing additional board + /// configuration details related to the SPI chip. The SPI peripheral layer + /// uses this data structure when configuring the chip. + /// + CONST VOID *ConfigurationData; + + /// + /// The address of an EFI_SPI_BUS data structure which describes the SPI bus + /// to which this chip is connected. + /// + CONST EFI_SPI_BUS *SpiBus; + + /// + /// Address of the routine which controls the chip select pin for this SPI + /// peripheral. Call the SPI host controller's chip select routine when this + /// value is set to NULL. + /// + EFI_SPI_CHIP_SELECT ChipSelect; + + /// + /// Address of a data structure containing the additional values which + /// describe the necessary control for the chip select. When ChipSelect is + /// NULL, the declaration for this data structure is provided by the vendor + /// of the host's SPI controller driver. The vendor's documentation specifies + /// the necessary values to use for the chip select pin selection and + /// control. When Chipselect is not NULL, the declaration for this data + /// structure is provided by the board layer. + /// + VOID *ChipSelectParameter; +}; + +/// +/// Describe the details of the board's SPI busses to the SPI driver stack. +/// The board layer uses the EFI_SPI_CONFIGURATION_PROTOCOL to expose the data +/// tables which describe the board's SPI busses, The SPI bus layer uses these +/// tables to configure the clock, chip select and manage the SPI transactions +/// on the SPI controllers. +/// +typedef struct _EFI_SPI_CONFIGURATION_PROTOCOL { + /// + /// The number of SPI busses on the board. + /// + UINT32 BusCount; + + /// + /// The address of an array of EFI_SPI_BUS data structure addresses. + /// + CONST EFI_SPI_BUS *CONST *CONST Buslist; +} EFI_SPI_CONFIGURATION_PROTOCOL; + +extern EFI_GUID gEfiSpiConfigurationProtocolGuid; + +#endif // __SPI_CONFIGURATION_PROTOCOL_H__ |