EFI Shell Developer's Guide - FTP

EFI Shell Developer’s GuideVersion 0.91June 27, 2005

Information in this document is provided in connection with Intel products. No license, express or implied, by estoppel orotherwise, to any intellectual property rights is granted by this document. Except as provided in Intel's Terms and Conditionsof Sale for such products, Intel assumes no liability whatsoever, and INTEL DISCLAIMS ANY EXPRESS OR IMPLIEDWARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIESRELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT,COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT. Intel products are not intended for use in medical, lifesaving, or life sustaining applications. Intel may make changes to specifications and product descriptions at any time,without notice.This document contains information on products in the design phase. The information here is subject to change withoutnotice. Do not finalize a design with this information.Designers must not rely on the absence or characteristics of any features or instructions marked "reserved" or "undefined."Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arisingfrom future changes to them.This document as well as the software described in it is furnished under license and may only be used or copied inaccordance with the terms of the license. The information in this manual is furnished for informational use only, is subject tochange without notice, and should not be construed as a commitment by Intel Corporation to update or revise theinformation or document. Intel Corporation assumes no responsibility or liability for any errors or inaccuracies that mayappear in this document or any software that may be provided in association with this document.This document provides website addresses for certain third party websites. The referenced sites are not under the control ofIntel and Intel is not responsible for the content of any referenced site or any link contained in a referenced site. Intel doesnot endorse companies or products for sites which it references. If you decide to access any of the third party sitesreferenced in this document, you do this entirely at your own risk.*Other names and brands may be claimed as the property of others.Intel, the Intel logo, Itanium, and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries inthe United States and other countries.Copyright © 2000–2005, Intel Corporation. All Rights Reserved.Version 0.91 June 27, 2005 ii

Revision HistoryRevision Revision History Date0.9 Includes all known edits/revisions. 02/23/050.91.0 Beta release to Open Source 06/27/05Version 0.9 February, 2005 iii

Contents1 Introduction ...................................................................................................... 91.1 Overview ........................................................................................................................ 91.2 Related Information........................................................................................................91.3 Conventions Used in This Document.............................................................................91.3.1 Data Structure Descriptions.............................................................................91.3.2 Procedure Descriptions .................................................................................101.3.3 Pseudo-Code Conventions............................................................................111.3.4 Typographic Conventions..............................................................................112 Building the Environment Setup................................................................... 132.1 Microsoft* Tools Installation .........................................................................................132.1.1 Visual C++ .....................................................................................................132.1.2 Microsoft* C/C++ Optimizing Compiler..........................................................132.2 EFI Shell Installation ....................................................................................................133 Building an EFI Shell Application................................................................. 153.1 Building an Application.................................................................................................153.1.1 Build Example................................................................................................154 Composing an EFI Shell Application............................................................ 174.1 String Resource .uni File..............................................................................................174.2 Component Description .inf File ...................................................................................184.2.1 DEFINES Section ..........................................................................................184.2.2 SOURCES.COMMON Section ......................................................................194.2.3 INCLUDES.COMMON Section......................................................................194.2.4 LIBRARIES.COMMON Section .....................................................................194.2.5 NMAKE.COMMON Section ...........................................................................194.3 Writing an EFI Shell Application...................................................................................194.3.1 Required .h Files ...........................................................................................194.3.2 Strings ...........................................................................................................204.3.3 Declaring the Entry Point...............................................................................204.3.4 Initializing the Execution Environment...........................................................204.3.5 Registering the String Package .....................................................................214.3.6 Checking for Available System Services .......................................................214.3.7 HelloWorld Example ......................................................................................214.3.8 UseArg Example............................................................................................244.3.9 UseVar Example............................................................................................264.4 Writing an Application That Can Be Either Internal Command or External Command334.4.1 Rules to Follow ..............................................................................................334.5 Switching Between Internal and External Commands .................................................354.5.1 External to Internal ........................................................................................354.5.2 Internal to External ........................................................................................355 EFI Shell Library Introduction....................................................................... 375.1 Data Types and Global Variables ................................................................................37Version 0.9 February, 2005 v

5.1.1 EFI_SHELL_INTERFACE Data Type............................................................375.1.2 Global Variables ............................................................................................385.2 Initialization Functions..................................................................................................395.2.1 LibInitializeShellApplication().........................................................................405.2.2 LibInitializeStrings() .......................................................................................415.2.3 LibUnInitializeStrings()...................................................................................425.3 String Functions ...........................................................................................................435.3.1 StrCmp() ........................................................................................................445.3.2 StrnCmp() ......................................................................................................455.3.3 StrCpy() .........................................................................................................465.3.4 StrCat() ..........................................................................................................475.3.5 StrLen()..........................................................................................................485.3.6 StrLwr()..........................................................................................................495.3.7 StrUpr()..........................................................................................................505.3.8 Xtoi() ..............................................................................................................515.3.9 Atoi() ..............................................................................................................525.3.10 LibDevicePathToStr() ....................................................................................535.3.11 StriCmp() .......................................................................................................555.3.12 StrSize().........................................................................................................565.3.13 StrDuplicate().................................................................................................575.3.14 Strlena().........................................................................................................585.3.15 Strcmpa().......................................................................................................595.3.16 Strncmpa().....................................................................................................605.3.17 StrSubCmp()..................................................................................................615.3.18 StrChr()..........................................................................................................625.3.19 StrStr() ...........................................................................................................635.3.20 StrTrim() ........................................................................................................645.4 Memory Support Functions ..........................................................................................655.4.1 SetMem().......................................................................................................665.4.2 CopyMem()....................................................................................................675.4.3 CompareMem() .............................................................................................685.4.4 AllocatePool() ................................................................................................695.4.5 FreePool()......................................................................................................705.4.6 AllocateZeroPool().........................................................................................715.5 FILE I/O FUNCTIONS..................................................................................................725.5.1 LibGetFileInfo()..............................................................................................735.5.2 LibSetFileInfo() ..............................................................................................745.5.3 LibOpenFile().................................................................................................755.5.4 LibOpenFileByName() ...................................................................................775.5.5 LibCreateDirectory() ......................................................................................795.5.6 LibReadFile() .................................................................................................815.5.7 LibWriteFile() .................................................................................................835.5.8 LibCloseFile() ................................................................................................845.5.9 LibDeleteFile() ...............................................................................................855.5.10 LibSetPosition() .............................................................................................865.5.11 LibGetPosition().............................................................................................875.5.12 LibFlushFile().................................................................................................885.5.13 LibFindFirstFile()............................................................................................89Version 0.91 June 27, 2005 vi

5.5.14 LibFindNextFile() ...........................................................................................905.5.15 LibGetFileSize().............................................................................................915.5.16 LibFileDevicePath() .......................................................................................925.6 Text I/O Functions........................................................................................................935.6.1 Input() ............................................................................................................955.6.2 Output() .........................................................................................................965.6.3 Print().............................................................................................................975.6.4 PrintAt() .........................................................................................................985.6.5 Sprint()...........................................................................................................995.6.6 PrintToken().................................................................................................1005.7 Math Functions...........................................................................................................1015.7.1 LshiftU64() ...................................................................................................1025.7.2 RshiftU64() ..................................................................................................1035.7.3 MultU64x32() ...............................................................................................1045.7.4 DivU64x32().................................................................................................1055.8 Spin Lock Functions...................................................................................................1065.8.1 InitializeLock()..............................................................................................1075.8.2 AcquireLock() ..............................................................................................1085.8.3 ReleaseLock() .............................................................................................1095.9 Device Path Support Functions..................................................................................1105.9.1 DevicePathFromHandle() ............................................................................1115.9.2 DevicePathInstance() ..................................................................................1125.9.3 AppendDevicePath() ...................................................................................1135.9.4 DevicePathSize().........................................................................................1145.9.5 UnpackDevicePath()....................................................................................1155.10 Shell Interface Support Functions ..............................................................................1165.10.1 GetExecutionBreak() ...................................................................................1175.10.2 ShellGetEnv() ..............................................................................................1185.10.3 ShellGetMap() .............................................................................................1195.10.4 ShellExecute() .............................................................................................1205.10.5 ShellCurDir()................................................................................................1215.10.6 EnablePageBreak() .....................................................................................1225.10.7 DisablePageBreak() ....................................................................................1235.10.8 GetPageBreak()...........................................................................................1245.10.9 ShellFileMetaArg().......................................................................................1255.10.10 ShellFileMetaArgNoWildCard() ...................................................................1265.10.11 ShellFreeFileList() .......................................................................................1275.10.12 ShellInitHandleEnumerator() .......................................................................1285.10.13 ShellNextHandle() .......................................................................................1295.10.14 ShellSkipHandle()........................................................................................1305.10.15 ShellResetHandleEnumerator()...................................................................1315.10.16 ShellCloseHandleEnumerator()...................................................................1325.10.17 ShellGetHandleNum() .................................................................................133TablesTable 4-1. Shell Environment Services II........................................................................34Table 5-1. Initialization Functions ...................................................................................39Version 0.91 June 27, 2005 vii

Table 5-2. String Functions.............................................................................................43Table 5-3. Hardware Device Path Output Formats.........................................................53Table 5-4. Messaging Device Path Output Formats.......................................................53Table 5-5. Media Device Path Output Formats ..............................................................54Table 5-6. BBS Device Path Output Formats .................................................................54Table 5-7. Memory Support Functions ...........................................................................65Table 5-8. File I/O Functions ..........................................................................................72Table 5-9. Format String Attribute and Argument Specification .....................................93Table 5-10. Text I/O Functions .........................................................................................94Table 5-11. Math Functions ............................................................................................101Table 5-12. Spin Lock Functions ....................................................................................106Table 5-13. Device Path Support Functions ...................................................................110Table 5-14. Shell Interface Support Functions ...............................................................116Version 0.91 June 27, 2005 viii

1Introduction1.1 OverviewThe primary objective of this document is to provide detailed instructions for developing andbuilding an EFI shell application using the EFI Shell Package. In addition, this document introducesthe EFI Shell library in detail, and provides application examples in the instructions. In order tobuild the EFI Shell the EFI Developer Kit (hereafter referred to as “EDK”) will be needed. Refer tothe EDK Getting Started Guide.1.2 Related InformationThe following publications and sources of information may be useful to you or are referred to bythis specification:• EFI 1.10 Specification, Intel Corporation, http://developer.intel.com/technology/efiThe following terms are used throughout this document.TermDescriptionEFI Shell Core The core framework of the EFI Shell and the internal-only commands.IA-32Intel® Architecture for 32-bitEDKEFI Developer Kit. (needed to build the EFI-Shell)EDK SOURCE An environmental variable that specifies the base directory where the EFIsourcefiles are located. Typically this directory will be C:\TianoCore\Edk.EFIExtensible Firmware InterfaceEFI DriverModular firmware code that supports chipset or platform features and is reusable inmultiple system contexts. Code relating to a device or function that is run in the PreOS phase of execution. (Formerly known as an option ROM.)1.3 Conventions Used in This DocumentThis document uses the typographic and illustrative conventions described below.1.3.1 Data Structure DescriptionsIntel ® processors based on 32-bit Intel architecture (IA-32) are “little endian” machines. Thisdistinction means that the low-order byte of a multibyte data item in memory is at the lowestaddress, while the high-order byte is at the highest address. Processors of the Intel ® Itanium ®processor family may be configured for both “little endian” and “big endian” operation. Allimplementations designed to conform to this specification will use “little endian” operation.Version 0.9 February, 2005 9

IntroductionIn some memory layout descriptions, certain fields are marked reserved. Software must initializesuch fields to zero and ignore them when read. On an update operation, software must preserveany reserved field.The data structures described in this document generally have the following format:STRUCTURE NAME: The formal name of the data structure.Summary:Prototype:Parameters:Description:Related Definitions:1.3.2 Procedure DescriptionsA brief description of the data structure.A “C-style” type declaration for the data structure.A brief description of each field in the data structure prototype.A description of the functionality provided by the data structure,including any limitations and caveats of which the caller shouldbe aware.The type declarations and constants that are used only bythis data structure.The procedures described in this document generally have the following format:ProcedureName(): The formal name of the procedure.Summary:Prototype:Parameters:Description:Related Definitions:A brief description of the procedure.A “C-style” procedure header defining the calling sequence.A brief description of each field in the procedure prototype.A description of the functionality provided by the interface,including any limitations and caveats of which the caller shouldbe aware.The type declarations and constants that are used only bythis procedure.Status Codes Returned: A description of any codes returned by the interface. Theprocedure is required to implement any status codes listed in thistable. Additional error codes may be returned, but they will notbe tested by standard compliance tests, and any software thatuses the procedure cannot depend on any of the extended errorcodes that an implementation may provide.Version 0.91 June 27, 2005 10

Introduction1.3.3 Pseudo-Code ConventionsPseudo code is presented to describe algorithms in a more concise form. None of the algorithms inthis document are intended to be compiled directly. The code is presented at a level correspondingto the surrounding text.In describing variables, a list is an unordered collection of homogeneous objects. A queue is anordered list of homogeneous objects. Unless otherwise noted, the ordering is assumed to be First InFirst Out (FIFO).Pseudo code is presented in a C-like format, using C conventions where appropriate. The codingstyle, particularly the indentation style, is used for readability and does not necessarily comply withan implementation of the Extensible Firmware Interface Specification.1.3.4 Typographic ConventionsThis document uses the typographic and illustrative conventions described below:Plain textThe normal text typeface is used for the vast majority of the descriptivetext in a specification.Plain text (blue) Any plain text that is underlined and in blue indicates an active link tothe cross-reference. Click on the word to follow the hyperlink.BoldIn text, a Bold typeface identifies a processor register name. In otherinstances, a Bold typeface can be used as a running head within aparagraph.ItalicIn text, an Italic typeface can be used as emphasis to introduce a newterm or to indicate a manual or specification name.BOLD Monospace Computer code, example code segments, and all prototype codesegments use a BOLD Monospace typeface with a dark red color.These code listings normally appear in one or more separate paragraphs,though words or segments can also be embedded in a normal textparagraph.Italic Monospace In code or in text, words in Italic Monospace indicate placeholdernames for variable information that must be supplied (i.e., arguments).Plain Monospace In code, words in a Plain Monospace typeface that is a dark redcolor but is not bold or italicized indicate pseudo code or example code.These code segments typically occur in one or more separate paragraphs.See the master Framework glossary in the Framework Interoperability and ComponentSpecifications help system for definitions of terms and abbreviations that are used in this documentor that might be useful in understanding the descriptions presented in this document.See the master Framework references in the Interoperability and Component Specifications helpsystem for a complete list of the additional documents and specifications that are required orsuggested for interpreting the information presented in this document.The Framework Interoperability and Component Specifications help system is available at thefollowing URL:http://www.intel.com/technology/framework/spec.htmVersion 0.91 June 27, 2005 11

