[mirror_edk2.git] / OvmfPkg / Include / Library / QemuFwCfgS3Lib.h

/** @file\r
  S3 support for QEMU fw_cfg\r
\r
  This library class enables driver modules (a) to query whether S3 support was\r
  enabled on the QEMU command line, (b) to produce fw_cfg DMA operations that\r
  are to be replayed at S3 resume time.\r
\r
  Copyright (C) 2017, Red Hat, Inc.\r
\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
**/\r
\r
#ifndef __FW_CFG_S3_LIB__\r
#define __FW_CFG_S3_LIB__\r
\r
#include <Base.h>\r
\r
/**\r
  Determine if S3 support is explicitly enabled.\r
\r
  @retval  TRUE   If S3 support is explicitly enabled. Other functions in this\r
                  library may be called (subject to their individual\r
                  restrictions).\r
\r
           FALSE  Otherwise. This includes unavailability of the firmware\r
                  configuration interface. No other function in this library\r
                  must be called.\r
**/\r
BOOLEAN\r
EFIAPI\r
QemuFwCfgS3Enabled (\r
  VOID\r
  );\r
\r
/**\r
  Prototype for the callback function that the client module provides.\r
\r
  In the callback function, the client module calls the\r
  QemuFwCfgS3ScriptWriteBytes(), QemuFwCfgS3ScriptReadBytes(),\r
  QemuFwCfgS3ScriptSkipBytes(), and QemuFwCfgS3ScriptCheckValue() functions.\r
  Those functions produce ACPI S3 Boot Script opcodes that will perform fw_cfg\r
  DMA operations, and will check any desired values that were read, during S3\r
  resume.\r
\r
  The callback function is invoked when the production of ACPI S3 Boot Script\r
  opcodes becomes possible. This may occur directly on the call stack of\r
  QemuFwCfgS3CallWhenBootScriptReady() (see below), or after\r
  QemuFwCfgS3CallWhenBootScriptReady() has successfully returned.\r
\r
  The callback function must not return if it fails -- in the general case,\r
  there is noone to propagate any errors to. Therefore, on error, an error\r
  message should be logged, and CpuDeadLoop() must be called.\r
\r
  @param[in,out] Context        Carries information from the client module\r
                                itself (i.e., from the invocation of\r
                                QemuFwCfgS3CallWhenBootScriptReady()) to the\r
                                callback function.\r
\r
                                If Context points to dynamically allocated\r
                                storage, then the callback function must\r
                                release it.\r
\r
  @param[in,out] ScratchBuffer  Points to reserved memory, allocated by\r
                                QemuFwCfgS3CallWhenBootScriptReady()\r
                                internally.\r
\r
                                ScratchBuffer is typed and sized by the client\r
                                module when it calls\r
                                QemuFwCfgS3CallWhenBootScriptReady(). The\r
                                client module defines a union type of\r
                                structures for ScratchBuffer such that the\r
                                union can hold client data for any desired\r
                                fw_cfg DMA read and write operations, and value\r
                                checking.\r
\r
                                The callback function casts ScratchBuffer to\r
                                the union type described above. It passes union\r
                                member sizes as NumberOfBytes to\r
                                QemuFwCfgS3ScriptReadBytes() and\r
                                QemuFwCfgS3ScriptWriteBytes(). It passes field\r
                                addresses and sizes in structures in the union\r
                                as ScratchData and ValueSize to\r
                                QemuFwCfgS3ScriptCheckValue().\r
\r
                                ScratchBuffer is aligned at 8 bytes.\r
**/\r
typedef\r
VOID(EFIAPI FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION)(\r
  IN OUT VOID *Context       OPTIONAL,\r
  IN OUT VOID *ScratchBuffer\r
  );\r
