#include <Uefi.h>
#include <Library/OcConfigurationLib.h>
#include <Library/OcStorageLib.h>
#include <Protocol/OcFirmwareRuntime.h>

Macros
#define	OPEN_CORE_NVRAM_ROOT_PATH L"NVRAM"

#define	OPEN_CORE_NVRAM_FILENAME L"nvram.plist"

#define	OPEN_CORE_NVRAM_FALLBACK_FILENAME L"nvram.fallback"

#define	OPEN_CORE_NVRAM_USED_FILENAME L"nvram.used"

#define	OPEN_CORE_NVRAM_ATTR (EFI_VARIABLE_BOOTSERVICE_ACCESS \| EFI_VARIABLE_RUNTIME_ACCESS)

#define	OPEN_CORE_NVRAM_NV_ATTR (EFI_VARIABLE_BOOTSERVICE_ACCESS \| EFI_VARIABLE_RUNTIME_ACCESS \| EFI_VARIABLE_NON_VOLATILE)

#define	OPEN_CORE_INT_NVRAM_ATTR EFI_VARIABLE_BOOTSERVICE_ACCESS

Typedefs
typedef enum _OC_PROCESS_VARIABLE_RESULT	OC_PROCESS_VARIABLE_RESULT

typedef OC_PROCESS_VARIABLE_RESULT(EFIAPI *	OC_PROCESS_VARIABLE) (IN EFI_GUID Guid, IN CHAR16 Name, IN VOID *Context OPTIONAL)

Enumerations
enum	_OC_PROCESS_VARIABLE_RESULT { OcProcessVariableContinue , OcProcessVariableRestart , OcProcessVariableAbort }

Functions
VOID	OcVariableInit (IN BOOLEAN ForceOcWriteFlash)

EFI_STATUS	OcSetSystemVariable (IN CHAR16 VariableName, IN UINT32 Attributes, IN UINTN DataSize, IN VOID Data, IN EFI_GUID *VendorGuid OPTIONAL)

EFI_STATUS	OcProcessVariableGuid (IN CONST CHAR8 AsciiVariableGuid, OUT GUID VariableGuid, IN OC_NVRAM_LEGACY_MAP Schema OPTIONAL, OUT OC_NVRAM_LEGACY_ENTRY *SchemaEntry OPTIONAL)

BOOLEAN	OcVariableIsAllowedBySchemaEntry (IN OC_NVRAM_LEGACY_ENTRY SchemaEntry, IN EFI_GUID VariableGuid OPTIONAL, IN CONST VOID *VariableName, IN OC_STRING_FORMAT StringFormat)

VOID	OcSetNvramVariable (IN CONST CHAR8 AsciiVariableName, IN EFI_GUID VariableGuid, IN UINT32 Attributes, IN UINT32 VariableSize, IN VOID VariableData, IN OC_NVRAM_LEGACY_ENTRY SchemaEntry OPTIONAL, IN BOOLEAN Overwrite)

EFI_LOAD_OPTION *	OcGetBootOptionData (OUT UINTN OptionSize, IN UINT16 BootOption, IN CONST EFI_GUID BootGuid)

EFI_STATUS	OcResetNvram (IN BOOLEAN PreserveBoot)

OC_FIRMWARE_RUNTIME_PROTOCOL *	OcDisableNvramProtection (VOID)

VOID	OcRestoreNvramProtection (IN OC_FIRMWARE_RUNTIME_PROTOCOL *FwRuntime)

VOID	OcDeleteVariables (IN BOOLEAN PreserveBoot)

VOID	OcScanVariables (IN OC_PROCESS_VARIABLE ProcessVariable, IN VOID *Context)

EFI_STATUS	OcGetSip (OUT UINT32 CsrActiveConfig, OUT UINT32 Attributes OPTIONAL)

EFI_STATUS	OcSetSip (IN UINT32 *CsrActiveConfig, IN UINT32 Attributes)

BOOLEAN	OcIsSipEnabled (IN EFI_STATUS GetStatus, IN UINT32 CsrActiveConfig)

EFI_STATUS	OcToggleSip (IN UINT32 CsrActiveConfig)

