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