[mirror_edk2.git] / OvmfPkg / Library / QemuFwCfgS3Lib / QemuFwCfgS3BasePei.c

/** @file\r
  Shared code for the Base Null and PEI fw_cfg instances of the QemuFwCfgS3Lib\r
  class.\r
\r
  Copyright (C) 2017, Red Hat, Inc.\r
\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
**/\r
\r
#include <Library/DebugLib.h>\r
#include <Library/QemuFwCfgS3Lib.h>\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
  ASSERT (FALSE);\r
  return RETURN_UNSUPPORTED;\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
  ASSERT (FALSE);\r
  return RETURN_UNSUPPORTED;\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
  ASSERT (FALSE);\r
  return RETURN_UNSUPPORTED;\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
  ASSERT (FALSE);\r
  return RETURN_UNSUPPORTED;\r
}\r
Commit	Line	Data
33ead2dd LE	1	/** @file\r
	2	Shared code for the Base Null and PEI fw_cfg instances of the QemuFwCfgS3Lib\r
	3	class.\r
	4	\r
	5	Copyright (C) 2017, Red Hat, Inc.\r
	6	\r
b26f0cf9	7	SPDX-License-Identifier: BSD-2-Clause-Patent\r
33ead2dd LE	8	**/\r
	9	\r
	10	#include <Library/DebugLib.h>\r
	11	#include <Library/QemuFwCfgS3Lib.h>\r
	12	\r
	13	/**\r
	14	Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,\r
	15	and transfer data to it.\r
	16	\r
	17	The opcodes produced by QemuFwCfgS3ScriptWriteBytes() will first restore\r
	18	NumberOfBytes bytes in ScratchBuffer in-place, in reserved memory, then write\r
	19	them to fw_cfg using DMA.\r
	20	\r
	21	If the operation fails during S3 resume, the boot script will hang.\r
	22	\r
	23	This function may only be called from the client module's\r
	24	FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
	25	QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
	26	\r
	27	@param[in] FirmwareConfigItem The UINT16 selector key of the firmware config\r
	28	item to write, expressed as INT32. If\r
	29	FirmwareConfigItem is -1, no selection is\r
	30	made, the write will occur to the currently\r
	31	selected item, at its currently selected\r
	32	offset. Otherwise, the specified item will be\r
	33	selected, and the write will occur at offset\r
	34	0.\r
	35	\r
	36	@param[in] NumberOfBytes Size of the data to restore in ScratchBuffer,\r
	37	and to write from ScratchBuffer, during S3\r
	38	resume. NumberOfBytes must not exceed\r
	39	ScratchBufferSize, which was passed to\r
	40	QemuFwCfgS3CallWhenBootScriptReady().\r
	41	\r
	42	@retval RETURN_SUCCESS The opcodes were appended to the ACPI S3\r
	43	Boot Script successfully. There is no way\r
	44	to undo this action.\r
	45	\r
	46	@retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.\r
	47	\r
	48	@retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is larger than\r
	49	ScratchBufferSize.\r
	50	\r
	51	@return Error codes from underlying functions.\r
	52	**/\r
33ead2dd	53	RETURN_STATUS\r
08bed3fb	54	EFIAPI\r
33ead2dd	55	QemuFwCfgS3ScriptWriteBytes (\r
ac0a286f MK	56	IN INT32 FirmwareConfigItem,\r
ac0a286f MK	57	IN UINTN NumberOfBytes\r
33ead2dd LE	58	)\r
	59	{\r
	60	ASSERT (FALSE);\r
	61	return RETURN_UNSUPPORTED;\r
	62	}\r
	63	\r
33ead2dd LE	64	/**\r
	65	Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,\r
	66	and transfer data from it.\r
	67	\r
	68	The opcodes produced by QemuFwCfgS3ScriptReadBytes() will read NumberOfBytes\r
	69	bytes from fw_cfg using DMA, storing the result in ScratchBuffer, in reserved\r
	70	memory.\r
	71	\r
	72	If the operation fails during S3 resume, the boot script will hang.\r
	73	\r
	74	This function may only be called from the client module's\r
	75	FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
	76	QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
	77	\r
	78	@param[in] FirmwareConfigItem The UINT16 selector key of the firmware config\r
	79	item to read, expressed as INT32. If\r
	80	FirmwareConfigItem is -1, no selection is\r
	81	made, the read will occur from the currently\r
	82	selected item, from its currently selected\r
	83	offset. Otherwise, the specified item will be\r
	84	selected, and the read will occur from offset\r
	85	0.\r
	86	\r
	87	@param[in] NumberOfBytes Size of the data to read during S3 resume.\r
	88	NumberOfBytes must not exceed\r
	89	ScratchBufferSize, which was passed to\r
	90	QemuFwCfgS3CallWhenBootScriptReady().\r
	91	\r
	92	@retval RETURN_SUCCESS The opcodes were appended to the ACPI S3\r
	93	Boot Script successfully. There is no way\r
	94	to undo this action.\r
	95	\r
	96	@retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.\r
	97	\r
	98	@retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is larger than\r
	99	ScratchBufferSize.\r
	100	\r
	101	@return Error codes from underlying functions.\r
	102	**/\r
