2 Base Null library instance of the QemuFwCfgS3Lib class.
4 This library instance returns constant FALSE from QemuFwCfgS3Enabled(), and
5 all other library functions trigger assertion failures. It is suitable for
6 QEMU targets and machine types that never enable S3.
8 Copyright (C) 2017, Red Hat, Inc.
10 SPDX-License-Identifier: BSD-2-Clause-Patent
13 #include <Library/DebugLib.h>
14 #include <Library/QemuFwCfgS3Lib.h>
17 Determine if S3 support is explicitly enabled.
19 @retval TRUE If S3 support is explicitly enabled. Other functions in this
20 library may be called (subject to their individual
23 FALSE Otherwise. This includes unavailability of the firmware
24 configuration interface. No other function in this library
37 Install the client module's FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION callback for
38 when the production of ACPI S3 Boot Script opcodes becomes possible.
40 Take ownership of the client-provided Context, and pass it to the callback
41 function, when the latter is invoked.
43 Allocate scratch space for those ACPI S3 Boot Script opcodes to work upon
44 that the client will produce in the callback function.
46 @param[in] Callback FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION to invoke
47 when the production of ACPI S3 Boot Script
48 opcodes becomes possible. Callback() may be
49 called immediately from
50 QemuFwCfgS3CallWhenBootScriptReady().
52 @param[in,out] Context Client-provided data structure for the
53 Callback() callback function to consume.
55 If Context points to dynamically allocated
56 memory, then Callback() must release it.
58 If Context points to dynamically allocated
60 QemuFwCfgS3CallWhenBootScriptReady() returns
61 successfully, then the caller of
62 QemuFwCfgS3CallWhenBootScriptReady() must
63 neither dereference nor even evaluate Context
64 any longer, as ownership of the referenced area
65 has been transferred to Callback().
67 @param[in] ScratchBufferSize The size of the scratch buffer that will hold,
68 in reserved memory, all client data read,
69 written, and checked by the ACPI S3 Boot Script
70 opcodes produced by Callback().
72 @retval RETURN_UNSUPPORTED The library instance does not support this
75 @retval RETURN_NOT_FOUND The fw_cfg DMA interface to QEMU is
78 @retval RETURN_BAD_BUFFER_SIZE ScratchBufferSize is too large.
80 @retval RETURN_OUT_OF_RESOURCES Memory allocation failed.
82 @retval RETURN_SUCCESS Callback() has been installed, and the
83 ownership of Context has been transferred.
84 Reserved memory has been allocated for the
87 A successful invocation of
88 QemuFwCfgS3CallWhenBootScriptReady() cannot
91 @return Error codes from underlying functions.
95 QemuFwCfgS3CallWhenBootScriptReady (
96 IN FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION
*Callback
,
97 IN OUT VOID
*Context OPTIONAL
,
98 IN UINTN ScratchBufferSize
102 return RETURN_UNSUPPORTED
;