IntroductionVersion 0.91 June 27, 2005 12

2Building the Environment SetupThis section describes the steps necessary to initially setup the EFI Shell environment inpreparation for building the EFI shell application. The base-build system must be a functionalWindows* 2000 or Windows* XP system.2.1 Microsoft* Tools InstallationSeveral Microsoft* tools are needed to build the EFI Shell and shell commands. The followingtools must be installed on the development system.2.1.1 Visual C++Install Microsoft Visual Studio .NET* 2003 Professional (7.1), on your system. It is recommended,but not required, that the default installation settings be used. It is also recommended that theenvironmental variables changes be accepted. If they are not, then VCVARS32.BAT can bemanually run prior to start of a build of the EFI Shell source or shell command source.2.1.2 Microsoft* C/C++ Optimizing CompilerIn order to build the EFI Shell image and application images for Itanium®-based platforms, youwill need to install Microsoft* C/C++ Optimizing Compiler Version 13.10.2240.8 for IA-64 in theMicrosoft Windows Server* 2003 DDK (Build 3790). This compiler can be obtained in theMicrosoft* Windows Server* 2003 Driver Development Kit (DDK), Build 3790).2.2 EFI Shell InstallationThe EFI Shell is a sub-project of EDK. The EFI Shell binaries are used for building the EFI Shellenvironment and user-defined EFI Shell applications. It includes the following components:• Source code for the EFI Shell, EFI Shell internal commands, EFI Shell external commands, andEFI Shell library.EFI Shell source code installation is simple; copy the whole directory under the EDK subdirectory.(Example: If the EDK location is C:\EDK, then copy the Shell project to theC:\EDK\Other\Maintained\Application\Shell).Refer to the EDK Getting Started Guide for the EDK installation.Version 0.9 February, 2005 13

3Building an EFI Shell ApplicationThis section describes how to use the EDK and Shell (source code and library code) to build EFIShell applications.3.1 Building an Application3.1.1 Build ExampleIn this build example, suppose the EDK folder is located at C:\EDK and the source code of anapplication named HelloWorld is located atC:\EDK\Other\Maintained\Application\Shell\HelloWorld. The .inf file ofHelloWorld is HelloWorld.inf.1. To build an IA-32 version of HelloWorld:Open the description file C:\EDK\Sample\Platform\Nt32\Build\Nt32.dscAdd:“Other\Maintained\Application\Shell\Library\EfiShellLib.inf”to the [Libraries.Platform] section, per the following example:[Libraries.Platform]Other\Maintained\Application\Shell\Library\EfiShellLib.inf……Add:“Other\Maintained\Application\Shell\HelloWorld\HelloWorld.inf FV=NULL”To the [Components] section, like this:[Components]……Other\Maintained\Application\Shell\HelloWorld\HelloWorld.infFV=NULL……Type the command:Cd C:\EDK\Sample\Platform\Nt32\BuildSet the environment variable:C:\EDK\Sample\Platform\Nt32\Build>Set EDK_SOURCE=C:\EDKBuild:C:\EDK\Sample\Platform\Nt32\Build>nmakeThe application’s binary is:C:\EDK\Sample\Platform\Nt32\Build\IA32\HelloWorld.efiVersion 0.9 February, 2005 15

Building an EFI Shell Application2. To build an Itanium® architecture version of HelloWorld:Open the description file C:\EDK\Sample\Platform\Ipf\Build\Ipf.dscAdd:“Other\Maintained\Application\Shell\Library\EfiShellLib.inf”To the [Libraries.Platform] section, like this:[Libraries.Platform]Other\Maintained\Application\Shell\Library\EfiShellLib.inf……Add:“Other\Maintained\Application\Shell\HelloWorld\HelloWorld.inf FV=NULL”To the [Components] section, like this:[Components]……Other\Maintained\Application\Shell\HelloWorld\HelloWorld.infFV=NULL……Type the command:Cd C:\EDK\Sample\Platform\Ipf\BuildSet the environment variable:C:\EDK\Sample\Platform\Ipf\Build>Set EDK_SOURCE=C:\EDKBuild:C:\EDK\Sample\Platform\Ipf\Build>nmakeThe application’s binary is:C:\EDK\Sample\Platform\Ipf\Build\Ipf\HelloWorld.efiAll the applications built in this way are external commands. They are individual images. If youwant to build your application as an EFI Shell internal command, you need to re-build the EFI Shellto include your applications as an internal command. Please refer to section 4.5.1, External toInternal for detailed instructions. NOTEIt is highly recommended that you do a cleanup before building the EFI Shell or applications. Thecleanup will help assure the building process is successful.Version 0.91 June 27, 2005 16

4Composing an EFI Shell ApplicationThis section describes how to compose the following files to create an EFI Shell application.• C header file(s)• C source file(s)• A string resource .uni file (This is optional; it depends on whether the application uses itsown strings.)• A component description .inf file that describes how to build the application.It is assumed that an application developer already knows the purpose of C header and C sourcefiles, so no explanation is given here.4.1 String Resource .uni FileThe string resource file is where string resources are stored in a Unicode text format with a filesuffix of .uni. Applications that will not use string resources do not need a string resource file. Anexample of a .uni file is shown below.//// HelloWorldStrings.uni//// String resources for HelloWorld application///=##langdef#langdefeng “English”fra “Français”#string STR_HELLOWORLD #language eng “Hello, world!\n”#language fra “Hello, world!\n”#string STR_GOODBYE #language eng “Goodbye, cruel world!\n”#language fra “Goodbye, cruel world!\n”The contents of this .uni file must start with a line of “/=#” and use #langdef to define whichlanguages are supported. In the example above of a string resource file, eng and fra respectivelyare defined for English and French. The key word #string defines a string token and itscorresponding string resource for each supported language. String tokens, such asSTR_HELLOWORLD, are used in applications to refer to the string associated with it. Applicationdevelopers can use the key word #string to define their own string tokens and associated strings.All the strings in the .uni file are compiled to produce a C source file that contains a formattedarray. In this array all the strings are stored in a specific format. This C source file will be built withthe application’s source code. How this array is referenced in the application’s source code isdiscussed later.Version 0.9 February, 2005 17

Composing an EFI Shell ApplicationIn addition, the EFI Shell provides a standard .uni file named ShCommonStrings.uni. In thisfile many frequently used and standard message strings are defined. It is highly recommended thatthis file be included in projects to take advantage of these common messages.4.2 Component Description .inf FileThis file instructs the compiler how to compile the application to produce an .efi file. Eachapplication must have a component description file to be an external command. An example of an.inf file is shown below.## HelloWorld.inf## Component description file#[defines]BASE_NAME = HelloWorldFILE_GUID = 0B2E45BA-3539-4a2a-B853-3723E3CAAB1BCOMPONENT_TYPE = APPLICATION[sources.common]HelloWorldStrings.uniHelloWorld.c[includes.common]$(EDK_SOURCE)\Foundation$(EDK_SOURCE)\Foundation\Core\Dxe$(EDK_SOURCE)\Foundation\Efi$(EDK_SOURCE)\Foundation\Efi\Include$(EDK_SOURCE)\Foundation\Framework$(EDK_SOURCE)\Foundation\Framework\Include$(EDK_SOURCE)\Foundation\Include$(EDK_SOURCE)\Foundation\Include\IndustryStandard$(EDK_SOURCE)\Other\Maintained\Application\Shell\Inc$(EDK_SOURCE)\Other\Maintained\Application\Shell\Library$(DEST_DIR)\[libraries.common]EfiShellLib[nmake.common]C_STD_INCLUDE =IMAGE_ENTRY_POINT = HelloMainC_STD_FLAGS=$(C_STD_FLAGS) /DSTRING_ARRAY_NAME=$(BASE_NAME)StringsC_STD_FLAGS=$(C_FALGS) /DSTRING_DEFINES_FILE=\”$(BASE_NAME)StrDefs.h\”C_STD_FLAGS=$(C_FALGS) /DEFI_BOOTSHELL4.2.1 DEFINES SectionBASE_NAME specifies the name of the application. This BASE_NAME will become the name ofthe executable image after building is completed.Version 0.91 June 27, 2005 18

Composing an EFI Shell ApplicationFILE_GUID specifies the GUID associated with the application.COMPONENT_TYPE specifies the type of application. For EFI Shell applications it should beAPPLICATION.4.2.2 SOURCES.COMMON SectionThis section lists the files that should be compiled to produce an .efi file of the application. Theorder of the files in this list can be arbitrary, except when there are .uni files. When there are.uni files, they must be put ahead of any other program files.4.2.3 INCLUDES.COMMON SectionThis section lists the directories where the .h files referenced by the application can be found. Youmust add entries in this section for the directories containing .h files that will be referenced byyour application. If you do not, the compiler will report an error saying it can not open the .h file.These macros are very useful:EDK_SOURCE refers to the root directory of the EDK.DEST_DIR refers to the working directory when building.4.2.4 LIBRARIES.COMMON SectionThis section lists the libraries that normally should be linked to an application. Since the libraries inthis example file are exhaustive enough for most applications, you should be able to copy the list toyour own .inf file.4.2.5 NMAKE.COMMON SectionThis section contains information that is passed to the compiler to enable compiling. You mustspecify the entry point name for the variable IMAGE_ENTRY_POINT. The entry point name mustbe the same as the entry function name in your application.The last two lines define the variables STRING_ARRAY_NAME and STRING_DEFINES_FILEthat are used in applications that need string resources. They are replaced by the compiler withvalues from the NMAKE.COMMON section to enable the application to find the string tokendefinition .h file and .c file (containing all the strings in an array as mentioned earlier). TheEFI_BOOTSHELL is defined to enable the declaration of an entry point in the source code file.4.3 Writing an EFI Shell ApplicationThis section describes how to write an EFI Shell Application.How-to-write examples are provided in sections 4.3.7, 4.3.8, and 4.3.9.4.3.1 Required .h FilesInitially, an application must include EfiShellLib.h.EfiShellLib.h contains definitions of library functions the application is able to use.Version 0.91 June 27, 2005 19

Composing an EFI Shell Application4.3.2 StringsIf the application will use strings, include these two lines of code:#include STRING_DEFINES_FILEextern UINT8 STRING_ARRAY_NAME[];STRING_DEFINES_FILE and STRING_ARRAY_NAME are replaced by the building tool whenthe .inf file has been processed. Afterwards, the STRING_DEFINES_FILE refers to the .h filethat contains definitions of all the string tokens used in the application. STRING_ARRAY_NAMEwill be the array name in the .c file mentioned in 4.2.5.4.3.3 Declaring the Entry PointThe entry point of an application must be declared as shown below:#ifdef EFI_BOOTSHELLEFI_APPLICATION_ENTRY_POINT (HelloMain)#endifEFI_STATUSEFIAPIHelloMain (IN EFI_HANDLEIN EFI_SYSTEM_TABLE){……}ImageHandle,*SystemTableThe entry point must be declared by the macro EFI_APPLICATION_ENTRY_POINT. In theexample above, HelloMain is the name of the entry point function. For your application, youmay choose any leagal name that you like as long as it is consistent with the value specified in thevariable IMAGE_ENTRY_POINT in your .inf file.The declaration must be put in the block #ifdef EFI_BOOTSHELL …#endif and the symbolEFI_BOOTSHELL must be defined in the application’s .inf file. If it is not, and the application isbuilt as an internal command of the EFI Shell, and the declaration is at the entry point of theapplication, link conflict will occur. Putting the declaration in the #ifdefEFI_BOOTSHELL…#endif block avoids this conflict since, when building the EFI Shell, theEFI_BOOTSHELL is not defined.4.3.4 Initializing the Execution EnvironmentThe application must call LibInitializeShellApplication() to initialize the executionenvironment before starting to use the library’s global variables and services. It is highlyrecommended that you use the macro EFI_SHELL_APP_INIT() to initialize applications. Thismacro just wraps around LibInitializeShellApplication().Version 0.91 June 27, 2005 20

Composing an EFI Shell Application4.3.5 Registering the String PackageIf an application uses strings, it must call LibInitializeStrings() to register its stringpackage. It is highly recommended that you use the macro EFI_SHELL_STR_INIT() toinitialize the string package. Upon the successful return of this function, a valid HII handle will bereturned; the application should use this HII handle to perform any string operations that arerequired. HII based string services are available only after the successful initialization of the strings. NOTEJust prior to the application exiting, call LibUnInitializeStrings() to un-register theregistered string package. If this is not done, a memory leak will occur.4.3.6 Checking for Available System ServicesIf your application uses any system services (Boot Services, Runtime Services, etc.), useEFI_PROPER_VERSION() to determine if the version number of the underlying EFIimplementation has the services your application requires.To use EFI_PROPER_VERSION(), two input arguments are required concerning the revisionnumber of the EFI specification that governs the underlying EFI implementation. The firstargument is the major revision number and the second argument is the minor revision number. Foran EFI 1.02 implementation, the minor revision number should be between 0 and 99. For both anEFI 1.1 sample implementation and an Intel® Platform Innovation Framework for EFIimplementation, the minor revision number should be between 1 and 10.An application should use this macro with the lowest version it requires. If this macro returnsTRUE, the application can keep going. If the function returns FALSE, the application should quitgracefully.4.3.7 HelloWorld ExampleHelloWorld demonstrates how to initialize the execution environment and initialize the stringpackage.//// HelloWorldStrings.uni//// String resources for HelloWorld application///=##langdef eng "English"#langdef fra "Français"#string STR_HELLOWORLD #language eng "Hello, world!\n"#language fra "Hello, world!\n"#string STR_GOODBYE #language eng "Goodbye, cruel world!\n"#language fra "Goodbye, cruel world!\n"Version 0.91 June 27, 2005 21

