| /** @file | |
| Shared code for the Base Null and PEI fw_cfg instances of the QemuFwCfgS3Lib | |
| class. | |
| Copyright (C) 2017, Red Hat, Inc. | |
| This program and the accompanying materials are licensed and made available | |
| under the terms and conditions of the BSD License which accompanies this | |
| distribution. The full text of the license may be found at | |
| http://opensource.org/licenses/bsd-license.php | |
| THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT | |
| WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. | |
| **/ | |
| #include <Library/DebugLib.h> | |
| #include <Library/QemuFwCfgS3Lib.h> | |
| /** | |
| Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item, | |
| and transfer data to it. | |
| The opcodes produced by QemuFwCfgS3ScriptWriteBytes() will first restore | |
| NumberOfBytes bytes in ScratchBuffer in-place, in reserved memory, then write | |
| them to fw_cfg using DMA. | |
| If the operation fails during S3 resume, the boot script will hang. | |
| This function may only be called from the client module's | |
| FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to | |
| QemuFwCfgS3CallWhenBootScriptReady() as Callback. | |
| @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config | |
| item to write, expressed as INT32. If | |
| FirmwareConfigItem is -1, no selection is | |
| made, the write will occur to the currently | |
| selected item, at its currently selected | |
| offset. Otherwise, the specified item will be | |
| selected, and the write will occur at offset | |
| 0. | |
| @param[in] NumberOfBytes Size of the data to restore in ScratchBuffer, | |
| and to write from ScratchBuffer, during S3 | |
| resume. NumberOfBytes must not exceed | |
| ScratchBufferSize, which was passed to | |
| QemuFwCfgS3CallWhenBootScriptReady(). | |
| @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3 | |
| Boot Script successfully. There is no way | |
| to undo this action. | |
| @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid. | |
| @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is larger than | |
| ScratchBufferSize. | |
| @return Error codes from underlying functions. | |
| **/ | |
| RETURN_STATUS | |
| EFIAPI | |
| QemuFwCfgS3ScriptWriteBytes ( | |
| IN INT32 FirmwareConfigItem, | |
| IN UINTN NumberOfBytes | |
| ) | |
| { | |
| ASSERT (FALSE); | |
| return RETURN_UNSUPPORTED; | |
| } | |
| /** | |
| Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item, | |
| and transfer data from it. | |
| The opcodes produced by QemuFwCfgS3ScriptReadBytes() will read NumberOfBytes | |
| bytes from fw_cfg using DMA, storing the result in ScratchBuffer, in reserved | |
| memory. | |
| If the operation fails during S3 resume, the boot script will hang. | |
| This function may only be called from the client module's | |
| FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to | |
| QemuFwCfgS3CallWhenBootScriptReady() as Callback. | |
| @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config | |
| item to read, expressed as INT32. If | |
| FirmwareConfigItem is -1, no selection is | |
| made, the read will occur from the currently | |
| selected item, from its currently selected | |
| offset. Otherwise, the specified item will be | |
| selected, and the read will occur from offset | |
| 0. | |
| @param[in] NumberOfBytes Size of the data to read during S3 resume. | |
| NumberOfBytes must not exceed | |
| ScratchBufferSize, which was passed to | |
| QemuFwCfgS3CallWhenBootScriptReady(). | |
| @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3 | |
| Boot Script successfully. There is no way | |
| to undo this action. | |
| @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid. | |
| @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is larger than | |
| ScratchBufferSize. | |
| @return Error codes from underlying functions. | |
| **/ | |
| RETURN_STATUS | |
| EFIAPI | |
| QemuFwCfgS3ScriptReadBytes ( | |
| IN INT32 FirmwareConfigItem, | |
| IN UINTN NumberOfBytes | |
| ) | |
| { | |
| ASSERT (FALSE); | |
| return RETURN_UNSUPPORTED; | |
| } | |
| /** | |
| Produce ACPI S3 Boot Script opcodes that (optionally) select an fw_cfg item, | |
| and increase its offset. | |
| If the operation fails during S3 resume, the boot script will hang. | |
| This function may only be called from the client module's | |
| FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to | |
| QemuFwCfgS3CallWhenBootScriptReady() as Callback. | |
| @param[in] FirmwareConfigItem The UINT16 selector key of the firmware config | |
| item to advance the offset of, expressed as | |
| INT32. If FirmwareConfigItem is -1, no | |
| selection is made, and the offset for the | |
| currently selected item is increased. | |
| Otherwise, the specified item will be | |
| selected, and the offset increment will occur | |
| from offset 0. | |
| @param[in] NumberOfBytes The number of bytes to skip in the subject | |
| fw_cfg item. | |
| @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3 | |
| Boot Script successfully. There is no way | |
| to undo this action. | |
| @retval RETURN_INVALID_PARAMETER FirmwareConfigItem is invalid. | |
| @retval RETURN_BAD_BUFFER_SIZE NumberOfBytes is too large. | |
| @return Error codes from underlying functions. | |
| **/ | |
| RETURN_STATUS | |
| EFIAPI | |
| QemuFwCfgS3ScriptSkipBytes ( | |
| IN INT32 FirmwareConfigItem, | |
| IN UINTN NumberOfBytes | |
| ) | |
| { | |
| ASSERT (FALSE); | |
| return RETURN_UNSUPPORTED; | |
| } | |
| /** | |
| Produce ACPI S3 Boot Script opcodes that check a value in ScratchBuffer. | |
| If the check fails during S3 resume, the boot script will hang. | |
| This function may only be called from the client module's | |
| FW_CFG_BOOT_SCRIPT_CALLBACK_FUNCTION, which was passed to | |
| QemuFwCfgS3CallWhenBootScriptReady() as Callback. | |
| @param[in] ScratchData Pointer to the UINT8, UINT16, UINT32 or UINT64 field | |
| in ScratchBuffer that should be checked. The caller | |
| is responsible for populating the field during S3 | |
| resume, by calling QemuFwCfgS3ScriptReadBytes() ahead | |
| of QemuFwCfgS3ScriptCheckValue(). | |
| ScratchData must point into ScratchBuffer, which was | |
| allocated, and passed to Callback(), by | |
| QemuFwCfgS3CallWhenBootScriptReady(). | |
| ScratchData must be aligned at ValueSize bytes. | |
| @param[in] ValueSize One of 1, 2, 4 or 8, specifying the size of the field | |
| to check. | |
| @param[in] ValueMask The value read from ScratchData is binarily AND-ed | |
| with ValueMask, and the result is compared against | |
| Value. If the masked data equals Value, the check | |
| passes, and the boot script can proceed. Otherwise, | |
| the check fails, and the boot script hangs. | |
| @param[in] Value Refer to ValueMask. | |
| @retval RETURN_SUCCESS The opcodes were appended to the ACPI S3 | |
| Boot Script successfully. There is no way | |
| to undo this action. | |
| @retval RETURN_INVALID_PARAMETER ValueSize is invalid. | |
| @retval RETURN_INVALID_PARAMETER ValueMask or Value cannot be represented in | |
| ValueSize bytes. | |
| @retval RETURN_INVALID_PARAMETER ScratchData is not aligned at ValueSize | |
| bytes. | |
| @retval RETURN_BAD_BUFFER_SIZE The ValueSize bytes at ScratchData aren't | |
| wholly contained in the ScratchBufferSize | |
| bytes at ScratchBuffer. | |
| @return Error codes from underlying functions. | |
| **/ | |
| RETURN_STATUS | |
| EFIAPI | |
| QemuFwCfgS3ScriptCheckValue ( | |
| IN VOID *ScratchData, | |
| IN UINT8 ValueSize, | |
| IN UINT64 ValueMask, | |
| IN UINT64 Value | |
| ) | |
| { | |
| ASSERT (FALSE); | |
| return RETURN_UNSUPPORTED; | |
| } |