S3BootScriptLib.h@ 58459

Last change on this file since 58459 was 58459, checked in by vboxsync, 9 years ago
EFI/Firmware: 'svn merge ^{/vendor/edk2/UDK2010.SR1}/vendor/edk2/current .', reverting and removing files+dirs listed in ReadMe.vbox, resolving conflicts with help from ../UDK2014.SP1/. This is a raw untested merge.
Property svn:eol-style set to `native`
File size: 23.9 KB

Line
1	/** @file
2	Defines library APIs used by modules to save EFI Boot Script Opcodes.
3	These OpCode will be restored by S3 related modules.
4	Note that some of the API defined in the Library class may not
5	be provided in the Framework version library instance, which means some of these
6	APIs cannot be used if the underlying firmware is Framework and not PI.
7
8	Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.<BR>
9
10	This program and the accompanying materials
11	are licensed and made available under the terms and conditions
12	of the BSD License which accompanies this distribution. The
13	full text of the license may be found at
14	http://opensource.org/licenses/bsd-license.php
15
16	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
17	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
18
19	**/
20
21	#ifndef _S3_BOOT_SCRIPT_LIB_H_
22	#define _S3_BOOT_SCRIPT_LIB_H_
23
24	#include <Library/BaseLib.h>
25	#include <IndustryStandard/SmBus.h>
26
27	/**
28	Macro that converts PCI Bus, PCI Device, PCI Function and PCI Register to an
29	address that can be passed to the S3 Boot Script Library PCI functions.
30
31	@param Bus PCI Bus number. Range 0..255.
32	@param Device PCI Device number. Range 0..31.
33	@param Function PCI Function number. Range 0..7.
34	@param Register PCI Register number. Range 0..255 for PCI. Range 0..4095
35	for PCI Express.
36
37	@return The encoded PCI address.
38
39	**/
40	#define S3_BOOT_SCRIPT_LIB_PCI_ADDRESS(Bus,Device,Function,Register) \
41	(UINT64) ( \
42	(((UINTN) Bus) << 24) \| \
43	(((UINTN) Device) << 16) \| \
44	(((UINTN) Function) << 8) \| \
45	(((UINTN) (Register)) < 256 ? ((UINTN) (Register)) : (UINT64) (LShiftU64 ((UINT64) (Register), 32))))
46
47	///
48	/// S3 Boot Script Width.
49	///
50	typedef enum {
51	S3BootScriptWidthUint8, ///< 8-bit operation.
52	S3BootScriptWidthUint16, ///< 16-bit operation.
53	S3BootScriptWidthUint32, ///< 32-bit operation.
54	S3BootScriptWidthUint64, ///< 64-bit operation.
55	S3BootScriptWidthFifoUint8, ///< 8-bit FIFO operation.
56	S3BootScriptWidthFifoUint16, ///< 16-bit FIFO operation.
57	S3BootScriptWidthFifoUint32, ///< 32-bit FIFO operation.
58	S3BootScriptWidthFifoUint64, ///< 64-bit FIFO operation.
59	S3BootScriptWidthFillUint8, ///< 8-bit Fill operation.
60	S3BootScriptWidthFillUint16, ///< 16-bit Fill operation.
61	S3BootScriptWidthFillUint32, ///< 32-bit Fill operation.
62	S3BootScriptWidthFillUint64, ///< 64-bit Fill operation.
63	S3BootScriptWidthMaximum
64	} S3_BOOT_SCRIPT_LIB_WIDTH;
65
66	/**
67	Save I/O write to boot script.
68
69	@param[in] Width The width of the I/O operations.
70	@param[in] Address The base address of the I/O operations.
71	@param[in] Count The number of I/O operations to perform.
72	@param[in] Buffer The source buffer from which to write data.
73
74	@retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
75	the operation.
76	@retval RETURN_SUCCESS The opcode was added.
77
78	**/
79	RETURN_STATUS
80	EFIAPI
81	S3BootScriptSaveIoWrite (
82	IN S3_BOOT_SCRIPT_LIB_WIDTH Width,
83	IN UINT64 Address,
84	IN UINTN Count,
85	IN VOID *Buffer
86	);
87
88	/**
89	Adds a record for an I/O modify operation into a S3 boot script table.
90
91	@param[in] Width The width of the I/O operations.
92	@param[in] Address The base address of the I/O operations.
93	@param[in] Data A pointer to the data to be OR-ed.
94	@param[in] DataMask A pointer to the data mask to be AND-ed with the data
95	read from the register.
96
97	@retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
98	the operation.
99	@retval RETURN_SUCCESS The opcode was added.
100
101	**/
102	RETURN_STATUS
103	EFIAPI
104	S3BootScriptSaveIoReadWrite (
105	IN S3_BOOT_SCRIPT_LIB_WIDTH Width,
106	IN UINT64 Address,
107	IN VOID *Data,
108	IN VOID *DataMask
109	);
110
111	/**
112	Adds a record for a memory write operation into a specified boot script table.
113
114	@param[in] Width The width of the I/O operations.
115	@param[in] Address The base address of the memory operations
116	@param[in] Count The number of memory operations to perform.
117	@param[in] Buffer The source buffer from which to write the data.
118
119	@retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
120	the operation.
121	@retval RETURN_SUCCESS The opcode was added.
122	**/
123	RETURN_STATUS
124	EFIAPI
125	S3BootScriptSaveMemWrite (
126	IN S3_BOOT_SCRIPT_LIB_WIDTH Width,
127	IN UINT64 Address,
128	IN UINTN Count,
129	IN VOID *Buffer
130	);
131
132	/**
133	Adds a record for a memory modify operation into a specified boot script table.
134
135	@param[in] Width The width of the I/O operations.
136	@param[in] Address The base address of the memory operations. Address needs
137	alignment, if required
138	@param[in] Data A pointer to the data to be OR-ed.
139	@param[in] DataMask A pointer to the data mask to be AND-ed with the data
140	read from the register.
141
142	@retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
143	the operation.
144	@retval RETURN_SUCCESS The opcode was added.
145	**/
146	RETURN_STATUS
147	EFIAPI
148	S3BootScriptSaveMemReadWrite (
149	IN S3_BOOT_SCRIPT_LIB_WIDTH Width,
150	IN UINT64 Address,
151	IN VOID *Data,
152	IN VOID *DataMask
153	);
154
155	/**
156	Adds a record for a PCI configuration space write operation into a specified boot script table.
157
158	@param[in] Width The width of the I/O operations.
159	@param[in] Address The address within the PCI configuration space.
160	@param[in] Count The number of PCI operations to perform.
161	@param[in] Buffer The source buffer from which to write the data.
162
163	@retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
164	the operation.
165	@retval RETURN_SUCCESS The opcode was added.
166	**/
167	RETURN_STATUS
168	EFIAPI
169	S3BootScriptSavePciCfgWrite (
170	IN S3_BOOT_SCRIPT_LIB_WIDTH Width,
171	IN UINT64 Address,
172	IN UINTN Count,
173	IN VOID *Buffer
174	);
175
176	/**
177	Adds a record for a PCI configuration space modify operation into a specified boot script table.
178
179	@param[in] Width The width of the I/O operations.
180	@param[in] Address The address within the PCI configuration space.
181	@param[in] Data A pointer to the data to be OR-ed.The size depends on Width.
182	@param[in] DataMask A pointer to the data mask to be AND-ed.
183
184	@retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
185	the operation.
186	@retval RETURN__SUCCESS The opcode was added.
187	**/
188	RETURN_STATUS
189	EFIAPI
190	S3BootScriptSavePciCfgReadWrite (
191	IN S3_BOOT_SCRIPT_LIB_WIDTH Width,
192	IN UINT64 Address,
193	IN VOID *Data,
194	IN VOID *DataMask
195	);
196
197	/**
198	Adds a record for a PCI configuration space modify operation into a specified boot script table.
199
200	@param[in] Width The width of the I/O operations.
201	@param[in] Segment The PCI segment number for Address.
202	@param[in] Address The address within the PCI configuration space.
203	@param[in] Count The number of PCI operations to perform.
204	@param[in] Buffer The source buffer from which to write the data.
205
206	@retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
207	the operation.
208	@retval RETURN_SUCCESS The opcode was added.
209	**/
210	RETURN_STATUS
211	EFIAPI
212	S3BootScriptSavePciCfg2Write (
213	IN S3_BOOT_SCRIPT_LIB_WIDTH Width,
214	IN UINT16 Segment,
215	IN UINT64 Address,
216	IN UINTN Count,
217	IN VOID *Buffer
218	);
219
220	/**
221	Adds a record for a PCI configuration space modify operation into a specified boot script table.
222
223	@param[in] Width The width of the I/O operations.
224	@param[in] Segment The PCI segment number for Address.
225	@param[in] Address The address within the PCI configuration space.
226	@param[in] Data A pointer to the data to be OR-ed. The size depends on Width.
227	@param[in] DataMask A pointer to the data mask to be AND-ed.
228
229	@retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
230	the operation.
231	@retval RETURN_SUCCESS The opcode was added.
232	**/
233	RETURN_STATUS
234	EFIAPI
235	S3BootScriptSavePciCfg2ReadWrite (
236	IN S3_BOOT_SCRIPT_LIB_WIDTH Width,
237	IN UINT16 Segment,
238	IN UINT64 Address,
239	IN VOID *Data,
240	IN VOID *DataMask
241	);
242
243	/**
244	Adds a record for an SMBus command execution into a specified boot script table.
245
246	@param[in] SmBusAddress Address that encodes the SMBUS Slave Address, SMBUS
247	Command, SMBUS Data Length, and PEC.
248	@param[in] Operation Indicates which particular SMBus protocol it will use
249	to execute the SMBus transactions.
250	@param[in] Length A pointer to signify the number of bytes that this
251	operation will do.
252	@param[in] Buffer Contains the value of data to execute to the SMBUS
253	slave device.
254
255	@retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
256	the operation.
257	@retval RETURN_SUCCESS The opcode was added.
258	**/
259	RETURN_STATUS
260	EFIAPI
261	S3BootScriptSaveSmbusExecute (
262	IN UINTN SmBusAddress,
263	IN EFI_SMBUS_OPERATION Operation,
264	IN UINTN *Length,
265	IN VOID *Buffer
266	);
267
268	/**
269	Adds a record for an execution stall on the processor into a specified boot script table.
270
271	@param[in] Duration The duration in microseconds of the stall.
272
273	@retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
274	the operation.
275	@retval RETURN_SUCCESS The opcode was added.
276	**/
277	RETURN_STATUS
278	EFIAPI
279	S3BootScriptSaveStall (
280	IN UINTN Duration
281	);
282
283	/**
284	Adds a record for dispatching specified arbitrary code into a specified boot script table.
285
286	@param[in] EntryPoint The entry point of the code to be dispatched.
287	@param[in] Context The argument to be passed into the EntryPoint of the code
288	to be dispatched.
289
290	@retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
291	the operation.
292	@retval RETURN_SUCCESS The opcode was added.
293	**/
294	RETURN_STATUS
295	EFIAPI
296	S3BootScriptSaveDispatch2 (
297	IN VOID *EntryPoint,
298	IN VOID *Context
299	);
300
301	/**
302	Adds a record for dispatching specified arbitrary code into a specified boot script table.
303
304	@param[in] EntryPoint The entry point of the code to be dispatched.
305
306	@retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
307	the operation.
308	@retval RETURN_SUCCESS The opcode was added.
309	**/
310	RETURN_STATUS
311	EFIAPI
312	S3BootScriptSaveDispatch (
313	IN VOID *EntryPoint
314	);
315
316	/**
317	Adds a record for memory reads of the memory location and continues when the exit
318	criteria is satisfied, or after a defined duration.
319
320	Please aware, below interface is different with PI specification, Vol 5:
321	EFI_S3_SAVE_STATE_PROTOCOL.Write() for EFI_BOOT_SCRIPT_MEM_POLL_OPCODE.
322	"Duration" below is microseconds, while "Delay" in PI specification means
323	the number of 100ns units to poll.
324
325	@param[in] Width The width of the memory operations.
326	@param[in] Address The base address of the memory operations.
327	@param[in] BitMask A pointer to the bit mask to be AND-ed with the data read
328	from the register.
329	@param[in] BitValue A pointer to the data value after to be Masked.
330	@param[in] Duration The duration in microseconds of the stall.
331	@param[in] LoopTimes The times of the register polling.
332
333	@retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
334	the operation.
335	@retval RETURN_SUCCESS The opcode was added.
336
337	**/
338	RETURN_STATUS
339	EFIAPI
340	S3BootScriptSaveMemPoll (
341	IN S3_BOOT_SCRIPT_LIB_WIDTH Width,
342	IN UINT64 Address,
343	IN VOID *BitMask,
344	IN VOID *BitValue,
345	IN UINTN Duration,
346	IN UINTN LoopTimes
347	);
348
349	/**
350	Store arbitrary information in the boot script table. This opcode is a no-op on
351	dispatch and is only used for debugging script issues.
352
353	@param[in] InformationLength Length of the data in bytes
354	@param[in] Information Information to be logged in the boot scrpit
355
356	@retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
357	the operation.
358	@retval RETURN_SUCCESS The opcode was added.
359
360	**/
361	RETURN_STATUS
362	EFIAPI
363	S3BootScriptSaveInformation (
364	IN UINT32 InformationLength,
365	IN VOID *Information
366	);
367	/**
368	Adds a record for I/O reads the I/O location and continues when the exit criteria
369	is satisfied, or after a defined duration.
370
371	@param Width The width of the I/O operations.
372	@param Address The base address of the I/O operations.
373	@param Data The comparison value used for the polling exit criteria.
374	@param DataMask The mask used for the polling criteria. The bits in
375	the bytes below Width which are zero in Data are
376	ignored when polling the memory address.
377	@param Delay The number of 100ns units to poll. Note that timer
378	available may be of insufficient granularity, so the
379	delay may be longer.
380
381	@retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the
382	operation.
383	@retval RETURN_SUCCESS The opcode was added.
384	@note The FRAMEWORK version implementation does not support this API
385	**/
386	RETURN_STATUS
387	EFIAPI
388	S3BootScriptSaveIoPoll (
389	IN S3_BOOT_SCRIPT_LIB_WIDTH Width,
390	IN UINT64 Address,
391	IN VOID *Data,
392	IN VOID *DataMask,
393	IN UINT64 Delay
394	);
395
396	/**
397	Adds a record for PCI configuration space reads and continues when the exit
398	criteria is satisfied ,or after a defined duration.
399
400	@param Width The width of the I/O operations.
401	@param Address The address within the PCI configuration space.
402	@param Data The comparison value used for the polling exit
403	criteria.
404	@param DataMask Mask used for the polling criteria. The bits in
405	the bytes below Width which are zero in Data are
406	ignored when polling the memory address.
407	@param Delay The number of 100ns units to poll. Note that timer
408	available may be of insufficient granularity, so the
409	delay may be longer.
410
411	@retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the
412	operation.
413	@retval RETURN_SUCCESS The opcode was added.
414	@note The FRAMEWORK version implementation does not support this API
415	**/
416	RETURN_STATUS
417	EFIAPI
418	S3BootScriptSavePciPoll (
419	IN S3_BOOT_SCRIPT_LIB_WIDTH Width,
420	IN UINT64 Address,
421	IN VOID *Data,
422	IN VOID *DataMask,
423	IN UINT64 Delay
424	);
425	/**
426	Adds a record for PCI configuration space reads and continues when the exit criteria
427	is satisfied, or after a defined duration.
428
429	@param Width The width of the I/O operations.
430	@param Segment The PCI segment number for Address.
431	@param Address The address within the PCI configuration space.
432	@param Data The comparison value used for the polling exit
433	criteria.
434	@param DataMask Mask used for the polling criteria. The bits in
435	the bytes below Width which are zero
436	in Data are ignored when polling the memory address
437	@param Delay The number of 100ns units to poll. Note that timer
438	available may be of insufficient granularity so the delay
439	may be longer.
440
441	@retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform the
442	operation.
443	@retval RETURN_SUCCESS The opcode was added.
444	@note A known Limitations in the implementation: When interpreting the opcode
445	EFI_BOOT_SCRIPT_PCI_CONFIG2_WRITE_OPCODE, EFI_BOOT_SCRIPT_PCI_CONFIG2_READ_WRITE_OPCODE
446	and EFI_BOOT_SCRIPT_PCI_CONFIG2_POLL_OPCODE, the 'Segment' parameter is assumed as
447	Zero, or else, assert.
448	The FRAMEWORK version implementation does not support this API.
449
450	**/
451	RETURN_STATUS
452	EFIAPI
453	S3BootScriptSavePci2Poll (
454	IN S3_BOOT_SCRIPT_LIB_WIDTH Width,
455	IN UINT16 Segment,
456	IN UINT64 Address,
457	IN VOID *Data,
458	IN VOID *DataMask,
459	IN UINT64 Delay
460	);
461	/**
462	Save ASCII string information specified by Buffer to boot script with opcode
463	EFI_BOOT_SCRIPT_INFORMATION_OPCODE.
464
465	@param[in] String The Null-terminated ASCII string to store into the S3 boot
466	script table.
467
468	@retval RETURN_OUT_OF_RESOURCES Not enough memory for the table to perform
469	the operation.
470	@retval RETURN_SUCCESS The opcode was added.
471
472	**/
473	RETURN_STATUS
474	EFIAPI
475	S3BootScriptSaveInformationAsciiString (
476	IN CONST CHAR8 *String
477	);
478
479	/**
480	This is an function to close the S3 boot script table. The function could only
481	be called in BOOT time phase. To comply with the Framework spec definition on
482	EFI_BOOT_SCRIPT_SAVE_PROTOCOL.CloseTable(), this function will fulfill following things:
483	1. Closes the specified boot script table
484	2. It allocates a new memory pool to duplicate all the boot scripts in the specified table.
485	Once this function is called, the table maintained by the library will be destroyed
486	after it is copied into the allocated pool.
487	3. Any attempts to add a script record after calling this function will cause a
488	new table to be created by the library.
489	4. The base address of the allocated pool will be returned in Address. Note that
490	after using the boot script table, the CALLER is responsible for freeing the
491	pool that is allocated by this function.
492
493	In Spec PI1.1, this EFI_BOOT_SCRIPT_SAVE_PROTOCOL.CloseTable() is retired. This
494	API is supplied here to meet the requirements of the Framework Spec.
495
496	If anyone does call CloseTable() on a real platform, then the caller is responsible
497	for figuring out how to get the script to run on an S3 resume because the boot script
498	maintained by the lib will be destroyed.
499
500	@return the base address of the new copy of the boot script table.
501
502	**/
503	UINT8*
504	EFIAPI
505	S3BootScriptCloseTable (
506	VOID
507	);
508
509	/**
510	Executes the S3 boot script table.
511
512	@retval RETURN_SUCCESS The boot script table was executed successfully.
513	@retval RETURN_UNSUPPORTED Invalid script table or opcode.
514
515	**/
516	RETURN_STATUS
517	EFIAPI
518	S3BootScriptExecute (
519	VOID
520	);
521	/**
522	Move the last boot script entry to the position
523
524	@param BeforeOrAfter Specifies whether the opcode is stored before
525	(TRUE) or after (FALSE) the positionin the boot
526	script table specified by Position. If Position
527	is NULL or points to NULL then the new opcode is
528	inserted at the beginning of the table (if TRUE)
529	or end of the table (if FALSE).
530	@param Position On entry, specifies the position in the boot script
531	table where the opcode will be inserted, either
532	before or after, depending on BeforeOrAfter. On
533	exit, specifies the position of the inserted opcode
534	in the boot script table.
535
536	@retval RETURN_OUT_OF_RESOURCES The table is not available.
537	@retval RETURN_INVALID_PARAMETER The Position is not a valid position in the
538	boot script table.
539	@retval RETURN_SUCCESS The opcode was inserted.
540	@note The FRAMEWORK version implementation does not support this API.
541	**/
542	RETURN_STATUS
543	EFIAPI
544	S3BootScriptMoveLastOpcode (
545	IN BOOLEAN BeforeOrAfter,
546	IN OUT VOID **Position OPTIONAL
547	);
548	/**
549	Find a label within the boot script table and, if not present, optionally create it.
550
551	@param BeforeOrAfter Specifies whether the opcode is stored before (TRUE)
552	or after (FALSE) the position in the boot script table
553	specified by Position.
554	@param CreateIfNotFound Specifies whether the label will be created if the
555	label does not exists (TRUE) or not (FALSE).
556	@param Position On entry, specifies the position in the boot script
557	table where the opcode will be inserted, either
558	before or after, depending on BeforeOrAfter. On exit,
559	specifies the positionof the inserted opcode in
560	the boot script table.
561	@param Label Points to the label which will be inserted in the
562	boot script table.
563	@retval EFI_SUCCESS The operation succeeded. A record was added into
564	the specified script table.
565	@retval EFI_INVALID_PARAMETER The parameter is illegal or the given boot script
566	is not supported. If the opcode is unknow or not
567	supported because of the PCD Feature Flags.
568	@retval EFI_OUT_OF_RESOURCES There is insufficient memory to store the boot script.
569	@note The FRAMEWORK version implementation does not support this API
570
571	**/
572	RETURN_STATUS
573	EFIAPI
574	S3BootScriptLabel (
575	IN BOOLEAN BeforeOrAfter,
576	IN BOOLEAN CreateIfNotFound,
577	IN OUT VOID **Position OPTIONAL,
578	IN CONST CHAR8 *Label
579	);
580	/**
581	Compare two positions in the boot script table and return their relative position.
582	@param Position1 The positions in the boot script table to compare
583	@param Position2 The positions in the boot script table to compare
584	@param RelativePosition On return, points to the result of the comparison
585
586	@retval EFI_SUCCESS The operation succeeded. A record was added into the
587	specified script table.
588	@retval EFI_INVALID_PARAMETER The parameter is illegal or the given boot script
589	is not supported. If the opcode is unknow or not s
590	upported because of the PCD Feature Flags.
591	@retval EFI_OUT_OF_RESOURCES There is insufficient memory to store the boot script.
592	@note The FRAMEWORK version implementation does not support this API
593	**/
594	RETURN_STATUS
595	EFIAPI
596	S3BootScriptCompare (
597	IN UINT8 *Position1,
598	IN UINT8 *Position2,
599	OUT UINTN *RelativePosition
600	);
601
602	#endif

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/Devices/EFI/Firmware/MdePkg/Include/Library/S3BootScriptLib.h@ 58459

Download in other formats: