Intel Extensible Firmware Interface - Manual (Page 200)

Extensible Firmware Interface Specification
6-8 12/01/02 Version 1.10
support variable. It is created at firmware initialization time for access by EFI components that
may need the information, but does not need to be backed up to nonvolatile storage.
EFI_VARIABLE_NON_VOLATILE variables are stored in fixed hardware that has a limited
storage capacity; sometimes a severely limited capacity. Software should only use a nonvolatile
variable when absolutely necessary. In addition, if software uses a nonvolatile variable it should
use a variable that is only accessible at boot services time if possible.
A variable must contain one or more bytes of Data . Using SetVariable() with a DataSize
of zero causes the entire variable to be deleted. The space consumed by the deleted variable may
not be available until the next power cycle.
The Attributes have the following usage rules:
• Storage attributes are only applied to a variable when creating the variable. If a preexisting
variable is rewritten with different attributes, the result is indeterminate and may vary between
implementations. The correct method of changing the attributes of a variable is to delete the
variable and recreate it with different attributes. There is one exception to this rule. If a
preexisting variable is rewritten with no access attributes specified, the variable will be deleted.
• Setting a data variable with no access, or zero
DataSize attributes specified causes it to be
deleted.
• Runtime access to a data variable implies boot service access. Attributes that have
EFI_VARIABLE_RUNTIME_ACCESS set must also have
EFI_VARIABLE_BOOTSERVICE_ACCESS set. The caller is responsible for following this
rule.
• Once
ExitBootServices() is performed, data variables that did not have
EFI_VARIABLE_RUNTIME_ACCESS set are no longer visible to GetVariable() .
• Once
ExitBootServices() is performed, only variables that have
EFI_VARIABLE_RUNTIME_ACCESS and EFI_VARIABLE_NON_VOLATILE set can be
set with SetVariable() . Variables that have runtime access but that are not nonvolatile are
read-only data variables once ExitBootServices() is performed.
The only rules the firmware must implement when saving a nonvolatile variable is that it has
actually been saved to nonvolatile storage before returning
EFI_SUCCESS, and that a partial save
is not performed. If power fails during a call to SetVariable() the variable may contain its
previous value, or its new value. In addition there is no read, write, or delete security protection.
Status Codes Returned
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 was supplied, or the
DataSize exceeds the maximum allowed.
EFI_INVALID_PARAMETER VariableName is an empty Unicode 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 saved due to a hardware failure.