IntelFrameworkPkg/Include/Protocol/FrameworkFormCallback.h

   1 /** @file
   2   The EFI_FORM_CALLBACK_PROTOCOL is the defined interface for access to custom
   3   NV storage devices as well as communication of user selections in a more
   4   interactive environment.  This protocol should be published by hardware
   5   specific drivers which want to export access to custom hardware storage or
   6   publish IFR which has a requirement to call back the original driver.
   7
   8   Copyright (c) 2006 - 2009, Intel Corporation
   9   All rights reserved. This program and the accompanying materials
  10   are licensed and made available under the terms and conditions of the BSD License
  11   which accompanies this distribution.  The full text of the license may be found at
  12   http://opensource.org/licenses/bsd-license.php
  13
  14   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  15   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  16
  17   @par Revision Reference:
  18   This protocol is defined in HII spec 0.92.
  19
  20 **/
  21
  22 #ifndef __FORM_CALLBACK_H__
  23 #define __FORM_CALLBACK_H__
  24
  25 #include <FrameworkDxe.h>
  26
  27 #include <Protocol/FrameworkHii.h>
  28 #include <Protocol/FrameworkFormBrowser.h>
  29
  30 #define EFI_FORM_CALLBACK_PROTOCOL_GUID \
  31   { \
  32     0xf3e4543d, 0xcf35, 0x6cef, {0x35, 0xc4, 0x4f, 0xe6, 0x34, 0x4d, 0xfc, 0x54 } \
  33   }
  34
  35 //
  36 // Forward reference for pure ANSI compatability
  37 //
  38 typedef struct _EFI_FORM_CALLBACK_PROTOCOL  EFI_FORM_CALLBACK_PROTOCOL;
  39
  40 ///
  41 ///  Inconsistent with specification here:
  42 ///  EFI_IFR_DATA_ENTRY RESET_REQUIRED, EXIT_REQUIRED, SAVE_REQUIRED, NV_CHANGED
  43 //// and NV_NOT_CHANGED are not defined in HII specification. These Flags of EFI_IFR_DATA_ENTRY
  44 ///  should be defined to describe the standard behavior of the browser after the callback.
  45 ///
  46
  47 ///
  48 /// If this flag is set, the browser will exit and reset after processing callback results
  49 ///
  50 #define RESET_REQUIRED  1
  51 ///
  52 /// If this flag is set, the browser will exit after processing callback results
  53 ///
  54 #define EXIT_REQUIRED   2
  55 ///
  56 /// If this flag is set, the browser will save the NV data after processing callback results
  57 ///
  58 #define SAVE_REQUIRED   4
  59 ///
  60 /// If this flag is set, the browser will turn the NV flag on after processing callback results
  61 ///
  62 #define NV_CHANGED      8
  63 ///
  64 /// If this flag is set, the browser will turn the NV flag off after processing callback results
  65 ///
  66 #define NV_NOT_CHANGED  16
  67
  68 #pragma pack(1)
  69 typedef struct {
  70   UINT8   OpCode;           ///< Likely a string, numeric, or one-of
  71   UINT8   Length;           ///< Length of the FRAMEWORK_EFI_IFR_DATA_ENTRY packet
  72   UINT16  Flags;            ///< Flags settings to determine what behavior is desired from the browser after the callback
  73   VOID    *Data;            ///< The data in the form based on the op-code type - this is not a pointer to the data, the data follows immediately
  74   ///
  75   /// If the OpCode is a OneOf or Numeric type - Data is a UINT16 value
  76   /// If the OpCode is a String type - Data is a CHAR16[x] type
  77   /// If the OpCode is a Checkbox type - Data is a UINT8 value
  78   /// If the OpCode is a NV Access type - Data is a FRAMEWORK_EFI_IFR_NV_DATA structure
  79   ///
  80 } FRAMEWORK_EFI_IFR_DATA_ENTRY;
  81
  82 typedef struct {
  83   VOID                *NvRamMap;  ///< If the flag of the op-code specified retrieval of a copy of the NVRAM map,
  84   //
  85   // this is a pointer to a buffer copy
  86   //
  87   UINT32              EntryCount; ///< How many FRAMEWORK_EFI_IFR_DATA_ENTRY entries
  88   //
  89   // FRAMEWORK_EFI_IFR_DATA_ENTRY  Data[1];    // The in-line Data entries.
  90   //
  91 } FRAMEWORK_EFI_IFR_DATA_ARRAY;
  92
  93
  94 typedef union {
  95   FRAMEWORK_EFI_IFR_DATA_ARRAY  DataArray;  ///< Primarily used by those who call back to their drivers and use HII as a repository
  96   FRAMEWORK_EFI_IFR_PACKET      DataPacket; ///< Primarily used by those which do not use HII as a repository
  97   CHAR16                        String[1];  ///< If returning an error - fill the string with null-terminated contents
  98 } EFI_HII_CALLBACK_PACKET;
  99
 100 typedef struct {
 101   FRAMEWORK_EFI_IFR_OP_HEADER Header;
 102   UINT16            QuestionId;   ///< Offset into the map
 103   UINT8             StorageWidth; ///< Width of the value
 104   //
 105   // CHAR8             Data[1];      // The Data itself
 106   //
 107 } FRAMEWORK_EFI_IFR_NV_DATA;
 108
 109 #pragma pack()
 110 //
 111 // The following types are currently defined:
 112 //
 113 /**
 114   Returns the value of a variable.
 115
 116   @param  This                  A pointer to the EFI_FORM_CALLBACK_PROTOCOL instance.
 117   @param  VariableName          A NULL-terminated Unicode string that is the
 118                                 name of the vendor's variable.
 119   @param  VendorGuid            A unique identifier for the vendor.
 120   @param  Attributes            If not NULL, a pointer to the memory location to
 121                                 return the attribute's bit-mask for the variable.
 122   @param  DataSize              The size in bytes of the Buffer. A size of zero causes
 123                                 the variable to be deleted.
 124   @param  Buffer                The buffer to return the contents of the variable.
 125
 126   @retval EFI_SUCCESS           The function completed successfully.
 127   @retval EFI_NOT_FOUND         The variable was not found.
 128   @retval EFI_BUFFER_TOO_SMALL  The DataSize is too small for the result.
 129                                 DataSize has been updated with the size needed to complete the request.
 130   @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
 131   @retval EFI_DEVICE_ERROR      The variable could not be saved due to a hardware failure.
 132
 133 **/
 134 typedef
 135 EFI_STATUS
 136 (EFIAPI *EFI_NV_READ)(
 137   IN     EFI_FORM_CALLBACK_PROTOCOL    *This,
 138   IN     CHAR16                        *VariableName,
 139   IN     EFI_GUID                      *VendorGuid,
 140   OUT    UINT32                        *Attributes OPTIONAL,
 141   IN OUT UINTN                         *DataSize,
 142   OUT    VOID                          *Buffer
 143   );
 144
 145 /**
 146   Sets the value of a variable.
 147
 148   @param  This                  A pointer to the EFI_FORM_CALLBACK_PROTOCOL instance.
 149   @param  VariableName          A NULL-terminated Unicode string that is the
 150                                 name of the vendor's variable. Each VariableName is unique for each VendorGuid.
 151   @param  VendorGuid            A unique identifier for the vendor.
 152   @param  Attributes            Attributes bit-mask to set for the variable.
 153                                 Inconsistent with specification here:
 154                                 Attributes data type has been changed from UINT32 * to UINT32,
 155                                 because the input paramter is not necessary to use pointer date type.
 156   @param  DataSize              The size in bytes of the Buffer. A size of zero causes
 157                                 the variable to be deleted.
 158   @param  Buffer                The buffer containing the contents of the variable.
 159   @param  ResetRequired         Returns a value from the driver that abstracts
 160                                 this information and will enable a system to know if a system reset
 161                                 is required to achieve the configuration changes being enabled through
 162                                 this function.
 163
 164   @retval EFI_SUCCESS           The firmware has successfully stored the variable and
 165                                 its data as defined by the Attributes.
 166   @retval EFI_OUT_OF_RESOURCES  Not enough storage is available to hold
 167                                 the variable and its data.
 168   @retval EFI_INVALID_PARAMETER An invalid combination of Attributes bits
 169                                 was supplied, or the DataSize exceeds the maximum allowed.
 170   @retval EFI_DEVICE_ERROR      The variable could not be saved due to a hardware failure.
 171
 172 **/
 173 typedef
 174 EFI_STATUS
 175 (EFIAPI *EFI_NV_WRITE)(
 176   IN     EFI_FORM_CALLBACK_PROTOCOL    *This,
 177   IN     CHAR16                        *VariableName,
 178   IN     EFI_GUID                      *VendorGuid,
 179   IN     UINT32                        Attributes,
 180   IN     UINTN                         DataSize,
 181   IN     VOID                          *Buffer,
 182   OUT    BOOLEAN                       *ResetRequired
 183   );
 184
 185 /**
 186   This function is called to provide results data to the driver.
 187
 188   @param  This                  A pointer to the EFI_FORM_CALLBACK_PROTOCOL instance.
 189   @param  KeyValue              A unique value which is sent to the original exporting
 190                                 driver so that it can identify the type of data to expect. The format of
 191                                 the data tends to vary based on the opcode that generated the callback.
 192   @param  Data                  A pointer to the data being sent to the original exporting driver.
 193   @param  Packet                A pointer to a packet of information which a driver passes
 194                                 back to the browser.
 195
 196   @return Status Code
 197
 198 **/
 199 typedef
 200 EFI_STATUS
 201 (EFIAPI *EFI_FORM_CALLBACK)(
 202   IN     EFI_FORM_CALLBACK_PROTOCOL    *This,
 203   IN     UINT16                        KeyValue,
 204   IN     FRAMEWORK_EFI_IFR_DATA_ARRAY  *Data,
 205   OUT    EFI_HII_CALLBACK_PACKET       **Packet
 206   );
 207
 208 /**
 209   The EFI_FORM_CALLBACK_PROTOCOL is the defined interface for access to
 210   custom NVS devices as well as communication of user selections in a more
 211   interactive environment. This protocol should be published by platform-specific
 212   drivers that want to export access to custom hardware storage or publish IFR
 213   that has a requirement to call back the original driver.
 214 **/
 215 struct _EFI_FORM_CALLBACK_PROTOCOL {
 216   EFI_NV_READ       NvRead;     ///< The read operation to access the NV data serviced by a hardware-specific driver.
 217   EFI_NV_WRITE      NvWrite;    ///< The write operation to access the NV data serviced by a hardware-specific driver.
 218   EFI_FORM_CALLBACK Callback;   ///< The function that is called from the configuration browser to communicate key value pairs.
 219 };
 220
 221 extern EFI_GUID gEfiFormCallbackProtocolGuid;
 222
 223 #endif