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