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