VOID	OcLoadLegacyNvram (IN OC_STORAGE_CONTEXT Storage, IN OC_NVRAM_LEGACY_MAP LegacyMap, IN BOOLEAN LegacyOverwrite, IN BOOLEAN RequestBootVarRouting)

VOID EFIAPI	OcSaveLegacyNvram (VOID)

VOID EFIAPI	OcResetLegacyNvram (VOID)

VOID EFIAPI	OcSwitchToFallbackLegacyNvram (VOID)

EFI_STATUS	OcShimRetainProtocol (IN BOOLEAN Required)

Detailed Description

OpenCore Variable library.

Copyright (c) 2016-2022, Vitaly Cheptsov, Marvin Haeuser, Mike Beaton. All rights reserved.
SPDX-License-Identifier: BSD-3-Clause

Definition in file OcVariableLib.h.

Macro Definition Documentation

◆ OPEN_CORE_INT_NVRAM_ATTR

#define OPEN_CORE_INT_NVRAM_ATTR EFI_VARIABLE_BOOTSERVICE_ACCESS

Definition at line 28 of file OcVariableLib.h.

◆ OPEN_CORE_NVRAM_ATTR

#define OPEN_CORE_NVRAM_ATTR (EFI_VARIABLE_BOOTSERVICE_ACCESS | EFI_VARIABLE_RUNTIME_ACCESS)

Definition at line 24 of file OcVariableLib.h.

◆ OPEN_CORE_NVRAM_FALLBACK_FILENAME

#define OPEN_CORE_NVRAM_FALLBACK_FILENAME L"nvram.fallback"

Definition at line 20 of file OcVariableLib.h.

◆ OPEN_CORE_NVRAM_FILENAME

#define OPEN_CORE_NVRAM_FILENAME L"nvram.plist"

Definition at line 18 of file OcVariableLib.h.

◆ OPEN_CORE_NVRAM_NV_ATTR

#define OPEN_CORE_NVRAM_NV_ATTR (EFI_VARIABLE_BOOTSERVICE_ACCESS | EFI_VARIABLE_RUNTIME_ACCESS | EFI_VARIABLE_NON_VOLATILE)

Definition at line 26 of file OcVariableLib.h.

◆ OPEN_CORE_NVRAM_ROOT_PATH

#define OPEN_CORE_NVRAM_ROOT_PATH L"NVRAM"

Definition at line 16 of file OcVariableLib.h.

◆ OPEN_CORE_NVRAM_USED_FILENAME

#define OPEN_CORE_NVRAM_USED_FILENAME L"nvram.used"

Definition at line 22 of file OcVariableLib.h.

Typedef Documentation

◆ OC_PROCESS_VARIABLE

typedef OC_PROCESS_VARIABLE_RESULT(EFIAPI * OC_PROCESS_VARIABLE) (IN EFI_GUID *Guid, IN CHAR16 *Name, IN VOID *Context OPTIONAL)

Process variable during OcScanVariables. Any filtering of which variables to use is done within this function.

Parameters

[in]	Guid	Variable GUID.
[in]	Name	Variable Name.
[in]	Context	Caller-provided context.

Return values

Indicates whether the scan should continue, restart or abort.

Definition at line 226 of file OcVariableLib.h.

◆ OC_PROCESS_VARIABLE_RESULT

typedef enum _OC_PROCESS_VARIABLE_RESULT OC_PROCESS_VARIABLE_RESULT

Process variable result.

Enumeration Type Documentation

◆ _OC_PROCESS_VARIABLE_RESULT

enum _OC_PROCESS_VARIABLE_RESULT

Process variable result.

Enumerator
OcProcessVariableContinue
OcProcessVariableRestart
OcProcessVariableAbort

Definition at line 209 of file OcVariableLib.h.

Function Documentation

◆ OcDeleteVariables()

VOID OcDeleteVariables ( IN BOOLEAN PreserveBoot )

Perform NVRAM UEFI variable deletion.

Definition at line 457 of file VariableManagement.c.

◆ OcDisableNvramProtection()

OC_FIRMWARE_RUNTIME_PROTOCOL * OcDisableNvramProtection ( VOID )

When compatible protocol is found, disable OpenRuntime NVRAM protection then return relevant protocol for subsequent restore, else return NULL. Always call OcRestoreNvramProtection to restore normal OpenRuntime operation before booting anything, after disabling with this call.

