Porting an EDK Shell Extension - lzeng14/tianocore GitHub Wiki

The goal of this section is to enable an engineer to easily take an EDK Shell Extension and move that to an EDK II UEFI Shell 2.0 application. This means primarily removing and replacing 3 types of references.

• EDK Shell protocols usage
• EDK Shell library usage
• EDK library usage and ‘standard’ EDK globals

The last of these three items is not always present whereas the first two are almost always present.

Table of Contents Eliminating the EDK Shell Protocols Eliminating EFI_SHELL_ENVIRONMENT2 Execute GetEnv GetMap AddCmd AddProt GetProt CurDir FileMetaArg FreeFileList NewShell BatchIsActive FreeResources EnablePageBreak DisablePageBreak GetPageBreak SetKeyFilter GetKeyFilter GetExecutionBreak IncrementShellNestingLevel DecrementShellNestingLevel IsRootShell CloseConsoleProxy HandleEnumerator (function group) ProtocolInfoEnumerator (function group) GetDeviceName GetShellMode NameToPath GetFsName FileMetaArgNoWildcard DelDupFileArg GetFsDevicePath Eliminating EFI_SHELL_INTERFACE ImageHandle Info Argv Argc RedirArgv RedirArgc StdIn StdOut StdErr ArgInfo EchoOn Eliminating Shell library functions Eliminating common EfiShellLib functions EFI_SHELL_APP_INIT, other initialization macro, or any initialization function EFI_SHELL_STR_INIT, LibInitializeStrings, or any string function. Math Functions GetBestLanguage LibGetDriverName Printing functions PrintAt Print Output SPrint PoolPrint PrintToken CatPrint Command Line Variable functions GetNextArg, GetFirstArg, GetFirstFlag LibCheckVarFreeVarList LibCheckVarGetFlag LibCheckVariables LibCheckRedirVariables LibGetStdRedirFilename LibGetErrRedirFilename Eliminating EDK library usage and ‘standard’ EDK globals Eliminating EDK library usage Eliminating ‘standard’ EDK globals RT BS gSPP gSP

There are 3 protocols directly associated with the EDK Shell. The protocols are:

• EFI_SHELL_ENVIRONMENT
• EFI_SHELL_ENVIRONMENT2
• EFI_SHELL_INTERFACE

The first protocol (EFI_SHELL_ENVIRONMENT) is a subset of the second one (EFI_SHELL_ENVIRONMENT2) and will not have a separate section.

Use EFI_SHELL_PROTOCOL->Execute. This function does not exactly match, but has almost all of the same features. The major change is that the UEFI Shell Spec 2.0 does not allow for the running of internal shell commands through this function.

Use EFI_SHELL_PROTOCOL->GetEnv.

This concept does not exist in the new shell. Use Shell Environment instead of shell maps.

This concept does not exist in the new shell. There is no way to dynamically add a command to the shell.

This concept does not exist in the new shell. There is no way to dynamically add protocol information to the shell. You can look at the HandleParsingLib for some similar functionality.

This concept does not exist in the new shell. There is no way to query protocol information in the shell. You can look at the HandleParsingLib for some similar functionality.

Use EFI_SHELL_PROTOCOL-> GetCurDir.

Use EFI_SHELL_PROTOCOL-> OpenFileList

Use EFI_SHELL_PROTOCOL-> FreeFileList

This concept does not exist in the new shell. You can spawn a new shell via the Execute function.

Use EFI_SHELL_PROTOCOL-> BatchIsActive

This concept does not exist in the new shell.

Use EFI_SHELL_PROTOCOL-> EnablePageBreak (Note that this is automatically controlled via ShellLib command line parsing functions)

Use EFI_SHELL_PROTOCOL-> DisablePageBreak

Use EFI_SHELL_PROTOCOL-> GetPageBreak

This concept is not part of the UEFI Shell. Key filtering must be done either manually or via the ShellLib with the functions ShellPromptForResponse and ShellPromptForResponseHii.

This concept is not part of the UEFI Shell. Key filtering must be done either manually or via the ShellLib with the functions ShellPromptForResponse and ShellPromptForResponseHii.

This concept has changed in the UEFI Shell. There is a event that you can query EFI_SHELL_PROTOCOL-> ExecutionBreak. There is also a function in the ShellLib that helps (ShellGetExecutionBreakFlag).

This concept does not exist in the new shell. The nesting level cannot be controlled outside the shell.

