3 Copyright (c) 2004 - 2005, Intel Corporation
4 All rights reserved. This program and the accompanying materials
5 are licensed and made available under the terms and conditions of the BSD License
6 which accompanies this distribution. The full text of the license may be found at
7 http://opensource.org/licenses/bsd-license.php
9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
17 The file contain all library function for Ifr Operations.
25 #include "EfiDriverLib.h"
27 #include EFI_PROTOCOL_DEFINITION (Hii)
28 #include EFI_GUID_DEFINITION (GlobalVariable)
30 #define DEFAULT_FORM_BUFFER_SIZE 0xFFFF
31 #define DEFAULT_STRING_BUFFER_SIZE 0xFFFF
35 CHAR16
*OptionString
; // Passed in string to generate a token for in a truly dynamic form creation
36 STRING_REF StringToken
; // This is used when creating a single op-code without generating a StringToken (have one already)
51 Determine what is the current language setting
55 Lang - Pointer of system language
66 IN VOID
*StringBuffer
,
69 IN OUT STRING_REF
*StringToken
75 Add a string to the incoming buffer and return the token and offset data
79 StringBuffer - The incoming buffer
81 Language - Currrent language
83 String - The string to be added
85 StringToken - The index where the string placed
89 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
91 EFI_SUCCESS - String successfully added to the incoming buffer
99 IN OUT VOID
*OpCodeData
105 Add op-code data to the FormBuffer
109 FormBuffer - Form buffer to be inserted to
111 OpCodeData - Op-code data to be inserted
115 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
117 EFI_SUCCESS - Op-code data successfully inserted
124 IN CHAR16
*FormSetTitle
,
128 IN OUT VOID
**FormBuffer
,
129 IN OUT VOID
**StringBuffer
139 FormSetTitle - Title of formset
141 Guid - Guid of formset
143 Class - Class of formset
145 SubClass - Sub class of formset
147 FormBuffer - Pointer of the formset created
149 StringBuffer - Pointer of FormSetTitile string created
153 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
155 EFI_SUCCESS - Formset successfully created
162 IN CHAR16
*FormTitle
,
164 IN OUT VOID
*FormBuffer
,
165 IN OUT VOID
*StringBuffer
175 FormTitle - Title of the form
177 FormId - Id of the form
179 FormBuffer - Pointer of the form created
181 StringBuffer - Pointer of FormTitil string created
185 EFI_SUCCESS - Form successfully created
193 IN OUT VOID
*FormBuffer
,
194 IN OUT VOID
*StringBuffer
204 SubTitle - Sub title to be created
206 FormBuffer - Where this subtitle to add to
208 StringBuffer - String buffer created for subtitle
212 EFI_SUCCESS - Subtitle successfully created
224 IN OUT VOID
*FormBuffer
,
225 IN OUT VOID
*StringBuffer
231 Create a line of text
235 String - First string of the text
237 String2 - Second string of the text
239 String3 - Help string of the text
241 Flags - Flag of the text
243 Key - Key of the text
245 FormBuffer - The form where this text adds to
247 StringBuffer - String buffer created for String, String2 and String3
251 EFI_SUCCESS - Text successfully created
260 IN OUT VOID
*FormBuffer
,
261 IN OUT VOID
*StringBuffer
271 FormId - Form ID of the hyperlink
273 Prompt - Prompt of the hyperlink
275 FormBuffer - The form where this hyperlink adds to
277 StringBuffer - String buffer created for Prompt
281 EFI_SUCCESS - Hyperlink successfully created
288 IN UINT16 QuestionId
,
292 IN IFR_OPTION
*OptionsList
,
293 IN UINTN OptionCount
,
294 IN OUT VOID
*FormBuffer
,
295 IN OUT VOID
*StringBuffer
301 Create a one-of question with a set of options to choose from. The
302 OptionsList is a pointer to a null-terminated list of option descriptions.
306 QuestionId - Question ID of the one-of box
308 DataWidth - DataWidth of the one-of box
310 Prompt - Prompt of the one-of box
312 Help - Help of the one-of box
314 OptionsList - Each string in it is an option of the one-of box
316 OptionCount - Option string count
318 FormBuffer - The form where this one-of box adds to
320 StringBuffer - String buffer created for Prompt, Help and Option strings
324 EFI_DEVICE_ERROR - DataWidth > 2
326 EFI_SUCCESS - One-Of box successfully created.
333 IN UINT16 QuestionId
,
337 IN IFR_OPTION
*OptionsList
,
338 IN UINTN OptionCount
,
339 IN OUT VOID
*FormBuffer
,
340 IN OUT VOID
*StringBuffer
346 Create a one-of question with a set of options to choose from. The
347 OptionsList is a pointer to a null-terminated list of option descriptions.
351 QuestionId - Question ID of the ordered list
353 MaxEntries - MaxEntries of the ordered list
355 Prompt - Prompt of the ordered list
357 Help - Help of the ordered list
359 OptionsList - Each string in it is an option of the ordered list
361 OptionCount - Option string count
363 FormBuffer - The form where this ordered list adds to
365 StringBuffer - String buffer created for Prompt, Help and Option strings
369 EFI_SUCCESS - Ordered list successfully created.
376 IN UINT16 QuestionId
,
381 IN OUT VOID
*FormBuffer
,
382 IN OUT VOID
*StringBuffer
392 QuestionId - Question ID of the check box
394 DataWidth - DataWidth of the check box
396 Prompt - Prompt of the check box
398 Help - Help of the check box
400 Flags - Flags of the check box
402 FormBuffer - The form where this check box adds to
404 StringBuffer - String buffer created for Prompt and Help.
408 EFI_DEVICE_ERROR - DataWidth > 1
410 EFI_SUCCESS - Check box successfully created
417 IN UINT16 QuestionId
,
427 IN OUT VOID
*FormBuffer
,
428 IN OUT VOID
*StringBuffer
438 QuestionId - Question ID of the numeric
440 DataWidth - DataWidth of the numeric
442 Prompt - Prompt of the numeric
444 Help - Help of the numeric
446 Minimum - Minumun boundary of the numeric
448 Maximum - Maximum boundary of the numeric
450 Step - Step of the numeric
452 Default - Default value
454 Flags - Flags of the numeric
456 Key - Key of the numeric
458 FormBuffer - The form where this numeric adds to
460 StringBuffer - String buffer created for Prompt and Help.
464 EFI_DEVICE_ERROR - DataWidth > 2
466 EFI_SUCCESS - Numeric is successfully created
473 IN UINT16 QuestionId
,
481 IN OUT VOID
*FormBuffer
,
482 IN OUT VOID
*StringBuffer
492 QuestionId - Question ID of the string
494 DataWidth - DataWidth of the string
496 Prompt - Prompt of the string
498 Help - Help of the string
500 MinSize - Min size boundary of the string
502 MaxSize - Max size boundary of the string
504 Flags - Flags of the string
506 Key - Key of the string
508 FormBuffer - The form where this string adds to
510 StringBuffer - String buffer created for Prompt and Help.
514 EFI_SUCCESS - String successfully created.
520 ExtractDataFromHiiHandle (
521 IN EFI_HII_HANDLE HiiHandle
,
522 IN OUT UINT16
*ImageLength
,
523 OUT UINT8
*DefaultImage
,
530 Extract information pertaining to the HiiHandle
534 HiiHandle - Hii handle
536 ImageLength - For input, length of DefaultImage;
537 For output, length of actually required
539 DefaultImage - Image buffer prepared by caller
541 Guid - Guid information about the form
545 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
547 EFI_BUFFER_TOO_SMALL - DefualtImage has no enough ImageLength
549 EFI_SUCCESS - Successfully extract data from Hii database.
557 IN OUT EFI_HII_PROTOCOL
**HiiProtocol
, OPTIONAL
563 Finds HII handle for given pack GUID previously registered with the HII.
566 HiiProtocol - pointer to pointer to HII protocol interface.
567 If NULL, the interface will be found but not returned.
568 If it points to NULL, the interface will be found and
569 written back to the pointer that is pointed to.
570 Guid - The GUID of the pack that registered with the HII.
573 Handle to the HII pack previously registered by the memory driver.
579 CreateSubTitleOpCode (
580 IN STRING_REF StringToken
,
581 IN OUT VOID
*FormBuffer
587 Create a SubTitle opcode independent of string creation
588 This is used primarily by users who need to create just one particular valid op-code and the string
589 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
590 location to pre-defined forms in HII)
594 StringToken - StringToken of the subtitle
596 FormBuffer - Output of subtitle as a form
600 EFI_SUCCESS - Subtitle created to be a form
607 IN STRING_REF StringToken
,
608 IN STRING_REF StringTokenTwo
,
609 IN STRING_REF StringTokenThree
,
612 IN OUT VOID
*FormBuffer
618 Create a Text opcode independent of string creation
619 This is used primarily by users who need to create just one particular valid op-code and the string
620 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
621 location to pre-defined forms in HII)
625 StringToken - First string token of the text
627 StringTokenTwo - Second string token of the text
629 StringTokenThree - Help string token of the text
631 Flags - Flag of the text
633 Key - Key of the text
635 FormBuffer - Output of text as a form
639 EFI_SUCCESS - Text created to be a form
647 IN STRING_REF StringToken
,
648 IN STRING_REF StringTokenTwo
,
651 IN OUT VOID
*FormBuffer
657 Create a hyperlink opcode independent of string creation
658 This is used primarily by users who need to create just one particular valid op-code and the string
659 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
660 location to pre-defined forms in HII)
664 FormId - Form ID of the hyperlink
666 StringToken - Prompt string token of the hyperlink
668 StringTokenTwo - Help string token of the hyperlink
670 Flags - Flags of the hyperlink
672 Key - Key of the hyperlink
674 FormBuffer - Output of hyperlink as a form
678 EFI_SUCCESS - Hyperlink created to be a form
685 IN UINT16 QuestionId
,
687 IN STRING_REF PromptToken
,
688 IN STRING_REF HelpToken
,
689 IN IFR_OPTION
*OptionsList
,
690 IN UINTN OptionCount
,
691 IN OUT VOID
*FormBuffer
697 Create a one-of opcode with a set of option op-codes to choose from independent of string creation.
698 This is used primarily by users who need to create just one particular valid op-code and the string
699 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
700 location to pre-defined forms in HII)
702 OptionsList is a pointer to a null-terminated list of option descriptions. Ensure that OptionsList[x].StringToken
703 has been filled in since this routine will not generate StringToken values.
707 QuestionId - Question ID of the one-of box
709 DataWidth - DataWidth of the one-of box
711 PromptToken - Prompt string token of the one-of box
713 HelpToken - Help string token of the one-of box
715 OptionsList - Each string in it is an option of the one-of box
717 OptionCount - Option string count
719 FormBuffer - Output of One-Of box as a form
723 EFI_SUCCESS - One-Of box created to be a form
725 EFI_DEVICE_ERROR - DataWidth > 2
731 CreateOrderedListOpCode (
732 IN UINT16 QuestionId
,
734 IN STRING_REF PromptToken
,
735 IN STRING_REF HelpToken
,
736 IN IFR_OPTION
*OptionsList
,
737 IN UINTN OptionCount
,
738 IN OUT VOID
*FormBuffer
744 Create a ordered list opcode with a set of option op-codes to choose from independent of string creation.
745 This is used primarily by users who need to create just one particular valid op-code and the string
746 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
747 location to pre-defined forms in HII)
749 OptionsList is a pointer to a null-terminated list of option descriptions. Ensure that OptionsList[x].StringToken
750 has been filled in since this routine will not generate StringToken values.
754 QuestionId - Question ID of the ordered list
756 MaxEntries - MaxEntries of the ordered list
758 PromptToken - Prompt string token of the ordered list
760 HelpToken - Help string token of the ordered list
762 OptionsList - Each string in it is an option of the ordered list
764 OptionCount - Option string count
766 FormBuffer - Output of ordered list as a form
770 EFI_SUCCESS - Ordered list created to be a form
776 CreateCheckBoxOpCode (
777 IN UINT16 QuestionId
,
779 IN STRING_REF PromptToken
,
780 IN STRING_REF HelpToken
,
783 IN OUT VOID
*FormBuffer
789 Create a checkbox opcode independent of string creation
790 This is used primarily by users who need to create just one particular valid op-code and the string
791 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
792 location to pre-defined forms in HII)
796 QuestionId - Question ID of the check box
798 DataWidth - DataWidth of the check box
800 PromptToken - Prompt string token of the check box
802 HelpToken - Help string token of the check box
804 Flags - Flags of the check box
806 Key - Key of the check box
808 FormBuffer - Output of the check box as a form
812 EFI_SUCCESS - Checkbox created to be a form
814 EFI_DEVICE_ERROR - DataWidth > 1
820 CreateNumericOpCode (
821 IN UINT16 QuestionId
,
823 IN STRING_REF PromptToken
,
824 IN STRING_REF HelpToken
,
831 IN OUT VOID
*FormBuffer
837 Create a numeric opcode independent of string creation
838 This is used primarily by users who need to create just one particular valid op-code and the string
839 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
840 location to pre-defined forms in HII)
844 QuestionId - Question ID of the numeric
846 DataWidth - DataWidth of the numeric
848 PromptToken - Prompt string token of the numeric
850 HelpToken - Help string token of the numeric
852 Minimum - Minumun boundary of the numeric
854 Maximum - Maximum boundary of the numeric
856 Step - Step of the numeric
858 Default - Default value of the numeric
860 Flags - Flags of the numeric
862 Key - Key of the numeric
864 FormBuffer - Output of the numeric as a form
868 EFI_SUCCESS - The numeric created to be a form.
870 EFI_DEVICE_ERROR - DataWidth > 2
877 IN UINT16 QuestionId
,
879 IN STRING_REF PromptToken
,
880 IN STRING_REF HelpToken
,
885 IN OUT VOID
*FormBuffer
891 Create a numeric opcode independent of string creation
892 This is used primarily by users who need to create just one particular valid op-code and the string
893 data will be assumed to exist in the HiiDatabase already. (Useful when exporting op-codes at a label
894 location to pre-defined forms in HII)
898 QuestionId - Question ID of the string
900 DataWidth - DataWidth of the string
902 PromptToken - Prompt token of the string
904 HelpToken - Help token of the string
906 MinSize - Min size boundary of the string
908 MaxSize - Max size boundary of the string
910 Flags - Flags of the string
912 Key - Key of the string
914 FormBuffer - Output of the string as a form
918 EFI_SUCCESS - String created to be a form.
924 ValidateDataFromHiiHandle (
925 IN EFI_HII_HANDLE HiiHandle
,
932 Validate that the data associated with the HiiHandle in NVRAM is within
933 the reasonable parameters for that FormSet. Values for strings and passwords
934 are not verified due to their not having the equivalent of valid range settings.
938 HiiHandle - Handle of the HII database entry to query
940 Results - If return Status is EFI_SUCCESS, Results provides valid data
941 TRUE = NVRAM Data is within parameters
942 FALSE = NVRAM Data is NOT within parameters
946 EFI_OUT_OF_RESOURCES - No enough buffer to allocate
948 EFI_SUCCESS - Data successfully validated
955 IN UINT16 LineNumber
,
957 IN OUT VOID
*FormBuffer
963 Create a banner opcode. This is primarily used by the FrontPage implementation from BDS.
967 Title - Title of the banner
969 LineNumber - LineNumber of the banner
971 Alignment - Alignment of the banner
973 FormBuffer - Output of banner as a form
977 EFI_SUCCESS - Banner created to be a form.
984 IN UINTN NumberOfPackages
,
992 Assemble EFI_HII_PACKAGES according to the passed in packages.
996 NumberOfPackages - Number of packages.
997 GuidId - Package GUID.
1001 Pointer of EFI_HII_PACKAGES.
1007 EfiLibHiiVariablePackGetMap (
1008 IN EFI_HII_VARIABLE_PACK
*Pack
,
1009 OUT CHAR16
**Name
, OPTIONAL
1010 OUT EFI_GUID
**Guid
, OPTIONAL
1011 OUT UINT16
*Id
, OPTIONAL
1012 OUT VOID
**Var
, OPTIONAL
1013 OUT UINTN
*Size OPTIONAL
1017 Routine Description:
1019 Extracts a variable form a Pack.
1023 Pack - List of variables
1024 Name - Name of the variable/map
1025 Guid - GUID of the variable/map
1026 Var - Pointer to the variable/map
1027 Size - Size of the variable/map in bytes
1037 EfiLibHiiVariablePackListGetMapCnt (
1038 IN EFI_HII_VARIABLE_PACK_LIST
*List
1042 Routine Description:
1044 Finds a count of the variables/maps in the List.
1048 List - List of variables
1052 Number of Map in the variable pack list.
1057 typedef VOID (EFI_LIB_HII_VARIABLE_PACK_LIST_CALLBACK
) (
1066 Routine Description:
1068 type definition for the callback to be
1069 used with EfiLibHiiVariablePackListForEachVar().
1073 Id - Variable/Map ID
1074 Name - Name of the variable/map
1075 Guid - GUID of the variable/map
1076 Var - Pointer to the variable/map
1077 Size - Size of the variable/map in bytes
1087 EfiLibHiiVariablePackListForEachVar (
1088 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1089 IN EFI_LIB_HII_VARIABLE_PACK_LIST_CALLBACK
*Callback
1093 Routine Description:
1095 Will iterate all variable/maps as appearing
1096 in List and for each, it will call the Callback.
1100 List - List of variables
1101 Callback - Routine to be called for each iterated variable.
1111 EfiLibHiiVariablePackListGetMapByIdx (
1113 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1114 OUT CHAR16
**Name
, OPTIONAL
1115 OUT EFI_GUID
**Guid
, OPTIONAL
1116 OUT UINT16
*Id
, OPTIONAL
1122 Routine Description:
1124 Finds a variable form List given
1125 the order number as appears in the List.
1129 Idx - The index of the variable/map to retrieve
1130 List - List of variables
1131 Name - Name of the variable/map
1132 Guid - GUID of the variable/map
1133 Var - Pointer to the variable/map
1134 Size - Size of the variable/map in bytes
1138 EFI_SUCCESS - Variable is found, OUT parameters are valid
1139 EFI_NOT_FOUND - Variable is not found, OUT parameters are not valid
1145 EfiLibHiiVariablePackListGetMapById (
1147 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1148 OUT CHAR16
**Name
, OPTIONAL
1149 OUT EFI_GUID
**Guid
, OPTIONAL
1155 Routine Description:
1157 Finds a variable form List given the
1158 order number as appears in the List.
1162 Id - The ID of the variable/map to retrieve
1163 List - List of variables
1164 Name - Name of the variable/map
1165 Guid - GUID of the variable/map
1166 Var - Pointer to the variable/map
1167 Size - Size of the variable/map in bytes
1171 EFI_SUCCESS - Variable is found, OUT parameters are valid
1172 EFI_NOT_FOUND - Variable is not found, OUT parameters are not valid
1178 EfiLibHiiVariablePackListGetMap (
1179 IN EFI_HII_VARIABLE_PACK_LIST
*List
,
1188 Routine Description:
1190 Finds a variable form EFI_HII_VARIABLE_PACK_LIST given name and GUID.
1194 List - List of variables
1195 Name - Name of the variable/map to be found
1196 Guid - GUID of the variable/map to be found
1197 Var - Pointer to the variable/map found
1198 Size - Size of the variable/map in bytes found
1202 EFI_SUCCESS - variable is found, OUT parameters are valid
1203 EFI_NOT_FOUND - variable is not found, OUT parameters are not valid
1209 EfiLibHiiVariableRetrieveFromNv (
1217 Routine Description:
1218 Finds out if a variable of specific Name/Guid/Size exists in NV.
1219 If it does, it will retrieve it into the Var.
1222 Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly.
1223 Var - Variable will be retrieved into buffer pointed by this pointer.
1224 If pointing to NULL, the buffer will be allocated. Caller is responsible for releasing the buffer.
1226 EFI_SUCCESS - The variable of exact Name/Guid/Size parameters was retrieved and written to Var.
1227 EFI_NOT_FOUND - The variable of this Name/Guid was not found in the NV.
1228 EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error.
1234 //// Variable override support.
1238 EfiLibHiiVariableOverrideIfSuffix (
1247 Routine Description:
1248 Overrrides the variable with NV data if found.
1249 But it only does it if the Name ends with specified Suffix.
1250 For example, if Suffix="MyOverride" and the Name="XyzSetupMyOverride",
1251 the Suffix matches the end of Name, so the variable will be loaded from NV
1252 provided the variable exists and the GUID and Size matches.
1255 Suffix - Suffix the Name should end with.
1256 Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly.
1257 Var - Variable will be retrieved into this buffer.
1258 Caller is responsible for providing storage of exactly Size size in bytes.
1260 EFI_SUCCESS - The variable was overriden with NV variable of same Name/Guid/Size.
1261 EFI_INVALID_PARAMETER - The name of the variable does not end with <Suffix>.
1262 EFI_NOT_FOUND - The variable of this Name/Guid was not found in the NV.
1263 EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error.
1269 EfiLibHiiVariableOverrideBySuffix (
1278 Routine Description:
1279 Overrrides the variable with NV data if found.
1280 But it only does it if the NV contains the same variable with Name is appended with Suffix.
1281 For example, if Suffix="MyOverride" and the Name="XyzSetup",
1282 the Suffix will be appended to the end of Name, and the variable with Name="XyzSetupMyOverride"
1283 will be loaded from NV provided the variable exists and the GUID and Size matches.
1286 Suffix - Suffix the variable will be appended with.
1287 Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly.
1288 Var - Variable will be retrieved into this buffer.
1289 Caller is responsible for providing storage of exactly Size size in bytes.
1292 EFI_SUCCESS - The variable was overriden with NV variable of same Name/Guid/Size.
1293 EFI_NOT_FOUND - The variable of this Name/Guid was not found in the NV.
1294 EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error.