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