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