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