Services
Version 1.02 12/12/00 83
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 non-volatile
variable when absolutely necessary. In addition, if software uses a non-volatile 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 pre-existing
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 re-create it with different attributes. There is one exception to this rule. If a pre-
existing 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 non-volatile
are effective read-only data variables once ExitBootServices() is performed.
The only rules the firmware must implement when saving a non-volatile variable is that it has
actually been saved to non-volatile 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
VariableSize exceeds the maximum allowed.
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.