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 412