\r
/**\r
  Install the client module's FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION callback for\r
  when the production of ACPI S3 Boot Script opcodes becomes possible.\r
\r
  Take ownership of the client-provided Context, and pass it to the callback\r
  function, when the latter is invoked.\r
\r
  Allocate scratch space for those ACPI S3 Boot Script opcodes to work upon\r
  that the client will produce in the callback function.\r
\r
  @param[in] Callback           FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION to invoke\r
                                when the production of ACPI S3 Boot Script\r
                                opcodes becomes possible. Callback() may be\r
                                called immediately from\r
                                QemuFwCfgS3CallWhenBootScriptReady().\r
\r
  @param[in,out] Context        Client-provided data structure for the\r
                                Callback() callback function to consume.\r
\r
                                If Context points to dynamically allocated\r
                                memory, then Callback() must release it.\r
\r
                                If Context points to dynamically allocated\r
                                memory, and\r
                                QemuFwCfgS3CallWhenBootScriptReady() returns\r
                                successfully, then the caller of\r
                                QemuFwCfgS3CallWhenBootScriptReady() must\r
                                neither dereference nor even evaluate Context\r
                                any longer, as ownership of the referenced area\r
                                has been transferred to Callback().\r
\r
  @param[in] ScratchBufferSize  The size of the scratch buffer that will hold,\r
                                in reserved memory, all client data read,\r
                                written, and checked by the ACPI S3 Boot Script\r
                                opcodes produced by Callback().\r
\r
  @retval RETURN_UNSUPPORTED       The library instance does not support this\r
                                   function.\r
\r
  @retval RETURN_NOT_FOUND         The fw_cfg DMA interface to QEMU is\r
                                   unavailable.\r
\r
  @retval RETURN_BAD_BUFFER_SIZE   ScratchBufferSize is too large.\r
\r
  @retval RETURN_OUT_OF_RESOURCES  Memory allocation failed.\r
\r
  @retval RETURN_SUCCESS           Callback() has been installed, and the\r
                                   ownership of Context has been transferred.\r
                                   Reserved memory has been allocated for the\r
                                   scratch buffer.\r
\r
                                   A successful invocation of\r
                                   QemuFwCfgS3CallWhenBootScriptReady() cannot\r
                                   be rolled back.\r
\r
  @return                          Error codes from underlying functions.\r
**/\r
RETURN_STATUS\r
EFIAPI\r
QemuFwCfgS3CallWhenBootScriptReady (\r
  IN     FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION  *Callback,\r
  IN OUT VOID                                  *Context           OPTIONAL,\r
  IN     UINTN                                 ScratchBufferSize\r
  );\r
\r
/**\r
  Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,\r
  and transfer data to it.\r
\r
  The opcodes produced by QemuFwCfgS3ScriptWriteBytes() will first restore\r
  NumberOfBytes bytes in ScratchBuffer in-place, in reserved memory, then write\r
  them to fw_cfg using DMA.\r
\r
  If the operation fails during S3 resume, the boot script will hang.\r
\r
  This function may only be called from the client module's\r
  FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
  QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
\r
  @param[in] FirmwareConfigItem  The UINT16 selector key of the firmware config\r
                                 item to write, expressed as INT32. If\r
                                 FirmwareConfigItem is -1, no selection is\r
                                 made, the write will occur to the currently\r
                                 selected item, at its currently selected\r
                                 offset. Otherwise, the specified item will be\r
                                 selected, and the write will occur at offset\r
                                 0.\r
\r
  @param[in] NumberOfBytes       Size of the data to restore in ScratchBuffer,\r
                                 and to write from ScratchBuffer, during S3\r
                                 resume. NumberOfBytes must not exceed\r
                                 ScratchBufferSize, which was passed to\r
                                 QemuFwCfgS3CallWhenBootScriptReady().\r
\r
  @retval RETURN_SUCCESS            The opcodes were appended to the ACPI S3\r
                                    Boot Script successfully. There is no way\r
                                    to undo this action.\r
\r
  @retval RETURN_INVALID_PARAMETER  FirmwareConfigItem is invalid.\r
\r
  @retval RETURN_BAD_BUFFER_SIZE    NumberOfBytes is larger than\r
                                    ScratchBufferSize.\r
\r
  @return                           Error codes from underlying functions.\r
**/\r
RETURN_STATUS\r
EFIAPI\r
QemuFwCfgS3ScriptWriteBytes (\r
  IN INT32  FirmwareConfigItem,\r
  IN UINTN  NumberOfBytes\r
  );\r