Return values

Compatible protocol if found and firmware runtime was disabled, NULL otherwise.

Definition at line 419 of file VariableManagement.c.

◆ OcGetBootOptionData()

EFI_LOAD_OPTION * OcGetBootOptionData	(	OUT UINTN *	OptionSize,
		IN UINT16	BootOption,
		IN CONST EFI_GUID *	BootGuid )

Get EFI boot option from specified namespace.

Parameters

[out]	OptionSize	Boot option size.
[in]	BootOption	Which boot option to return.
[in]	BootGuid	Boot namespace to use (OC or default).

Return values

EFI	boot option data.

Definition at line 55 of file VariableManagement.c.

◆ OcGetSip()

EFI_STATUS OcGetSip	(	OUT UINT32 *	CsrActiveConfig,
		OUT UINT32 *Attributes	OPTIONAL )

Get current SIP setting.

Parameters

[out]	CsrActiveConfig	Returned csr-active-config variable; uninitialised if variable not found, or other error.
[out]	Attributes	If not NULL, a pointer to the memory location to return the attributes bitmask for the variable; uninitialised if variable not found, or other error.

Return values

EFI_SUCCESS,EFI_NOT_FOUND,or other error returned by called code.

Definition at line 15 of file Sip.c.

◆ OcIsSipEnabled()

BOOLEAN OcIsSipEnabled	(	IN EFI_STATUS	GetStatus,
		IN UINT32	CsrActiveConfig )

Is SIP enabled?

Parameters

[in]	GetStatus	Return status from previous OcGetSip or gRT->GetVariable call.
[in]	CsrActiveConfig	csr-active-config value from previous OcGetSip or gRT->GetVariable call. This value is never used unless GetStatus is EFI_SUCCESS.

Return values

TRUE	if SIP should be considered enabled based on the passed values.

Definition at line 58 of file Sip.c.

◆ OcLoadLegacyNvram()

VOID OcLoadLegacyNvram	(	IN OC_STORAGE_CONTEXT *	Storage,
		IN OC_NVRAM_LEGACY_MAP *	LegacyMap,
		IN BOOLEAN	LegacyOverwrite,
		IN BOOLEAN	RequestBootVarRouting )

Load emulated NVRAM using installed protocol when present.

Parameters

[in]	Storage	OpenCore storage.
[in]	LegacyMap	OpenCore legacy NVRAM map, stating which variables are allowed to be read/written.
[in]	LegacyOverwrite	Whether to overwrite any pre-existing variables found in emulated NVRAM.
[in]	RequestBootVarRouting	Whether OpenCore boot variable routing is enabled.

Definition at line 54 of file LegacyNvramWrapper.c.

◆ OcProcessVariableGuid()

EFI_STATUS OcProcessVariableGuid	(	IN CONST CHAR8 *	AsciiVariableGuid,
		OUT GUID *	VariableGuid,
		IN OC_NVRAM_LEGACY_MAP *Schema	OPTIONAL,
		OUT OC_NVRAM_LEGACY_ENTRY **SchemaEntry	OPTIONAL )

Test NVRAM GUID against legacy schema.

Parameters

[in]	AsciiVariableGuid	Guid to test in ASCII format.
[out]	VariableGuid	On success AsciiVariableGuid converted to GUID format.
[in]	Schema	Schema to test against.
[out]	SchemaEntry	On success list of allowed variable names for this GUID.

Returns: EFI_SUCCESS If at least some variables are allowed under this GUID.

Definition at line 27 of file LegacyNvramSupport.c.

◆ OcResetLegacyNvram()

VOID EFIAPI OcResetLegacyNvram ( VOID )

Reset emulated NVRAM using installed protocol when present. If protocol is present, does not return and restarts system.

Definition at line 147 of file LegacyNvramWrapper.c.

◆ OcResetNvram()

EFI_STATUS OcResetNvram ( IN BOOLEAN PreserveBoot )

Resets selected NVRAM variables and reboots the system.

Parameters

[in] PreserveBoot Should reset preserve Boot### entries.

Return values

EFI_SUCCESS,or error returned by called code.

