1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
|
/** @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
|
