/** @file | |
The file provides services to manage the movement of | |
configuration data from drivers to configuration applications. | |
It then serves as the single point to receive configuration | |
information from configuration applications, routing the | |
results to the appropriate drivers. | |
Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> | |
This program and the accompanying materials are licensed and made available under | |
the terms and conditions of the BSD License that accompanies this distribution. | |
The full text of the license may be found at | |
http://opensource.org/licenses/bsd-license.php. | |
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, | |
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. | |
**/ | |
#ifndef __HII_CONFIG_ROUTING_H__ | |
#define __HII_CONFIG_ROUTING_H__ | |
#define EFI_HII_CONFIG_ROUTING_PROTOCOL_GUID \ | |
{ 0x587e72d7, 0xcc50, 0x4f79, { 0x82, 0x09, 0xca, 0x29, 0x1f, 0xc1, 0xa1, 0x0f } } | |
typedef struct _EFI_HII_CONFIG_ROUTING_PROTOCOL EFI_HII_CONFIG_ROUTING_PROTOCOL; | |
/** | |
This function allows the caller to request the current | |
configuration for one or more named elements from one or more | |
drivers. The resulting string is in the standard HII | |
configuration string format. If Successful, Results contains an | |
equivalent string with "=" and the values associated with all | |
names added in. The expected implementation is for each | |
<ConfigRequest> substring in the Request to call the HII | |
Configuration Routing Protocol ExtractProtocol function for the | |
driver corresponding to the <ConfigHdr> at the start of the | |
<ConfigRequest> substring. The request fails if no driver | |
matches the <ConfigRequest> substring. Note: Alternative | |
configuration strings may also be appended to the end of the | |
current configuration string. If they are, they must appear | |
after the current configuration. They must contain the same | |
routing (GUID, NAME, PATH) as the current configuration string. | |
They must have an additional description indicating the type of | |
alternative configuration the string represents, | |
"ALTCFG=<StringToken>". That <StringToken> (when converted from | |
hexadecimal (encoded as text) to binary) is a reference to a string in the | |
associated string pack. As an example, assume that the Request | |
string is: | |
GUID=...&NAME=00480050&PATH=...&Fred&George&Ron&Neville A result | |
might be: | |
GUID=...&NAME=00480050&PATH=...&Fred=16&George=16&Ron=12&Neville=11& | |
GUID=...&NAME=00480050&PATH=...&ALTCFG=0037&Fred=12&Neville=7 | |
@param This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL | |
instance. | |
@param Request A null-terminated string in <MultiConfigRequest> format. | |
@param Progress On return, points to a character in the | |
Request string. Points to the string's null | |
terminator if the request was successful. Points | |
to the most recent '&' before the first | |
failing name / value pair (or the beginning | |
of the string if the failure is in the first | |
name / value pair) if the request was not | |
successful | |
@param Results A null-terminated string in <MultiConfigAltResp> format | |
which has all values filled in for the names in the | |
Request string. | |
@retval EFI_SUCCESS The Results string is filled with the | |
values corresponding to all requested | |
names. | |
@retval EFI_OUT_OF_RESOURCES Not enough memory to store the | |
parts of the results that must be | |
stored awaiting possible future | |
protocols. | |
@retval EFI_INVALID_PARAMETER For example, passing in a NULL | |
for the Request parameter | |
would result in this type of | |
error. The Progress parameter | |
is set to NULL. | |
@retval EFI_NOT_FOUND Routing data doesn't match any | |
known driver. Progress set to | |
the "G" in "GUID" of the | |
routing header that doesn't | |
match. Note: There is no | |
requirement that all routing | |
data be validated before any | |
configuration extraction. | |
@retval EFI_INVALID_PARAMETER Illegal syntax. Progress set | |
to the most recent & before the | |
error, or the beginning of the | |
string. | |
@retval EFI_INVALID_PARAMETER The ExtractConfig function of the | |
underlying HII Configuration | |
Access Protocol returned | |
EFI_INVALID_PARAMETER. Progress | |
set to most recent & before the | |
error or the beginning of the | |
string. | |
**/ | |
typedef | |
EFI_STATUS | |
(EFIAPI * EFI_HII_EXTRACT_CONFIG)( | |
IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This, | |
IN CONST EFI_STRING Request, | |
OUT EFI_STRING *Progress, | |
OUT EFI_STRING *Results | |
); | |
/** | |
This function allows the caller to request the current configuration | |
for the entirety of the current HII database and returns the data in | |
a null-terminated string. | |
This function allows the caller to request the current | |
configuration for all of the current HII database. The results | |
include both the current and alternate configurations as | |
described in ExtractConfig() above. | |
@param This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance. | |
@param Results Null-terminated Unicode string in | |
<MultiConfigAltResp> format which has all values | |
filled in for the entirety of the current HII | |
database. String to be allocated by the called | |
function. De-allocation is up to the caller. | |
@retval EFI_SUCCESS The Results string is filled with the | |
values corresponding to all requested | |
names. | |
@retval EFI_OUT_OF_RESOURCES Not enough memory to store the | |
parts of the results that must be | |
stored awaiting possible future | |
protocols. | |
@retval EFI_INVALID_PARAMETERS For example, passing in a NULL | |
for the Results parameter | |
would result in this type of | |
error. | |
**/ | |
typedef | |
EFI_STATUS | |
(EFIAPI * EFI_HII_EXPORT_CONFIG)( | |
IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This, | |
OUT EFI_STRING *Results | |
); | |
/** | |
This function routes the results of processing forms to the | |
appropriate targets. It scans for <ConfigHdr> within the string | |
and passes the header and subsequent body to the driver whose | |
location is described in the <ConfigHdr>. Many <ConfigHdr>s may | |
appear as a single request. The expected implementation is to | |
hand off the various <ConfigResp> substrings to the | |
Configuration Access Protocol RouteConfig routine corresponding | |
to the driver whose routing information is defined by the | |
<ConfigHdr> in turn. | |
@param This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance. | |
@param Configuration A null-terminated string in <MulltiConfigResp> format. | |
@param Progress A pointer to a string filled in with the | |
offset of the most recent '&' before the | |
first failing name / value pair (or the | |
beginning of the string if the failure is in | |
the first name / value pair), or the | |
terminating NULL if all was successful. | |
@retval EFI_SUCCESS The results have been distributed or are | |
awaiting distribution. | |
@retval EFI_OUT_OF_RESOURCES Not enough memory to store the | |
parts of the results that must be | |
stored awaiting possible future | |
protocols. | |
@retval EFI_INVALID_PARAMETERS Passing in a NULL for the | |
Results parameter would result | |
in this type of error. | |
@retval EFI_NOT_FOUND The target for the specified routing data | |
was not found. | |
**/ | |
typedef | |
EFI_STATUS | |
(EFIAPI * EFI_HII_ROUTE_CONFIG)( | |
IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This, | |
IN CONST EFI_STRING Configuration, | |
OUT EFI_STRING *Progress | |
); | |
/** | |
This function extracts the current configuration from a block of | |
bytes. To do so, it requires that the ConfigRequest string | |
consists of a list of <BlockName> formatted names. It uses the | |
offset in the name to determine the index into the Block to | |
start the extraction and the width of each name to determine the | |
number of bytes to extract. These are mapped to a string | |
using the equivalent of the C "%x" format (with optional leading | |
spaces). The call fails if, for any (offset, width) pair in | |
ConfigRequest, offset+value >= BlockSize. | |
@param This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance. | |
@param ConfigRequest A null-terminated string in <ConfigRequest> format. | |
@param Block An array of bytes defining the block's | |
configuration. | |
@param BlockSize The length in bytes of Block. | |
@param Config The filled-in configuration string. String | |
allocated by the function. Returned only if | |
call is successful. The null-terminated string | |
will be <ConfigResp> format. | |
@param Progress A pointer to a string filled in with the | |
offset of the most recent '&' before the | |
first failing name / value pair (or the | |
beginning of the string if the failure is in | |
the first name / value pair), or the | |
terminating NULL if all was successful. | |
@retval EFI_SUCCESS The request succeeded. Progress points | |
to the null terminator at the end of the | |
ConfigRequest string. | |
@retval EFI_OUT_OF_RESOURCES Not enough memory to allocate | |
Config. Progress points to the | |
first character of ConfigRequest. | |
@retval EFI_INVALID_PARAMETERS Passing in a NULL for the | |
ConfigRequest or Block | |
parameter would result in this | |
type of error. Progress points | |
to the first character of | |
ConfigRequest. | |
@retval EFI_NOT_FOUND The target for the specified routing data | |
was not found. Progress points to the | |
'G' in "GUID" of the errant routing | |
data. | |
@retval EFI_DEVICE_ERROR The block is not large enough. Progress undefined. | |
@retval EFI_INVALID_PARAMETER Encountered non <BlockName> | |
formatted string. Block is | |
left updated and Progress | |
points at the '&' preceding | |
the first non-<BlockName>. | |
**/ | |
typedef | |
EFI_STATUS | |
(EFIAPI * EFI_HII_BLOCK_TO_CONFIG)( | |
IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This, | |
IN CONST EFI_STRING ConfigRequest, | |
IN CONST UINT8 *Block, | |
IN CONST UINTN BlockSize, | |
OUT EFI_STRING *Config, | |
OUT EFI_STRING *Progress | |
); | |
/** | |
This function maps a configuration containing a series of | |
<BlockConfig> formatted name value pairs in ConfigResp into a | |
Block so it may be stored in a linear mapped storage such as a | |
UEFI Variable. If present, the function skips GUID, NAME, and | |
PATH in <ConfigResp>. It stops when it finds a non-<BlockConfig> | |
name / value pair (after skipping the routing header) or when it | |
reaches the end of the string. | |
Example Assume an existing block containing: 00 01 02 03 04 05 | |
And the ConfigResp string is: | |
OFFSET=4&WIDTH=1&VALUE=7&OFFSET=0&WIDTH=2&VALUE=AA55 | |
The results are | |
55 AA 02 07 04 05 | |
@param This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance. | |
@param ConfigResp A null-terminated string in <ConfigResp> format. | |
@param Block A possibly null array of bytes | |
representing the current block. Only | |
bytes referenced in the ConfigResp | |
string in the block are modified. If | |
this parameter is null or if the | |
BlockLength parameter is (on input) | |
shorter than required by the | |
Configuration string, only the BlockSize | |
parameter is updated, and an appropriate | |
status (see below) is returned. | |
@param BlockSize The length of the Block in units of UINT8. | |
On input, this is the size of the Block. On | |
output, if successful, contains the largest | |
index of the modified byte in the Block, or | |
the required buffer size if the Block is not | |
large enough. | |
@param Progress On return, points to an element of the | |
ConfigResp string filled in with the offset | |
of the most recent "&" before the first | |
failing name / value pair (or the beginning | |
of the string if the failure is in the first | |
name / value pair), or the terminating NULL | |
if all was successful. | |
@retval EFI_SUCCESS The request succeeded. Progress points to the null | |
terminator at the end of the ConfigResp string. | |
@retval EFI_OUT_OF_RESOURCES Not enough memory to allocate Config. Progress | |
points to the first character of ConfigResp. | |
@retval EFI_INVALID_PARAMETER Passing in a NULL for the ConfigResp or | |
Block parameter would result in this type of | |
error. Progress points to the first character of | |
ConfigResp. | |
@retval EFI_INVALID_PARAMETER Encountered non <BlockName> formatted name / | |
value pair. Block is left updated and | |
Progress points at the '&' preceding the first | |
non-<BlockName>. | |
@retval EFI_DEVICE_ERROR Block not large enough. Progress undefined. | |
@retval EFI_NOT_FOUND Target for the specified routing data was not found. | |
Progress points to the "G" in "GUID" of the errant | |
routing data. | |
@retval EFI_BUFFER_TOO_SMALL Block not large enough. Progress undefined. | |
BlockSize is updated with the required buffer size. | |
**/ | |
typedef | |
EFI_STATUS | |
(EFIAPI * EFI_HII_CONFIG_TO_BLOCK)( | |
IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This, | |
IN CONST EFI_STRING ConfigResp, | |
IN OUT UINT8 *Block, | |
IN OUT UINTN *BlockSize, | |
OUT EFI_STRING *Progress | |
); | |
/** | |
This helper function is to be called by drivers to extract portions of | |
a larger configuration string. | |
@param This A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance. | |
@param ConfigResp A null-terminated string in <ConfigAltResp> format. | |
@param Guid A pointer to the GUID value to search for in the | |
routing portion of the ConfigResp string when retrieving | |
the requested data. If Guid is NULL, then all GUID | |
values will be searched for. | |
@param Name A pointer to the NAME value to search for in the | |
routing portion of the ConfigResp string when retrieving | |
the requested data. If Name is NULL, then all Name | |
values will be searched for. | |
@param DevicePath A pointer to the PATH value to search for in the | |
routing portion of the ConfigResp string when retrieving | |
the requested data. If DevicePath is NULL, then all | |
DevicePath values will be searched for. | |
@param AltCfgId A pointer to the ALTCFG value to search for in the | |
routing portion of the ConfigResp string when retrieving | |
the requested data. If this parameter is NULL, | |
then the current setting will be retrieved. | |
@param AltCfgResp A pointer to a buffer which will be allocated by the | |
function which contains the retrieved string as requested. | |
This buffer is only allocated if the call was successful. | |
The null-terminated string will be <ConfigResp> format. | |
@retval EFI_SUCCESS The request succeeded. The requested data was extracted | |
and placed in the newly allocated AltCfgResp buffer. | |
@retval EFI_OUT_OF_RESOURCES Not enough memory to allocate AltCfgResp. | |
@retval EFI_INVALID_PARAMETER Any parameter is invalid. | |
@retval EFI_NOT_FOUND The target for the specified routing data was not found. | |
**/ | |
typedef | |
EFI_STATUS | |
(EFIAPI * EFI_HII_GET_ALT_CFG)( | |
IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This, | |
IN CONST EFI_STRING ConfigResp, | |
IN CONST EFI_GUID *Guid, | |
IN CONST EFI_STRING Name, | |
IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, | |
IN CONST UINT16 *AltCfgId, | |
OUT EFI_STRING *AltCfgResp | |
); | |
/// | |
/// This protocol defines the configuration routing interfaces | |
/// between external applications and the HII. There may only be one | |
/// instance of this protocol in the system. | |
/// | |
struct _EFI_HII_CONFIG_ROUTING_PROTOCOL { | |
EFI_HII_EXTRACT_CONFIG ExtractConfig; | |
EFI_HII_EXPORT_CONFIG ExportConfig; | |
EFI_HII_ROUTE_CONFIG RouteConfig; | |
EFI_HII_BLOCK_TO_CONFIG BlockToConfig; | |
EFI_HII_CONFIG_TO_BLOCK ConfigToBlock; | |
EFI_HII_GET_ALT_CFG GetAltConfig; | |
}; | |
extern EFI_GUID gEfiHiiConfigRoutingProtocolGuid; | |
#endif | |