This concept does not exist in the new shell. The nesting level cannot be controlled outside the shell.

Use EFI_SHELL_PROTOCOL->IsRootShell.

This concept does not exist in the new shell. The consoles cannot be controlled outside the shell.

This concept does not exist in the new shell. There is no way to query protocol information in the shell. You can look at the HandleParsingLib for some similar functionality.

This concept does not exist in the new shell. There is no way to query protocol information in the shell. You can look at the HandleParsingLib for some similar functionality.

Use EFI_SHELL_PROTOCOL-> GetDeviceName

This concept does not exist in the UEFI Shell. Shell support level and shell profiles present can be retrieved from environment variables.

Use EFI_SHELL_PROTOCOL-> GetDevicePathFromFilePath

Use EFI_SHELL_PROTOCOL-> GetMapFromDevicePath

Use EFI_SHELL_PROTOCOL-> OpenFileByName

Use EFI_SHELL_PROTOCOL-> RemoveDupInFileList

Use EFI_SHELL_PROTOCOL-> GetDevicePathFromMap

Use ImageHandle from entry point. Most apps have gImageHandle global variable linked in from libraries.

If you want EFI_LOADED_IMAGE_PROTOCOL you can get it manually.

Use EFI_SHELL_PARAMETERS_PROTOCOL->Argv

Use EFI_SHELL_PARAMETERS_PROTOCOL->Argv

This concept does not exist in the new shell. Redirection is handled before applications are launched.

This concept does not exist in the new shell. Redirection is handled before applications are launched.

Use EFI_SHELL_PARAMETERS_PROTOCOL->StdIn

Use EFI_SHELL_PARAMETERS_PROTOCOL->StdOut

Use EFI_SHELL_PARAMETERS_PROTOCOL->StdErr

This concept does not exist in the new shell.

This concept is not checkable in the new shell. The shell internally controls the echo state.

Due to the many different versions of the shell library and the many possible functions, only the most common functions will be covered here. If you find a function is not covered please report that as an enhancement request.

This should not be required. The EDKII ShellLib will automatically initialize itself. Only when building a shell internal command this is not true and the manual initialization must be called.

If you need some strings put into HII it is expected that you will handle this yourself. Please refer to the HiiLib library class for doing this.

• such as LShiftU64, RShiftU64, MultU64x32, DivU64x32, etc...

All of these should be changed to EDK II library class BaseLib math functions.

This function exists in the EDK II Library class UefiLib.

This function can be called directly via COMPONENT_NAME_PROTOCOL.

This function is replaced by the EDK II ShellLib functions ShellPrintEx and ShellPrintHiiEx. You decide which to use based on whether the format string to be printed is contained in HII or not.

This function exists in the EDK II Library class UefiLib.

This function is replaced by the Print() function.

This function is in the process of being ported to EDK II.

This function is in the process of being ported to EDK II.

This function is replaced by the EDK II ShellLib function ShellPrintHiiEx.

This function is replaced by the EDK II ShellLib function ShellPrintHiiEx.

The structure that you use for storing potential parameters is changed. Please see the new structure in the EDK II ShellLib.

These are all deprecated. The order of flags/arguments is not verified in the automatic parsing. For command lines where there are items passed in, but these items are not associated with a flag (for example, “command 0xff 0xaa” there is the EDK II ShellLib function ShellCommandLineGetRawValue.

Use the EDK II ShellLib function ShellCommandLineFreeVarList.

This function is divided into 2 EDK II ShellLib functions. The first is ShellCommandLineGetFlag and is used to get whether a flag was present on the command line. The second is ShellCommandLineGetValue and is used to get the value that followed a flag on the command line (if there was a following value).

Use the EDK II ShellLib function ShellCommandLineParseEx.

This concept does not exist in the new shell. Redirection is handled before applications are launched.

This concept does not exist in the new shell. Redirection is handled before applications are launched.

This concept does not exist in the new shell. Redirection is handled before applications are launched.

All EDK library usage must be replaced.

If your application is linked to the UefiRuntimeServicesTableLib then you will get a global called gRT. This is the replacement for RT.

If your application is linked to the UefiBootServicesTableLib then you will get a global called gBS. This is the replacement for BS.

If your application is linked to the ShellLib then you will get a global called gEfiShellParametersProtocol. This is the replacement for gSPP.

ShellLib header

If your application is linked to the ShellLib then you will get a global called gEfiShellProtocol. This is the replacement for gSP.

ShellLib header