You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

294 lines
11 KiB

/** @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__