4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Serialize Variables Library implementation
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Copyright (c) 2004 - 2011, Intel Corporation. All rights reserved.<BR>
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync This program and the accompanying materials
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync are licensed and made available under the terms and conditions of the BSD License
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync which accompanies this distribution. The full text of the license may be found at
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Serialization format:
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync The SerializeVariablesLib interface does not specify a format
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync for the serialization of the variable data. This library uses
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync a packed array of a non-uniformly sized data structure elements.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Each variable is stored (packed) as:
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync UINT32 VendorNameSize; // Name size in bytes
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync CHAR16 VendorName[?]; // The variable unicode name including the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync // null terminating character.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync EFI_GUID VendorGuid; // The variable GUID
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync UINT32 DataSize; // The size of variable data in bytes
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync UINT8 Data[?]; // The variable data
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Unpacks the next variable from the buffer
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Buffer - Buffer pointing to the next variable instance
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync On subsequent calls, the pointer should be incremented
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync by the returned SizeUsed value.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] MaxSize - Max allowable size for the variable data
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync On subsequent calls, this should be decremented
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync by the returned SizeUsed value.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[out] Name - Variable name string (address in Buffer)
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[out] NameSize - Size of Name in bytes
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[out] Guid - GUID of variable (address in Buffer)
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[out] Attributes - Attributes of variable
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[out] Data - Buffer containing Data for variable (address in Buffer)
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[out] DataSize - Size of Data in bytes
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[out] SizeUsed - Total size used for this variable instance in Buffer
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @return EFI_STATUS based on the success or failure of the operation
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Iterates through the variables in the buffer, and calls a callback
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync function for each variable found.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] CallbackFunction - Function called for each variable instance
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Context - Passed to each call of CallbackFunction
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Buffer - Buffer containing serialized variables
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] MaxSize - Size of Buffer in bytes
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @return EFI_STATUS based on the success or failure of the operation
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync IN VARIABLE_SERIALIZATION_ITERATION_CALLBACK CallbackFunction,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync // We copy the name to a separately allocated buffer,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync // to be sure it is 16-bit aligned.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync // Run the callback function
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync // Make sure the entire buffer was used, or else return an error
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync "Deserialize variables error: TotalSizeUsed(%d) != MaxSize(%d)\n",
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync // Double the required size to lessen the need to re-allocate in the future
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync CopyMem (NewBuffer, Instance->BufferPtr, Instance->DataSize);
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync ASSERT ((Instance->DataSize + Size) <= Instance->BufferSize);
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync (VOID*) (((UINT8*) (Instance->BufferPtr)) + Instance->DataSize),
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Creates a new variable serialization instance
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[out] Handle - Handle for a variable serialization instance
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_SUCCESS - The variable serialization instance was
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync successfully created.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_OUT_OF_RESOURCES - There we not enough resources to
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync create the variable serialization instance.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Free memory associated with a variable serialization instance
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Handle - Handle for a variable serialization instance
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_SUCCESS - The variable serialization instance was
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync successfully freed.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_INVALID_PARAMETER - Handle was not a valid
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync variable serialization instance.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Creates a new variable serialization instance using the given
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync binary representation of the variables to fill the new instance
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[out] Handle - Handle for a variable serialization instance
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Buffer - A buffer with the serialized representation
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync of the variables. Must be the same format as produced
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync by SerializeVariablesToBuffer.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Size - This is the size of the binary representation
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync of the variables.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_SUCCESS - The binary representation was successfully
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync imported into a new variable serialization instance
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_OUT_OF_RESOURCES - There we not enough resources to
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync create the new variable serialization instance
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Iterates all variables found with RuntimeServices GetNextVariableName
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] CallbackFunction - Function called for each variable instance
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Context - Passed to each call of CallbackFunction
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_SUCCESS - All variables were iterated without the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync CallbackFunction returning an error
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_OUT_OF_RESOURCES - There we not enough resources to
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync iterate through the variables
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @return Any of RETURN_ERROR indicates an error reading the variable
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync or an error was returned from CallbackFunction
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync IN VARIABLE_SERIALIZATION_ITERATION_CALLBACK CallbackFunction,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync // Initialize the variable name and data buffer variables.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync VariableName = AllocateZeroPool (VariableNameBufferSize);
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync // Get the next variable name and guid
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync // The currently allocated VariableName buffer is too small,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync // so we allocate a larger buffer, and copy the old buffer
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync CopyMem (NewBuffer, VariableName, VariableNameBufferSize);
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync // Try to get the next variable name again with the larger buffer.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync // Get the variable data and attributes
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync // The currently allocated VariableData buffer is too small,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync // so we allocate a larger buffer.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync // Try to read the variable again with the larger buffer.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync // Run the callback function
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Iterates all variables found in the variable serialization instance
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Handle - Handle for a variable serialization instance
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] CallbackFunction - Function called for each variable instance
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Context - Passed to each call of CallbackFunction
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_SUCCESS - All variables were iterated without the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync CallbackFunction returning an error
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_OUT_OF_RESOURCES - There we not enough resources to
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync iterate through the variables
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @return Any of RETURN_ERROR indicates an error reading the variable
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync or an error was returned from CallbackFunction
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync IN VARIABLE_SERIALIZATION_ITERATION_CALLBACK CallbackFunction,
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync if ((Instance->BufferPtr != NULL) && (Instance->DataSize != 0)) {
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Sets all variables found in the variable serialization instance
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Handle - Handle for a variable serialization instance
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_SUCCESS - All variables were set successfully
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_OUT_OF_RESOURCES - There we not enough resources to
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync set all the variables
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @return Any of RETURN_ERROR indicates an error reading the variables
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync or in attempting to set a variable
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync return SerializeVariablesIterateInstanceVariables (
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Adds a variable to the variable serialization instance
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Handle - Handle for a variable serialization instance
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] VariableName - Refer to RuntimeServices GetVariable
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] VendorGuid - Refer to RuntimeServices GetVariable
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Attributes - Refer to RuntimeServices GetVariable
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] DataSize - Refer to RuntimeServices GetVariable
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Data - Refer to RuntimeServices GetVariable
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_SUCCESS - All variables were set successfully
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_OUT_OF_RESOURCES - There we not enough resources to
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync add the variable
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_INVALID_PARAMETER - Handle was not a valid
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync variable serialization instance or
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync VariableName, VariableGuid or Data are NULL.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync (VariableName == NULL) || (VendorGuid == NULL) || (Data == NULL)) {
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync SerializedNameSize = (UINT32) StrSize (VariableName);
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync // Add name size (UINT32)
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync AppendToBuffer (Instance, (VOID*) &SerializedNameSize, sizeof (SerializedNameSize));
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync // Add variable unicode name string
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync AppendToBuffer (Instance, (VOID*) VariableName, SerializedNameSize);
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync // Add variable GUID
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync AppendToBuffer (Instance, (VOID*) VendorGuid, sizeof (*VendorGuid));
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync // Add variable attributes
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync AppendToBuffer (Instance, (VOID*) &Attributes, sizeof (Attributes));
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync // Add variable data size (UINT32)
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync AppendToBuffer (Instance, (VOID*) &SerializedDataSize, sizeof (SerializedDataSize));
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync // Add variable data
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Serializes the variables known to this instance into the
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync provided buffer.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in] Handle - Handle for a variable serialization instance
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[out] Buffer - A buffer to store the binary representation
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync of the variables.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @param[in,out] Size - On input this is the size of the buffer.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync On output this is the size of the binary representation
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync of the variables.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_SUCCESS - The binary representation was successfully
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync completed and returned in the buffer.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_OUT_OF_RESOURCES - There we not enough resources to
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync save the variables to the buffer.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_INVALID_PARAMETER - Handle was not a valid
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync variable serialization instance or
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync Size or Buffer were NULL.
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync @retval RETURN_BUFFER_TOO_SMALL - The Buffer size as indicated by
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync the Size parameter was too small for the serialized
4fd606d1f5abe38e1f42c38de1d2e895166bd0f4vboxsync variable data. Size is returned with the required size.