Definition at line 539 of file VariableManagement.c.

◆ OcRestoreNvramProtection()

VOID OcRestoreNvramProtection ( IN OC_FIRMWARE_RUNTIME_PROTOCOL * FwRuntime )

Restore OpenRuntime NVRAM protection if it was disabled by a previous call to OcDisableNvramProtection. Noop when FwRuntime argument is NULL.

Parameters

[in] FwRuntime Firmware runtime protocol or NULL, from previous call to OcDisableNvramProtection.

Definition at line 446 of file VariableManagement.c.

◆ OcSaveLegacyNvram()

VOID EFIAPI OcSaveLegacyNvram ( VOID )

Save to emulated NVRAM using installed protocol when present.

Definition at line 124 of file LegacyNvramWrapper.c.

◆ OcScanVariables()

VOID OcScanVariables	(	IN OC_PROCESS_VARIABLE	ProcessVariable,
		IN VOID *	Context )

Apply function to each NVRAM variable.

Parameters

[in]	ProcessVariable	Function to apply.
[in]	Context	Caller-provided context.

Definition at line 181 of file VariableManagement.c.

◆ OcSetNvramVariable()

VOID OcSetNvramVariable	(	IN CONST CHAR8 *	AsciiVariableName,
		IN EFI_GUID *	VariableGuid,
		IN UINT32	Attributes,
		IN UINT32	VariableSize,
		IN VOID *	VariableData,
		IN OC_NVRAM_LEGACY_ENTRY *SchemaEntry	OPTIONAL,
		IN BOOLEAN	Overwrite )

Set NVRAM variable - for internal use at NVRAM setup only.

Parameters

[in]	AsciiVariableName	Variable name.
[in]	VariableGuid	Variably Guid.
[in]	Attributes	Attributes.
[in]	VariableSize	Data size.
[in]	VariableData	Data.
[in]	SchemaEntry	Optional schema to filter by.
[in]	Overwrite	If TRUE pre-existing variables can be overwritten.

Definition at line 106 of file LegacyNvramSupport.c.

◆ OcSetSip()

EFI_STATUS OcSetSip	(	IN UINT32 *	CsrActiveConfig,
		IN UINT32	Attributes )

Set current SIP setting.

Parameters

[in]	CsrActiveConfig	csr-active-config value to set, or NULL to clear the variable.
[in]	Attributes	Attributes to apply.

Return values

EFI_SUCCESS,EFI_NOT_FOUND,or other error returned by called code.

Definition at line 39 of file Sip.c.

◆ OcSetSystemVariable()

EFI_STATUS OcSetSystemVariable	(	IN CHAR16 *	VariableName,
		IN UINT32	Attributes,
		IN UINTN	DataSize,
		IN VOID *	Data,
		IN EFI_GUID *VendorGuid	OPTIONAL )

Sets the value of an OpenCore system variable to the OpenCore vendor GUID. If the write is to be performed non-volatile, this function guarantees to not request a write if the existing data is identical to the data requested to be written.

Parameters

[in]	VariableName	A Null-terminated string that is the name of the vendor's variable. Each VariableName is unique for each VendorGuid. VariableName must contain 1 or more characters. If VariableName is an empty string, then EFI_INVALID_PARAMETER is returned.
[in]	Attributes	Attributes bitmask to set for the variable.
[in]	DataSize	The size in bytes of the Data buffer. Unless the EFI_VARIABLE_APPEND_WRITE or EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS attribute is set, a size of zero causes the variable to be deleted. When the EFI_VARIABLE_APPEND_WRITE attribute is set, then a SetVariable() call with a DataSize of zero will not cause any change to the variable value (the timestamp associated with the variable may be updated however even if no new data value is provided,see the description of the EFI_VARIABLE_AUTHENTICATION_2 descriptor below. In this case the DataSize will not be zero since the EFI_VARIABLE_AUTHENTICATION_2 descriptor will be populated).
[in]	Data	The contents for the variable.
[in]	VendorGuid	Variable GUID, defaults to gOcVendorVariableGuid if NULL.

Return values