33ead2dd	103	RETURN_STATUS\r
08bed3fb	104	EFIAPI\r
33ead2dd	105	QemuFwCfgS3ScriptReadBytes (\r
ac0a286f MK	106	IN INT32 FirmwareConfigItem,\r
ac0a286f MK	107	IN UINTN NumberOfBytes\r
33ead2dd LE	108	)\r
	109	{\r
	110	ASSERT (FALSE);\r
	111	return RETURN_UNSUPPORTED;\r
	112	}\r
	113	\r
33ead2dd LE	114	/**\r
	115	Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item,\r
	116	and increase its offset.\r
	117	\r
	118	If the operation fails during S3 resume, the boot script will hang.\r
	119	\r
	120	This function may only be called from the client module's\r
	121	FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
	122	QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
	123	\r
	124	@param[in] FirmwareConfigItem The UINT16 selector key of the firmware config\r
	125	item to advance the offset of, expressed as\r
	126	INT32. If FirmwareConfigItem is -1, no\r
	127	selection is made, and the offset for the\r
	128	currently selected item is increased.\r
	129	Otherwise, the specified item will be\r
	130	selected, and the offset increment will occur\r
	131	from offset 0.\r
	132	\r
	133	@param[in] NumberOfBytes The number of bytes to skip in the subject\r
	134	fw_cfg item.\r
	135	\r
	136	@retval RETURN_SUCCESS The opcodes were appended to the ACPI S3\r
	137	Boot Script successfully. There is no way\r
	138	to undo this action.\r
	139	\r
	140	@retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid.\r
	141	\r
	142	@retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is too large.\r
	143	\r
	144	@return Error codes from underlying functions.\r
	145	**/\r
33ead2dd	146	RETURN_STATUS\r
08bed3fb	147	EFIAPI\r
33ead2dd	148	QemuFwCfgS3ScriptSkipBytes (\r
ac0a286f MK	149	IN INT32 FirmwareConfigItem,\r
ac0a286f MK	150	IN UINTN NumberOfBytes\r
33ead2dd LE	151	)\r
	152	{\r
	153	ASSERT (FALSE);\r
	154	return RETURN_UNSUPPORTED;\r
	155	}\r
	156	\r
33ead2dd LE	157	/**\r
	158	Produce ACPI S3 Boot Script opcodes that check a value in ScratchBuffer.\r
	159	\r
	160	If the check fails during S3 resume, the boot script will hang.\r
	161	\r
	162	This function may only be called from the client module's\r
	163	FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to\r
	164	QemuFwCfgS3CallWhenBootScriptReady() as Callback.\r
	165	\r
	166	@param[in] ScratchData Pointer to the UINT8, UINT16, UINT32 or UINT64 field\r
	167	in ScratchBuffer that should be checked. The caller\r
	168	is responsible for populating the field during S3\r
	169	resume, by calling QemuFwCfgS3ScriptReadBytes() ahead\r
	170	of QemuFwCfgS3ScriptCheckValue().\r
	171	\r
	172	ScratchData must point into ScratchBuffer, which was\r
	173	allocated, and passed to Callback(), by\r
	174	QemuFwCfgS3CallWhenBootScriptReady().\r
	175	\r
	176	ScratchData must be aligned at ValueSize bytes.\r
	177	\r
	178	@param[in] ValueSize One of 1, 2, 4 or 8, specifying the size of the field\r
	179	to check.\r
	180	\r
	181	@param[in] ValueMask The value read from ScratchData is binarily AND-ed\r
	182	with ValueMask, and the result is compared against\r
	183	Value. If the masked data equals Value, the check\r
	184	passes, and the boot script can proceed. Otherwise,\r
	185	the check fails, and the boot script hangs.\r
	186	\r
	187	@param[in] Value Refer to ValueMask.\r
	188	\r
	189	@retval RETURN_SUCCESS The opcodes were appended to the ACPI S3\r
	190	Boot Script successfully. There is no way\r
	191	to undo this action.\r
	192	\r
	193	@retval RETURN_INVALID_PARAMETER ValueSize is invalid.\r
	194	\r
	195	@retval RETURN_INVALID_PARAMETER ValueMask or Value cannot be represented in\r
	196	ValueSize bytes.\r
	197	\r
	198	@retval RETURN_INVALID_PARAMETER ScratchData is not aligned at ValueSize\r
	199	bytes.\r
	200	\r
	201	@retval RETURN_BAD_BUFFER_SIZE The ValueSize bytes at ScratchData aren't\r
	202	wholly contained in the ScratchBufferSize\r
	203	bytes at ScratchBuffer.\r
	204	\r
	205	@return Error codes from underlying functions.\r
	206	**/\r
33ead2dd	207	RETURN_STATUS\r
08bed3fb	208	EFIAPI\r
33ead2dd	209	QemuFwCfgS3ScriptCheckValue (\r
ac0a286f MK	210	IN VOID *ScratchData,\r
	211	IN UINT8 ValueSize,\r
	212	IN UINT64 ValueMask,\r
	213	IN UINT64 Value\r
33ead2dd LE	214	)\r
	215	{\r
	216	ASSERT (FALSE);\r
	217	return RETURN_UNSUPPORTED;\r
	218	}\r