\r
/**\r
  Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,\r
  and transfer data from it.\r
\r
  The opcodes produced by QemuFwCfgS3ScriptReadBytes() will read NumberOfBytes\r
  bytes from fw_cfg using DMA, storing the result in ScratchBuffer, in reserved\r
  memory.\r
\r
  If the operation fails during S3 resume, the boot script will hang.\r
\r
  This function may only be called from the client module's\r
  FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
  QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
\r
  @param[in] FirmwareConfigItem  The UINT16 selector key of the firmware config\r
                                 item to read, expressed as INT32. If\r
                                 FirmwareConfigItem is -1, no selection is\r
                                 made, the read will occur from the currently\r
                                 selected item, from its currently selected\r
                                 offset. Otherwise, the specified item will be\r
                                 selected, and the read will occur from offset\r
                                 0.\r
\r
  @param[in] NumberOfBytes       Size of the data to read during S3 resume.\r
                                 NumberOfBytes must not exceed\r
                                 ScratchBufferSize, which was passed to\r
                                 QemuFwCfgS3CallWhenBootScriptReady().\r
\r
  @retval RETURN_SUCCESS            The opcodes were appended to the ACPI S3\r
                                    Boot Script successfully. There is no way\r
                                    to undo this action.\r
\r
  @retval RETURN_INVALID_PARAMETER  FirmwareConfigItem is invalid.\r
\r
  @retval RETURN_BAD_BUFFER_SIZE    NumberOfBytes is larger than\r
                                    ScratchBufferSize.\r
\r
  @return                           Error codes from underlying functions.\r
**/\r
RETURN_STATUS\r
EFIAPI\r
QemuFwCfgS3ScriptReadBytes (\r
  IN INT32  FirmwareConfigItem,\r
  IN UINTN  NumberOfBytes\r
  );\r
\r
/**\r
  Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,\r
  and increase its offset.\r
\r
  If the operation fails during S3 resume, the boot script will hang.\r
\r
  This function may only be called from the client module's\r
  FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
  QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
\r
  @param[in] FirmwareConfigItem  The UINT16 selector key of the firmware config\r
                                 item to advance the offset of, expressed as\r
                                 INT32. If FirmwareConfigItem is -1, no\r
                                 selection is made, and the offset for the\r
                                 currently selected item is increased.\r
                                 Otherwise, the specified item will be\r
                                 selected, and the offset increment will occur\r
                                 from offset 0.\r
\r
  @param[in] NumberOfBytes       The number of bytes to skip in the subject\r
                                 fw_cfg item.\r
\r
  @retval RETURN_SUCCESS            The opcodes were appended to the ACPI S3\r
                                    Boot Script successfully. There is no way\r
                                    to undo this action.\r
\r
  @retval RETURN_INVALID_PARAMETER  FirmwareConfigItem is invalid.\r
\r
  @retval RETURN_BAD_BUFFER_SIZE    NumberOfBytes is too large.\r
\r
  @return                           Error codes from underlying functions.\r
**/\r
RETURN_STATUS\r
EFIAPI\r
QemuFwCfgS3ScriptSkipBytes (\r
  IN INT32  FirmwareConfigItem,\r
  IN UINTN  NumberOfBytes\r
  );\r
\r
/**\r
  Produce ACPI S3 Boot Script opcodes that check a value in ScratchBuffer.\r
\r
  If the check fails during S3 resume, the boot script will hang.\r
\r
  This function may only be called from the client module's\r
  FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
  QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
\r
  @param[in] ScratchData  Pointer to the UINT8, UINT16, UINT32 or UINT64 field\r
                          in ScratchBuffer that should be checked. The caller\r
                          is responsible for populating the field during S3\r
                          resume, by calling QemuFwCfgS3ScriptReadBytes() ahead\r
                          of QemuFwCfgS3ScriptCheckValue().\r
\r
                          ScratchData must point into ScratchBuffer, which was\r
                          allocated, and passed to Callback(), by\r
                          QemuFwCfgS3CallWhenBootScriptReady().\r
\r
                          ScratchData must be aligned at ValueSize bytes.\r
\r
  @param[in] ValueSize    One of 1, 2, 4 or 8, specifying the size of the field\r
                          to check.\r
\r
  @param[in] ValueMask    The value read from ScratchData is binarily AND-ed\r
                          with ValueMask, and the result is compared against\r
                          Value. If the masked data equals Value, the check\r
                          passes, and the boot script can proceed. Otherwise,\r
                          the check fails, and the boot script hangs.\r
\r
  @param[in] Value        Refer to ValueMask.\r
\r
  @retval RETURN_SUCCESS            The opcodes were appended to the ACPI S3\r
                                    Boot Script successfully. There is no way\r
                                    to undo this action.\r
\r
  @retval RETURN_INVALID_PARAMETER  ValueSize is invalid.\r
\r
  @retval RETURN_INVALID_PARAMETER  ValueMask or Value cannot be represented in\r
                                    ValueSize bytes.\r
\r
  @retval RETURN_INVALID_PARAMETER  ScratchData is not aligned at ValueSize\r
                                    bytes.\r
\r
  @retval RETURN_BAD_BUFFER_SIZE    The ValueSize bytes at ScratchData aren't\r
                                    wholly contained in the ScratchBufferSize\r
                                    bytes at ScratchBuffer.\r
\r
  @return                           Error codes from underlying functions.\r
**/\r
RETURN_STATUS\r
EFIAPI\r
QemuFwCfgS3ScriptCheckValue (\r
  IN VOID    *ScratchData,\r
  IN UINT8   ValueSize,\r
  IN UINT64  ValueMask,\r
  IN UINT64  Value\r
  );\r
