1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
/** @file
This file defines the SPI Host Controller Protocol.
Copyright (c) 2017, Intel Corporation. All rights reserved.<BR>
Copyright (C) 2024 Advanced Micro Devices, Inc. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent
@par Revision Reference:
This Protocol was introduced in UEFI PI Specification 1.8 A.
**/
#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
);
///
/// Definitions of SPI Host Controller Attributes.
///
#define HC_SUPPORTS_WRITE_ONLY_OPERATIONS BIT0
#define HC_SUPPORTS_READ_ONLY_OPERATIONS BIT1
#define HC_SUPPORTS_WRITE_THEN_READ_OPERATIONS BIT2
#define HC_TX_FRAME_IN_MOST_SIGNIFICANT_BITS BIT3
#define HC_RX_FRAME_IN_MOST_SIGNIFICANT_BITS BIT4
#define HC_SUPPORTS_2_BIT_DATA_BUS_WIDTH BIT5
#define HC_SUPPORTS_4_BIT_DATA_BUS_WIDTH BIT6
#define HC_SUPPORTS_8_BIT_DATA_BUS_WIDTH BIT7
#define HC_TRANSFER_SIZE_INCLUDES_OPCODE BIT8
#define HC_TRANSFER_SIZE_INCLUDES_ADDRESS BIT9
///
/// 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__
|