Composing an EFI Shell Application#string STR_SHELLENV_GNC_COMMAND_NOT_SUPPORT#language eng "%hs: This command is not supported in the \n""underlaying EFI version, required EFI version \n""should be %hd.%hd or above\n\n"#language fra "%hs: This command is not supported in the \n""underlaying EFI version, required EFI version \n""should be %hd.%hd or above\n\n"//// HelloWorld.h//#ifndef _EFI_HELLOWORLD_H#define _EFI_HELLOWORLD_H#define HELLOWORLD_STRING_PACK_GUID \{0x6435f523, 0x5cd3, 0x444f, 0xa4, 0x23, 0x83, 0x4f, 0xbb,0x71, 0x29, 0xc7};#endif//// HelloWorld.c//#include "EfiShellLib.h"#include "Helloworld.h"//// This is the generated header file which includes whatever needs// to be exported (string tokens)//#include STRING_DEFINES_FILE//// This will be replaced by build tool with the name of array in// automatically generated .c file//extern UINT8 STRING_ARRAY_NAME[];//// Entry point declaration//#ifdef EFI_BOOTSHELLEFI_APPLICATION_ENTRY_POINT (HelloMain)#endif//// Entry point function - HelloMain//EFI_STATUSEFIAPIHelloMain (IN EFI_HANDLEImageHandle,IN EFI_SYSTEM_TABLE*SystemTable){EFI_HII_HANDLE HiiHandle;Version 0.91 June 27, 2005 22

Composing an EFI Shell ApplicationEFI_GUID HelloGuid = HELLOWORLD_STRING_PACK_GUID;//// Initialize the execution environment first//EFI_SHELL_APP_INIT (ImageHandle, SystemTable);//// If we are to use strings in application, we must call// EFI_SHELL_STR_INIT() first to register our string package// to HII database//EFI_SHELL_STR_INIT (HiiHandle, STRING_ARRAY_NAME, HelloGuid);}//// Check the required version of EFI system// At least, we should run on a system that keeps to EFI1.02 SPEC//if (!EFI_PROPER_VERSION (0, 99)) {PrintToken (STRING_TOKEN (STR_SHELLENV_GNC_COMMAND_NOT_SUPPORT),HiiHandle,L"helloworld",EFI_VERSION_0_99);LibUnInitializeStrings();return EFI_UNSUPPORTED;}//// Say Hello to the world//PrintToken (STRING_TOKEN(STR_HELLOWORLD), HiiHandle);//// Say Goodbye to the world//PrintToken (STRING_TOKEN(STR_GOODBYE), HiiHandle);LibUnInitializeStrings ();return EFI_SUCCESS;## HelloWorld.inf## Component description file#[defines]BASE_NAME = HelloWorldFILE_GUID = 0B2E45BA-3539-4a2a-B853-3723E3CAAB1BCOMPONENT_TYPE = APPLICATION[sources.common]HelloWorldStrings.uniVersion 0.91 June 27, 2005 23

Composing an EFI Shell ApplicationHelloWorld.c[includes.common]$(EDK_SOURCE)\Foundation$(EDK_SOURCE)\Foundation\Core\Dxe$(EDK_SOURCE)\Foundation\Efi$(EDK_SOURCE)\Foundation\Efi\Include$(EDK_SOURCE)\Foundation\Framework$(EDK_SOURCE)\Foundation\Framework\Include$(EDK_SOURCE)\Foundation\Include$(EDK_SOURCE)\Foundation\Include\IndustryStandard$(EDK_SOURCE)\Other\Maintained\Application\Shell\Inc$(EDK_SOURCE)\Other\Maintained\Application\Shell\Library$(DEST_DIR)\[libraries.common]EfiShellLib[nmake.common]C_STD_INCLUDE =IMAGE_ENTRY_POINT = HelloMainC_STD_FLAGS=$(C_STD_FLAGS) /DSTRING_ARRAY_NAME=$(BASE_NAME)StringsC_STD_FLAGS=$(C_STD_FLAGS)/DSTRING_DEFINES_FILE=\"$(BASE_NAME)StrDefs.h\"C_STD_FLAGS=$(C_STD_FLAGS) /DEFI_BOOTSHELLOutput:fs0:\> helloworld.efiHello, world!Goodbye, cruel world!fs0:\> _4.3.8 UseArg ExampleUseArg demonstrates how to get the command line arguments into applications.//// UseArg.c//#include "EfiShellLib.h"#ifdef EFI_BOOTSHELLEFI_APPLICATION_ENTRY_POINT (UseArgMain)#endifEFI_STATUSEFIAPIUseArgMain (IN EFI_HANDLEIN EFI_SYSTEM_TABLE){ImageHandle,*SystemTableVersion 0.91 June 27, 2005 24

Composing an EFI Shell ApplicationUINTNIndex;//// Initialize the execution environment first//EFI_SHELL_APP_INIT (ImageHandle, SystemTable);//// We don’t need to check the version of the system here// because we didn’t use any boot services or runtime services//Print (L"The arguments are:\n");for (Index = 0; Index < SI->Argc; Index++) {Print (L"%s\n", SI->Argv[Index]);}}return EFI_SUCCESS;## UseArg.inf## Components description file#[defines]BASE_NAME= UseArgFILE_GUID= 181157FA-77B2-4798-B3F7-003756ECE6EDCOMPONENT_TYPE = APPLICATION[sources.common]UseArg.c[includes.common]$(EDK_SOURCE)\Foundation$(EDK_SOURCE)\Foundation\Core\Dxe$(EDK_SOURCE)\Foundation\Efi$(EDK_SOURCE)\Foundation\Efi\Include$(EDK_SOURCE)\Foundation\Framework$(EDK_SOURCE)\Foundation\Framework\Include$(EDK_SOURCE)\Foundation\Include$(EDK_SOURCE)\Foundation\Include\IndustryStandard$(EDK_SOURCE)\Other\Maintained\Application\Shell\Inc$(EDK_SOURCE)\Other\Maintained\Application\Shell\Library$(DEST_DIR)\[libraries.common]EfiShellLib[nmake.common]C_STD_INCLUDE=IMAGE_ENTRY_POINT=UseArgMainC_STD_FLAGS=$(C_STD_FLAGS) /DEFI_BOOTSHELLOutput:fs0:\> usearg 1 2 3 “oh god!” EFIThe arguments are:Version 0.91 June 27, 2005 25

Composing an EFI Shell Applicationusearg123oh god!EFIfs0:\> _4.3.9 UseVar ExampleUseVar demonstrates how to use BS and RT services to read/write the variables.//// UseVarStrings.uni//// String resources for UseVar application///=##langdef eng "English"#langdef fra "Français"#string STR_TITLE#language eng "%HThe content of variable 'SampleVar' is:%N\n"#language fra "%HThe content of variable 'SampleVar' is:%N\n"#string STR_VAR#language eng "%s\n"#language fra "%s\n"#string STR_NOT_FOUND#language eng "Variable %H'SampleVar'%N not found!\n"#language fra "Variable %H'SampleVar'%N not found!\n"#string STR_WRITE_FAIL#language eng "Fail to write variable %H'SampleVar'%N.\n"#language fra "Fail to write variable %H'SampleVar'%N.\n"#string STR_USAGE#language eng "USEVAR [string | -?]\n""\n"" string - String will be written in variable\n"" named 'SampleVar'.\n"" -? - Display the help information.\n""\n""Examples:\n"" *To write a string into variable 'SampleVar':\n"" fs0:\\> usevar \"EFI, One generation ahead!\"\n""\n"" *To display the content of variable 'SampleVar':\n"" fs0:\\> usevar\n"" The content of variable 'SampleVar' is:\n"Version 0.91 June 27, 2005 26

Composing an EFI Shell Application" EFI, One generation ahead!\n"#language fra "USEVAR [string | -?]\n""\n"" string - String will be written in variable\n"" named 'SampleVar'.\n"" -? - Display the help information.\n""\n""Examples:\n"" *To write a string into variable 'SampleVar':\n"" fs0:\\> usevar \"EFI, One generation ahead!\"\n""\n"" *To display the content of variable 'SampleVar':\n"" fs0:\\> usevar\n"" The content of variable 'SampleVar' is:\n"" EFI, One generation ahead!\n"#string STR_SHELLENV_GNC_COMMAND_NOT_SUPPORT#language eng "%hs: This command is not supported in the \n""underlaying EFI version, required EFI version \n""should be %hd.%hd or above\n\n"#language fra "%hs: This command is not supported in the \n""underlaying EFI version, required EFI version \n""should be %hd.%hd or above\n\n"//// UseVar.h//#ifndef _EFI_USEVAR_H#define _EFI_USEVAR_H#define VAR_NAMEL"SampleVar"#define USEVAR_STRING_PACK_GUID \{0xe35ab40b, 0x1116, 0x43a3, 0x91, 0x41, 0xa3, 0xcd, 0xa8, 0x85,0x1, 0xb7}#define VAR_GUID \{0x11299421, 0xa2a5, 0x4206, 0xb1, 0x93, 0x9c, 0xf3, 0xe8, 0x21,0x29, 0x5c}#endif//// UseVar.c//#include "EfiShellLib.h"#include "UseVar.h"//// This is the generated header file which includes whatever needs// to be exported (strings + IFR)//#include STRING_DEFINES_FILEextern UINT8 STRING_ARRAY_NAME[];BOOLEANVersion 0.91 June 27, 2005 27

Composing an EFI Shell ApplicationIsQuoted (void);EFI_STATUSOutputVar (EFI_HII_HANDLE);EFI_STATUSWriteVar (CHAR16EFI_HII_HANDLE);HiiHandle*Str2Write,HiiHandle#ifdef EFI_BOOTSHELLEFI_APPLICATION_ENTRY_POINT (UseVarMain)#endifEFI_STATUSEFIAPIUseVarMain (IN EFI_HANDLEIN EFI_SYSTEM_TABLE){EFI_STATUSEFI_HII_HANDLEEFI_GUIDImageHandle,*SystemTableStatus;HiiHandle;StrGuid = USEVAR_STRING_PACK_GUID;EFI_SHELL_APP_INIT(ImageHandle, SystemTable);//// If we are to use strings in application, we must call// EFI_SHELL_STR_INIT() first to register our string package// to HII database//EFI_SHELL_STR_INIT (HiiHandle, STRING_ARRAY_NAME, StrGuid);//// Make sure we are running on EFI1.10 comformable system//if (!EFI_PROPER_VERSION (1, 10)) {PrintToken (STRING_TOKEN (STR_SHELLENV_GNC_COMMAND_NOT_SUPPORT),HiiHandle,L"usevar",EFI_VERSION_1_10);LibUnInitializeStrings ();return EFI_UNSUPPORTED;}Status = EFI_SUCCESS;switch (SI->Argc) {Version 0.91 June 27, 2005 28

Composing an EFI Shell Application}case 1:Status = OutputVar (HiiHandle);break;case 2:if (!StriCmp (SI->Argv[1], L"-?") && !IsQuoted ()) {PrintToken (STRING_TOKEN(STR_USAGE), HiiHandle);break;}Status = WriteVar (SI->Argv[1], HiiHandle);break;default:PrintToken (STRING_TOKEN(STR_USAGE), HiiHandle);break;}LibUnInitializeStrings ();return Status;EFI_STATUSOutputVar (EFI_HII_HANDLE HiiHandle){EFI_STATUS Status;UINTNBufferSize;VOID*Buffer;EFI_GUID VarGuid = VAR_GUID;Buffer = NULL;//// Pass in a zero size buffer to find the required buffer size.//BufferSize = 0;Status = RT->GetVariable (VAR_NAME,&VarGuid,NULL,&BufferSize,Buffer);if (Status == EFI_BUFFER_TOO_SMALL) {//// Allocate the buffer to hold the content of variable//Status = BS->AllocatePool (EfiBootServicesData,BufferSize,&Buffer);if (EFI_ERROR (Status)) {return Status;}Version 0.91 June 27, 2005 29

Composing an EFI Shell Application}//// Read variable into the allocated buffer.//Status = RT->GetVariable (VAR_NAME,&VarGuid,NULL,&BufferSize,Buffer);if (EFI_ERROR (Status)) {return Status;}} else if (EFI_NOT_FOUND == Status) {PrintToken (STRING_TOKEN(STR_NOT_FOUND), HiiHandle);return Status;}PrintToken (STRING_TOKEN(STR_TITLE), HiiHandle);PrintToken (STRING_TOKEN(STR_VAR), HiiHandle, Buffer);BS->FreePool (Buffer);return Status;EFI_STATUSWriteVar (CHAR16EFI_HII_HANDLE){EFI_STATUSUINTNEFI_GUID*Str2Write,HiiHandleStatus = EFI_SUCCESS;VarSize;VarGuid = VAR_GUID;if (NULL == Str2Write) {return EFI_INVALID_PARAMETER;}//// Calculate the size of the string to write// including the end NULL//VarSize = (StrLen (Str2Write) + 1) * sizeof (CHAR16);Status = RT->SetVariable (VAR_NAME,&VarGuid,EFI_VARIABLE_BOOTSERVICE_ACCESS|\EFI_VARIABLE_RUNTIME_ACCESS|\EFI_VARIABLE_NON_VOLATILE,VarSize,Str2Write);if (EFI_ERROR (Status)) {PrintToken (STRING_TOKEN(STR_WRITE_FAIL), HiiHandle);}return Status;Version 0.91 June 27, 2005 30