\r
#endif\r
Commit	Line	Data
f70b071e LE	1	/** @file\r
	2	S3 support for QEMU fw_cfg\r
	3	\r
	4	This library class enables driver modules (a) to query whether S3 support was\r
	5	enabled on the QEMU command line, (b) to produce fw_cfg DMA operations that\r
	6	are to be replayed at S3 resume time.\r
	7	\r
	8	Copyright (C) 2017, Red Hat, Inc.\r
	9	\r
b26f0cf9	10	SPDX-License-Identifier: BSD-2-Clause-Patent\r
f70b071e LE	11	**/\r
	12	\r
	13	#ifndef __FW_CFG_S3_LIB__\r
	14	#define __FW_CFG_S3_LIB__\r
	15	\r
06a265b9 LE	16	#include <Base.h>\r
06a265b9 LE	17	\r
f70b071e LE	18	/**\r
	19	Determine if S3 support is explicitly enabled.\r
	20	\r
	21	@retval TRUE If S3 support is explicitly enabled. Other functions in this\r
	22	library may be called (subject to their individual\r
	23	restrictions).\r
	24	\r
	25	FALSE Otherwise. This includes unavailability of the firmware\r
	26	configuration interface. No other function in this library\r
	27	must be called.\r
	28	**/\r
	29	BOOLEAN\r
	30	EFIAPI\r
	31	QemuFwCfgS3Enabled (\r
	32	VOID\r
	33	);\r
	34	\r
06a265b9 LE	35	/**\r
	36	Prototype for the callback function that the client module provides.\r
	37	\r
	38	In the callback function, the client module calls the\r
	39	QemuFwCfgS3ScriptWriteBytes(), QemuFwCfgS3ScriptReadBytes(),\r
	40	QemuFwCfgS3ScriptSkipBytes(), and QemuFwCfgS3ScriptCheckValue() functions.\r
	41	Those functions produce ACPI S3 Boot Script opcodes that will perform fw_cfg\r
	42	DMA operations, and will check any desired values that were read, during S3\r
	43	resume.\r
	44	\r
	45	The callback function is invoked when the production of ACPI S3 Boot Script\r
	46	opcodes becomes possible. This may occur directly on the call stack of\r
	47	QemuFwCfgS3CallWhenBootScriptReady() (see below), or after\r
	48	QemuFwCfgS3CallWhenBootScriptReady() has successfully returned.\r
	49	\r
	50	The callback function must not return if it fails -- in the general case,\r
	51	there is noone to propagate any errors to. Therefore, on error, an error\r
	52	message should be logged, and CpuDeadLoop() must be called.\r
	53	\r
	54	@param[in,out] Context Carries information from the client module\r
	55	itself (i.e., from the invocation of\r
	56	QemuFwCfgS3CallWhenBootScriptReady()) to the\r
	57	callback function.\r
	58	\r
	59	If Context points to dynamically allocated\r
	60	storage, then the callback function must\r
	61	release it.\r
	62	\r
	63	@param[in,out] ScratchBuffer Points to reserved memory, allocated by\r
	64	QemuFwCfgS3CallWhenBootScriptReady()\r
	65	internally.\r
	66	\r
	67	ScratchBuffer is typed and sized by the client\r
	68	module when it calls\r
	69	QemuFwCfgS3CallWhenBootScriptReady(). The\r
	70	client module defines a union type of\r
	71	structures for ScratchBuffer such that the\r
	72	union can hold client data for any desired\r
	73	fw_cfg DMA read and write operations, and value\r
	74	checking.\r
	75	\r
	76	The callback function casts ScratchBuffer to\r
	77	the union type described above. It passes union\r
	78	member sizes as NumberOfBytes to\r
	79	QemuFwCfgS3ScriptReadBytes() and\r
	80	QemuFwCfgS3ScriptWriteBytes(). It passes field\r
	81	addresses and sizes in structures in the union\r
	82	as ScratchData and ValueSize to\r
	83	QemuFwCfgS3ScriptCheckValue().\r
	84	\r
	85	ScratchBuffer is aligned at 8 bytes.\r
	86	**/\r
	87	typedef\r
