xref: /illumos-gate/usr/src/boot/efi/include/Protocol/HiiConfigKeyword.h (revision f334afcfaebea1b7dc3430015651d8d748fa8a3e)
1 /** @file
2   The file provides the mechanism to set and get the values
3   associated with a keyword exposed through a x-UEFI- prefixed
4   configuration language namespace.
5 
6 Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR>
7 SPDX-License-Identifier: BSD-2-Clause-Patent
8 
9   @par Revision Reference:
10   This Protocol was introduced in UEFI Specification 2.5.
11 
12 
13 **/
14 
15 #ifndef __EFI_CONFIG_KEYWORD_HANDLER_H__
16 #define __EFI_CONFIG_KEYWORD_HANDLER_H__
17 
18 #define EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL_GUID \
19 { \
20   0x0a8badd5, 0x03b8, 0x4d19, {0xb1, 0x28, 0x7b, 0x8f, 0x0e, 0xda, 0xa5, 0x96 } \
21 }
22 
23 // ***********************************************************
24 // Progress Errors
25 // ***********************************************************
26 #define KEYWORD_HANDLER_NO_ERROR                     0x00000000
27 #define KEYWORD_HANDLER_NAMESPACE_ID_NOT_FOUND       0x00000001
28 #define KEYWORD_HANDLER_MALFORMED_STRING             0x00000002
29 #define KEYWORD_HANDLER_KEYWORD_NOT_FOUND            0x00000004
30 #define KEYWORD_HANDLER_INCOMPATIBLE_VALUE_DETECTED  0x00000008
31 #define KEYWORD_HANDLER_ACCESS_NOT_PERMITTED         0x00000010
32 #define KEYWORD_HANDLER_UNDEFINED_PROCESSING_ERROR   0x80000000
33 
34 typedef struct _EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL;
35 
36 /**
37 
38   This function accepts a <MultiKeywordResp> formatted string, finds the associated
39   keyword owners, creates a <MultiConfigResp> string from it and forwards it to the
40   EFI_HII_ROUTING_PROTOCOL.RouteConfig function.
41 
42   If there is an issue in resolving the contents of the KeywordString, then the
43   function returns an error and also sets the Progress and ProgressErr with the
44   appropriate information about where the issue occurred and additional data about
45   the nature of the issue.
46 
47   In the case when KeywordString containing multiple keywords, when an EFI_NOT_FOUND
48   error is generated during processing the second or later keyword element, the system
49   storage associated with earlier keywords is not modified. All elements of the
50   KeywordString must successfully pass all tests for format and access prior to making
51   any modifications to storage.
52 
53   In the case when EFI_DEVICE_ERROR is returned from the processing of a KeywordString
54   containing multiple keywords, the state of storage associated with earlier keywords
55   is undefined.
56 
57 
58   @param This             Pointer to the EFI_KEYWORD_HANDLER _PROTOCOL instance.
59 
60   @param KeywordString    A null-terminated string in <MultiKeywordResp> format.
61 
62   @param Progress         On return, points to a character in the KeywordString.
63                           Points to the string's NULL terminator if the request
64                           was successful. Points to the most recent '&' before
65                           the first failing name / value pair (or the beginning
66                           of the string if the failure is in the first name / value
67                           pair) if the request was not successful.
68 
69   @param ProgressErr      If during the processing of the KeywordString there was
70                           a failure, this parameter gives additional information
71                           about the possible source of the problem. The various
72                           errors are defined in "Related Definitions" below.
73 
74 
75   @retval EFI_SUCCESS             The specified action was completed successfully.
76 
77   @retval EFI_INVALID_PARAMETER   One or more of the following are TRUE:
78                                   1. KeywordString is NULL.
79                                   2. Parsing of the KeywordString resulted in an
80                                      error. See Progress and ProgressErr for more data.
81 
82   @retval EFI_NOT_FOUND           An element of the KeywordString was not found.
83                                   See ProgressErr for more data.
84 
85   @retval EFI_OUT_OF_RESOURCES    Required system resources could not be allocated.
86                                   See ProgressErr for more data.
87 
88   @retval EFI_ACCESS_DENIED       The action violated system policy. See ProgressErr
89                                   for more data.
90 
91   @retval EFI_DEVICE_ERROR        An unexpected system error occurred. See ProgressErr
92                                   for more data.
93 
94 **/
95 typedef
96 EFI_STATUS
97 (EFIAPI *EFI_CONFIG_KEYWORD_HANDLER_SET_DATA)(
98   IN EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL *This,
99   IN CONST EFI_STRING                    KeywordString,
100   OUT EFI_STRING                         *Progress,
101   OUT UINT32                             *ProgressErr
102   );
103 
104 /**
105 
106   This function accepts a <MultiKeywordRequest> formatted string, finds the underlying
107   keyword owners, creates a <MultiConfigRequest> string from it and forwards it to the
108   EFI_HII_ROUTING_PROTOCOL.ExtractConfig function.
109 
110   If there is an issue in resolving the contents of the KeywordString, then the function
111   returns an EFI_INVALID_PARAMETER and also set the Progress and ProgressErr with the
112   appropriate information about where the issue occurred and additional data about the
113   nature of the issue.
114 
115   In the case when KeywordString is NULL, or contains multiple keywords, or when
116   EFI_NOT_FOUND is generated while processing the keyword elements, the Results string
117   contains values returned for all keywords processed prior to the keyword generating the
118   error but no values for the keyword with error or any following keywords.
119 
120 
121   @param This           Pointer to the EFI_KEYWORD_HANDLER _PROTOCOL instance.
122 
123   @param NameSpaceId    A null-terminated string containing the platform configuration
124                         language to search through in the system. If a NULL is passed
125                         in, then it is assumed that any platform configuration language
126                         with the prefix of "x-UEFI-" are searched.
127 
128   @param KeywordString  A null-terminated string in <MultiKeywordRequest> format. If a
129                         NULL is passed in the KeywordString field, all of the known
130                         keywords in the system for the NameSpaceId specified are
131                         returned in the Results field.
132 
133   @param Progress       On return, points to a character in the KeywordString. Points
134                         to the string's NULL terminator if the request was successful.
135                         Points to the most recent '&' before the first failing name / value
136                         pair (or the beginning of the string if the failure is in the first
137                         name / value pair) if the request was not successful.
138 
139   @param ProgressErr    If during the processing of the KeywordString there was a
140                         failure, this parameter gives additional information about the
141                         possible source of the problem. See the definitions in SetData()
142                         for valid value definitions.
143 
144   @param Results        A null-terminated string in <MultiKeywordResp> format is returned
145                         which has all the values filled in for the keywords in the
146                         KeywordString. This is a callee-allocated field, and must be freed
147                         by the caller after being used.
148 
149   @retval EFI_SUCCESS             The specified action was completed successfully.
150 
151   @retval EFI_INVALID_PARAMETER   One or more of the following are TRUE:
152                                   1.Progress, ProgressErr, or Results is NULL.
153                                   2.Parsing of the KeywordString resulted in an error. See
154                                     Progress and ProgressErr for more data.
155 
156 
157   @retval EFI_NOT_FOUND           An element of the KeywordString was not found. See
158                                   ProgressErr for more data.
159 
160   @retval EFI_NOT_FOUND           The NamespaceId specified was not found.  See ProgressErr
161                                   for more data.
162 
163   @retval EFI_OUT_OF_RESOURCES    Required system resources could not be allocated.  See
164                                   ProgressErr for more data.
165 
166   @retval EFI_ACCESS_DENIED       The action violated system policy.  See ProgressErr for
167                                   more data.
168 
169   @retval EFI_DEVICE_ERROR        An unexpected system error occurred.  See ProgressErr
170                                   for more data.
171 
172 **/
173 typedef
174 EFI_STATUS
175 (EFIAPI *EFI_CONFIG_KEYWORD_HANDLER_GET_DATA)(
176   IN EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL  *This,
177   IN CONST EFI_STRING                     NameSpaceId  OPTIONAL,
178   IN CONST EFI_STRING                     KeywordString  OPTIONAL,
179   OUT EFI_STRING                          *Progress,
180   OUT UINT32                              *ProgressErr,
181   OUT EFI_STRING                          *Results
182   );
183 
184 ///
185 /// The EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL provides the mechanism
186 /// to set and get the values associated with a keyword exposed
187 /// through a x-UEFI- prefixed configuration language namespace
188 ///
189 
190 struct _EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL {
191   EFI_CONFIG_KEYWORD_HANDLER_SET_DATA    SetData;
192   EFI_CONFIG_KEYWORD_HANDLER_GET_DATA    GetData;
193 };
194 
195 extern EFI_GUID  gEfiConfigKeywordHandlerProtocolGuid;
196 
197 #endif
198