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