ac0a286f	88	VOID(EFIAPI FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION)(\r
79d49e16	89	IN OUT VOID *Context OPTIONAL,\r
06a265b9 LE	90	IN OUT VOID *ScratchBuffer\r
	91	);\r
	92	\r
06a265b9 LE	93	/**\r
	94	Install the client module's FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION callback for\r
	95	when the production of ACPI S3 Boot Script opcodes becomes possible.\r
	96	\r
	97	Take ownership of the client-provided Context, and pass it to the callback\r
	98	function, when the latter is invoked.\r
	99	\r
	100	Allocate scratch space for those ACPI S3 Boot Script opcodes to work upon\r
	101	that the client will produce in the callback function.\r
	102	\r
	103	@param[in] Callback FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION to invoke\r
	104	when the production of ACPI S3 Boot Script\r
	105	opcodes becomes possible. Callback() may be\r
	106	called immediately from\r
	107	QemuFwCfgS3CallWhenBootScriptReady().\r
	108	\r
	109	@param[in,out] Context Client-provided data structure for the\r
	110	Callback() callback function to consume.\r
	111	\r
	112	If Context points to dynamically allocated\r
	113	memory, then Callback() must release it.\r
	114	\r
	115	If Context points to dynamically allocated\r
	116	memory, and\r
	117	QemuFwCfgS3CallWhenBootScriptReady() returns\r
	118	successfully, then the caller of\r
	119	QemuFwCfgS3CallWhenBootScriptReady() must\r
	120	neither dereference nor even evaluate Context\r
	121	any longer, as ownership of the referenced area\r
	122	has been transferred to Callback().\r
	123	\r
	124	@param[in] ScratchBufferSize The size of the scratch buffer that will hold,\r
	125	in reserved memory, all client data read,\r
	126	written, and checked by the ACPI S3 Boot Script\r
	127	opcodes produced by Callback().\r
	128	\r
	129	@retval RETURN_UNSUPPORTED The library instance does not support this\r
	130	function.\r
	131	\r
	132	@retval RETURN_NOT_FOUND The fw_cfg DMA interface to QEMU is\r
	133	unavailable.\r
	134	\r
	135	@retval RETURN_BAD_BUFFER_SIZE ScratchBufferSize is too large.\r
	136	\r
	137	@retval RETURN_OUT_OF_RESOURCES Memory allocation failed.\r
	138	\r
	139	@retval RETURN_SUCCESS Callback() has been installed, and the\r
	140	ownership of Context has been transferred.\r
	141	Reserved memory has been allocated for the\r
	142	scratch buffer.\r
	143	\r
	144	A successful invocation of\r
	145	QemuFwCfgS3CallWhenBootScriptReady() cannot\r
	146	be rolled back.\r
	147	\r
	148	@return Error codes from underlying functions.\r
	149	**/\r
