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.
293 lines
12 KiB
293 lines
12 KiB
4 years ago
|
/** @file
|
||
|
|
This file defines the SPI I/O 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_IO_PROTOCOL_H__
|
||
|
|
#define __SPI_IO_PROTOCOL_H__
|
||
|
|
|
||
|
|
#include <Protocol/LegacySpiController.h>
|
||
|
|
#include <Protocol/SpiConfiguration.h>
|
||
|
|
|
||
|
|
typedef struct _EFI_SPI_IO_PROTOCOL EFI_SPI_IO_PROTOCOL;
|
||
|
|
|
||
|
|
///
|
||
|
|
/// Note: The UEFI PI 1.6 specification does not specify values for the
|
||
|
|
/// members below. The order matches the specification.
|
||
|
|
///
|
||
|
|
typedef enum {
|
||
|
|
///
|
||
|
|
/// Data flowing in both direction between the host and
|
||
|
|
/// SPI peripheral.ReadBytes must equal WriteBytes and both ReadBuffer and
|
||
|
|
/// WriteBuffer must be provided.
|
||
|
|
///
|
||
|
|
SPI_TRANSACTION_FULL_DUPLEX,
|
||
|
|
|
||
|
|
///
|
||
|
|
/// Data flowing from the host to the SPI peripheral.ReadBytes must be
|
||
|
|
/// zero.WriteBytes must be non - zero and WriteBuffer must be provided.
|
||
|
|
///
|
||
|
|
SPI_TRANSACTION_WRITE_ONLY,
|
||
|
|
|
||
|
|
///
|
||
|
|
/// Data flowing from the SPI peripheral to the host.WriteBytes must be
|
||
|
|
/// zero.ReadBytes must be non - zero and ReadBuffer must be provided.
|
||
|
|
///
|
||
|
|
SPI_TRANSACTION_READ_ONLY,
|
||
|
|
|
||
|
|
///
|
||
|
|
/// Data first flowing from the host to the SPI peripheral and then data
|
||
|
|
/// flows from the SPI peripheral to the host.These types of operations get
|
||
|
|
/// used for SPI flash devices when control data (opcode, address) must be
|
||
|
|
/// passed to the SPI peripheral to specify the data to be read.
|
||
|
|
///
|
||
|
|
SPI_TRANSACTION_WRITE_THEN_READ
|
||
|
|
} EFI_SPI_TRANSACTION_TYPE;
|
||
|
|
|
||
|
|
/**
|
||
|
|
Initiate a SPI transaction between the host and a SPI peripheral.
|
||
|
|
|
||
|
|
This routine must be called at or below TPL_NOTIFY.
|
||
|
|
This routine works with the SPI bus layer to pass the SPI transaction to the
|
||
|
|
SPI controller for execution on the SPI bus. There are four types of
|
||
|
|
supported transactions supported by this routine:
|
||
|
|
* Full Duplex: WriteBuffer and ReadBuffer are the same size.
|
||
|
|
* Write Only: WriteBuffer contains data for SPI peripheral, ReadBytes = 0
|
||
|
|
* Read Only: ReadBuffer to receive data from SPI peripheral, WriteBytes = 0
|
||
|
|
* Write Then Read: WriteBuffer contains control data to write to SPI
|
||
|
|
peripheral before data is placed into the ReadBuffer.
|
||
|
|
Both WriteBytes and ReadBytes must be non-zero.
|
||
|
|
|
||
|
|
@param[in] This Pointer to an EFI_SPI_IO_PROTOCOL structure.
|
||
|
|
@param[in] TransactionType Type of SPI transaction.
|
||
|
|
@param[in] DebugTransaction Set TRUE only when debugging is desired.
|
||
|
|
Debugging may be turned on for a single SPI
|
||
|
|
transaction. Only this transaction will display
|
||
|
|
debugging messages. All other transactions with
|
||
|
|
this value set to FALSE will not display any
|
||
|
|
debugging messages.
|
||
|
|
@param[in] ClockHz Specify the ClockHz value as zero (0) to use
|
||
|
|
the maximum clock frequency supported by the
|
||
|
|
SPI controller and part. Specify a non-zero
|
||
|
|
value only when a specific SPI transaction
|
||
|
|
requires a reduced clock rate.
|
||
|
|
@param[in] BusWidth Width of the SPI bus in bits: 1, 2, 4
|
||
|
|
@param[in] FrameSize Frame size in bits, range: 1 - 32
|
||
|
|
@param[in] WriteBytes The length of the WriteBuffer in bytes.
|
||
|
|
Specify zero for read-only operations.
|
||
|
|
@param[in] WriteBuffer The buffer containing data to be sent from the
|
||
|
|
host to the SPI chip. Specify NULL for read
|
||
|
|
only operations.
|
||
|
|
* Frame sizes 1-8 bits: UINT8 (one byte) per
|
||
|
|
frame
|
||
|
|
* Frame sizes 7-16 bits: UINT16 (two bytes) per
|
||
|
|
frame
|
||
|
|
* Frame sizes 17-32 bits: UINT32 (four bytes)
|
||
|
|
per frame The transmit frame is in the least
|
||
|
|
significant N bits.
|
||
|
|
@param[in] ReadBytes The length of the ReadBuffer in bytes.
|
||
|
|
Specify zero for write-only operations.
|
||
|
|
@param[out] ReadBuffer The buffer to receeive data from the SPI chip
|
||
|
|
during the transaction. Specify NULL for write
|
||
|
|
only operations.
|
||
|
|
* Frame sizes 1-8 bits: UINT8 (one byte) per
|
||
|
|
frame
|
||
|
|
* Frame sizes 7-16 bits: UINT16 (two bytes) per
|
||
|
|
frame
|
||
|
|
* Frame sizes 17-32 bits: UINT32 (four bytes)
|
||
|
|
per frame The received frame is in the least
|
||
|
|
significant N bits.
|
||
|
|
|
||
|
|
@retval EFI_SUCCESS The SPI transaction completed successfully
|
||
|
|
@retval EFI_BAD_BUFFER_SIZE The writeBytes value was invalid
|
||
|
|
@retval EFI_BAD_BUFFER_SIZE The ReadBytes value was invalid
|
||
|
|
@retval EFI_INVALID_PARAMETER TransactionType is not valid,
|
||
|
|
or BusWidth not supported by SPI peripheral or
|
||
|
|
SPI host controller,
|
||
|
|
or WriteBytes non-zero and WriteBuffer is
|
||
|
|
NULL,
|
||
|
|
or ReadBytes non-zero and ReadBuffer is NULL,
|
||
|
|
or ReadBuffer != WriteBuffer for full-duplex
|
||
|
|
type,
|
||
|
|
or WriteBuffer was NULL,
|
||
|
|
or TPL is too high
|
||
|
|
@retval EFI_OUT_OF_RESOURCES Insufficient memory for SPI transaction
|
||
|
|
@retval EFI_UNSUPPORTED The FrameSize is not supported by the SPI bus
|
||
|
|
layer or the SPI host controller
|
||
|
|
@retval EFI_UNSUPPORTED The SPI controller was not able to support
|
||
|
|
|
||
|
|
**/
|
||
|
|
typedef
|
||
|
|
EFI_STATUS
|
||
|
|
(EFIAPI *EFI_SPI_IO_PROTOCOL_TRANSACTION) (
|
||
|
|
IN CONST EFI_SPI_IO_PROTOCOL *This,
|
||
|
|
IN EFI_SPI_TRANSACTION_TYPE TransactionType,
|
||
|
|
IN BOOLEAN DebugTransaction,
|
||
|
|
IN UINT32 ClockHz OPTIONAL,
|
||
|
|
IN UINT32 BusWidth,
|
||
|
|
IN UINT32 FrameSize,
|
||
|
|
IN UINT32 WriteBytes,
|
||
|
|
IN UINT8 *WriteBuffer,
|
||
|
|
IN UINT32 ReadBytes,
|
||
|
|
OUT UINT8 *ReadBuffer
|
||
|
|
);
|
||
|
|
|
||
|
|
/**
|
||
|
|
Update the SPI peripheral associated with this SPI 10 instance.
|
||
|
|
|
||
|
|
Support socketed SPI parts by allowing the SPI peripheral driver to replace
|
||
|
|
the SPI peripheral after the connection is made. An example use is socketed
|
||
|
|
SPI NOR flash parts, where the size and parameters change depending upon
|
||
|
|
device is in the socket.
|
||
|
|
|
||
|
|
@param[in] This Pointer to an EFI_SPI_IO_PROTOCOL structure.
|
||
|
|
@param[in] SpiPeripheral Pointer to an EFI_SPI_PERIPHERAL structure.
|
||
|
|
|
||
|
|
@retval EFI_SUCCESS The SPI peripheral was updated successfully
|
||
|
|
@retval EFI_INVALID_PARAMETER The SpiPeripheral value is NULL,
|
||
|
|
or the SpiPeripheral->SpiBus is NULL,
|
||
|
|
or the SpiP eripheral - >SpiBus pointing at
|
||
|
|
wrong bus,
|
||
|
|
or the SpiP eripheral - >SpiPart is NULL
|
||
|
|
|
||
|
|
**/
|
||
|
|
typedef EFI_STATUS
|
||
|
|
(EFIAPI *EFI_SPI_IO_PROTOCOL_UPDATE_SPI_PERIPHERAL) (
|
||
|
|
IN CONST EFI_SPI_IO_PROTOCOL *This,
|
||
|
|
IN CONST EFI_SPI_PERIPHERAL *SpiPeripheral
|
||
|
|
);
|
||
|
|
|
||
|
|
///
|
||
|
|
/// The EFI_SPI_BUS_ TRANSACTION data structure contains the description of the
|
||
|
|
/// SPI transaction to perform on the host controller.
|
||
|
|
///
|
||
|
|
typedef struct _EFI_SPI_BUS_TRANSACTION {
|
||
|
|
///
|
||
|
|
/// Pointer to the SPI peripheral being manipulated.
|
||
|
|
///
|
||
|
|
CONST EFI_SPI_PERIPHERAL *SpiPeripheral;
|
||
|
|
|
||
|
|
///
|
||
|
|
/// Type of transaction specified by one of the EFI_SPI_TRANSACTION_TYPE
|
||
|
|
/// values.
|
||
|
|
///
|
||
|
|
EFI_SPI_TRANSACTION_TYPE TransactionType;
|
||
|
|
|
||
|
|
///
|
||
|
|
/// TRUE if the transaction is being debugged. Debugging may be turned on for
|
||
|
|
/// a single SPI transaction. Only this transaction will display debugging
|
||
|
|
/// messages. All other transactions with this value set to FALSE will not
|
||
|
|
/// display any debugging messages.
|
||
|
|
///
|
||
|
|
BOOLEAN DebugTransaction;
|
||
|
|
|
||
|
|
///
|
||
|
|
/// SPI bus width in bits: 1, 2, 4
|
||
|
|
///
|
||
|
|
UINT32 BusWidth;
|
||
|
|
|
||
|
|
///
|
||
|
|
/// Frame size in bits, range: 1 - 32
|
||
|
|
///
|
||
|
|
UINT32 FrameSize;
|
||
|
|
|
||
|
|
///
|
||
|
|
/// Length of the write buffer in bytes
|
||
|
|
///
|
||
|
|
UINT32 WriteBytes;
|
||
|
|
|
||
|
|
///
|
||
|
|
/// Buffer containing data to send to the SPI peripheral
|
||
|
|
/// Frame sizes 1 - 8 bits: UINT8 (one byte) per frame
|
||
|
|
/// Frame sizes 7 - 16 bits : UINT16 (two bytes) per frame
|
||
|
|
///
|
||
|
|
UINT8 *WriteBuffer;
|
||
|
|
|
||
|
|
///
|
||
|
|
/// Length of the read buffer in bytes
|
||
|
|
///
|
||
|
|
UINT32 ReadBytes;
|
||
|
|
|
||
|
|
///
|
||
|
|
/// Buffer to receive the data from the SPI peripheral
|
||
|
|
/// * Frame sizes 1 - 8 bits: UINT8 (one byte) per frame
|
||
|
|
/// * Frame sizes 7 - 16 bits : UINT16 (two bytes) per frame
|
||
|
|
/// * Frame sizes 17 - 32 bits : UINT32 (four bytes) per frame
|
||
|
|
///
|
||
|
|
UINT8 *ReadBuffer;
|
||
|
|
} EFI_SPI_BUS_TRANSACTION;
|
||
|
|
|
||
|
|
///
|
||
|
|
/// Support managed SPI data transactions between the SPI controller and a SPI
|
||
|
|
/// chip.
|
||
|
|
///
|
||
|
|
struct _EFI_SPI_IO_PROTOCOL {
|
||
|
|
///
|
||
|
|
/// Address of an EFI_SPI_PERIPHERAL data structure associated with this
|
||
|
|
/// protocol instance.
|
||
|
|
///
|
||
|
|
CONST EFI_SPI_PERIPHERAL *SpiPeripheral;
|
||
|
|
|
||
|
|
///
|
||
|
|
/// Address of the original EFI_SPI_PERIPHERAL data structure associated with
|
||
|
|
/// this protocol instance.
|
||
|
|
///
|
||
|
|
CONST EFI_SPI_PERIPHERAL *OriginalSpiPeripheral;
|
||
|
|
|
||
|
|
///
|
||
|
|
/// Mask of frame sizes which the SPI 10 layer 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. Frame sizes of 16, 24 and 32-bits are converted to
|
||
|
|
/// 8-bit frame sizes by the SPI bus layer if the frame size is not supported
|
||
|
|
/// by the SPI host controller.
|
||
|
|
///
|
||
|
|
UINT32 FrameSizeSupportMask;
|
||
|
|
|
||
|
|
///
|
||
|
|
/// Maximum transfer size in bytes: 1 - Oxffffffff
|
||
|
|
///
|
||
|
|
UINT32 MaximumTransferBytes;
|
||
|
|
|
||
|
|
///
|
||
|
|
/// Transaction attributes: One or more from:
|
||
|
|
/// * SPI_10_SUPPORTS_2_B1T_DATA_BUS_W1DTH
|
||
|
|
/// - The SPI host and peripheral supports a 2-bit data bus
|
||
|
|
/// * SPI_IO_SUPPORTS_4_BIT_DATA_BUS_W1DTH
|
||
|
|
/// - The SPI host and peripheral supports a 4-bit data bus
|
||
|
|
/// * SPI_IO_TRANSFER_SIZE_INCLUDES_OPCODE
|
||
|
|
/// - Transfer size includes the opcode byte
|
||
|
|
/// * SPI_IO_TRANSFER_SIZE_INCLUDES_ADDRESS
|
||
|
|
/// - Transfer size includes the 3 address bytes
|
||
|
|
///
|
||
|
|
UINT32 Attributes;
|
||
|
|
|
||
|
|
///
|
||
|
|
/// Pointer to legacy SPI controller protocol
|
||
|
|
///
|
||
|
|
CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *LegacySpiProtocol;
|
||
|
|
|
||
|
|
///
|
||
|
|
/// Initiate a SPI transaction between the host and a SPI peripheral.
|
||
|
|
///
|
||
|
|
EFI_SPI_IO_PROTOCOL_TRANSACTION Transaction;
|
||
|
|
|
||
|
|
///
|
||
|
|
/// Update the SPI peripheral associated with this SPI 10 instance.
|
||
|
|
///
|
||
|
|
EFI_SPI_IO_PROTOCOL_UPDATE_SPI_PERIPHERAL UpdateSpiPeripheral;
|
||
|
|
};
|
||
|
|
|
||
|
|
#endif // __SPI_IO_PROTOCOL_H__
|