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