06a265b9	150	RETURN_STATUS\r
08bed3fb	151	EFIAPI\r
06a265b9	152	QemuFwCfgS3CallWhenBootScriptReady (\r
ac0a286f MK	153	IN FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION *Callback,\r
	154	IN OUT VOID *Context OPTIONAL,\r
	155	IN UINTN ScratchBufferSize\r
06a265b9 LE	156	);\r
06a265b9 LE	157	\r
06a265b9 LE	158	/**\r
	159	Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,\r
	160	and transfer data to it.\r
	161	\r
	162	The opcodes produced by QemuFwCfgS3ScriptWriteBytes() will first restore\r
	163	NumberOfBytes bytes in ScratchBuffer in-place, in reserved memory, then write\r
	164	them to fw_cfg using DMA.\r
	165	\r
	166	If the operation fails during S3 resume, the boot script will hang.\r
	167	\r
	168	This function may only be called from the client module's\r
	169	FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
	170	QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
	171	\r
	172	@param[in] FirmwareConfigItem The UINT16 selector key of the firmware config\r
	173	item to write, expressed as INT32. If\r
	174	FirmwareConfigItem is -1, no selection is\r
	175	made, the write will occur to the currently\r
	176	selected item, at its currently selected\r
	177	offset. Otherwise, the specified item will be\r
	178	selected, and the write will occur at offset\r
	179	0.\r
	180	\r
	181	@param[in] NumberOfBytes Size of the data to restore in ScratchBuffer,\r
	182	and to write from ScratchBuffer, during S3\r
	183	resume. NumberOfBytes must not exceed\r
	184	ScratchBufferSize, which was passed to\r
	185	QemuFwCfgS3CallWhenBootScriptReady().\r
	186	\r
	187	@retval RETURN_SUCCESS The opcodes were appended to the ACPI S3\r
	188	Boot Script successfully. There is no way\r
	189	to undo this action.\r
	190	\r
	191	@retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.\r
	192	\r
	193	@retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is larger than\r
	194	ScratchBufferSize.\r
	195	\r
	196	@return Error codes from underlying functions.\r
	197	**/\r
06a265b9	198	RETURN_STATUS\r
08bed3fb	199	EFIAPI\r
06a265b9	200	QemuFwCfgS3ScriptWriteBytes (\r
ac0a286f MK	201	IN INT32 FirmwareConfigItem,\r
ac0a286f MK	202	IN UINTN NumberOfBytes\r
06a265b9 LE	203	);\r
06a265b9 LE	204	\r
06a265b9 LE	205	/**\r
	206	Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,\r
	207	and transfer data from it.\r
	208	\r
	209	The opcodes produced by QemuFwCfgS3ScriptReadBytes() will read NumberOfBytes\r
	210	bytes from fw_cfg using DMA, storing the result in ScratchBuffer, in reserved\r
	211	memory.\r
	212	\r
	213	If the operation fails during S3 resume, the boot script will hang.\r
	214	\r
	215	This function may only be called from the client module's\r
	216	FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
	217	QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
	218	\r
	219	@param[in] FirmwareConfigItem The UINT16 selector key of the firmware config\r
	220	item to read, expressed as INT32. If\r
	221	FirmwareConfigItem is -1, no selection is\r
	222	made, the read will occur from the currently\r
	223	selected item, from its currently selected\r
	224	offset. Otherwise, the specified item will be\r
	225	selected, and the read will occur from offset\r
	226	0.\r
	227	\r
	228	@param[in] NumberOfBytes Size of the data to read during S3 resume.\r
	229	NumberOfBytes must not exceed\r
	230	ScratchBufferSize, which was passed to\r
	231	QemuFwCfgS3CallWhenBootScriptReady().\r
	232	\r
	233	@retval RETURN_SUCCESS The opcodes were appended to the ACPI S3\r
	234	Boot Script successfully. There is no way\r
	235	to undo this action.\r
	236	\r
	237	@retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.\r
	238	\r
	239	@retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is larger than\r
	240	ScratchBufferSize.\r
	241	\r
	242	@return Error codes from underlying functions.\r
	243	**/\r
