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
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
|
/** @file
S3 support for QEMU fw_cfg
This library class enables driver modules (a) to query whether S3 support was
enabled on the QEMU command line, (b) to produce fw_cfg DMA operations that
are to be replayed at S3 resume time.
Copyright (C) 2017, Red Hat, Inc.
SPDX-License-Identifier: BSD-2-Clause-Patent
**/
#ifndef __FW_CFG_S3_LIB__
#define __FW_CFG_S3_LIB__
#include <Base.h>
/**
Determine if S3 support is explicitly enabled.
@retval TRUE If S3 support is explicitly enabled. Other functions in this
library may be called (subject to their individual
restrictions).
FALSE Otherwise. This includes unavailability of the firmware
configuration interface. No other function in this library
must be called.
**/
BOOLEAN
EFIAPI
QemuFwCfgS3Enabled (
VOID
);
/**
Prototype for the callback function that the client module provides.
In the callback function, the client module calls the
QemuFwCfgS3ScriptWriteBytes(), QemuFwCfgS3ScriptReadBytes(),
QemuFwCfgS3ScriptSkipBytes(), and QemuFwCfgS3ScriptCheckValue() functions.
Those functions produce ACPI S3 Boot Script opcodes that will perform fw_cfg
DMA operations, and will check any desired values that were read, during S3
resume.
The callback function is invoked when the production of ACPI S3 Boot Script
opcodes becomes possible. This may occur directly on the call stack of
QemuFwCfgS3CallWhenBootScriptReady() (see below), or after
QemuFwCfgS3CallWhenBootScriptReady() has successfully returned.
The callback function must not return if it fails -- in the general case,
there is noone to propagate any errors to. Therefore, on error, an error
message should be logged, and CpuDeadLoop() must be called.
@param[in,out] Context Carries information from the client module
itself (i.e., from the invocation of
QemuFwCfgS3CallWhenBootScriptReady()) to the
callback function.
If Context points to dynamically allocated
storage, then the callback function must
release it.
@param[in,out] ScratchBuffer Points to reserved memory, allocated by
QemuFwCfgS3CallWhenBootScriptReady()
internally.
ScratchBuffer is typed and sized by the client
module when it calls
QemuFwCfgS3CallWhenBootScriptReady(). The
client module defines a union type of
structures for ScratchBuffer such that the
union can hold client data for any desired
fw_cfg DMA read and write operations, and value
checking.
The callback function casts ScratchBuffer to
the union type described above. It passes union
member sizes as NumberOfBytes to
QemuFwCfgS3ScriptReadBytes() and
QemuFwCfgS3ScriptWriteBytes(). It passes field
addresses and sizes in structures in the union
as ScratchData and ValueSize to
QemuFwCfgS3ScriptCheckValue().
ScratchBuffer is aligned at 8 bytes.
**/
typedef
VOID (EFIAPI FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION) (
IN OUT VOID *Context, OPTIONAL
IN OUT VOID *ScratchBuffer
);
/**
Install the client module's FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION callback for
when the production of ACPI S3 Boot Script opcodes becomes possible.
Take ownership of the client-provided Context, and pass it to the callback
function, when the latter is invoked.
Allocate scratch space for those ACPI S3 Boot Script opcodes to work upon
that the client will produce in the callback function.
@param[in] Callback FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION to invoke
when the production of ACPI S3 Boot Script
opcodes becomes possible. Callback() may be
called immediately from
QemuFwCfgS3CallWhenBootScriptReady().
@param[in,out] Context Client-provided data structure for the
Callback() callback function to consume.
If Context points to dynamically allocated
memory, then Callback() must release it.
If Context points to dynamically allocated
memory, and
QemuFwCfgS3CallWhenBootScriptReady() returns
successfully, then the caller of
QemuFwCfgS3CallWhenBootScriptReady() must
neither dereference nor even evaluate Context
any longer, as ownership of the referenced area
has been transferred to Callback().
@param[in] ScratchBufferSize The size of the scratch buffer that will hold,
in reserved memory, all client data read,
written, and checked by the ACPI S3 Boot Script
opcodes produced by Callback().
@retval RETURN_UNSUPPORTED The library instance does not support this
function.
@retval RETURN_NOT_FOUND The fw_cfg DMA interface to QEMU is
unavailable.
@retval RETURN_BAD_BUFFER_SIZE ScratchBufferSize is too large.
@retval RETURN_OUT_OF_RESOURCES Memory allocation failed.
@retval RETURN_SUCCESS Callback() has been installed, and the
ownership of Context has been transferred.
Reserved memory has been allocated for the
scratch buffer.
A successful invocation of
QemuFwCfgS3CallWhenBootScriptReady() cannot
be rolled back.
@return Error codes from underlying functions.
**/
RETURN_STATUS
EFIAPI
QemuFwCfgS3CallWhenBootScriptReady (
IN FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION *Callback,
IN OUT VOID *Context, OPTIONAL
IN UINTN ScratchBufferSize
);
/**
Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
and transfer data to it.
The opcodes produced by QemuFwCfgS3ScriptWriteBytes() will first restore
NumberOfBytes bytes in ScratchBuffer in-place, in reserved memory, then write
them to fw_cfg using DMA.
If the operation fails during S3 resume, the boot script will hang.
This function may only be called from the client module's
FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
QemuFwCfgS3CallWhenBootScriptReady() as Callback.
@param[in] FirmwareConfigItem The UINT16 selector key of the firmware config
item to write, expressed as INT32. If
FirmwareConfigItem is -1, no selection is
made, the write will occur to the currently
selected item, at its currently selected
offset. Otherwise, the specified item will be
selected, and the write will occur at offset
0.
@param[in] NumberOfBytes Size of the data to restore in ScratchBuffer,
and to write from ScratchBuffer, during S3
resume. NumberOfBytes must not exceed
ScratchBufferSize, which was passed to
QemuFwCfgS3CallWhenBootScriptReady().
@retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
Boot Script successfully. There is no way
to undo this action.
@retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.
@retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is larger than
ScratchBufferSize.
@return Error codes from underlying functions.
**/
RETURN_STATUS
EFIAPI
QemuFwCfgS3ScriptWriteBytes (
IN INT32 FirmwareConfigItem,
IN UINTN NumberOfBytes
);
/**
Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
and transfer data from it.
The opcodes produced by QemuFwCfgS3ScriptReadBytes() will read NumberOfBytes
bytes from fw_cfg using DMA, storing the result in ScratchBuffer, in reserved
memory.
If the operation fails during S3 resume, the boot script will hang.
This function may only be called from the client module's
FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
QemuFwCfgS3CallWhenBootScriptReady() as Callback.
@param[in] FirmwareConfigItem The UINT16 selector key of the firmware config
item to read, expressed as INT32. If
FirmwareConfigItem is -1, no selection is
made, the read will occur from the currently
selected item, from its currently selected
offset. Otherwise, the specified item will be
selected, and the read will occur from offset
0.
@param[in] NumberOfBytes Size of the data to read during S3 resume.
NumberOfBytes must not exceed
ScratchBufferSize, which was passed to
QemuFwCfgS3CallWhenBootScriptReady().
@retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
Boot Script successfully. There is no way
to undo this action.
@retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.
@retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is larger than
ScratchBufferSize.
@return Error codes from underlying functions.
**/
RETURN_STATUS
EFIAPI
QemuFwCfgS3ScriptReadBytes (
IN INT32 FirmwareConfigItem,
IN UINTN NumberOfBytes
);
/**
Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,
and increase its offset.
If the operation fails during S3 resume, the boot script will hang.
This function may only be called from the client module's
FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
QemuFwCfgS3CallWhenBootScriptReady() as Callback.
@param[in] FirmwareConfigItem The UINT16 selector key of the firmware config
item to advance the offset of, expressed as
INT32. If FirmwareConfigItem is -1, no
selection is made, and the offset for the
currently selected item is increased.
Otherwise, the specified item will be
selected, and the offset increment will occur
from offset 0.
@param[in] NumberOfBytes The number of bytes to skip in the subject
fw_cfg item.
@retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
Boot Script successfully. There is no way
to undo this action.
@retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.
@retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is too large.
@return Error codes from underlying functions.
**/
RETURN_STATUS
EFIAPI
QemuFwCfgS3ScriptSkipBytes (
IN INT32 FirmwareConfigItem,
IN UINTN NumberOfBytes
);
/**
Produce ACPI S3 Boot Script opcodes that check a value in ScratchBuffer.
If the check fails during S3 resume, the boot script will hang.
This function may only be called from the client module's
FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to
QemuFwCfgS3CallWhenBootScriptReady() as Callback.
@param[in] ScratchData Pointer to the UINT8, UINT16, UINT32 or UINT64 field
in ScratchBuffer that should be checked. The caller
is responsible for populating the field during S3
resume, by calling QemuFwCfgS3ScriptReadBytes() ahead
of QemuFwCfgS3ScriptCheckValue().
ScratchData must point into ScratchBuffer, which was
allocated, and passed to Callback(), by
QemuFwCfgS3CallWhenBootScriptReady().
ScratchData must be aligned at ValueSize bytes.
@param[in] ValueSize One of 1, 2, 4 or 8, specifying the size of the field
to check.
@param[in] ValueMask The value read from ScratchData is binarily AND-ed
with ValueMask, and the result is compared against
Value. If the masked data equals Value, the check
passes, and the boot script can proceed. Otherwise,
the check fails, and the boot script hangs.
@param[in] Value Refer to ValueMask.
@retval RETURN_SUCCESS The opcodes were appended to the ACPI S3
Boot Script successfully. There is no way
to undo this action.
@retval RETURN_INVALID_PARAMETER ValueSize is invalid.
@retval RETURN_INVALID_PARAMETER ValueMask or Value cannot be represented in
ValueSize bytes.
@retval RETURN_INVALID_PARAMETER ScratchData is not aligned at ValueSize
bytes.
@retval RETURN_BAD_BUFFER_SIZE The ValueSize bytes at ScratchData aren't
wholly contained in the ScratchBufferSize
bytes at ScratchBuffer.
@return Error codes from underlying functions.
**/
RETURN_STATUS
EFIAPI
QemuFwCfgS3ScriptCheckValue (
IN VOID *ScratchData,
IN UINT8 ValueSize,
IN UINT64 ValueMask,
IN UINT64 Value
);
#endif
|