Composing an EFI Shell Application}BOOLEANIsQuoted (void)/*++Description:To determine if the first argument was quoted--*/{EFI_SHELL_ARG_INFO*ArgInfo;//// Attribute of ARG_IS_QUOTED means that at least part of the// argument was quoted in a pair of quotation marks.// Attribute of ARG_PARTIALLY_QUOTED means that not all the// chararcters of the argument were quoted.//ArgInfo = SI->ArgInfo;if (ArgInfo[1].Attributes & ARG_IS_QUOTED&& !(ArgInfo[1].Attributes & ARG_PARTIALLY_QUOTED)) {return TRUE;}}return FALSE;## UseVar.inf## Components description file#[defines]BASE_NAME= UseVarFILE_GUID= 7BD2613C-4EF8-49f5-876D-DF94A42B9B09COMPONENT_TYPE = APPLICATION[sources.common]UseVarStrings.uniUseVar.c[includes.common]Version 0.91 June 27, 2005 31

Composing an EFI Shell Application$(EDK_SOURCE)\Foundation$(EDK_SOURCE)\Foundation\Core\Dxe$(EDK_SOURCE)\Foundation\Efi$(EDK_SOURCE)\Foundation\Efi\Include$(EDK_SOURCE)\Foundation\Framework$(EDK_SOURCE)\Foundation\Framework\Include$(EDK_SOURCE)\Foundation\Include$(EDK_SOURCE)\Foundation\Include\IndustryStandard$(EDK_SOURCE)\Other\Maintained\Application\Shell\Inc$(EDK_SOURCE)\Other\Maintained\Application\Shell\Library$(DEST_DIR)\[libraries.common]EfiShellLib[nmake.common]C_STD_INCLUDE=IMAGE_ENTRY_POINT=UseVarMainC_STD_FLAGS=$(C_STD_FLAGS) /DSTRING_ARRAY_NAME=$(BASE_NAME)StringsC_STD_FLAGS=$(C_STD_FLAGS)/DSTRING_DEFINES_FILE=\"$(BASE_NAME)StrDefs.h\"C_STD_FLAGS=$(C_STD_FLAGS) /DEFI_BOOTSHELLOutput:fs0:\> usevar “EFI, One generation ahead!”fs0:\> usevarThe content of variable 'SampleVar' is:EFI, One generation ahead!fs0:\> usevar -?USEVAR [string | -?]string - String will be written in variablenamed 'SampleVar'.-? - Display the help information.Examples:*To write a string into variable 'SampleVar':fs0:\> usevar "EFI, One generation ahead!"*To display the content of variable 'SampleVar':fs0:\> usevarThe content of variable 'SampleVar' is:EFI, One generation ahead!fs0:\> _Version 0.91 June 27, 2005 32

Composing an EFI Shell Application4.4 Writing an Application That Can Be EitherInternal Command or External Command4.4.1 Rules to FollowThese are the rules you must follow when writing a command that can be either an internalcommand or an external command:• Never make a direct call to shell core services. Instead, use SE or SE2 to access thoseservices.If a command is built as an external command, it will be an individual image from theshell.efi. Therefore, it does not make sense to directly call shell core services or to directlyaccess shell core data in a command that is expected to be external. Most of the useful servicesare encapsulated in SE and SE2, and should be enough.• Always process flag ‘-?’ to provide verbose help information.In a new EFI Shell, each internal command has to process flag ‘-?’ to provide verbose helpinformation output for itself. Therefore, if a command is expected to be internal it has toprocess flag ‘-?’.• Always provide a specific function to return the line help information of the command.The line help information is provided by each internal command through a specific functionthat has the following interface:EFI_STATUS XXXGetLineHelp (OUT CHAR16 **Str)Internal commands are responsible to return line help string through this function in variableStr.• Call GetExecutionBreak() to detect execution interruption. (Optional)If you want your command to be able to be interrupted during execution, you have to detect theinterruption signal by calling GetExecutionBreak() and exit your command if the returnvalue is true. An interruption signal can be issued by pressing the ESC key. Usually, if there isa time-consuming loop in your command, you need to place a statement to detect whether aninterruption signal happens so that the command can be terminated immediately. This is anoptional requirement and you do not have to implement it to make your command be able to beeither internal or external.• Process flag ‘-b’ to control the streaming of output. (Optional)Most of the help information of commands can not be held in one screen. Therefore, it isrecommended that all commands process flag ‘-b’ to automatically pause the standard output ifthe output content exceeds one screen size. This is an optional requirement. You do not have toimplement it to make your command be able to be either internal or external.Table 4-1 lists all the services exported by Shell Environment Services II (which has been enhancedand expanded in the new EFI Shell). These services can be very useful to write commands orapplications that need to interact with the shell core. NOTEImproper use of the services exported by Shell Environment Services II can damage the shell core.Version 0.91 June 27, 2005 33

Composing an EFI Shell ApplicationTable 4-1. Shell Environment Services IIService NameExecuteGetEnvGetMapGetProtCurDirFileMetaArgFreeFileListBatchIsActiveEnablePageBreakDisablePageBreakGetPageBreakSetKeyFilterGetKeyFilterGetExecutionBreakIsRootShellCloseConsoleProxyHandleEnumeratorInitNextSkipResetCloseGetNumProtocolInfoEnumeratorInitNextSkipResetCloseGetDeviceNameGetShellModeNameToPathGetFsNameFileMetaArgNoWildCardDelDupFileArgGetFsDevicePathDescriptionExecutes a command lineGets an environment variableGets the device path for the specified mapping nameGets the protocol name stringGets the current working directory in the specified deviceGenerates a list of files that match the input patternFrees the list generated by FileMetaArgReturns if it is in a scriptEnables screen output page breakDisables screen output page breakReturns if page break is enabledSets the filter mask that filters specific keysGets the filter maskReturns if ‘ESC’ has been pressed during execution.Returns if the current shell instance is the rootCloses the console proxy opened by current shellThe interface to manipulate all the handles in the systemInitializes the enumeratorNavigates to the next handle in the handle databaseSkips the current handleResets the enumeratorCloses the enumeratorGets the number of handles in the systemThe interface to get information of all the known protocolsInitializes the enumeratorNavigates to the next protocol information in the protocol information databaseSkips the current protocol informationResets the enumeratorCloses the enumeratorGets the devices name for the specified device handleGets the current running mode of shellTranslates the file path to device pathGets mapping name for the specified device pathGenerates a list of files that match the input string without wildcard-matchDeletes the duplicated files in list generated by FileMetaArg orFileMetaArgNoWildCardGets the device path for the specified mapping nameVersion 0.91 June 27, 2005 34

Composing an EFI Shell Application4.5 Switching Between Internal and External Commands NOTEInternal-only commands can only be internal. They are not able to be switched to be externalcommands.4.5.1 External to InternalFollow the steps below to switch an external command to an internal command:1. Put all the files of your external command (or application) under a sub-directory of the EFIShell source root directory in the release package. For example, if the root directory of the EDKis C:\EDK, you should put your source code directory underC:\EDK\Other\Maintained\Application\Shell (i.e.,C:\EDK\Other\Maintained\Application\Shell\Hello).2. Add lines into the section ‘sources.common’ of the shell.inf that is located under theEFI Shell source root directory, to include all the source files of your external command. Ifyour external command uses any .uni files, they should be included here and must be putahead of any .c files of your command. For example:Hello\HelloString.uniHello\Hello.c• The Hello at the beginning of the above two lines indicates the path relative to the EFIShell source directory.• If your external command (or application) uses any .h files, add lines into the section‘includes.common’ to indicate where the .h files can be found. For example, if fileHello.h is under C:\EDK\Other\Maintained\Application\Shell\Hello,then:$(EDK_SOURCE)\Other\Maintained\Application\Shell\Hello• Macro EDK_SOURCE represents the root directory of the EDK. It should be followed bythe relative path from the root where the .h files can be found.3. In file source\shellenv\cmddisp.c, declare the entry point function and line helpfunction of your external command ahead of the SEnvInternalCommands table.4. Add an entry for your external command into the SEnvInternalCommands table using thefollowing values in order: the entry point function, the internal command name, and the linehelp function. You must add the entry inside the #ifdef EFI_MONOSHELL…#endif block.5. After building the EFI Shell, your external command should have been added as an internalcommand.4.5.2 Internal to ExternalFollow the steps below to switch an internal command to an external command (or application):1. Write an .inf file for your external command (or application). Refer to section 4.2.2. Remove the lines for the internal command from the shell.inf file that is located under theEFI Shell source root directory.Version 0.91 June 27, 2005 35

Composing an EFI Shell Application3. Remove the declarations of entry point function and line help function fromOther\Maintained\Application\Shell\shellenv\cmddisp.c.4. Remove the entry for the internal command from the SEnvInternalCommands table.5. Use nmake to build the external command (mentioned in step 1).Version 0.91 June 27, 2005 36

5.1 Data Types and Global Variables5.1.1 EFI_SHELL_INTERFACE Data Type5EFI Shell Library IntroductionThis data type describes the environment handled by the shell core of the application. Only thefields which are related to application development are described in detail here.typedef struct _EFI_SHELL_ARG_INFO {UINT32Attributes;} EFI_SHELL_ARG_INFO;typedef struct _EFI_SHELL_INTERFACE {EFI_HANDLEImageHandle;EFI_LOADED_IMAGE_PROTOCOL *Info;CHAR16**Argv;UINTNArgc;CHAR16**RedirArgv;UINTNRedirArgc;EFI_FILE_HANDLEStdIn;EFI_FILE_HANDLEStdOut;EFI_FILE_HANDLEStdErr;EFI_SHELL_ARG_INFO*ArgInfo;BOOLEANEchoOn;} EFI_SHELL_INTERFACE;Data MembersArgvArguments array. A Unicode string array contains each argument string in thecommand line; the first one is the command name string.ArgcArgument count. The count of arguments in the command line including commandname string.ArgInfoAn array that is associated with Argv. Each argument has a corresponding elementin this array. The element is with type of EFI_SHELL_ARG_INFO. Currently thereis only one member called attributes in this structure. This structure is used todescribe some of the useful information about the argument when it was on thecommand line originally. The structure will be extended in the future if necessary.Currently available values for the attributes field are listed below.ARG_NO_ATTRIB(0x0, argument doesn’t have any attributes)Version 0.9 February, 2005 37

EFI Shell Library5.2 Initialization FunctionsThe initialization functions in the EFI Shell Library are used to initialize the execution environmentso that other EFI service functions may be used, and some of the key global variables can beaccessed. Table 5-1 lists the initialization support functions that are described in the followingsections.Table 5-1. Initialization FunctionsNameDescriptionLibInitializeShellApplication Initializes the EFI Shell Library.LibInitializeStringsInitializes the string package for each applicationLibUnInitializeStrings Uninstalls the string package if the application registered it.Version 0.91 June 27, 2005 39

EFI Shell Library5.2.1 LibInitializeShellApplication()SummaryInitializes the EFI shell execution environment for the application.PrototypeEFI_STATUSLibInitializeShellApplication (IN EFI_HANDLEIN EFI_SYSTEM_TABLE);ImageHandle,*SystemTableParametersImageHandleA handle of an image that is initializing the librarySystemTableA pointer to EFI system tableDescriptionThis function must be called at the very beginning of an application to enable the use of all the EFILibrary functions. If this function fails, the application will exit to the shell.Status Codes ReturnedEFI_SUCCESSEFI VersionEFI 1.02 or above.Initialize success.Version 0.91 June 27, 2005 40

EFI Shell Library5.2.2 LibInitializeStrings()SummaryRegisters the included string package to HII and returns the HII handle to the data. If previouslyregistered, the function simply returns the handle.PrototypeEFI_STATUSLibInitializeStrings (OUT EFI_HII_HANDLEIN UINT8IN EFI_GUID);*HiiHandle,*StringPack,*StringPackGuidParametersHiiHandleA pointer to the HII handle on which the string package resides.StringPackA pointer to an array which contains a structured string package.StringPackGuidA pointer to a GUID which specifies the string package.DescriptionThis function must be called to install the application’s string package (if the application needs touse strings; such as outputting strings).For more information about string packages, refer to the HII Spec.Status Codes ReturnedEFI_SUCCESSEFI_NOT_FOUNDEFI_INVALID_PARAMETEREFI VersionEFI 1.02 or above.Command completed successfully.Can’t find the HII Protocol.The parameters are not valid.Version 0.91 June 27, 2005 41

EFI Shell Library5.2.3 LibUnInitializeStrings()SummaryUninstalls the included string package for HII.PrototypeEFI_STATUSLibUnInitializeStrings (VOID);ParametersNoneDescriptionThis function must be called to uninstall the application’s string package it registered.Status Codes ReturnedEFI_SUCCESSEFI VersionEFI 1.02 or above.Command completed successfully.Version 0.91 June 27, 2005 42

EFI Shell Library5.3 String FunctionsThe string functions in the EFI Library perform operations on Unicode and ASCII strings.Table 5-2 contains the list of string support functions that are described in the following sections.Table 5-2. String FunctionsNameStrCmpStrnCmpStrCpyStrCatStrLenStrLwrStrUprXtoiAtoiLibDevicePathToStrStriCmpStrSizeStrDuplicatestrlenastrcmpastrncmpaStrSubCmpStrChrStrStrStrTrimDescriptionCompares two Unicode strings.Compares a portion of two Unicode strings.Copies one Unicode string to another Unicode string.Concatenates two Unicode strings.Returns the length of a Unicode string.Converts characters in a Unicode string to upper case characters.Converts characters in a Unicode string to lower case characters.Converts a hexadecimal formatted Unicode string to an integer.Converts a decimal formatted Unicode string to an integer.Converts a device path data structure into a Unicode string.Compares two Unicode strings case-insensitively.Returns the size of a Unicode string in bytes including NULL.Duplicates an Unicode string.Returns the length of an ASCII string.Compares two ASCII strings.Compares a portion of two ASCII strings.Performs a substring searching in NULL-terminated Unicode string.Gets a substring start from the specified character.Gets the index of the first occurrence of the specified pattern in the string.Removes (trims) specified leading and trailing characters from a string.Version 0.91 June 27, 2005 43

EFI Shell Library5.3.1 StrCmp()SummaryCompares two Unicode strings.PrototypeINTNStrCmp (IN CHAR16 *s1,IN CHAR16 *s2);Parameterss1s2DescriptionPointer to a Null-terminated Unicode string.Pointer to a Null-terminated Unicode string.This function compares the Unicode string s1 to the Unicode string s2. If s1 is identical to s2,then 0 is returned. Otherwise, the difference between the first mismatched Unicode characters isreturned.Status Codes Returned0 s1 is identical to s2.≠0 s1 is not identical to s2.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 44

EFI Shell Library5.3.2 StrnCmp()SummaryCompares a portion of two Unicode strings case-sensitively.PrototypeINTNStrnCmp (IN CHAR16IN CHAR16IN UINTN);*s1,*s2,lenParameterss1s2LenDescriptionPointer to a Null-terminated Unicode string.Pointer to a Null-terminated Unicode string.Number of Unicode characters to compare.This function compares Unicode characters from s1 to Unicode characters from s2. If allcharacters from s1 and s2 are identical, then 0 is returned. Otherwise, the difference between thefirst mismatched Unicode characters is returned.Status Codes Returned0 s1 is identical to s2.≠0 s1 is not identical to s2.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 45

EFI Shell Library5.3.3 StrCpy()SummaryCopies one Unicode string to another Unicode string.PrototypeVOIDStrCpy (OUT CHAR16IN CHAR16);*Dest,*SrcParametersDestSrcDescriptionPointer to a Null-terminated Unicode string.Pointer to a Null-terminated Unicode string.This function copies the contents of the Unicode string Src to the Unicode string Dest. The callershould ensure Dest is large enough to hold the whole Src; otherwise, a buffer overflow mayoccur.Status Codes ReturnedNoneEFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 46

EFI Shell Library5.3.4 StrCat()SummaryConcatenates one Unicode string to another Unicode string.PrototypeVOIDStrCat (IN OUT CHAR16 *Dest,IN CHAR16 *Src);ParametersDestSrcDescriptionPointer to a Null-terminated Unicode string.Pointer to a Null-terminated Unicode string.This function concatenates two Unicode strings. The contents of Unicode string Src areconcatenated to the end of Unicode string Dest. The caller should ensure Dest is large enough tohold both strings and a Null-terminator; otherwise, a buffer overflow may occur.Status Codes ReturnedNoneEFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 47

EFI Shell Library5.3.5 StrLen()SummaryDetermines the length of a Unicode string.PrototypeUINTNStrLen (IN CHAR16 *s1);Parameterss1DescriptionPointer to a Null-terminated Unicode string.Returns the number of Unicode characters in the Unicode string s1, excluding the Null terminator.Status Codes Returned≥0 The length of string s1.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 48

EFI Shell Library5.3.6 StrLwr()SummaryConverts all the characters in a Unicode string to lower case.PrototypeVOIDStrLwr (IN OUT CHAR16);*StrParametersStrPointer to a Null-terminated Unicode string.DescriptionThis function converts all the characters in the Unicode string Str to lower case characters.Status Codes ReturnedNoneEFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 49

EFI Shell Library5.3.7 StrUpr()SummaryConverts all the characters in a Unicode string to upper case.PrototypeVOIDStrUpr (IN OUT CHAR16);*StrParametersStrPointer to a Null-terminated Unicode string.DescriptionThis function converts all the characters in the Unicode string Str to upper case characters.Status Codes ReturnedNoneEFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 50

EFI Shell Library5.3.8 Xtoi()SummaryConverts a hexadecimal formatted Unicode string to a value.PrototypeUINTNXtoi (IN CHAR16);*strParametersStrDescriptionPointer to a Null-terminated Unicode string.This function converts the hexadecimal formatted Unicode string str into an unsigned integer andreturns that integer. Any preceding white space character in str is ignored. The input string is asequence of Unicode characters that can be interpreted as a hexadecimal value of the specified type.The function stops reading the input string at the first Unicode character that it cannot recognize aspart of a number and returns the unsigned integer that has been converted. This Unicode charactermay be the Null character terminating the string. If no Unicode character is converted, then 0 willbe returned.The str argument has the following form: [whitespace] [0x] [characters], wherecharacters are one or more hexadecimal characters (‘0’-‘9’, ‘a’-‘f’, ‘A’-‘F’). This function canonly convert the string within the range of 0 to (UINTN-1). If the value is out of range, then(UINTN-1) will be returned.Status Codes Returned≥0EFI VersionEFI 1.02 or above.A UINTN number that the string str expresses.Version 0.91 June 27, 2005 51

EFI Shell Library5.3.9 Atoi()SummaryConverts a decimal formatted Unicode string to a value.PrototypeUINTNAtoi (IN CHAR16);*strParametersStrDescriptionPointer to a Null-terminated Unicode string.This function converts the decimal formatted Unicode string str into an unsigned integer andreturns that integer. Any preceding white space character in str is ignored. The input string is asequence of Unicode characters that can be interpreted as a numerical value of the specified type.The function stops reading the input string at the first Unicode character that it cannot recognize aspart of a number and returns the unsigned integer that has been converted. This Unicode charactermay be the null character terminating the string. If no Unicode character is converted, then 0 will bereturned.The str argument has the following form: [whitespace] [digits], where digits are one ormore decimal digits. This function can only convert the string within the range of 0 to (UINTN-1). If the value is out of range, then (UINTN-1) will be returned.Status Codes Returned≥0EFI VersionEFI 1.02 or above.A UINTN number that the string str expresses.Version 0.91 June 27, 2005 52

EFI Shell Library5.3.10 LibDevicePathToStr()SummaryConverts a device path data structure into a printable Null-terminated Unicode string.PrototypeCHAR16 *LibDevicePathToStr (IN EFI_DEVICE_PATH);*DevPathParametersDevPathA pointer to a device path data structure.DescriptionThis function converts a device path data structure into a Null-terminated Unicode string. Thememory for the Unicode string is allocated from pool, and a pointer to the Unicode string isreturned. Table 5-3 through Table 5-6 show the conversions from the different device path typesinto printable strings. Device path nodes are separated by a ‘\’ and device path instances areseparated by a ‘,’.Status Codes Returned≥0A string that the DevPath expresses.Table 5-3. Hardware Device Path Output FormatsHardware Device Path Type Output FormatPCI Device Path“Pci(||)”PCCARD Device Path“Pccard(Function)”Vendor Device Path“VenHw()”Vendor Device Path(Legacy) “VenHw(:)”ACPI Device Path“Acpi(,)”ACPI Device Path(EISA)“Acpi(PNP,)”Unknown “?”Table 5-4. Messaging Device Path Output FormatsMessaging Device Path Type Output FormatATAPI Master“ATA(Master,)”ATAPI Slave“ATA(Slave,)”Version 0.91 June 27, 2005 53

EFI Shell LibraryMessaging Device Path Type Output FormatSCSI“Scsi(,)”FibreChannel“Fibre()1394 “1394()”USB“Usb()”I2O“I2O()”TCPIP“Tcpip()”TCPIPv6"Tcpip-v6()"NGIO“Ngio(Mac,)”Vendor“VenMsg()”Vendor(Legacy)“VenMsg(:)”Unknown “?”Table 5-5. Media Device Path Output FormatsMedia Device Path Type Output FormatHard Drive“HD(Part,Sig)”CDROM“CDROM(Entry)”Vendor“VenMedia()”Vendor(Legacy)“VenMedia(:)”FilePath“”Protocol""Unknown “?”Table 5-6. BBS Device Path Output FormatsBBS Device Path TypeOutput FormatFloppy“Floppy”HardDrive“Harddrive”CDROM“CDROM”PCMCIA“PCMCIA”USB“USB”Embedded Network“Net”Other “?”Unknown “?”EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 54

EFI Shell Library5.3.11 StriCmp()SummaryCompares two Unicode strings case-insensitively.PrototypeINTNStriCmp (IN CHAR16 *s1,IN CHAR16 *s2);Parameterss1S2DescriptionPointer to a Null-terminated Unicode string.Pointer to a Null-terminated Unicode string.This function compares the Unicode string s1 to the Unicode string s2. If s1 is identical to s2case-insensitively, then 0 is returned. Otherwise, the difference between the first mismatchedUnicode characters is returned.Status Codes Returned0 s1 is identical to s2.≠0 s1 is not identical to s2.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 55

EFI Shell Library5.3.12 StrSize()SummaryReturns the size of a Unicode string in bytes including NULL end.PrototypeUINTNStrSize (IN CHAR16 *s1);Parameterss1DescriptionPointer to a Null-terminated Unicode string.This function returns the size of a Unicode string in bytes including NULL end.Status Codes Returned≥0 The size of string s1.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 56

EFI Shell Library5.3.13 StrDuplicate()SummaryDuplicates a Unicode string.PrototypeCHAR16*StrDuplicate (IN CHAR16);*StrParametersStrDescriptionPointer to a Null-terminated Unicode string.This function returns the copy of a Unicode string. It is the caller’s responsibility to free thereturned string.Status Codes Returned≠NULLNULLEFI VersionEFI 1.02 or above.A pointer to the new string.Cannot allocate memory for new string.Version 0.91 June 27, 2005 57

EFI Shell Library5.3.14 Strlena()SummaryReturns the length of an ASCII string.PrototypeUINTNstrlena (IN CHAR8 *s1);Parameterss1DescriptionPointer to a Null-terminated ASCII string.This function returns the length of an ASCII string, excluding the Null terminator.Status Codes Returned≥0 The length of the ASCII string s1.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 58

EFI Shell Library5.3.15 Strcmpa()SummaryCompares two ASCII strings case-sensitively.PrototypeUINTNstrcmpa (IN CHAR8 *s1,IN CHAR8 *s2);Parameterss1S2DescriptionPointer to a Null-terminated ASCII string.Pointer to a Null-terminated ASCII string.This function compares the ASCII string s1 to the ASCII string s2. If s1 is identical to s2, then 0is returned.Status Codes Returned0 s1 is identical to s2.≠0 s1 is not identical to s2.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 59

EFI Shell Library5.3.16 Strncmpa()SummaryCompares a portion of two ASCII strings case-sensitively.PrototypeUINTNstrcmpa (IN CHAR8IN CHAR8IN UINTN);*s1,*s2,lenParameterss1S2LenDescriptionPointer to a Null-terminated ASCII string.Pointer to a Null-terminated ASCII string.The length of the portion of string that will be compared.This function compares the ASCII string s1 to the ASCII string s2; at most, the first characters ins1 and s2 will be compared.Status Codes Returned0 The first characters in s1 and are identical.≠0 s1 is not identical to s2.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 60

EFI Shell Library5.3.17 StrSubCmp()SummaryPerforms a substring searching in a Null-terminated Unicode strings, case sensitively.PrototypeBOOLEANStrSubCmp (IN CHAR16IN CHAR16IN UINTN);*s1,*s2,lenParameterss1S2LenDescriptionPointer to a Null-terminated Unicode substring to be searched for.Pointer to a Null-terminated Unicode string to be searched in.Compares size.This function searches substring s1 in string s2 case sensitively. If s1 is found in s2 it returnsTRUE, otherwise FALSE.Status Codes ReturnedTRUEFound s1 in s2FALSE Can not find s1 in s2.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 61

EFI Shell Library5.3.18 StrChr()SummaryGets a substring start from the specified character, case sensitively.PrototypeCHAR16 *StrChr(IN CHAR16IN CHAR16);*Str,cParametersStrCDescriptionPointer to a Null-terminated Unicode string.A Unicode character.If success, returns the address of the first occurrence of the specified character in the str; if notreturns NULL.Status Codes Returned≠NULLNULLEFI VersionEFI 1.02 or above.The substring.The substring does not exist.Version 0.91 June 27, 2005 62

EFI Shell Library5.3.19 StrStr()SummaryGets the index of the first occurrence of the specified pattern in the string case sensitively.PrototypeUINTNStrStr (IN CHAR16IN CHAR16);*Str,*PatParametersStrPatDescriptionPointer to a Null-terminated Unicode string.Pointer to a Null-terminated Unicode string.If found, the Pat in the Str returns the first position (starting from 1) of the Pat’s occurrence; ifnot found it returns 0.Status Codes Returned0 Not found.>0 The index is (return value – 1).EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 63

EFI Shell Library5.3.20 StrTrim()SummaryRemoves (trims) specified leading and trailing characters from a string.PrototypeVOIDStrTrim (IN OUT CHAR16IN CHAR16);*str,cParametersStrCPointer to the Null-terminated string to be trimmed. On return, str will hold thetrimmed string.Status Codes ReturnedNoneDescriptionCharacter that will be trimmed from str.The string pointed to by str will be modified on return if there are leading and/or endingcharacters of c.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 64

EFI Shell Library5.4 Memory Support FunctionsThe EFI Shell Library provides a set of functions that operate on buffers in memory. Buffers caneither be allocated on the stack, as global variables, or from the memory pool. To prevent memoryleaks, it is the caller’s responsibility to maintain buffers allocated from pool. This means that thecaller must free a buffer when that buffer is no longer needed. Table 5-7 contains the list ofmemory support functions that are described in the following sections.Table 5-7. Memory Support FunctionsNameSetMemCopyMemCompareMemAllocatePoolFreePoolAllocateZeroPoolDescriptionFills a buffer with a value.Copies the contents of one buffer to another buffer.Compares the contents of two buffers.Allocates a buffer from pool.Frees a previously allocated buffer.Allocates pool memory and initializes the memory to zeros.Version 0.91 June 27, 2005 65

EFI Shell Library5.4.1 SetMem()SummaryFills a buffer with a specified value.PrototypeVOIDSetMem (IN OUT VOID *Buffer,IN UINTN Size,IN UINT8 Value);ParametersBufferPointer to the buffer to fill.SizeNumber of bytes in the buffer to fill.ValueValue to fill buffer with.DescriptionThis function fills Size bytes of Buffer with Value.Status Codes ReturnedNoneEFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 66

EFI Shell Library5.4.2 CopyMem()SummaryCopies the contents of one buffer to another buffer.PrototypeVOIDCopyMem (IN VOIDIN VOIDIN UINTN);*Dest,*Src,LenParametersDestSrcLenDescriptionPointer to the destination buffer of the memory copy.Pointer to the source buffer of the memory copy.Number of bytes to copy from Src to Dest.This function copies bytes from the buffer Src to the buffer Dest. It can deal with the case of thesource and destination buffers overlapping. The caller should ensure Dest is large enough to holdbytes of Src; otherwise, a buffer overflow may occur.Status Codes ReturnedNoneEFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 67

EFI Shell Library5.4.3 CompareMem()SummaryCompares the contents of two buffers.PrototypeINTNCompareMem (IN VOIDIN VOIDIN UINTN);*Dest,*Src,LenParametersDestSrcLenDescriptionPointer to the buffer to compare.Pointer to the buffer to compare.Number of bytes to compare.This function compares Len bytes of Src to Len bytes of Dest. If the two buffers are identical forLen bytes, then 0 is returned. Otherwise, the difference between the first two mismatched bytes isreturned. A positive return number indicates the first unmatched byte in Dest is greater than thecorresponding byte in Src, while a negative return number indicates the first unmatched byte inSrc is greater than the corresponding byte in Dest.Status Codes Returned0 Dest is identical to Src for Len bytes.>0 Dest is not identical to Src for Len bytesEFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 68

EFI Shell Library5.4.4 AllocatePool()SummaryAllocates a buffer from memory with type PoolAllocationType.PrototypeVOID *AllocatePool (IN UINTN);Size≠NULLParametersSizeDescriptionThe size of the buffer to allocate from pool.This function attempts to allocate Size bytes from memory with type PoolAllocationType.If the memory allocation fails, NULL is returned. Otherwise a pointer to the allocated buffer isreturned. Here PoolAllocationType is defined as EfiBootServicesData.Status Codes ReturnedAllocation succeeded and the base pointer is returned.NULLAllocation failed.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 69

EFI Shell Library5.4.5 FreePool()SummaryReleases a previously allocated buffer.PrototypeVOIDFreePool (IN VOID);*PointerParametersPointerA pointer to the buffer to be freed.DescriptionThis function frees the buffer that has been previously allocated with AllocatePool(). Thefreed memory is returned to the available pool. The Pointer must be a pointer returned byAllocatePool() in the previous calling. If the Pointer has been freed or is not a pointerallocated by AllocatePool(), an exception may be generated.Status Codes ReturnedNoneEFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 70

EFI Shell Library5.4.6 AllocateZeroPool()SummaryAllocates pool memory and initializes the memory to zeros.PrototypeVOID *AllocateZeroPool (IN UINTN);SizeParametersSizeDescriptionSize in bytes of the pool being requested.This function attempts to allocate Size bytes from memory with type PoolAllocationTypeand initialize the memory area with zero. If the memory allocation fails, NULL is returned;otherwise a pointer to the allocated buffer is returned. Here PoolAllocationType is defined asEfiBootServicesData.Status Codes Returned≠NULLNULLEFI VersionEFI 1.02 or above.The pointer to the memory space that the requested number of bytes were allocated.The pool requested could not be allocated.Version 0.91 June 27, 2005 71

EFI Shell Library5.5 FILE I/O FUNCTIONSThe EFI Shell Library provides a set of functions that operate on file I/O. Table 5-8 lists the file I/Osupport functions that are described in the following sections. For more information aboutEFI_FILE_INFO and EFI_FILE please refer to EFI specification.Table 5-8. File I/O FunctionsNameLibGetFileInfoLibSetFileInfoLibOpenFileLibOpenFileByNameLibCreateDirectoryLibReadFileLibWriteFileLibCloseFileLibDeleteFileLibSetPositionLibGetPositionLibFlushFileLibFindFirstFileLibFindNextFileLibGetFileSizeLibFileDevicePathDescriptionGets the file information from an open file handle, and stores it in a bufferallocated from pool.Sets the file information to an open file handle.Opens a file.Opens a file by the file name.Creates a directory by the directory name.Reads data from the file.Writes data to the file.Closes the file handle.Closes and deletes the file handle.Sets a file’s current position.Gets a file’s current position.Flushes data back to the file handle.Gets the first file in a directory.Gets the next file in a directory.Gets the size of a file.Allocates a device path for a file and appends it to an existing device path.Version 0.91 June 27, 2005 72

EFI Shell Library5.5.1 LibGetFileInfo()SummaryGets the file information from an open file handle, and stores it in a buffer allocated from pool.PrototypeEFI_FILE_INFO *LibGetFileInfo (IN EFI_FILE_HANDLE);FileHandleParametersFileHandleA file handle.DescriptionThis function allocates a buffer to store the file’s information. It is the caller’s responsibility to freethe buffer allocated by LibGetFileInfo().Status Codes Returned≠NULLNULLEFI VersionEFI 1.02 or above.A pointer to a buffer with file information.Can not get the file info.Version 0.91 June 27, 2005 73

EFI Shell Library5.5.2 LibSetFileInfo()SummarySets the file information to an opened file handle.PrototypeEFI_STATUSLibSetFileInfo (IN EFI_FILE_HANDLEIN UINTNIN VOID);FileHandle,BufferSize,*BufferParametersFileHandleA file handle.BufferSizeThe size of the file info.BufferA pointer to the buffer where the file info will be stored.DescriptionThis function sets information of type EFI_FILE_INFO on the file handle. The data bufferpointer by Buffer must be a structure of type EFI_FILE_INFO.Status Codes ReturnedEFI_SUCCESSEFI_NO_MEDIAEFI_DEVICE_ERRORThe information was set.The device has no medium.The device reported an error.EFI_VOLUME_CORRUPTED The file system structures are corrupted.EFI_WRITE_PROTECTEDEFI_ACCESS_DENIEDEFI_VOLUME_FULLEFI_BAD_BUFFER_SIZEEFI VersionEFI 1.02 or above.The file or medium is write-protected.The file was opened read-only.The volume is full.BufferSize is smaller than the size of EFI_FILE_INFOVersion 0.91 June 27, 2005 74

EFI Shell Library5.5.3 LibOpenFile()SummaryOpens a file or a directory.PrototypeEFI_STATUSLibOpenFile(IN OUT EFI_DEVICE_PATH_PROTOCOLOUT EFI_HANDLEOUT EFI_FILE_HANDLEIN UINT64IN UINT64);**FilePath,*DeviceHandle,*FileHandle,OpenMode,AttributesParametersFilePathOn input, a pointer to the file path. On output, the file path pointer is modified topoint to the remaining part of the file path.DeviceHandleA pointer to the file system device handle.FileHandleA pointer to the opened file handle.OpenModeFile open mode.AttributesThe file’s File attributes.DescriptionThis function opens a file with the open mode according to the file path. The Attributes isvalid only for EFI_FILE_MODE_CREATE.Status Codes ReturnedEFI_SUCCESSEFI_INVALID_PARAMETEREFI_UNSUPPORTEDEFI_NOT_FOUNDEFI_NO_MEDIAEFI_MEDIA_CHANGEDThe file was opened.One of the parameters has an invalid value.Could not open the file path.The specified file could not be found on the device or the file system couldnot be found on the device.The device has no medium.The device has a different medium in it or the medium is no longerVersion 0.91 June 27, 2005 75

EFI Shell LibraryEFI_DEVICE_ERRORsupported.The device reported an error.EFI_VOLUME_CORRUPTED The file system structures are corrupted.EFI_WRITE_PROTECTEDEFI_ACCESS_DENIEDAn attempt was made to create a file, or to open a file for writing, when themedia is write protected.The service denied access to the file.EFI_OUT_OF_RESOURCES Not enough resources were available to open the file.EFI_VOLUME_FULLEFI VersionEFI 1.02 or above.The volume is full.Version 0.91 June 27, 2005 76

EFI Shell Library5.5.4 LibOpenFileByName()SummaryOpens a file or a directory by file name.PrototypeEFI_STATUSLibOpenFileByName(IN CHAR16OUT EFI_FILE_HANDLEIN UINT64IN UINT64);*FileName,*FileHandle,OpenMode,AttributesParametersFileNameA pointer to the file name.FileHandleA pointer to the opened file handle.OpenModeFile open mode.AttributesThe file’s File attributes.DescriptionIf return is EFI_SUCCESS, the Filehandle is the opened file’s handle; otherwise, theFilehandle is NULL. The Attributes is valid only for EFI_FILE_MODE_CREATE.Status Codes ReturnedEFI_SUCCESSEFI_INVALID_PARAMETEREFI_UNSUPPORTEDEFI_NOT_FOUNDEFI_NO_MEDIAEFI_MEDIA_CHANGEDEFI_DEVICE_ERRORThe file was opened.One of the parameters has an invalid value.Could not open the file path.The specified file could not be found on the device or the file system couldnot be found on the device.The device has no medium.The device has a different medium in it or the medium is no longersupported.The device reported an error or cannot get the file path according to theFileNameEFI_VOLUME_CORRUPTED The file system structures are corrupted.Version 0.91 June 27, 2005 77

EFI Shell LibraryEFI_WRITE_PROTECTEDEFI_ACCESS_DENIEDAn attempt was made to create a file, or to open a file for writing, when themedium is write protected.The service denied access to the file.EFI_OUT_OF_RESOURCES Not enough resources were available to open the file.EFI_VOLUME_FULLEFI VersionEFI 1.02 or above.The volume is full.Version 0.91 June 27, 2005 78

EFI Shell Library5.5.5 LibCreateDirectory()SummaryCreates a directory of the directory names.PrototypeEFI_STATUSLibCreateDiectory(IN CHAR16OUT EFI_FILE_HANDLE);*DirName,*FileHandleParametersDirNameA pointer to the directory name.FileHandleA pointer to the opened directory handle.DescriptionIf return is EFI_SUCCESS, the FileHandle is the directory’s handle; otherwise, theFilHandle is NULL. If the file has already existed, this function opens this directory.Status Codes ReturnedEFI_SUCCESSEFI_INVALID_PARAMETEREFI_UNSUPPORTEDEFI_NOT_FOUNDEFI_NO_MEDIAEFI_MEDIA_CHANGEDEFI_DEVICE_ERRORThe file was opened.One of the parameters has an invalid value.Could not open the file path.The specified file could not be found on the device or the file system couldnot be found on the device.The device has no media.The device has a different medium in it or the medium is no longersupported.The device reported an error or cannot get the file path according to theDirNameEFI_VOLUME_CORRUPTED The file system structures are corrupted.EFI_WRITE_PROTECTEDEFI_ACCESS_DENIEDAn attempt was made to create a file, or to open a file for writing, when themedia is write protected.The service denied access to the file.EFI_OUT_OF_RESOURCES Not enough resources were available to open the file.EFI_VOLUME_FULLThe volume is full.Version 0.91 June 27, 2005 79

EFI Shell LibraryEFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 80

EFI Shell Library5.5.6 LibReadFile()SummaryReads data from the file.PrototypeEFI_STATUSLibReadFile (IN EFI_FILE_HANDLEIN OUT UINTNOUT VOID);FileHandle,*ReadSize,*BufferParametersFileHandleThe opened file handle for reading.ReadSizeOn input, the size of Buffer. On output, the amount of data in Buffer. In bothcases, the size is measured in bytes.BufferThe buffer in which data is read.DescriptionIf FileHandle is not a directory, the function reads the requested number of bytes from the fileat the file’s current position and returns them in Buffer. If the read goes beyond the end of thefile, the read length is truncated to the end of the file. The file’s current position is increased by thenumber of bytes returned.If FileHandle is a directory, the function reads the directory entry at the file’s current positionand returns the entry in Buffer. If the Buffer is not large enough to hold the current directoryentry, then EFI_BUFFER_TOO_SMALL is returned and the current file position is not updated.BufferSize is set to be the size of the buffer needed to read the entry. On success, the currentposition is updated to the next directory entry. If there are no more directory entries, the readreturns a zero-length buffer. EFI_FILE_INFO is the structure returned as the directory entry.Status Codes ReturnedEFI_SUCCESSEFI_NO_MEDIAEFI_DEVICE_ERROREFI_VOLUME_CORRUPTEDEFI_BUFFER_TO_SMALLData was read.The device has no media.The device reported an error.The file system structures are corrupted.Buffer is too small. ReadSize contains required size.Version 0.91 June 27, 2005 81

EFI Shell LibraryEFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 82

EFI Shell Library5.5.7 LibWriteFile()SummaryWrites data to the file.PrototypeEFI_STATUSLibWriteFile(IN EFI_FILE_HANDLEIN OUT UINTNOUT VOID);FileHandle,*BufferSize,*BufferParametersFileHandleThe opened file handle for writing.BufferSizeOn input, size of Buffer. On output, the amount of data in Buffer.In both cases,the size is measured in bytes.BufferThe buffer in which data is written.DescriptionThis function writes the specified number of bytes to the file at the current file position. The currentfile position is advanced the actual number of bytes written, which is returned in BufferSize.Partial writes only occur when there has been a data error during the write attempt (such as“volume space full”). The file is automatically grown to hold the data if required. Direct writes toopened directories are not supported.Status Codes ReturnedEFI_SUCCESSEFI_UNSUPPORTEDEFI_NO_MEDIAEFI_DEVICE_ERROREFI_VOLUME_CORRUPTEDEFI_WRITE_PROTECTEDEFI_ACCESS_DENIEDEFI_VOLUME_FULLData was written.Writes to an open directory are not supported.The device has no media.The device reported an error.The file system structures are corrupted.The device is write-protected.The file was open for read only.The volume is full.Version 0.91 June 27, 2005 83

EFI Shell LibraryEFI VersionEFI 1.02 or above.5.5.8 LibCloseFile()SummaryCloses the file handle.PrototypeEFI_STATUSLibCloseFile (IN EFI_FILE_HANDLE);FileHandleParametersFileHandleThe file handle to be closed.DescriptionThis function closes a specified file handle. All “dirty” cached file data is flushed to the device, andthe file is closed. In all cases the handle is closed.Status Codes ReturnedEFI_SUCCESSEFI VersionEFI 1.02 or above.The file was closed successfully.Version 0.91 June 27, 2005 84

EFI Shell Library5.5.9 LibDeleteFile()SummaryCloses and deletes the file handle.PrototypeEFI_STATUSLibDeleteFile (IN EFI_FILE_HANDLE);FileHandleParametersFileHandleThe file handle to delete.DescriptionThis function closes and deletes a file. In all cases the file handle is closed. If the file cannot bedeleted, the warning code EFI_WARN_DELETE_FAILURE is returned, but the handle is stillclosed.Status Codes ReturnedEFI_SUCCESSEFI_WARN_DELETE_FAILUREThe file was closed and deleted, and the handle was closed.The handle was closed but the file was not deleted.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 85

EFI Shell Library5.5.10 LibSetPosition()SummarySets a file’s current position.PrototypeEFI_STATUSLibSetPosition (IN EFI_FILE_HANDLEIN UINT64);FileHandle,PositionParametersFileHandleThe file handle on which the requested position will be set.PositionByte position from the start of the fileDescriptionThis function sets the current file position for the handle to the position supplied. With theexception of seeking to position 0xFFFFFFFFFFFFFFFF, only absolute positioning is supported,and seeking past the end of the file is allowed (a subsequent write would grow the file). Seeking toposition 0xFFFFFFFFFFFFFFFF causes the current position to be set to the end of the file.If FileHandle is a directory, the only position that may be set is zero. This has the effect ofstarting the read process of the directory entries over.Status Codes ReturnedEFI_SUCCESSEFI_UNSUPPORTEDData was written.The seek request for nonzero is not valid on open directories.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 86

EFI Shell Library5.5.11 LibGetPosition()SummaryGets a file’s current positionPrototypeEFI_STATUSLibGetPosition (IN EFI_FILE_HANDLEOUT UINT64);FileHandle,*PositionParametersFileHandleThe file handle on which to get the current position.PositionByte position from the start of the fileDescriptionThis function returns the current file position for the file handle. For directories, the current fileposition has no meaning outside of the file system driver and as such the operation is not supported.An error is returned if FileHandle is a directory.Status Codes ReturnedEFI_SUCCESSEFI_UNSUPPORTEDData was accessed.The request is not valid on open directories.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 87

EFI Shell Library5.5.12 LibFlushFile()SummaryFlushes data back to a devicePrototypeEFI_STATUSLibFlushFile (IN EFI_FILE_HANDLE);FileHandleParametersFileHandleThe file handle to flush.DescriptionThis function flushes all modified data associated with a file to a device.Status Codes ReturnedEFI_SUCCESSEFI_NO_MEDIAEFI_DEVICE_ERROREFI_VOLUME_CORRUPTEDEFI_WRITE_PROTECTEDEFI_ACCESS_DENIEDEFI_VOLUME_FULLThe data was flushed.The device has no media.The device reported an error.The file system structures are corrupted.The file or medium is write protected.The file was opened for read-only.The volume is full.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 88

EFI Shell Library5.5.13 LibFindFirstFile()SummaryGets the first file in a directory.PrototypeEFI_STATUSLibFindFirstFile(IN EFI_FILE_HANDLEOUT EFI_FILE_INFO);DirHandle,*BufferParametersDirhandleThe handle of the directory to search in.BufferThe pointer to the buffer containing the first file’s info.DescriptionThis function opens a directory and gets the first file’s info in the directory. Caller can useLibFindNextFile() to get other files.Status Codes ReturnedEFI_SUCCESSEFI_NOT_FOUNDEFI_NO_MEDIAEFI_DEVICE_ERROREFI_VOLUME_CORRUPTEDFound the first file.Cannot find the directory.The device has no media.The device reported an error.The file system structures are corrupted.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 89

EFI Shell Library5.5.14 LibFindNextFile()SummaryGets the next file in a directory.PrototypeEFI_STATUSLibFindNextFile(IN EFI_FILE_HANDLEOUT EFI_FILE_INFOOUT BOOLEAN);DirHandle,*Buffer,*NoFileParametersDirHandleThe handle of the directory to search in.BufferA pointer to the buffer containing the file info.NoFileDetermines whether there are files that can be gotten or not.DescriptionTo use this function, caller must call the LibFindFirstFile() to get the first file, and then usethis function get other files. This function can be called for several times to get each file'sinformation in the directory. If the call of LibFindNextFile() got the last file in the directory,the next call of this function has no file to get. *NoFile will be set to TRUE and the data inBuffer is meaningless.Status Codes ReturnedEFI_SUCCESSEFI_NO_MEDIAEFI_DEVICE_ERROREFI_VOLUME_CORRUPTEDFound the next file.The device has no media.The device reported an error.The file system structures are corrupted.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 90

EFI Shell Library5.5.15 LibGetFileSize()SummaryGets the size of a file.PrototypeEFI_STATUSLibGetFileSize(IN EFI_FILE_HANDLEOUT UINT64);FileHandle,*SizeParametersFileHandleThe handle of the file.SizeThe size of this file.DescriptionThis function extracts the file size info from the FileHandle’s EFI_FILE_INFO data.Status Codes ReturnedEFI_SUCCESSEFI_DEVICE_ERRORGot the file’s size.Cannot access the file.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 91

EFI Shell Library5.5.16 LibFileDevicePath()SummaryAllocates a device path for a file.PrototypeEFI_DEVICE_PATH_PROTOCOL *LibFileDevicePath (IN EFI_HANDLEDevice OPTIONAL,IN CHAR16*FileName);ParametersDeviceA pointer to a device handle.FileNameA pointer to a Null-terminated Unicode string.DescriptionIf Device is not a valid device handle, then a device path for the file specified by FileName isallocated and returned. This function allocates a buffer to store the device path. It is the caller’sresponsibility to free the buffer allocated by LibFileDevicePath().Status Codes Returned≠NULLNULLEFI VersionEFI 1.02 or above.Device path successfully created.Cannot create path.Version 0.91 June 27, 2005 92

EFI Shell Library5.6 Text I/O FunctionsThe Text I/O functions in the EFI Library provide a simple means to get input and output from aconsole device. Both of the active console-in and console-out devices can be located in the EFIsystem table.Many of the output functions use a format string to describe how to format the output of variablearguments. The format string consists of normal text and argument descriptors. There are norestrictions for how the normal text and argument descriptors can be mixed. Each argumentdescriptor is of the form “%w.lF’, where ‘w’ is an optional integer value that represents theargument width parameter, ‘l’ is an optional integer value that represents the field width parameter,and ‘F’ is a set of optional field modifiers and the data type of the argument to print. Table 5-9 liststhe optional field modifiers and arguments types.Table 5-9. Format String Attribute and Argument SpecificationName Description0 Pads the field with zeros- Left justifies the argument in the field., Inserts commas in a decimal formatted integer.* The field width is provided as an argument.nSets the output attribute for this field to normal.hSets the output attribute for this field to highlight.eSets the output attribute for this field to error.lThe argument value is 64 bits. The default is a 32-bit argument.aThe argument is an ASCII string.sThe argument is a Unicode string.XPrints the argument as a hexadecimal value padded with zeros. The field width defaults to8 for 32-bit arguments, and 16 for 64-bit arguments.xPrints the argument as a hexadecimal value.dPrints the argument as a decimal value with optional commas.cThe argument is a Unicode character.tThe argument is a pointer to an EFI_TIME data structuregThe argument is a pointer to an EFI_GUID data structure.rThe argument is an EFI_STATUS value.NSets the output attribute to normal.HSets the output attribute to highlight.ESets the output attribute to error.% Prints a %Version 0.91 June 27, 2005 93

EFI Shell LibraryNameInputOutputPrintPrintAtSprintPrintTokenTable 5-10 contains the list of Text I/O functions that are described in the following sections.Table 5-10. Text I/O FunctionsDescriptionInputs a Unicode string at the current cursor location using the console-in and console-outdevices.Sends a Unicode string to the console-out device at the current cursor location.Sends a formatted Unicode string to the console-out device at the current cursor location..Sends a formatted Unicode string to the specified location on the console-out device.Sends a formatted Unicode string to the specified buffer.Sends a HII token to the specified output device.Version 0.91 June 27, 2005 94

EFI Shell Library5.6.1 Input()Summaryreads a Unicode string from the system console in device at the current cursor location.PrototypeVOIDInput (IN CHAR16OUT CHAR16IN UINTN);*Prompt OPTIONAL,*InStr,StrLenParametersPromptA pointer to a Unicode string.InStrA pointer to the Unicode string used to store the string read from the console-indevice.StrLenThe maximum length of the Unicode string to read from the console-in device.DescriptionIf Prompt is not NULL, then Prompt is displayed on the console-out device. Then, characters areread from the console-in device and displayed on the console-out device. In addition, thesecharacters are stored in InStr until either a ‘\n’ or a ‘\r’ character is received. If the backspace keyis pressed, then the last character in InStr is removed, and the display is updated to show that thecharacter has been erased. If more than StrLen characters are received, then the extra charactersare ignored.Status Codes ReturnedNoneEFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 95

EFI Shell Library5.6.2 Output()SummarySends a Unicode string to the system console-out device at the current cursor location.PrototypeVOIDOutput (IN CHAR16);*StrParametersStrA pointer to a Unicode string.DescriptionThis function sends the Unicode string Str to the console-out device specified in the system table.Status Codes ReturnedNoneEFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 96

EFI Shell Library5.6.3 Print()SummarySends a formatted Unicode string to the console-out device at the current cursor location.PrototypeUINTNPrint (IN CHAR16...);*fmt,Parametersfmt...DescriptionA pointer to a Unicode string containing format information.Variable length argument list.This function uses the format string fmt and the variable length argument list to build a formattedUnicode string. The size of this formatted Unicode string, including an additional null character, isno more than StrSize.Status Codes Returned≥0The length of the formatted string.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 97

EFI Shell Library5.6.4 PrintAt()SummarySends a formatted Unicode string to the console-out device at the specified cursor location.PrototypeUINTNPrintAt (IN UINTNIN UINTNIN CHAR16...);Column,Row,*fmt,ParametersColumnThe column number on the console-out device.RowThe row number on the console-out device.FmtA pointer to a Unicode string containing format information....Variable length argument list.DescriptionThis function uses the format string fmt and the variable length argument list to build a formattedUnicode string. This formatted Unicode string is then sent to the console-out device at the cursorlocation specified by Column and Row. The length of the formatted Unicode string is returned.Status Codes Returned≥0The length of the formatted Unicode string.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 98

EFI Shell Library5.6.5 Sprint()SummarySends a formatted Unicode string to the specified buffer.PrototypeUINTNSPrint (OUT CHAR16IN UINTNIN CHAR16...);*Str,StrSize,*fmt,ParametersStrA pointer to a Unicode string.StrSizeThe maximum length of the Unicode string Str.FmtA pointer to a Unicode string containing format information....Variable length argument list.DescriptionThis function uses the format string Fmt and the variable length argument list to build a formattedUnicode string. Note that a Null character will be appended automatically after the last character iswritten. This formatted Unicode string, including an additional Null character’s size, is no morethan StrSize.Status Codes Returned≥0The length of the formatted Unicode string.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 99

EFI Shell Library5.6.6 PrintToken()SummarySends a HII token to the specified output device at the current cursor location.PrototypeUINTNPrintToken (IN UINT16IN EFI_HII_HANDLE...);Token,Handle,ParametersTokenString token that was defined as a string previously.HandleThe handle on which the string resides...Variable length argument list.DescriptionThis function uses the format string defined in Token and the variable length argument list to builda formatted Unicode string. This formatted Unicode string is then sent to the console out device.The Token will be extracted from an installed HII package. Before this function can be available,InitializeStrings() has to be called first to register HII string package and get the validHandle. If the Token can not be found on the specified Handle or the specified Handle isinvalid, zero will be returned. Otherwise, the length of the formatted Unicode string is returned.Status Codes Returned≥0The length of the printed Unicode string.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 100

EFI Shell Library5.7 Math FunctionsNameLshiftU64RshiftU64MultiU64x32DivU64x32The EFI Shell Library provides a few math functions to operate on 64-bit operands. These includeshift operations, multiplication, and division. Table 5-11 lists the set of 64-bit math functions thatare described in the following sections.Table 5-11. Math FunctionsDescriptionShift a 64-bit integer left between 0 and 63 bits.Shift a 64-bit integer right between 0 and 63 bits.Multiply a 64-bit unsigned integer by a 32-bit unsigned integer and generate a64-bit unsigned result.Divide a 64-bit unsigned integer by a 32-bit unsigned integer and generate a64-bit unsigned result with an optional 32-bit unsigned remainder.Version 0.91 June 27, 2005 101

EFI Shell Library5.7.1 LshiftU64()SummaryShifts a 64-bit integer left between 0 and 63 bits.PrototypeUINT64LShiftU64 (IN UINT64IN UINTN);Operand,CountParametersOperandThe 64-bit operand to shift left.CountThe number of bits to shift left.DescriptionThis function shifts the 64-bit value Operand to the left by Count bits. The shifted value isreturned.Status Codes Returned≥0The shifted value.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 102

EFI Shell Library5.7.2 RshiftU64()SummaryShifts a 64-bit integer right between 0 and 63 bits.PrototypeUINT64RShiftU64 (IN UINT64IN UINTN);Operand,CountParametersOperandThe 64-bit operand to shift right.CountThe number of bits to shift right.DescriptionThis function shifts the 64-bit value Operand to the right by Count bits. The shifted value isreturned.Status Codes Returned≥0The shifted value.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 103

EFI Shell Library5.7.3 MultU64x32()SummaryMultiplies a 64-bit unsigned integer by a 32-bit unsigned integer and generates a 64-bit unsignedresult.PrototypeUINT64MultU64x32 (IN UINT64IN UINTN);Multiplicand,MultiplierParametersMultiplicandA 64-bit unsigned value.MultiplierA 32-bit unsigned value.DescriptionThis function multiplies the 64-bit unsigned value Multiplicand by the 32-bit unsigned valueMultiplier and generates a 64-bit unsigned result. This 64-bit unsigned result is returned.Status Codes Returned≥0EFI VersionEFI 1.02 or above.The 64-bit unsigned result.Version 0.91 June 27, 2005 104

EFI Shell Library5.7.4 DivU64x32()SummaryDivides a 64-bit unsigned integer by a 32-bit unsigned integer and generates a 64-bit unsignedresult and a 32-bit unsigned remainder.PrototypeUINT64DivU64x32 (IN UINT64IN UINTNOUT UINTN);Dividend,Divisor,*Remainder OPTIONALParametersDividendA 64-bit unsigned value.DivisorA 32-bit unsigned value.*RemainderA pointer to a 32-bit value.DescriptionThis function divides the 64-bit unsigned value Dividend by the unsigned value Divisor andgenerates an unsigned quotient. If Remainder is not NULL, then the unsigned remainder isreturned in Remainder. This function returns the 64-bit unsigned quotient. On IA-32 platforms,the Divisor and *Remainder are 32-bit unsigned values. On Itanium®-based platforms, theDivisor and *Remainder are 64-bit unsigned values.Status Codes Returned≥0EFI VersionEFI 1.02 or above.The 64-bit unsigned result.Version 0.91 June 27, 2005 105

EFI Shell Library5.8 Spin Lock FunctionsSpin locks are used to protect data structures that may be updated by more than one processor at atime, or a single processor that may update the same data structure while running a several differentpriority levels. A spin lock is stored in a FLOCK data structure.typedef struct _FLOCK {EFI_TPLTpl;EFI_TPLOwnerTpl;UINTNLock;} FLOCK;Table 5-12 lists the support functions for creating and maintaining spin locks. These functions aredescribed in the following sections.Table 5-12. Spin Lock FunctionsNameDescriptionInitializeLockInitialize a spin lock.AcquireLockAcquire a spin lock.ReleaseLockRelease a spin lock.Version 0.91 June 27, 2005 106

EFI Shell Library5.8.1 InitializeLock()SummaryInitializes a basic mutual exclusion lock.PrototypeVOIDInitializeLock (IN OUT FLOCKIN EFI_TPL);*Lock,PriorityParametersLockA pointer to the lock data structure to initialize.PriorityThe task priority level of the lock.DescriptionThis function initializes a basic mutual exclusion lock. Each lock provides mutual exclusion accessat its task priority level. Since there is no preemption or multiprocessor support in EFI, acquiringthe lock only consists of rising to the locks TPL.Status Codes ReturnedNoneEFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 107

EFI Shell Library5.8.2 AcquireLock()SummaryAcquires ownership of a lockPrototypeVOIDAcquireLock (IN FLOCK);*LockParametersLockDescriptionA pointer to the lock to acquire.This function raises the system’s current task priority level to the task priority level of the mutualexclusion lock. Then, it acquires ownership of the lock.Status Codes ReturnedNoneEFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 108

EFI Shell Library5.8.3 ReleaseLock()SummaryReleases ownership of a lockPrototypeVOIDReleaseLock (IN FLOCK);*LockParametersLockDescriptionA pointer to the lock to release.This function releases ownership of the mutual exclusion lock, and restores the system’s taskpriority level to its previous level.Status Codes ReturnedNoneEFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 109

EFI Shell Library5.9 Device Path Support FunctionsTable 5-13 lists the support functions for creating and maintaining device path data structures. Thesefunctions are described in the following sections.Table 5-13. Device Path Support FunctionsNameDevicePathFromHandleDevicePathInstanceAppendDevicePathDevicePathSizeUnpackDevicePathDescriptionRetrieves the device path from a specified handle.Retrieves the next device path instance from a device path.Appends a device path to all the instances of another device path.Returns the size of a device path in bytes.Naturally aligns all the nodes in a device path.Version 0.91 June 27, 2005 110

EFI Shell Library5.9.1 DevicePathFromHandle()SummaryRetrieves the device path for the specified handle.PrototypeEFI_DEVICE_PATH *DevicePathFromHandle (IN EFI_HANDLE);HandleParametersHandleA handle to retrieve the device path.DescriptionThis function retrieves the device path for a handle specified by Handle. If Handle is valid, thena pointer to the device path is returned. The caller should not attempt to free the returned pointer.When using this function, the user must guarantee the Handle is valid.Status Codes Returned≠NULLNULLEFI VersionEFI 1.02 or above.The pointer to the memory space that contain the requested device path.The Handle is invalid or no devices on it.Version 0.91 June 27, 2005 111

EFI Shell Library5.9.2 DevicePathInstance()SummaryRetrieves the next device path instance from a device path data structure.PrototypeEFI_DEVICE_PATH *DevicePathInstance (IN OUT EFI_DEVICE_PATHOUT UINTN);**DevicePath,*SizeParametersDevicePathA pointer to a device path data structure.SizeA pointer to the size of a device path instance in bytes.DescriptionThis function is used to parse device path instances from the device path DevicePath. Thisfunction returns a pointer to the current device path instance. In addition, it returns the size in bytesof the current device path instance in Size, and a pointer to the next device path instance inDevicePath. If there are no more device path instances in DevicePath, then DevicePathwill be set to NULL.Status Codes Returned≠NULLNULLEFI VersionEFI 1.02 or above.A pointer to the next device path instance in DevicePath.There are no more device path instances in DevicePath.Version 0.91 June 27, 2005 112

EFI Shell Library5.9.3 AppendDevicePath()SummaryUsed to append a device path to all the instances in another device path.PrototypeEFI_DEVICE_PATH *AppendDevicePath (IN EFI_DEVICE_PATHIN EFI_DEVICE_PATH);*Src1,*Src2ParametersSrc1Src2DescriptionA pointer to a device path data structure.A pointer to a device path data structure.This function appends the device path Src2 to every device path instance in Src1. A pointer tothe new device path is returned. NULL is returned if space for the new device path could not beallocated from pool. It is up to the caller to free the memory used by Src1 and Src2 if they are nolonger needed.Status Codes Returned≠NULLNULLEFI VersionEFI 1.02 or above.A pointer to the new appended device path.The space for the new device path could not be allocated from pool.Version 0.91 June 27, 2005 113

EFI Shell Library5.9.4 DevicePathSize()SummaryReturns the size of a device path in bytes.PrototypeUINTNDevicePathSize (IN EFI_DEVICE_PATH);*DevPathParametersDevPathA pointer to a device path data structure.DescriptionThis function determines the size of a data path data structure in bytes. This size is returned. Whenusing this function, the user must guarantee that the DevPath is valid.Status Codes Returned≥0EFI VersionEFI 1.02 or above.The size of the device path DevPathVersion 0.91 June 27, 2005 114

EFI Shell Library5.9.5 UnpackDevicePath()SummaryUnpacks a device path data structure so that all the nodes of a device path are naturally aligned.PrototypeEFI_DEVICE_PATH *UnpackDevicePath (IN EFI_DEVICE_PATH);*DevPathParametersDevPathA pointer to a device path data structure.DescriptionThis function allocates space for a new copy of the device path DevPath. The new copy ofDevPath is modified so that every node of the device path is naturally aligned. If the memory forthe device path is successfully allocated, then a pointer to the new device path is returned.Otherwise, NULL is returned.When using this function, the user must guarantee the DevPath is valid. It is the caller’sresponsibility to free the memory used by the new device path if it is no longer needed.Status Codes Returned≠NULLNULLEFI VersionEFI 1.02 or above.A pointer to the new device path.The space for the new device path could not be allocated from pool.Version 0.91 June 27, 2005 115

EFI Shell Library5.10 Shell Interface Support FunctionsThe EFI Shell Library provides a set of functions that access the shell environment.Table 5-14 contains the list of shell interface support functions that are described in the followingsections.Table 5-14. Shell Interface Support FunctionsNameGetExecutionBreakShellGetEnvShellGetMapShellExecuteShellCurDirEnablePageBreakDisablePageBreakGetPageBreakShellMetaFileArgShellMetaFileArgNoWildCardShellFreeFileListShellInitHandleEnumeratorShellNextHandleShellSkipHandleShellResetHandleEnumeratorShellCloseHandleEnumeratorShellGetHandleNumDescriptionGets the enable status of the execution break flag.Gets the environment variable.Gets the device path from the mapping name.Causes the shell to parse and execute the command line.Gets the current directory on the device.Enables the page break output mode.Disables the page break output mode.Gets the enable status of the page break output mode.Opens the files that match the path specified.Opens the files that match the path specified without wild card.Frees the file list that created by ShellMetaFileArg.Initializes the handle enumerator.Gets the next handle.Skips to the next n th handle.Resets the handle enumerator to the given value.Closes the handle enumerator.Gets the handle numbers in the system.Version 0.91 June 27, 2005 116

EFI Shell Library5.10.1 GetExecutionBreak()SummaryGets the enable status of the execution break flag.PrototypeBOOLEANGetExecutionBreak (IN VOID);ParametersNoneDescriptionThis function can be used to implement a break in the application. Applications use this function toreceive the break signal sent from system.Status Codes ReturnedTRUEFALSEEFI VersionEFI 1.02 or above.Enable.Disable.Version 0.91 June 27, 2005 117

EFI Shell Library5.10.2 ShellGetEnv()SummaryGets the environment variable.PrototypeCHAR16 *ShellGetEnv (IN CHAR16);*NameParametersNameDescriptionA pointer to the environment variable name.This function gets the environment variable set by command “set”. To set a variable, use thecommand “set”.Status Codes Returned≠NULLNULLEFI VersionEFI 1.02 or above.The environment variable’s value.The environment variable does not exist.Version 0.91 June 27, 2005 118

EFI Shell Library5.10.3 ShellGetMap()SummaryGets the device path from the mapping name.PrototypeEFI_DEVICE_PATH_PROTOCOL*ShellGetMap (IN CHAR16 *Name);ParametersNameDescriptionA pointer to the mapping name.This function gets the device path’s mapping name. User can use command ‘map’ set a newmapping name to a device.Status Codes Returned!=NULLNULLEFI VersionEFI 1.02 or above.The device path of the mapping name.The mapping name does not exist.Version 0.91 June 27, 2005 119

EFI Shell Library5.10.4 ShellExecute()SummaryCauses the shell to parse and execute the command line.PrototypeEFI_STATUSShellExecute (IN EFI_HANDLEIN CHAR16IN BOOLEAN);ImageHandle,*CmdLine,OutputParametersImageHandleA handle of an image that is initializing the library.CmdLineCommand line.OutputIf TRUE, it will output the result. If FALSE, it will not output the result.DescriptionThe user can use this function to execute a shell command or application.Status Codes ReturnedEFI_SUCCESSEFI_INVALID_PARAMETEREFI_OUT_OF_RESOURCESThe command executed successfully.The parameters are invalid.Out of resources.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 120

EFI Shell Library5.10.5 ShellCurDir()SummaryGets the current directory on the device.PrototypeCHAR16 *ShellCurDir (IN CHAR16);*DeviceName OPTIONALParametersDeviceNameThe device’s name.DescriptionIf the DeviceName is NULL, it returns the current device’s current directory name. If theDeviceName is not NULL, it returns the directory name specified by DeviceName’s currentname.Status Codes Returned!=NULLNULLEFI VersionEFI 1.02 or above.The current directory.Current directory does not exist.Version 0.91 June 27, 2005 121

EFI Shell Library5.10.6 EnablePageBreak()SummaryEnables the page break output mode.PrototypeVOIDEnablePageBreak (IN INT32 StartRow,IN BOOLEAN AutoWrap);ParametersStartRowThe start row numberAutoWrapIf TRUE, it will automatically wrap the line. If FALSE, it will not automatically wrapthe lineDescriptionThis function enables the page break output mode. The StartRow sets the rows in a page.Status Codes ReturnedNoneEFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 122

EFI Shell Library5.10.7 DisablePageBreak()SummaryDisables the page break output mode.PrototypeVOIDDisablePageBreak (VOID);ParametersNoneDescriptionThis function disables the page break output mode.Status Codes ReturnedNoneEFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 123

EFI Shell Library5.10.8 GetPageBreak()SummaryGets the enable status of the page break output mode.PrototypeBOOLEANGetPageBreak (VOID);ParametersNoneDescriptionThe user can use this function to determine current page break mode.Status Codes ReturnedTRUEFALSEEFI VersionEFI 1.02 or above.The page break output mode is enabled.The page break output mode is disabled.Version 0.91 June 27, 2005 124

EFI Shell Library5.10.9 ShellFileMetaArg()SummaryOpens the files that match the path specified.PrototypeEFI_STATUSShellFileMetaArg (IN CHAR16IN OUT EFI_LIST_ENTRY);*Arg,*ListHeadParametersArgA pointer to the path string.ListHeandA list of files that match the specified path.DescriptionThis function uses the Arg to open all the matching files. Each matched file has aSHELL_FILE_ARG structure to record the file information. These structures are placed on the listListHead. Users can get the SHELL_FILE_ARG structures from ListHead to access each file.This function supports wildcards.Status Codes ReturnedEFI_SUCCESSOther EFI Status CodesThe file list was successfully created.Cannot create the file list.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 125

EFI Shell Library5.10.10 ShellFileMetaArgNoWildCard()SummaryOpens the files that match the path specified without wild card.PrototypeEFI_STATUSShellFileMetaArgNoWildCard (IN CHAR16*Arg,IN OUT EFI_LIST_ENTRY *ListHead);ParametersArgA pointer to the path.ListHeadA list of files that match the specified path.DescriptionThis function is the same as the ShellFileMetaArg(), but does not support wildcards.Status Codes ReturnedEFI_SUCCESSOther EFI Status CodesThe file list was successfully created.Cannot create the file list.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 126

EFI Shell Library5.10.11 ShellFreeFileList()SummaryFrees the file list that was created by ShellMetaFileArg orShellMetaFileArgNoWildCard.PrototypeEFI_STATUSShellFreeFileList (IN OUT EFI_LIST_ENTRY);*ListHeadParametersListHeadThe list created by ShellMetaFileArg orShellMetaFileArgNoWildCard.DescriptionThis function performs clean-ups of the files represented by the file list. It will close the openedfiles in the list and free the associated resources.Status Codes ReturnedEFI_SUCCESSEFI VersionEFI 1.02 or above.The file list was successfully freed.Version 0.91 June 27, 2005 127

EFI Shell Library5.10.12 ShellInitHandleEnumerator()SummaryInitializes the handle enumerator.PrototypeVOIDShellInitHandleEnumerator (VOID);ParametersNoneDescriptionThe shell library provides serial functions to enable users to access the handle in the system. To usethese functions, the user must call this function first to initialize the environment.Status Codes ReturnedNoneEFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 128

EFI Shell Library5.10.13 ShellNextHandle()SummaryGets the next handle.PrototypeEFI_STATUSShellNextHandle (OUT EFI_HANDLE **Handle);ParametersHandleA pointer to the pointer to an EFI handle.DescriptionThis function returns the current handle in the handle table and moves the enumerator to the nexthandle.Status Codes ReturnedEFI_SUCCESSEFI_NOT_FOUNDGot the next handle; enumerator moved to next handle.Cannot get the next handle.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 129

EFI Shell Library5.10.14 ShellSkipHandle()SummarySkips to the next n th handle.PrototypeEFI_STATUSShellSkipHandle (IN UINTN);NumSkipParametersNumSkipThe handle number to skip.DescriptionThis function moves the enumerator to the next n th handle.Status Codes ReturnedEFI_SUCCESSSkipped to the next n th handle.EFI_ACCESS_DENIED Can not access the next n th handle.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 130

EFI Shell Library5.10.15 ShellResetHandleEnumerator()SummaryResets the handle enumerator.PrototypeVOIDShellResetHandleEnumerator (VOID);ParametersNoneDescriptionThis function sets the enumerator to zero.Status Codes ReturnedNoneEFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 131

EFI Shell Library5.10.16 ShellCloseHandleEnumerator()SummaryCloses the handle enumerator.PrototypeVOIDSEnvCloseHandleEnumerator (VOID);ParametersNoneDescriptionThis function releases the resource used to access the system handle.Status Codes ReturnedNoneEFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 132

EFI Shell Library5.10.17 ShellGetHandleNum()SummaryGets the handle number in the system.PrototypeUINTNShellGetHandleNum(VOID);ParametersNoneDescriptionThe ShellGetHandleNum() gets the handle number in the system.Status Codes Returned≥0The handle number in the system.EFI VersionEFI 1.02 or above.Version 0.91 June 27, 2005 133