06a265b9	244	RETURN_STATUS\r
08bed3fb	245	EFIAPI\r
06a265b9	246	QemuFwCfgS3ScriptReadBytes (\r
ac0a286f MK	247	IN INT32 FirmwareConfigItem,\r
ac0a286f MK	248	IN UINTN NumberOfBytes\r
06a265b9 LE	249	);\r
06a265b9 LE	250	\r
06a265b9 LE	251	/**\r
	252	Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,\r
	253	and increase its offset.\r
	254	\r
	255	If the operation fails during S3 resume, the boot script will hang.\r
	256	\r
	257	This function may only be called from the client module's\r
	258	FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
	259	QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
	260	\r
	261	@param[in] FirmwareConfigItem The UINT16 selector key of the firmware config\r
	262	item to advance the offset of, expressed as\r
	263	INT32. If FirmwareConfigItem is -1, no\r
	264	selection is made, and the offset for the\r
	265	currently selected item is increased.\r
	266	Otherwise, the specified item will be\r
	267	selected, and the offset increment will occur\r
	268	from offset 0.\r
	269	\r
	270	@param[in] NumberOfBytes The number of bytes to skip in the subject\r
	271	fw_cfg item.\r
	272	\r
	273	@retval RETURN_SUCCESS The opcodes were appended to the ACPI S3\r
	274	Boot Script successfully. There is no way\r
	275	to undo this action.\r
	276	\r
	277	@retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.\r
	278	\r
	279	@retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is too large.\r
	280	\r
	281	@return Error codes from underlying functions.\r
	282	**/\r
06a265b9	283	RETURN_STATUS\r
08bed3fb	284	EFIAPI\r
06a265b9	285	QemuFwCfgS3ScriptSkipBytes (\r
ac0a286f MK	286	IN INT32 FirmwareConfigItem,\r
ac0a286f MK	287	IN UINTN NumberOfBytes\r
06a265b9 LE	288	);\r
06a265b9 LE	289	\r
06a265b9 LE	290	/**\r
	291	Produce ACPI S3 Boot Script opcodes that check a value in ScratchBuffer.\r
	292	\r
	293	If the check fails during S3 resume, the boot script will hang.\r
	294	\r
	295	This function may only be called from the client module's\r
	296	FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
	297	QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
	298	\r
	299	@param[in] ScratchData Pointer to the UINT8, UINT16, UINT32 or UINT64 field\r
	300	in ScratchBuffer that should be checked. The caller\r
	301	is responsible for populating the field during S3\r
	302	resume, by calling QemuFwCfgS3ScriptReadBytes() ahead\r
	303	of QemuFwCfgS3ScriptCheckValue().\r
	304	\r
	305	ScratchData must point into ScratchBuffer, which was\r
	306	allocated, and passed to Callback(), by\r
	307	QemuFwCfgS3CallWhenBootScriptReady().\r
	308	\r
	309	ScratchData must be aligned at ValueSize bytes.\r
	310	\r
	311	@param[in] ValueSize One of 1, 2, 4 or 8, specifying the size of the field\r
	312	to check.\r
	313	\r
	314	@param[in] ValueMask The value read from ScratchData is binarily AND-ed\r
	315	with ValueMask, and the result is compared against\r
	316	Value. If the masked data equals Value, the check\r
	317	passes, and the boot script can proceed. Otherwise,\r
	318	the check fails, and the boot script hangs.\r
	319	\r
	320	@param[in] Value Refer to ValueMask.\r
	321	\r
	322	@retval RETURN_SUCCESS The opcodes were appended to the ACPI S3\r
	323	Boot Script successfully. There is no way\r
	324	to undo this action.\r
	325	\r
	326	@retval RETURN_INVALID_PARAMETER ValueSize is invalid.\r
	327	\r
	328	@retval RETURN_INVALID_PARAMETER ValueMask or Value cannot be represented in\r
	329	ValueSize bytes.\r
	330	\r
	331	@retval RETURN_INVALID_PARAMETER ScratchData is not aligned at ValueSize\r
	332	bytes.\r
	333	\r
	334	@retval RETURN_BAD_BUFFER_SIZE The ValueSize bytes at ScratchData aren't\r
	335	wholly contained in the ScratchBufferSize\r
	336	bytes at ScratchBuffer.\r
	337	\r
	338	@return Error codes from underlying functions.\r
	339	**/\r
06a265b9	340	RETURN_STATUS\r
08bed3fb	341	EFIAPI\r
06a265b9	342	QemuFwCfgS3ScriptCheckValue (\r
ac0a286f MK	343	IN VOID *ScratchData,\r
	344	IN UINT8 ValueSize,\r
	345	IN UINT64 ValueMask,\r
	346	IN UINT64 Value\r
06a265b9 LE	347	);\r
06a265b9 LE	348	\r
f70b071e	349	#endif\r