/** @file | |
This file defines the SPI Host Controller 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_HC_PROTOCOL_H__ | |
#define __SPI_HC_PROTOCOL_H__ | |
#include <Protocol/SpiConfiguration.h> | |
#include <Protocol/SpiIo.h> | |
/// | |
/// Global ID for the SPI Host Controller Protocol | |
/// | |
#define EFI_SPI_HOST_GUID \ | |
{ 0xc74e5db2, 0xfa96, 0x4ae2, \ | |
{ 0xb3, 0x99, 0x15, 0x97, 0x7f, 0xe3, 0x0, 0x2d }} | |
/// | |
/// EDK2-style name | |
/// | |
#define EFI_SPI_HC_PROTOCOL_GUID EFI_SPI_HOST_GUID | |
typedef struct _EFI_SPI_HC_PROTOCOL EFI_SPI_HC_PROTOCOL; | |
/** | |
Assert or deassert the SPI chip select. | |
This routine is called at 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] This Pointer to an EFI_SPI_HC_PROTOCOL structure. | |
@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 operati on. | |
@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 as requested | |
@retval EFI_NOT_READY Support for the chip select is not properly | |
initialized | |
@retval EFI_INVALID_PARAMETER The ChipSeLect value or its contents are | |
invalid | |
**/ | |
typedef EFI_STATUS | |
(EFIAPI *EFI_SPI_HC_PROTOCOL_CHIP_SELECT) ( | |
IN CONST EFI_SPI_HC_PROTOCOL *This, | |
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 is called at TPL_NOTIFY. | |
This routine updates the clock generator to generate the correct frequency | |
and polarity for the SPI clock. | |
@param[in] This Pointer to an EFI_SPI_HC_PROTOCOL structure. | |
@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 SPI | |
host controller 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 | |
SPI host controller 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_HC_PROTOCOL_CLOCK) ( | |
IN CONST EFI_SPI_HC_PROTOCOL *This, | |
IN CONST EFI_SPI_PERIPHERAL *SpiPeripheral, | |
IN UINT32 *ClockHz | |
); | |
/** | |
Perform the SPI transaction on the SPI peripheral using the SPI host | |
controller. | |
This routine is called at TPL_NOTIFY. | |
This routine synchronously returns EFI_SUCCESS indicating that the | |
asynchronous SPI transaction was started. The routine then waits for | |
completion of the SPI transaction prior to returning the final transaction | |
status. | |
@param[in] This Pointer to an EFI_SPI_HC_PROTOCOL structure. | |
@param[in] BusTransaction Pointer to a EFI_SPI_BUS_ TRANSACTION containing | |
the description of the SPI transaction to perform. | |
@retval EFI_SUCCESS The transaction completed successfully | |
@retval EFI_BAD_BUFFER_SIZE The BusTransaction->WriteBytes value is invalid, | |
or the BusTransaction->ReadinBytes value is | |
invalid | |
@retval EFI_UNSUPPORTED The BusTransaction-> Transaction Type is | |
unsupported | |
**/ | |
typedef EFI_STATUS | |
(EFIAPI *EFI_SPI_HC_PROTOCOL_TRANSACTION) ( | |
IN CONST EFI_SPI_HC_PROTOCOL *This, | |
IN EFI_SPI_BUS_TRANSACTION *BusTransaction | |
); | |
/// | |
/// Support a SPI data transaction between the SPI controller and a SPI chip. | |
/// | |
struct _EFI_SPI_HC_PROTOCOL { | |
/// | |
/// Host control attributes, may have zero or more of the following set: | |
/// * HC_SUPPORTS_WRITE_ONLY_OPERATIONS | |
/// * HC_SUPPORTS_READ_ONLY_OPERATIONS | |
/// * HC_SUPPORTS_WRITE_THEN_READ_OPERATIONS | |
/// * HC_TX_FRAME_IN_MOST_SIGNIFICANT_BITS | |
/// - The SPI host controller requires the transmit frame to be in most | |
/// significant bits instead of least significant bits.The host driver | |
/// will adjust the frames if necessary. | |
/// * HC_RX_FRAME_IN_MOST_SIGNIFICANT_BITS | |
/// - The SPI host controller places the receive frame to be in most | |
/// significant bits instead of least significant bits.The host driver | |
/// will adjust the frames to be in the least significant bits if | |
/// necessary. | |
/// * HC_SUPPORTS_2_BIT_DATA_BUS_W1DTH | |
/// - The SPI controller supports a 2 - bit data bus | |
/// * HC_SUPPORTS_4_B1T_DATA_BUS_WIDTH | |
/// - The SPI controller supports a 4 - bit data bus | |
/// * HC_TRANSFER_SIZE_INCLUDES_OPCODE | |
/// - Transfer size includes the opcode byte | |
/// * HC_TRANSFER_SIZE_INCLUDES_ADDRESS | |
/// - Transfer size includes the 3 address bytes | |
/// The SPI host controller must support full - duplex (receive while | |
/// sending) operation.The SPI host controller must support a 1 - bit bus | |
/// width. | |
/// | |
UINT32 Attributes; | |
/// | |
/// Mask of frame sizes which the SPI host controller supports. Frame size of | |
/// N-bits is supported when bit N-1 is set. The host controller must support | |
/// a frame size of 8-bits. | |
/// | |
UINT32 FrameSizeSupportMask; | |
/// | |
/// Maximum transfer size in bytes: 1 - Oxffffffff | |
/// | |
UINT32 MaximumTransferBytes; | |
/// | |
/// Assert or deassert the SPI chip select. | |
/// | |
EFI_SPI_HC_PROTOCOL_CHIP_SELECT ChipSelect; | |
/// | |
/// Set up the clock generator to produce the correct clock frequency, phase | |
/// and polarity for a SPI chip. | |
/// | |
EFI_SPI_HC_PROTOCOL_CLOCK Clock; | |
/// | |
/// Perform the SPI transaction on the SPI peripheral using the SPI host | |
/// controller. | |
/// | |
EFI_SPI_HC_PROTOCOL_TRANSACTION Transaction; | |
}; | |
extern EFI_GUID gEfiSpiHcProtocolGuid; | |
#endif // __SPI_HC_PROTOCOL_H__ |