EFI_SUCCESS	The firmware has successfully stored the variable and its data as defined by the Attributes.
EFI_INVALID_PARAMETER	An invalid combination of attribute bits, name, and GUID was supplied, or the DataSize exceeds the maximum allowed.
EFI_INVALID_PARAMETER	VariableName is an empty string.
EFI_OUT_OF_RESOURCES	Not enough storage is available to hold the variable and its data.
EFI_DEVICE_ERROR	The variable could not be retrieved due to a hardware error.
EFI_WRITE_PROTECTED	The variable in question is read-only.
EFI_WRITE_PROTECTED	The variable in question cannot be deleted.
EFI_SECURITY_VIOLATION	The variable could not be written due to EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACESS being set, but the AuthInfo does NOT pass the validation check carried out by the firmware.
EFI_NOT_FOUND	The variable trying to be updated or deleted was not found.

Definition at line 35 of file OcVariableLib.c.

◆ OcShimRetainProtocol()

EFI_STATUS OcShimRetainProtocol ( IN BOOLEAN Required )

If Required is TRUE set volatile BS-only ShimRetainProtocol variable to 1.

Parameters

[in] Required Is ShimRetainProtocol required.

Definition at line 13 of file Shim.c.

◆ OcSwitchToFallbackLegacyNvram()

VOID EFIAPI OcSwitchToFallbackLegacyNvram ( VOID )

Switch to fallback emulated NVRAM using installed protocol when present.

Definition at line 172 of file LegacyNvramWrapper.c.

◆ OcToggleSip()

EFI_STATUS OcToggleSip ( IN UINT32 CsrActiveConfig )

Toggle SIP.

Parameters

[in] CsrActiveConfig The csr-active-config value to use to disable SIP, if it was previously enabled.

Return values

TRUE	on successful operation.

Definition at line 73 of file Sip.c.

◆ OcVariableInit()

VOID OcVariableInit ( IN BOOLEAN ForceOcWriteFlash )

Initialize the OpenCore variable library. No other function may be called before this function has returned.

Parameters

[in] ForceOcWriteFlash Whether OC system variables should be forced to be written to flash.

Definition at line 23 of file OcVariableLib.c.

◆ OcVariableIsAllowedBySchemaEntry()

BOOLEAN OcVariableIsAllowedBySchemaEntry	(	IN OC_NVRAM_LEGACY_ENTRY *	SchemaEntry,
		IN EFI_GUID *VariableGuid	OPTIONAL,
		IN CONST VOID *	VariableName,
		IN OC_STRING_FORMAT	StringFormat )

Test NVRAM variable name against legacy schema.

Parameters

[in]	SchemaEntry	List of allowed names.
[in]	VariableGuid	Variable GUID (optional, for debug output only).
[in]	VariableName	Variable name.
[in]	StringFormat	Is VariableName Ascii or Unicode?

Definition at line 58 of file LegacyNvramSupport.c.

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ OPEN_CORE_INT_NVRAM_ATTR

◆ OPEN_CORE_NVRAM_ATTR

◆ OPEN_CORE_NVRAM_FALLBACK_FILENAME

◆ OPEN_CORE_NVRAM_FILENAME

◆ OPEN_CORE_NVRAM_NV_ATTR

◆ OPEN_CORE_NVRAM_ROOT_PATH

◆ OPEN_CORE_NVRAM_USED_FILENAME

Typedef Documentation

◆ OC_PROCESS_VARIABLE

◆ OC_PROCESS_VARIABLE_RESULT

Enumeration Type Documentation

◆ _OC_PROCESS_VARIABLE_RESULT

Function Documentation

◆ OcDeleteVariables()

◆ OcDisableNvramProtection()

◆ OcGetBootOptionData()

◆ OcGetSip()

◆ OcIsSipEnabled()

◆ OcLoadLegacyNvram()

◆ OcProcessVariableGuid()

◆ OcResetLegacyNvram()

◆ OcResetNvram()

◆ OcRestoreNvramProtection()

◆ OcSaveLegacyNvram()

◆ OcScanVariables()

◆ OcSetNvramVariable()

◆ OcSetSip()

◆ OcSetSystemVariable()

◆ OcShimRetainProtocol()

◆ OcSwitchToFallbackLegacyNvram()

◆ OcToggleSip()

◆ OcVariableInit()

◆ OcVariableIsAllowedBySchemaEntry()