MdePkg/Include/Protocol/HiiConfigRouting.h

   1 /** @file
   2   The file provides services to manage the movement of
   3   configuration data from drivers to configuration applications.
   4   It then serves as the single point to receive configuration
   5   information from configuration applications, routing the
   6   results to the appropriate drivers.
   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 was introduced in UEFI Specification 2.1.
  13
  14
  15 **/
  16
  17 #ifndef __HII_CONFIG_ROUTING_H__
  18 #define __HII_CONFIG_ROUTING_H__
  19
  20 #define EFI_HII_CONFIG_ROUTING_PROTOCOL_GUID \
  21   { 0x587e72d7, 0xcc50, 0x4f79, { 0x82, 0x09, 0xca, 0x29, 0x1f, 0xc1, 0xa1, 0x0f } }
  22
  23 typedef struct _EFI_HII_CONFIG_ROUTING_PROTOCOL EFI_HII_CONFIG_ROUTING_PROTOCOL;
  24
  25 /**
  26
  27   This function allows the caller to request the current
  28   configuration for one or more named elements from one or more
  29   drivers. The resulting string is in the standard HII
  30   configuration string format. If Successful, Results contains an
  31   equivalent string with "=" and the values associated with all
  32   names added in. The expected implementation is for each
  33   <ConfigRequest> substring in the Request to call the HII
  34   Configuration Routing Protocol ExtractProtocol function for the
  35   driver corresponding to the <ConfigHdr> at the start of the
  36   <ConfigRequest> substring. The request fails if no driver
  37   matches the <ConfigRequest> substring. Note: Alternative
  38   configuration strings may also be appended to the end of the
  39   current configuration string. If they are, they must appear
  40   after the current configuration. They must contain the same
  41   routing (GUID, NAME, PATH) as the current configuration string.
  42   They must have an additional description indicating the type of
  43   alternative configuration the string represents,
  44   "ALTCFG=<StringToken>". That <StringToken> (when converted from
  45   hexadecimal (encoded as text) to binary) is a reference to a string in the
  46   associated string pack. As an example, assume that the Request
  47   string is:
  48   GUID=...&NAME=00480050&PATH=...&Fred&George&Ron&Neville A result
  49   might be:
  50   GUID=...&NAME=00480050&PATH=...&Fred=16&George=16&Ron=12&Neville=11&
  51   GUID=...&NAME=00480050&PATH=...&ALTCFG=0037&Fred=12&Neville=7
  52
  53   @param This       Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL
  54                     instance.
  55
  56   @param Request    A null-terminated string in <MultiConfigRequest> format.
  57
  58   @param Progress   On return, points to a character in the
  59                     Request string. Points to the string's null
  60                     terminator if the request was successful. Points
  61                     to the most recent '&' before the first
  62                     failing name / value pair (or the beginning
  63                     of the string if the failure is in the first
  64                     name / value pair) if the request was not
  65                     successful
  66
  67   @param Results    A null-terminated string in <MultiConfigAltResp> format
  68                     which has all values filled in for the names in the
  69                     Request string.
  70
  71   @retval EFI_SUCCESS             The Results string is filled with the
  72                                   values corresponding to all requested
  73                                   names.
  74
  75   @retval EFI_OUT_OF_RESOURCES    Not enough memory to store the
  76                                   parts of the results that must be
  77                                   stored awaiting possible future
  78                                   protocols.
  79
  80   @retval EFI_INVALID_PARAMETER   For example, passing in a NULL
  81                                   for the Request parameter
  82                                   would result in this type of
  83                                   error. The Progress parameter
  84                                   is set to NULL.
  85
  86   @retval EFI_NOT_FOUND           Routing data doesn't match any
  87                                   known driver. Progress set to
  88                                   the "G" in "GUID" of the
  89                                   routing header that doesn't
  90                                   match. Note: There is no
  91                                   requirement that all routing
  92                                   data be validated before any
  93                                   configuration extraction.
  94
  95   @retval EFI_INVALID_PARAMETER   Illegal syntax. Progress set
  96                                   to the most recent & before the
  97                                   error, or the beginning of the
  98                                   string.
  99   @retval EFI_INVALID_PARAMETER   The ExtractConfig function of the
 100                                   underlying HII Configuration
 101                                   Access Protocol returned
 102                                   EFI_INVALID_PARAMETER. Progress
 103                                   set to most recent & before the
 104                                   error or the beginning of the
 105                                   string.
 106
 107 **/
 108 typedef
 109 EFI_STATUS
 110 (EFIAPI *EFI_HII_EXTRACT_CONFIG)(
 111   IN CONST  EFI_HII_CONFIG_ROUTING_PROTOCOL *This,
 112   IN CONST  EFI_STRING                      Request,
 113   OUT       EFI_STRING                      *Progress,
 114   OUT       EFI_STRING                      *Results
 115   );
 116
 117 /**
 118   This function allows the caller to request the current configuration
 119   for the entirety of the current HII database and returns the data in
 120   a null-terminated string.
 121
 122   This function allows the caller to request the current
 123   configuration for all of the current HII database. The results
 124   include both the current and alternate configurations as
 125   described in ExtractConfig() above.
 126
 127   @param This     Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance.
 128
 129   @param  Results Null-terminated Unicode string in
 130                   <MultiConfigAltResp> format which has all values
 131                   filled in for the entirety of the current HII
 132                   database. String to be allocated by the  called
 133                   function. De-allocation is up to the caller.
 134
 135   @retval EFI_SUCCESS             The Results string is filled with the
 136                                   values corresponding to all requested
 137                                   names.
 138
 139   @retval EFI_OUT_OF_RESOURCES    Not enough memory to store the
 140                                   parts of the results that must be
 141                                   stored awaiting possible future
 142                                   protocols.
 143
 144   @retval EFI_INVALID_PARAMETERS  For example, passing in a NULL
 145                                   for the Results parameter
 146                                   would result in this type of
 147                                   error.
 148
 149 **/
 150 typedef
 151 EFI_STATUS
 152 (EFIAPI *EFI_HII_EXPORT_CONFIG)(
 153   IN CONST  EFI_HII_CONFIG_ROUTING_PROTOCOL *This,
 154   OUT       EFI_STRING                      *Results
 155   );
 156
 157 /**
 158
 159   This function routes the results of processing forms to the
 160   appropriate targets. It scans for <ConfigHdr> within the string
 161   and passes the header and subsequent body to the driver whose
 162   location is described in the <ConfigHdr>. Many <ConfigHdr>s may
 163   appear as a single request. The expected implementation is to
 164   hand off the various <ConfigResp> substrings to the
 165   Configuration Access Protocol RouteConfig routine corresponding
 166   to the driver whose routing information is defined by the
 167   <ConfigHdr> in turn.
 168
 169   @param This           Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance.
 170
 171   @param Configuration  A null-terminated string in <MulltiConfigResp> format.
 172
 173   @param Progress       A pointer to a string filled in with the
 174                         offset of the most recent '&' before the
 175                         first failing name / value pair (or the
 176                         beginning of the string if the failure is in
 177                         the first name / value pair), or the
 178                         terminating NULL if all was successful.
 179
 180   @retval EFI_SUCCESS             The results have been distributed or are
 181                                   awaiting distribution.
 182
 183   @retval EFI_OUT_OF_RESOURCES    Not enough memory to store the
 184                                   parts of the results that must be
 185                                   stored awaiting possible future
 186                                   protocols.
 187
 188   @retval EFI_INVALID_PARAMETERS  Passing in a NULL for the
 189                                   Results parameter would result
 190                                   in this type of error.
 191
 192   @retval EFI_NOT_FOUND           The target for the specified routing data
 193                                   was not found.
 194
 195 **/
 196 typedef
 197 EFI_STATUS
 198 (EFIAPI *EFI_HII_ROUTE_CONFIG)(
 199   IN CONST  EFI_HII_CONFIG_ROUTING_PROTOCOL *This,
 200   IN CONST  EFI_STRING                      Configuration,
 201   OUT       EFI_STRING                      *Progress
 202   );
 203
 204 /**
 205
 206   This function extracts the current configuration from a block of
 207   bytes. To do so, it requires that the ConfigRequest string
 208   consists of a list of <BlockName> formatted names. It uses the
 209   offset in the name to determine the index into the Block to
 210   start the extraction and the width of each name to determine the
 211   number of bytes to extract. These are mapped to a string
 212   using the equivalent of the C "%x" format (with optional leading
 213   spaces). The call fails if, for any (offset, width) pair in
 214   ConfigRequest, offset+value >= BlockSize.
 215
 216   @param This      Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance.
 217
 218   @param ConfigRequest  A null-terminated string in <ConfigRequest> format.
 219
 220   @param Block      An array of bytes defining the block's
 221                     configuration.
 222
 223   @param BlockSize  The length in bytes of Block.
 224
 225   @param Config     The filled-in configuration string. String
 226                     allocated by the function. Returned only if
 227                     call is successful. The null-terminated string
 228                     will be <ConfigResp> format.
 229
 230   @param Progress   A pointer to a string filled in with the
 231                     offset of the most recent '&' before the
 232                     first failing name / value pair (or the
 233                     beginning of the string if the failure is in
 234                     the first name / value pair), or the
 235                     terminating NULL if all was successful.
 236
 237   @retval EFI_SUCCESS             The request succeeded. Progress points
 238                                   to the null terminator at the end of the
 239                                   ConfigRequest string.
 240
 241   @retval EFI_OUT_OF_RESOURCES    Not enough memory to allocate
 242                                   Config. Progress points to the
 243                                   first character of ConfigRequest.
 244
 245   @retval EFI_INVALID_PARAMETERS  Passing in a NULL for the
 246                                   ConfigRequest or Block
 247                                   parameter would result in this
 248                                   type of error. Progress points
 249                                   to the first character of
 250                                   ConfigRequest.
 251
 252   @retval EFI_NOT_FOUND           The target for the specified routing data
 253                                   was not found. Progress points to the
 254                                   'G' in "GUID" of the errant routing
 255                                   data.
 256   @retval EFI_DEVICE_ERROR        The block is not large enough. Progress undefined.
 257
 258   @retval EFI_INVALID_PARAMETER   Encountered non <BlockName>
 259                                   formatted string. Block is
 260                                   left updated and Progress
 261                                   points at the '&' preceding
 262                                   the first non-<BlockName>.
 263
 264 **/
 265 typedef
 266 EFI_STATUS
 267 (EFIAPI *EFI_HII_BLOCK_TO_CONFIG)(
 268   IN CONST  EFI_HII_CONFIG_ROUTING_PROTOCOL *This,
 269   IN CONST  EFI_STRING                      ConfigRequest,
 270   IN CONST  UINT8                           *Block,
 271   IN CONST  UINTN                           BlockSize,
 272   OUT       EFI_STRING                      *Config,
 273   OUT       EFI_STRING                      *Progress
 274   );
 275
 276 /**
 277   This function maps a configuration containing a series of
 278   <BlockConfig> formatted name value pairs in ConfigResp into a
 279   Block so it may be stored in a linear mapped storage such as a
 280   UEFI Variable. If present, the function skips GUID, NAME, and
 281   PATH in <ConfigResp>. It stops when it finds a non-<BlockConfig>
 282   name / value pair (after skipping the routing header) or when it
 283   reaches the end of the string.
 284   Example Assume an existing block containing: 00 01 02 03 04 05
 285   And the ConfigResp string is:
 286   OFFSET=4&WIDTH=1&VALUE=7&OFFSET=0&WIDTH=2&VALUE=AA55
 287   The results are
 288   55 AA 02 07 04 05
 289
 290   @param This           Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance.
 291
 292   @param ConfigResp     A null-terminated string in <ConfigResp> format.
 293
 294   @param Block          A possibly null array of bytes
 295                         representing the current block. Only
 296                         bytes referenced in the ConfigResp
 297                         string in the block are modified. If
 298                         this parameter is null or if the
 299                         BlockLength parameter is (on input)
 300                         shorter than required by the
 301                         Configuration string, only the BlockSize
 302                         parameter is updated, and an appropriate
 303                         status (see below) is returned.
 304
 305   @param BlockSize      The length of the Block in units of UINT8.
 306                         On input, this is the size of the Block. On
 307                         output, if successful, contains the largest
 308                         index of the modified byte in the Block, or
 309                         the required buffer size if the Block is not
 310                         large enough.
 311
 312   @param Progress       On return, points to an element of the
 313                         ConfigResp string filled in with the offset
 314                         of the most recent "&" before the first
 315                         failing name / value pair (or the beginning
 316                         of the string if the failure is in the first
 317                         name / value pair), or the terminating NULL
 318                         if all was successful.
 319
 320   @retval EFI_SUCCESS            The request succeeded. Progress points to the null
 321                                  terminator at the end of the ConfigResp string.
 322   @retval EFI_OUT_OF_RESOURCES   Not enough memory to allocate Config. Progress
 323                                  points to the first character of ConfigResp.
 324   @retval EFI_INVALID_PARAMETER  Passing in a NULL for the ConfigResp or
 325                                  Block parameter would result in this type of
 326                                  error. Progress points to the first character of
 327                                          ConfigResp.
 328   @retval EFI_INVALID_PARAMETER  Encountered non <BlockName> formatted name /
 329                                  value pair. Block is left updated and
 330                                  Progress points at the '&' preceding the first
 331                                  non-<BlockName>.
 332   @retval EFI_DEVICE_ERROR       Block not large enough. Progress undefined.
 333   @retval EFI_NOT_FOUND          Target for the specified routing data was not found.
 334                                  Progress points to the "G" in "GUID" of the errant
 335                                  routing data.
 336   @retval EFI_BUFFER_TOO_SMALL   Block not large enough. Progress undefined.
 337                                  BlockSize is updated with the required buffer size.
 338
 339 **/
 340 typedef
 341 EFI_STATUS
 342 (EFIAPI *EFI_HII_CONFIG_TO_BLOCK)(
 343   IN CONST  EFI_HII_CONFIG_ROUTING_PROTOCOL *This,
 344   IN CONST  EFI_STRING                      ConfigResp,
 345   IN OUT    UINT8                           *Block,
 346   IN OUT    UINTN                           *BlockSize,
 347   OUT       EFI_STRING                      *Progress
 348   );
 349
 350 /**
 351   This helper function is to be called by drivers to extract portions of
 352   a larger configuration string.
 353
 354   @param This              A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance.
 355   @param ConfigResp        A null-terminated string in <ConfigAltResp> format.
 356   @param Guid              A pointer to the GUID value to search for in the
 357                            routing portion of the ConfigResp string when retrieving
 358                            the requested data. If Guid is NULL, then all GUID
 359                            values will be searched for.
 360   @param Name              A pointer to the NAME value to search for in the
 361                            routing portion of the ConfigResp string when retrieving
 362                            the requested data. If Name is NULL, then all Name
 363                            values will be searched for.
 364   @param DevicePath        A pointer to the PATH value to search for in the
 365                            routing portion of the ConfigResp string when retrieving
 366                            the requested data. If DevicePath is NULL, then all
 367                            DevicePath values will be searched for.
 368   @param AltCfgId          A pointer to the ALTCFG value to search for in the
 369                            routing portion of the ConfigResp string when retrieving
 370                            the requested data.  If this parameter is NULL,
 371                            then the current setting will be retrieved.
 372   @param AltCfgResp        A pointer to a buffer which will be allocated by the
 373                            function which contains the retrieved string as requested.
 374                            This buffer is only allocated if the call was successful.
 375                            The null-terminated string will be <ConfigResp> format.
 376
 377   @retval EFI_SUCCESS             The request succeeded. The requested data was extracted
 378                                   and placed in the newly allocated AltCfgResp buffer.
 379   @retval EFI_OUT_OF_RESOURCES    Not enough memory to allocate AltCfgResp.
 380   @retval EFI_INVALID_PARAMETER   Any parameter is invalid.
 381   @retval EFI_NOT_FOUND           The target for the specified routing data was not found.
 382 **/
 383 typedef
 384 EFI_STATUS
 385 (EFIAPI *EFI_HII_GET_ALT_CFG)(
 386   IN  CONST EFI_HII_CONFIG_ROUTING_PROTOCOL    *This,
 387   IN  CONST EFI_STRING                         ConfigResp,
 388   IN  CONST EFI_GUID                           *Guid,
 389   IN  CONST EFI_STRING                         Name,
 390   IN  CONST EFI_DEVICE_PATH_PROTOCOL           *DevicePath,
 391   IN  CONST UINT16                             *AltCfgId,
 392   OUT EFI_STRING                               *AltCfgResp
 393   );
 394
 395 ///
 396 /// This protocol defines the configuration routing interfaces
 397 /// between external applications and the HII. There may only be one
 398 /// instance of this protocol in the system.
 399 ///
 400 struct _EFI_HII_CONFIG_ROUTING_PROTOCOL {
 401   EFI_HII_EXTRACT_CONFIG     ExtractConfig;
 402   EFI_HII_EXPORT_CONFIG      ExportConfig;
 403   EFI_HII_ROUTE_CONFIG       RouteConfig;
 404   EFI_HII_BLOCK_TO_CONFIG    BlockToConfig;
 405   EFI_HII_CONFIG_TO_BLOCK    ConfigToBlock;
 406   EFI_HII_GET_ALT_CFG        GetAltConfig;
 407 };
 408
 409 extern EFI_GUID  gEfiHiiConfigRoutingProtocolGuid;
 410
 411 #endif