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
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
|
/** @file
This file defines the Legacy SPI Controller Protocol.
Copyright (c) 2017, Intel Corporation. All rights reserved.<BR>
SPDX-License-Identifier: BSD-2-Clause-Patent
@par Revision Reference:
This Protocol was introduced in UEFI PI Specification 1.6.
**/
#ifndef __LEGACY_SPI_CONTROLLER_PROTOCOL_H__
#define __LEGACY_SPI_CONTROLLER_PROTOCOL_H__
///
/// Note: The UEFI PI 1.6 specification uses the character 'l' in the GUID
/// definition. This definition assumes it was supposed to be '1'.
///
/// Global ID for the Legacy SPI Controller Protocol
///
#define EFI_LEGACY_SPI_CONTROLLER_GUID \
{ 0x39136fc7, 0x1a11, 0x49de, \
{ 0xbf, 0x35, 0x0e, 0x78, 0xdd, 0xb5, 0x24, 0xfc }}
typedef
struct _EFI_LEGACY_SPI_CONTROLLER_PROTOCOL
EFI_LEGACY_SPI_CONTROLLER_PROTOCOL;
/**
Set the erase block opcode.
This routine must be called at or below TPL_NOTIFY.
The menu table contains SPI transaction opcodes which are accessible after
the legacy SPI flash controller's configuration is locked. The board layer
specifies the erase block size for the SPI NOR flash part. The SPI NOR flash
peripheral driver selects the erase block opcode which matches the erase
block size and uses this API to load the opcode into the opcode menu table.
@param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL
structure.
@param[in] EraseBlockOpcode Erase block opcode to be placed into the opcode
menu table.
@retval EFI_SUCCESS The opcode menu table was updated
@retval EFI_ACCESS_ERROR The SPI controller is locked
**/
typedef EFI_STATUS
(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_ERASE_BLOCK_OPCODE)(
IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This,
IN UINT8 EraseBlockOpcode
);
/**
Set the write status prefix opcode.
This routine must be called at or below TPL_NOTIFY.
The prefix table contains SPI transaction write prefix opcodes which are
accessible after the legacy SPI flash controller's configuration is locked.
The board layer specifies the write status prefix opcode for the SPI NOR
flash part. The SPI NOR flash peripheral driver uses this API to load the
opcode into the prefix table.
@param[in] This Pointer to an
EFI_LEGACY_SPI_CONTROLLER_PROTOCOL structure.
@param[in] WriteStatusPrefix Prefix opcode for the write status command.
@retval EFI_SUCCESS The prefix table was updated
@retval EFI_ACCESS_ERROR The SPI controller is locked
**/
typedef
EFI_STATUS
(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_WRITE_STATUS_PREFIX)(
IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This,
IN UINT8 WriteStatusPrefix
);
/**
Set the BIOS base address.
This routine must be called at or below TPL_NOTIFY.
The BIOS base address works with the protect range registers to protect
portions of the SPI NOR flash from erase and write operat ions. The BIOS
calls this API prior to passing control to the OS loader.
@param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL
structure.
@param[in] BiosBaseAddress The BIOS base address.
@retval EFI_SUCCESS The BIOS base address was properly set
@retval EFI_ACCESS_ERROR The SPI controller is locked
@retval EFI_INVALID_PARAMETER The BIOS base address is greater than
This->Maxi.mumOffset
@retval EFI_UNSUPPORTED The BIOS base address was already set
**/
typedef EFI_STATUS
(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_BIOS_BASE_ADDRESS)(
IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This,
IN UINT32 BiosBaseAddress
);
/**
Clear the SPI protect range registers.
This routine must be called at or below TPL_NOTIFY.
The BIOS uses this routine to set an initial condition on the SPI protect
range registers.
@param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL structure.
@retval EFI_SUCCESS The registers were successfully cleared
@retval EFI_ACCESS_ERROR The SPI controller is locked
**/
typedef
EFI_STATUS
(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_CLEAR_SPI_PROTECT)(
IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This
);
/**
Determine if the SPI range is protected.
This routine must be called at or below TPL_NOTIFY.
The BIOS uses this routine to verify a range in the SPI is protected.
@param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL
structure.
@param[in] BiosAddress Address within a 4 KiB block to start protecting.
@param[in] BytesToProtect The number of 4 KiB blocks to protect.
@retval TRUE The range is protected
@retval FALSE The range is not protected
**/
typedef
BOOLEAN
(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_IS_RANGE_PROTECTED)(
IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This,
IN UINT32 BiosAddress,
IN UINT32 BlocksToProtect
);
/**
Set the next protect range register.
This routine must be called at or below TPL_NOTIFY.
The BIOS sets the protect range register to prevent write and erase
operations to a portion of the SPI NOR flash device.
@param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL
structure.
@param[in] BiosAddress Address within a 4 KiB block to start protecting.
@param[in] BlocksToProtect The number of 4 KiB blocks to protect.
@retval EFI_SUCCESS The register was successfully updated
@retval EFI_ACCESS_ERROR The SPI controller is locked
@retval EFI_INVALID_PARAMETER BiosAddress < This->BiosBaseAddress, or
BlocksToProtect * 4 KiB
> This->MaximumRangeBytes, or
BiosAddress - This->BiosBaseAddress
+ (BlocksToProtect * 4 KiB)
> This->MaximumRangeBytes
@retval EFI_OUT_OF_RESOURCES No protect range register available
@retval EFI_UNSUPPORTED Call This->SetBaseAddress because the BIOS base
address is not set
**/
typedef
EFI_STATUS
(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_PROTECT_NEXT_RANGE)(
IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This,
IN UINT32 BiosAddress,
IN UINT32 BlocksToProtect
);
/**
Lock the SPI controller configuration.
This routine must be called at or below TPL_NOTIFY.
This routine locks the SPI controller's configuration so that the software
is no longer able to update:
* Prefix table
* Opcode menu
* Opcode type table
* BIOS base address
* Protect range registers
@param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL structure.
@retval EFI_SUCCESS The SPI controller was successfully locked
@retval EFI_ALREADY_STARTED The SPI controller was already locked
**/
typedef EFI_STATUS
(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_LOCK_CONTROLLER)(
IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This
);
///
/// Support the extra features of the legacy SPI flash controller.
///
struct _EFI_LEGACY_SPI_CONTROLLER_PROTOCOL {
///
/// Maximum offset from the BIOS base address that is able to be protected.
///
UINT32 MaximumOffset;
///
/// Maximum number of bytes that can be protected by one range register.
///
UINT32 MaximumRangeBytes;
///
/// The number of registers available for protecting the BIOS.
///
UINT32 RangeRegisterCount;
///
/// Set the erase block opcode.
///
EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_ERASE_BLOCK_OPCODE EraseBlockOpcode;
///
/// Set the write status prefix opcode.
///
EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_WRITE_STATUS_PREFIX WriteStatusPrefix;
///
/// Set the BIOS base address.
///
EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_BIOS_BASE_ADDRESS BiosBaseAddress;
///
/// Clear the SPI protect range registers.
///
EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_CLEAR_SPI_PROTECT ClearSpiProtect;
///
/// Determine if the SPI range is protected.
///
EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_IS_RANGE_PROTECTED IsRangeProtected;
///
/// Set the next protect range register.
///
EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_PROTECT_NEXT_RANGE ProtectNextRange;
///
/// Lock the SPI controller configuration.
///
EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_LOCK_CONTROLLER LockController;
};
extern EFI_GUID gEfiLegacySpiControllerProtocolGuid;
#endif // __LEGACY_SPI_CONTROLLER_PROTOCOL_H__
|
