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