OvmfPkg/Include/Library/SerializeVariablesLib.h

   1 /** @file
   2   Serialize & Deserialize UEFI Variables
   3
   4   Copyright (c) 2011, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef __SERIALIZE_VARIABLES_LIB__
  10 #define __SERIALIZE_VARIABLES_LIB__
  11
  12
  13 /**
  14   Callback function for each variable
  15
  16   @param[in] Context - Context as sent to the iteration function
  17   @param[in] VariableName - Refer to RuntimeServices GetNextVariableName
  18   @param[in] VendorGuid - Refer to RuntimeServices GetNextVariableName
  19   @param[in] Attributes - Refer to RuntimeServices GetVariable
  20   @param[in] DataSize - Refer to RuntimeServices GetVariable
  21   @param[in] Data - Refer to RuntimeServices GetVariable
  22
  23   @retval RETURN_SUCCESS         Continue iterating through the variables
  24   @return Any RETURN_ERROR       Stop iterating through the variables
  25
  26 **/
  27 typedef
  28 RETURN_STATUS
  29 (EFIAPI *VARIABLE_SERIALIZATION_ITERATION_CALLBACK)(
  30   IN  VOID                         *Context,
  31   IN  CHAR16                       *VariableName,
  32   IN  EFI_GUID                     *VendorGuid,
  33   IN  UINT32                       Attributes,
  34   IN  UINTN                        DataSize,
  35   IN  VOID                         *Data
  36   );
  37
  38
  39 /**
  40   Creates a new variable serialization instance
  41
  42   @param[out]  Handle - Handle for a variable serialization instance
  43
  44   @retval      RETURN_SUCCESS - The variable serialization instance was
  45                  successfully created.
  46   @retval      RETURN_OUT_OF_RESOURCES - There we not enough resources to
  47                  create the variable serialization instance.
  48
  49 **/
  50 RETURN_STATUS
  51 EFIAPI
  52 SerializeVariablesNewInstance (
  53   OUT EFI_HANDLE                      *Handle
  54   );
  55
  56
  57 /**
  58   Free memory associated with a variable serialization instance
  59
  60   @param[in]  Handle - Handle for a variable serialization instance
  61
  62   @retval      RETURN_SUCCESS - The variable serialization instance was
  63                  successfully freed.
  64   @retval      RETURN_INVALID_PARAMETER - Handle was not a valid
  65                  variable serialization instance.
  66
  67 **/
  68 RETURN_STATUS
  69 EFIAPI
  70 SerializeVariablesFreeInstance (
  71   IN EFI_HANDLE Handle
  72   );
  73
  74
  75 /**
  76   Creates a new variable serialization instance using the given
  77   binary representation of the variables to fill the new instance
  78
  79   @param[out] Handle - Handle for a variable serialization instance
  80   @param[in]  Buffer - A buffer with the serialized representation
  81                 of the variables.  Must be the same format as produced
  82                 by SerializeVariablesToBuffer.
  83   @param[in]  Size - This is the size of the binary representation
  84                 of the variables.
  85
  86   @retval      RETURN_SUCCESS - The binary representation was successfully
  87                  imported into a new variable serialization instance
  88   @retval      RETURN_OUT_OF_RESOURCES - There we not enough resources to
  89                  create the new variable serialization instance
  90
  91 **/
  92 RETURN_STATUS
  93 EFIAPI
  94 SerializeVariablesNewInstanceFromBuffer (
  95   OUT EFI_HANDLE                          *Handle,
  96   IN  VOID                                *Buffer,
  97   IN  UINTN                               Size
  98   );
  99
 100
 101 /**
 102   Iterates all variables found with RuntimeServices GetNextVariableName
 103
 104   @param[in]   CallbackFunction - Function called for each variable instance
 105   @param[in]   Context - Passed to each call of CallbackFunction
 106
 107   @retval      RETURN_SUCCESS - All variables were iterated without the
 108                  CallbackFunction returning an error
 109   @retval      RETURN_OUT_OF_RESOURCES - There we not enough resources to
 110                  iterate through the variables
 111   @return      Any of RETURN_ERROR indicates an error reading the variable
 112                  or an error was returned from CallbackFunction
 113
 114 **/
 115 RETURN_STATUS
 116 EFIAPI
 117 SerializeVariablesIterateSystemVariables (
 118   IN VARIABLE_SERIALIZATION_ITERATION_CALLBACK CallbackFunction,
 119   IN VOID                                      *Context
 120   );
 121
 122
 123 /**
 124   Iterates all variables found in the variable serialization instance
 125
 126   @param[in]   Handle - Handle for a variable serialization instance
 127   @param[in]   CallbackFunction - Function called for each variable instance
 128   @param[in]   Context - Passed to each call of CallbackFunction
 129
 130   @retval      RETURN_SUCCESS - All variables were iterated without the
 131                  CallbackFunction returning an error
 132   @retval      RETURN_OUT_OF_RESOURCES - There we not enough resources to
 133                  iterate through the variables
 134   @return      Any of RETURN_ERROR indicates an error reading the variable
 135                  or an error was returned from CallbackFunction
 136
 137 **/
 138 RETURN_STATUS
 139 EFIAPI
 140 SerializeVariablesIterateInstanceVariables (
 141   IN EFI_HANDLE                                Handle,
 142   IN VARIABLE_SERIALIZATION_ITERATION_CALLBACK CallbackFunction,
 143   IN VOID                                      *Context
 144   );
 145
 146
 147 /**
 148   Sets all variables found in the variable serialization instance
 149
 150   @param[in]   Handle - Handle for a variable serialization instance
 151
 152   @retval      RETURN_SUCCESS - All variables were set successfully
 153   @retval      RETURN_OUT_OF_RESOURCES - There we not enough resources to
 154                  set all the variables
 155   @return      Any of RETURN_ERROR indicates an error reading the variables
 156                  or in attempting to set a variable
 157
 158 **/
 159 RETURN_STATUS
 160 EFIAPI
 161 SerializeVariablesSetSerializedVariables (
 162   IN EFI_HANDLE                       Handle
 163   );
 164
 165
 166 /**
 167   Adds a variable to the variable serialization instance
 168
 169   @param[in] Handle - Handle for a variable serialization instance
 170   @param[in] VariableName - Refer to RuntimeServices GetVariable
 171   @param[in] VendorGuid - Refer to RuntimeServices GetVariable
 172   @param[in] Attributes - Refer to RuntimeServices GetVariable
 173   @param[in] DataSize - Refer to RuntimeServices GetVariable
 174   @param[in] Data - Refer to RuntimeServices GetVariable
 175
 176   @retval      RETURN_SUCCESS - All variables were set successfully
 177   @retval      RETURN_OUT_OF_RESOURCES - There we not enough resources to
 178                  add the variable
 179
 180 **/
 181 RETURN_STATUS
 182 EFIAPI
 183 SerializeVariablesAddVariable (
 184   IN EFI_HANDLE                   Handle,
 185   IN CHAR16                       *VariableName,
 186   IN EFI_GUID                     *VendorGuid,
 187   IN UINT32                       Attributes,
 188   IN UINTN                        DataSize,
 189   IN VOID                         *Data
 190   );
 191
 192
 193 /**
 194   Serializes the variables known to this instance into the
 195   provided buffer.
 196
 197   @param[in]     Handle - Handle for a variable serialization instance
 198   @param[out]    Buffer - A buffer to store the binary representation
 199                    of the variables.
 200   @param[in,out] Size - On input this is the size of the buffer.
 201                    On output this is the size of the binary representation
 202                    of the variables.
 203
 204   @retval      RETURN_SUCCESS - The binary representation was successfully
 205                  completed and returned in the buffer.
 206   @retval      RETURN_OUT_OF_RESOURCES - There we not enough resources to
 207                  save the variables to the buffer.
 208   @retval      RETURN_INVALID_PARAMETER - Handle was not a valid
 209                  variable serialization instance or
 210                  Size or Buffer were NULL.
 211
 212 **/
 213 RETURN_STATUS
 214 EFIAPI
 215 SerializeVariablesToBuffer (
 216   IN     EFI_HANDLE                       Handle,
 217   OUT    VOID                             *Buffer,
 218   IN OUT UINTN                            *Size
 219   );
 220
 221
 222 #endif
 223