9344f09215
https://bugzilla.tianocore.org/show_bug.cgi?id=1373 Replace BSD 2-Clause License with BSD+Patent License. This change is based on the following emails: https://lists.01.org/pipermail/edk2-devel/2019-February/036260.html https://lists.01.org/pipermail/edk2-devel/2018-October/030385.html RFCs with detailed process for the license change: V3: https://lists.01.org/pipermail/edk2-devel/2019-March/038116.html V2: https://lists.01.org/pipermail/edk2-devel/2019-March/037669.html V1: https://lists.01.org/pipermail/edk2-devel/2019-March/037500.html Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Michael D Kinney <michael.d.kinney@intel.com> Reviewed-by: Liming Gao <liming.gao@intel.com>
418 lines
19 KiB
C
418 lines
19 KiB
C
/** @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>
|
|
SPDX-License-Identifier: BSD-2-Clause-Patent
|
|
|
|
@par Revision Reference:
|
|
This Protocol was introduced in UEFI Specification 2.1.
|
|
|
|
|
|
**/
|
|
|
|
#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
|
|
|