diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-11 08:17:27 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-11 08:17:27 +0000 |
| commit | f215e02bf85f68d3a6106c2a1f4f7f063f819064 (patch) | |
| tree | 6bb5b92c046312c4e95ac2620b10ddf482d3fa8b /src/VBox/Devices/EFI/Firmware/ShellPkg/Include | |
| parent | Initial commit. (diff) | |
| download | virtualbox-f215e02bf85f68d3a6106c2a1f4f7f063f819064.tar.xz virtualbox-f215e02bf85f68d3a6106c2a1f4f7f063f819064.zip | |
Adding upstream version 7.0.14-dfsg.upstream/7.0.14-dfsg
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'src/VBox/Devices/EFI/Firmware/ShellPkg/Include')
14 files changed, 3997 insertions, 0 deletions
diff --git a/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Guid/ShellAliasGuid.h b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Guid/ShellAliasGuid.h new file mode 100644 index 00000000..82887479 --- /dev/null +++ b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Guid/ShellAliasGuid.h @@ -0,0 +1,19 @@ +/** @file + GUID for Shell Variable for Get/Set via runtime services. + + Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _SHELL_ALIAS_VARIABLE_GUID_H_ +#define _SHELL_ALIAS_VARIABLE_GUID_H_ + +#define SHELL_ALIAS_VARIABLE_GUID \ +{ \ + 0x0053d9d6, 0x2659, 0x4599, { 0xa2, 0x6b, 0xef, 0x45, 0x36, 0xe6, 0x31, 0xa9 } \ +} + +extern EFI_GUID gShellAliasGuid; + +#endif diff --git a/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Guid/ShellEnvironment2Ext.h b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Guid/ShellEnvironment2Ext.h new file mode 100644 index 00000000..7c2829e5 --- /dev/null +++ b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Guid/ShellEnvironment2Ext.h @@ -0,0 +1,19 @@ +/** @file + GUID for EFI shell Environment2 Extension. + + Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _SHELLPKG_SHELL_ENV2_EXT_GUID_H_ +#define _SHELLPKG_SHELL_ENV2_EXT_GUID_H_ + +#define SHELLPKG_SHELL_ENV2_EXT_GUID \ +{ \ + 0xd2c18636, 0x40e5, 0x4eb5, {0xa3, 0x1b, 0x36, 0x69, 0x5f, 0xd4, 0x2c, 0x87} \ +} + +extern EFI_GUID gEfiShellEnvironment2ExtGuid; + +#endif diff --git a/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Guid/ShellLibHiiGuid.h b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Guid/ShellLibHiiGuid.h new file mode 100644 index 00000000..eacd614d --- /dev/null +++ b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Guid/ShellLibHiiGuid.h @@ -0,0 +1,85 @@ +/** @file + GUIDs for HII package list installed by Shell libraries. + + Copyright (c) 2011 - 2016, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _SHELLLIB_HII_GUID_H_ +#define _SHELLLIB_HII_GUID_H_ + +#define HANDLE_PARSING_HII_GUID \ + { \ + 0xb8969637, 0x81de, 0x43af, { 0xbc, 0x9a, 0x24, 0xd9, 0x89, 0x13, 0xf2, 0xf6 } \ + } + +#define SHELL_DEBUG1_HII_GUID \ + { \ + 0x25f200aa, 0xd3cb, 0x470a, { 0xbf, 0x51, 0xe7, 0xd1, 0x62, 0xd2, 0x2e, 0x6f } \ + } + +#define SHELL_DRIVER1_HII_GUID \ + { \ + 0xaf0b742, 0x63ec, 0x45bd, {0x8d, 0xb6, 0x71, 0xad, 0x7f, 0x2f, 0xe8, 0xe8} \ + } + +#define SHELL_INSTALL1_HII_GUID \ + { \ + 0x7d574d54, 0xd364, 0x4d4a, { 0x95, 0xe3, 0x49, 0x45, 0xdb, 0x7a, 0xd3, 0xee } \ + } + +#define SHELL_LEVEL1_HII_GUID \ + { \ + 0xdec5daa4, 0x6781, 0x4820, { 0x9c, 0x63, 0xa7, 0xb0, 0xe4, 0xf1, 0xdb, 0x31 } \ + } + +#define SHELL_LEVEL2_HII_GUID \ + { \ + 0xf95a7ccc, 0x4c55, 0x4426, { 0xa7, 0xb4, 0xdc, 0x89, 0x61, 0x95, 0xb, 0xae } \ + } + +#define SHELL_LEVEL3_HII_GUID \ + { \ + 0x4344558d, 0x4ef9, 0x4725, { 0xb1, 0xe4, 0x33, 0x76, 0xe8, 0xd6, 0x97, 0x4f } \ + } + +#define SHELL_NETWORK1_HII_GUID \ + { \ + 0xf3d301bb, 0xf4a5, 0x45a8, { 0xb0, 0xb7, 0xfa, 0x99, 0x9c, 0x62, 0x37, 0xae } \ + } + +#define SHELL_NETWORK2_HII_GUID \ + { \ + 0x174b2b5, 0xf505, 0x4b12, { 0xaa, 0x60, 0x59, 0xdf, 0xf8, 0xd6, 0xea, 0x37 } \ + } + +#define SHELL_TFTP_HII_GUID \ + { \ + 0x738a9314, 0x82c1, 0x4592, { 0x8f, 0xf7, 0xc1, 0xbd, 0xf1, 0xb2, 0x0e, 0xd4 } \ + } + +#define SHELL_HTTP_HII_GUID \ + { \ + 0x390f84b3, 0x221c, 0x4d9e, { 0xb5, 0x06, 0x6d, 0xb9, 0x42, 0x3e, 0x0a, 0x7e } \ + } + +#define SHELL_BCFG_HII_GUID \ + { \ + 0x5f5f605d, 0x1583, 0x4a2d, {0xa6, 0xb2, 0xeb, 0x12, 0xda, 0xb4, 0xa2, 0xb6 } \ + } + +extern EFI_GUID gHandleParsingHiiGuid; +extern EFI_GUID gShellDebug1HiiGuid; +extern EFI_GUID gShellDriver1HiiGuid; +extern EFI_GUID gShellInstall1HiiGuid; +extern EFI_GUID gShellLevel1HiiGuid; +extern EFI_GUID gShellLevel2HiiGuid; +extern EFI_GUID gShellLevel3HiiGuid; +extern EFI_GUID gShellNetwork1HiiGuid; +extern EFI_GUID gShellNetwork2HiiGuid; +extern EFI_GUID gShellTftpHiiGuid; +extern EFI_GUID gShellHttpHiiGuid; +extern EFI_GUID gShellBcfgHiiGuid; + +#endif diff --git a/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Guid/ShellMapGuid.h b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Guid/ShellMapGuid.h new file mode 100644 index 00000000..9af44aa3 --- /dev/null +++ b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Guid/ShellMapGuid.h @@ -0,0 +1,19 @@ +/** @file + GUID for Shell Map for Get/Set via runtime services. + + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _SHELL_MAP_GUID_H_ +#define _SHELL_MAP_GUID_H_ + +#define SHELL_MAP_GUID \ +{ \ + 0x51271e13, 0x7de3, 0x43af, { 0x8b, 0xc2, 0x71, 0xad, 0x3b, 0x82, 0x43, 0x25 } \ +} + +extern EFI_GUID gShellMapGuid; + +#endif diff --git a/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Guid/ShellPkgTokenSpace.h b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Guid/ShellPkgTokenSpace.h new file mode 100644 index 00000000..4ffa1b78 --- /dev/null +++ b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Guid/ShellPkgTokenSpace.h @@ -0,0 +1,19 @@ +/** @file + GUID for ShellPkg PCD Token Space. + + Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _SHELLPKG_TOKEN_SPACE_GUID_H_ +#define _SHELLPKG_TOKEN_SPACE_GUID_H_ + +#define EFI_SHELLPKG_TOKEN_SPACE_GUID \ +{ \ + 0x171e9188, 0x31d3, 0x40f5, { 0xb1, 0xc, 0x53, 0x9b, 0x2d, 0xb9, 0x40, 0xcd } \ +} + +extern EFI_GUID gEfiShellPkgTokenSpaceGuid; + +#endif diff --git a/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Guid/ShellVariableGuid.h b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Guid/ShellVariableGuid.h new file mode 100644 index 00000000..8142922c --- /dev/null +++ b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Guid/ShellVariableGuid.h @@ -0,0 +1,19 @@ +/** @file + GUID for Shell Variable for Get/Set via runtime services. + + Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _SHELL_VARIABLE_GUID_H_ +#define _SHELL_VARIABLE_GUID_H_ + +#define SHELL_VARIABLE_GUID \ +{ \ + 0x158def5a, 0xf656, 0x419c, { 0xb0, 0x27, 0x7a, 0x31, 0x92, 0xc0, 0x79, 0xd2 } \ +} + +extern EFI_GUID gShellVariableGuid; + +#endif diff --git a/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Library/AcpiViewCommandLib.h b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Library/AcpiViewCommandLib.h new file mode 100644 index 00000000..0d2468e9 --- /dev/null +++ b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Library/AcpiViewCommandLib.h @@ -0,0 +1,46 @@ +/** @file + Library providing 'acpiview' functionality to display and + validate installed ACPI tables. + + Copyright (c) 2016 - 2020, ARM Limited. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent +**/ + +#ifndef ACPI_VIEW_COMMAND_LIB_H_ +#define ACPI_VIEW_COMMAND_LIB_H_ + +/** + Dump a buffer to a file. Print error message if a file cannot be created. + + @param[in] FileName The filename that shall be created to contain the buffer. + @param[in] Buffer Pointer to buffer that shall be dumped. + @param[in] BufferSize The size of buffer to be dumped in bytes. + + @return The number of bytes that were written +**/ +UINTN +EFIAPI +ShellDumpBufferToFile ( + IN CONST CHAR16* FileNameBuffer, + IN CONST VOID* Buffer, + IN CONST UINTN BufferSize + ); + +/** + Display and validate ACPI tables. + + @param[in] ImageHandle Handle to the Image (NULL if internal). + @param[in] SystemTable Pointer to the System Table (NULL if internal). + + @retval SHELL_INVALID_PARAMETER The command line invocation could not be parsed. + @retval SHELL_NOT_FOUND The command failed. + @retval SHELL_SUCCESS The command was successful. +**/ +SHELL_STATUS +EFIAPI +ShellCommandRunAcpiView ( + IN EFI_HANDLE ImageHandle, + IN EFI_SYSTEM_TABLE *SystemTable + ); + +#endif // UEFI_SHELL_ACPIVIEW_COMMAND_LIB_H_ diff --git a/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Library/BcfgCommandLib.h b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Library/BcfgCommandLib.h new file mode 100644 index 00000000..77eb723f --- /dev/null +++ b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Library/BcfgCommandLib.h @@ -0,0 +1,46 @@ +/** @file + Header file for BCFG command library. + + Copyright (c) 2014, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _BCFG_COMMAND_LIB_H_ +#define _BCFG_COMMAND_LIB_H_ + +/** + "Constructor" for the library. + + This will register the handler for the bcfg command. + + @param[in] ImageHandle the image handle of the process + @param[in] SystemTable the EFI System Table pointer + @param[in] Name the profile name to use + + @retval EFI_SUCCESS the shell command handlers were installed sucessfully + @retval EFI_UNSUPPORTED the shell level required was not found. +**/ +EFI_STATUS +EFIAPI +BcfgLibraryRegisterBcfgCommand ( + IN EFI_HANDLE ImageHandle, + IN EFI_SYSTEM_TABLE *SystemTable, + IN CONST CHAR16 *Name + ); + +/** + "Destructor" for the library. free any resources. + + @param ImageHandle The image handle of the process. + @param SystemTable The EFI System Table pointer. +**/ +EFI_STATUS +EFIAPI +BcfgLibraryUnregisterBcfgCommand ( + IN EFI_HANDLE ImageHandle, + IN EFI_SYSTEM_TABLE *SystemTable + ); + +#endif + diff --git a/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Library/HandleParsingLib.h b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Library/HandleParsingLib.h new file mode 100644 index 00000000..7d488aec --- /dev/null +++ b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Library/HandleParsingLib.h @@ -0,0 +1,404 @@ +/** @file + Provides interface to advanced shell functionality for parsing both handle and protocol database. + + Copyright (c) 2010 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef __HANDLE_PARSING_LIB__ +#define __HANDLE_PARSING_LIB__ + +#include <Uefi.h> + +/** + Function to add a new GUID/Name mapping. + + This cannot overwrite an existing mapping. + + @param[in] Guid The Guid + @param[in] TheName The Guid's name + @param[in] Lang RFC4646 language code list or NULL + + @retval EFI_SUCCESS The operation was sucessful + @retval EFI_ACCESS_DENIED There was a duplicate + @retval EFI_OUT_OF_RESOURCES A memory allocation failed +**/ +EFI_STATUS +EFIAPI +AddNewGuidNameMapping( + IN CONST EFI_GUID *Guid, + IN CONST CHAR16 *TheName, + IN CONST CHAR8 *Lang OPTIONAL + ); + +/** + Function to get the name of a protocol or struct from it's GUID. + + If Guid is NULL, then ASSERT. + + @param[in] Guid The GUID to look for the name of. + @param[in] Lang The language to use. + + @return The pointer to a string of the name. The caller + is responsible to free this memory. +**/ +CHAR16* +EFIAPI +GetStringNameFromGuid( + IN CONST EFI_GUID *Guid, + IN CONST CHAR8 *Lang OPTIONAL + ); + +/** + Function to get the Guid for a protocol or struct based on it's string name. + + Do not free or modify the returned GUID. + + @param[in] Name The pointer to the string name. + @param[in] Lang The pointer to the language code (string). + @param[out] Guid The pointer to the pointer to the Guid. + + @retval EFI_SUCCESS The operation was successful. +**/ +EFI_STATUS +EFIAPI +GetGuidFromStringName( + IN CONST CHAR16 *Name, + IN CONST CHAR8 *Lang OPTIONAL, + OUT EFI_GUID **Guid + ); + +/** + Function to dump protocol information from a handle. + + This function will return a allocated string buffer containing the + information. The caller is responsible for freeing the memory. + + If Guid is NULL, ASSERT(). + If TheHandle is NULL, ASSERT(). + + @param[in] TheHandle The handle to dump information from. + @param[in] Guid The GUID of the protocol to dump. + @param[in] Verbose TRUE for extra info. FALSE otherwise. + + @return The pointer to string. + @retval NULL An error was encountered. +**/ +CHAR16* +EFIAPI +GetProtocolInformationDump( + IN CONST EFI_HANDLE TheHandle, + IN CONST EFI_GUID *Guid, + IN CONST BOOLEAN Verbose + ); + +/** + Function to retrieve the driver name (if possible) from the ComponentName or + ComponentName2 protocol. + + The string returned must be callee freed. + + @param[in] TheHandle The driver handle to get the name of. + @param[in] Language The language to use. + + @retval NULL The name could not be found. + @return A pointer to the string name. Do not de-allocate the memory. +**/ +CONST CHAR16* +EFIAPI +GetStringNameFromHandle( + IN CONST EFI_HANDLE TheHandle, + IN CONST CHAR8 *Language + ); + +/** + Get best support language for this driver. + + First base on the user input language to search, second base on the current + platform used language to search, third get the first language from the + support language list. The caller need to free the buffer of the best language. + + @param[in] SupportedLanguages The support languages for this driver. + @param[in] InputLanguage The user input language. + @param[in] Iso639Language Whether get language for ISO639. + + @return The best support language for this driver. +**/ +CHAR8 * +EFIAPI +GetBestLanguageForDriver ( + IN CONST CHAR8 *SupportedLanguages, + IN CONST CHAR8 *InputLanguage, + IN BOOLEAN Iso639Language + ); + +#define HR_UNKNOWN 0 +#define HR_IMAGE_HANDLE BIT1 +#define HR_DRIVER_BINDING_HANDLE BIT2 // has driver binding +#define HR_DEVICE_DRIVER BIT3 // device driver (hybrid?) +#define HR_BUS_DRIVER BIT4 // a bus driver (hybrid?) +#define HR_DRIVER_CONFIGURATION_HANDLE BIT5 +#define HR_DRIVER_DIAGNOSTICS_HANDLE BIT6 +#define HR_COMPONENT_NAME_HANDLE BIT7 +#define HR_DEVICE_HANDLE BIT8 +#define HR_PARENT_HANDLE BIT9 +#define HR_CONTROLLER_HANDLE BIT10 +#define HR_CHILD_HANDLE BIT11 +#define HR_VALID_MASK (BIT1|BIT2|BIT3|BIT4|BIT5|BIT6|BIT7|BIT8|BIT9|BIT10|BIT11) + +/** + Gets all the related EFI_HANDLEs based on the mask supplied. + + This function will scan all EFI_HANDLES in the UEFI environment's handle database + and return all the ones with the specified relationship (Mask) to the specified + controller handle. + + If both DriverBindingHandle and ControllerHandle are NULL, then ASSERT. + If MatchingHandleCount is NULL, then ASSERT. + + If MatchingHandleBuffer is not NULL upon a successful return, the memory must be + caller freed. + + @param[in] DriverBindingHandle The handle with Driver Binding protocol on it. + @param[in] ControllerHandle The handle with Device Path protocol on it. + @param[in] Mask The mask of what relationship(s) is desired. + @param[in] MatchingHandleCount The pointer to UINTN specifying number of HANDLES in + MatchingHandleBuffer. + @param[out] MatchingHandleBuffer On a successful return, a buffer of MatchingHandleCount + EFI_HANDLEs with a terminating NULL EFI_HANDLE. + + @retval EFI_SUCCESS The operation was successful, and any related handles + are in MatchingHandleBuffer. + @retval EFI_NOT_FOUND No matching handles were found. + @retval EFI_INVALID_PARAMETER A parameter was invalid or out of range. + @sa ParseHandleDatabaseByRelationshipWithType +**/ +EFI_STATUS +EFIAPI +ParseHandleDatabaseByRelationship ( + IN CONST EFI_HANDLE DriverBindingHandle OPTIONAL, + IN CONST EFI_HANDLE ControllerHandle OPTIONAL, + IN CONST UINTN Mask, + IN UINTN *MatchingHandleCount, + OUT EFI_HANDLE **MatchingHandleBuffer OPTIONAL + ); + +/** + Gets all the related EFI_HANDLEs based on the mask supplied. + + This function scans all EFI_HANDLES in the UEFI environment's handle database + and returns the ones with the specified relationship (Mask) to the specified + controller handle. + + If both DriverBindingHandle and ControllerHandle are NULL, then ASSERT. + If MatchingHandleCount is NULL, then ASSERT. + + If MatchingHandleBuffer is not NULL upon a successful return the memory must be + caller freed. + + @param[in] DriverBindingHandle The handle with Driver Binding protocol on it. + @param[in] ControllerHandle The handle with Device Path protocol on it. + @param[in] MatchingHandleCount The pointer to UINTN that specifies the number of HANDLES in + MatchingHandleBuffer. + @param[out] MatchingHandleBuffer On a successful return, a buffer of MatchingHandleCount + EFI_HANDLEs with a terminating NULL EFI_HANDLE. + @param[out] HandleType An array of type information. + + @retval EFI_SUCCESS The operation was successful, and any related handles + are in MatchingHandleBuffer. + @retval EFI_NOT_FOUND No matching handles were found. + @retval EFI_INVALID_PARAMETER A parameter was invalid or out of range. +**/ +EFI_STATUS +EFIAPI +ParseHandleDatabaseByRelationshipWithType ( + IN CONST EFI_HANDLE DriverBindingHandle OPTIONAL, + IN CONST EFI_HANDLE ControllerHandle OPTIONAL, + IN UINTN *HandleCount, + OUT EFI_HANDLE **HandleBuffer, + OUT UINTN **HandleType + ); + +/** + Gets handles for any parents of the passed in controller. + + @param[in] ControllerHandle The handle of the controller. + @param[in] Count The pointer to the number of handles in + MatchingHandleBuffer on return. + @param[out] Buffer The buffer containing handles on a successful + return. + @retval EFI_SUCCESS The operation was successful. + @sa ParseHandleDatabaseByRelationship +**/ +#define PARSE_HANDLE_DATABASE_PARENTS(ControllerHandle, Count, Buffer) \ + ParseHandleDatabaseByRelationship(NULL, ControllerHandle, HR_PARENT_HANDLE, Count, Buffer) + +/** + Gets handles for any UEFI drivers of the passed in controller. + + @param[in] ControllerHandle The handle of the controller. + @param[in] Count The pointer to the number of handles in + MatchingHandleBuffer on return. + @param[out] Buffer The buffer containing handles on a successful + return. + @retval EFI_SUCCESS The operation was successful. + @sa ParseHandleDatabaseByRelationship +**/ +#define PARSE_HANDLE_DATABASE_UEFI_DRIVERS(ControllerHandle, Count, Buffer) \ + ParseHandleDatabaseByRelationship(NULL, ControllerHandle, HR_DRIVER_BINDING_HANDLE|HR_DEVICE_DRIVER, Count, Buffer) + +/** + Gets handles for any children of the passed in controller by the passed in driver handle. + + @param[in] DriverHandle The handle of the driver. + @param[in] ControllerHandle The handle of the controller. + @param[in] Count The pointer to the number of handles in + MatchingHandleBuffer on return. + @param[out] Buffer The buffer containing handles on a successful + return. + @retval EFI_SUCCESS The operation was successful. + @sa ParseHandleDatabaseByRelationship +**/ +#define PARSE_HANDLE_DATABASE_MANAGED_CHILDREN(DriverHandle, ControllerHandle, Count, Buffer) \ + ParseHandleDatabaseByRelationship(DriverHandle, ControllerHandle, HR_CHILD_HANDLE|HR_DEVICE_HANDLE, Count, Buffer) + +/** + Gets handles for any devices managed by the passed in driver. + + @param[in] DriverHandle The handle of the driver. + @param[in] Count The pointer to the number of handles in + MatchingHandleBuffer on return. + @param[out] Buffer The buffer containing handles on a successful + return. + @retval EFI_SUCCESS The operation was successful. + @sa ParseHandleDatabaseByRelationship +**/ +#define PARSE_HANDLE_DATABASE_DEVICES(DriverHandle, Count, Buffer) \ + ParseHandleDatabaseByRelationship(DriverHandle, NULL, HR_CONTROLLER_HANDLE|HR_DEVICE_HANDLE, Count, Buffer) + +/** + Gets handles for any child devices produced by the passed in driver. + + @param[in] DriverHandle The handle of the driver. + @param[in] MatchingHandleCount The pointer to the number of handles in + MatchingHandleBuffer on return. + @param[out] MatchingHandleBuffer The buffer containing handles on a successful + return. + @retval EFI_SUCCESS The operation was successful. + @sa ParseHandleDatabaseByRelationship +**/ +EFI_STATUS +EFIAPI +ParseHandleDatabaseForChildDevices( + IN CONST EFI_HANDLE DriverHandle, + IN UINTN *MatchingHandleCount, + OUT EFI_HANDLE **MatchingHandleBuffer OPTIONAL + ); + +/** + Gets handles for any child controllers of the passed in controller. + + @param[in] ControllerHandle The handle of the "parent controller". + @param[out] MatchingHandleCount The pointer to the number of handles in + MatchingHandleBuffer on return. + @param[out] MatchingHandleBuffer The buffer containing handles on a successful + return. + @retval EFI_SUCCESS The operation was successful. + @sa ParseHandleDatabaseByRelationship +**/ +EFI_STATUS +EFIAPI +ParseHandleDatabaseForChildControllers( + IN CONST EFI_HANDLE ControllerHandle, + OUT UINTN *MatchingHandleCount, + OUT EFI_HANDLE **MatchingHandleBuffer OPTIONAL + ); + + +/** + Function to retrieve the human-friendly index of a given handle. If the handle + does not have a index one will be automatically assigned. The index value is valid + until the termination of the shell application. + + @param[in] TheHandle The handle to retrieve an index for. + + @retval 0 A memory allocation failed. + @return The index of the handle. + +**/ +UINTN +EFIAPI +ConvertHandleToHandleIndex( + IN CONST EFI_HANDLE TheHandle + ); + +/** + Function to retrieve the EFI_HANDLE from the human-friendly index. + + @param[in] TheIndex The index to retrieve the EFI_HANDLE for. + + @retval NULL The index was invalid. + @return The EFI_HANDLE that index represents. + +**/ +EFI_HANDLE +EFIAPI +ConvertHandleIndexToHandle( + IN CONST UINTN TheIndex + ); + +/** + Function to get all handles that support a given protocol or all handles. + + The caller is responsible to free this memory. + + @param[in] ProtocolGuid The guid of the protocol to get handles for. If NULL + then the function will return all handles. + + @retval NULL A memory allocation failed. + @return A NULL terminated list of handles. +**/ +EFI_HANDLE* +EFIAPI +GetHandleListByProtocol ( + IN CONST EFI_GUID *ProtocolGuid OPTIONAL + ); + +/** + Function to get all handles that support some protocols. + + The caller is responsible to free this memory. + + @param[in] ProtocolGuids A NULL terminated list of protocol GUIDs. + + @retval NULL A memory allocation failed. + @retval NULL ProtocolGuids was NULL. + @return A NULL terminated list of EFI_HANDLEs. +**/ +EFI_HANDLE* +EFIAPI +GetHandleListByProtocolList ( + IN CONST EFI_GUID **ProtocolGuids + ); + + +/** + Return all supported GUIDs. + + @param[out] Guids The buffer to return all supported GUIDs. + @param[in, out] Count On input, the count of GUIDs the buffer can hold, + On output, the count of GUIDs to return. + + @retval EFI_INVALID_PARAMETER Count is NULL. + @retval EFI_BUFFER_TOO_SMALL Buffer is not enough to hold all GUIDs. + @retval EFI_SUCCESS GUIDs are returned successfully. +**/ +EFI_STATUS +EFIAPI +GetAllMappingGuids ( + OUT EFI_GUID *Guids, + IN OUT UINTN *Count + ); + +#endif // __HANDLE_PARSING_LIB__ diff --git a/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Library/ShellCEntryLib.h b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Library/ShellCEntryLib.h new file mode 100644 index 00000000..5ebf986a --- /dev/null +++ b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Library/ShellCEntryLib.h @@ -0,0 +1,34 @@ +/** @file + Provides application point extension for "C" style main function. + + Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _SHELL_C_ENTRY_LIB_ +#define _SHELL_C_ENTRY_LIB_ + +/** + UEFI application entry point which has an interface similar to a + standard C main function. + + The ShellCEntryLib library instance wrappers the actual UEFI application + entry point and calls this ShellAppMain function. + + @param[in] Argc The number of parameters. + @param[in] Argv The array of pointers to parameters. + + @retval 0 The application exited normally. + @retval Other An error occurred. + +**/ +INTN +EFIAPI +ShellAppMain ( + IN UINTN Argc, + IN CHAR16 **Argv + ); + +#endif + diff --git a/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Library/ShellCommandLib.h b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Library/ShellCommandLib.h new file mode 100644 index 00000000..61f7317b --- /dev/null +++ b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Library/ShellCommandLib.h @@ -0,0 +1,798 @@ +/** @file + Provides interface to shell internal functions for shell commands. + + This library is for use ONLY by shell commands linked into the shell application. + This library will not function if it is used for UEFI Shell 2.0 Applications. + + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + (C) Copyright 2016 Hewlett Packard Enterprise Development LP<BR> + (C) Copyright 2013-2014 Hewlett-Packard Development Company, L.P.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _SHELL_COMMAND_LIB_ +#define _SHELL_COMMAND_LIB_ + +#include <Uefi.h> + +#include <Protocol/Shell.h> +#include <Protocol/ShellParameters.h> +#include <Protocol/UnicodeCollation.h> +#include <Protocol/SimpleFileSystem.h> + +#include <Library/UefiBootServicesTableLib.h> + +// +// The extern global protocol poionters. +// +extern EFI_UNICODE_COLLATION_PROTOCOL *gUnicodeCollation; +extern CONST CHAR16* SupportLevel[]; + +// +// The map list objects. +// +typedef struct { + LIST_ENTRY Link; + EFI_DEVICE_PATH_PROTOCOL *DevicePath; + CHAR16 *MapName; + CHAR16 *CurrentDirectoryPath; + UINT64 Flags; +} SHELL_MAP_LIST; +/// List of Mappings - DeviceName and Drive Letter(ism). +extern SHELL_MAP_LIST gShellMapList; +/// Pointer to node of current directory in the mMapList. +extern SHELL_MAP_LIST *gShellCurMapping; + +/** + Returns the help MAN fileName for a given shell command. + + @retval !NULL The unicode string of the MAN filename. + @retval NULL An error ocurred. + +**/ +typedef +CONST CHAR16 * +(EFIAPI *SHELL_GET_MAN_FILENAME)( + VOID + ); + +/** + Runs a shell command on a given command line. + + The specific operation of a given shell command is specified in the UEFI Shell + Specification 2.0, or in the source of the given command. + + Upon completion of the command run the shell protocol and environment variables + may have been updated due to the operation. + + @param[in] ImageHandle The ImageHandle to the app, or NULL if + the command built into shell. + @param[in] SystemTable The pointer to the system table. + + @retval RETURN_SUCCESS The shell command was sucessful. + @retval RETURN_UNSUPPORTED The command is not supported. +**/ +typedef +SHELL_STATUS +(EFIAPI *SHELL_RUN_COMMAND)( + IN EFI_HANDLE ImageHandle, + IN EFI_SYSTEM_TABLE *SystemTable + ); + +/** + Registers the handlers of type SHELL_RUN_COMMAND and + SHELL_GET_MAN_FILENAME for each shell command. + + If the ShellSupportLevel is greater than the value of + PcdShellSupportLevel, then return RETURN_UNSUPPORTED. + + Registers the the handlers specified by GetHelpInfoHandler and CommandHandler + with the command specified by CommandString. If the command named by + CommandString has already been registered, then return + RETURN_ALREADY_STARTED. + + If there are not enough resources available to register the handlers, then + RETURN_OUT_OF_RESOURCES is returned. + + If CommandString is NULL, then ASSERT(). + If GetHelpInfoHandler is NULL, then ASSERT(). + If CommandHandler is NULL, then ASSERT(). + If ProfileName is NULL, then ASSERT(). + + @param[in] CommandString The pointer to the command name. This is the + name to look for on the command line in + the shell. + @param[in] CommandHandler The pointer to a function that runs the + specified command. + @param[in] GetManFileName The pointer to a function that provides man + filename. + @param[in] ShellMinSupportLevel The minimum Shell Support Level which has this + function. + @param[in] ProfileName The profile name to require for support of this + function. + @param[in] CanAffectLE Indicates whether this command's return value + can change the LASTERROR environment variable. + @param[in] HiiHandle The handle of this command's HII entry. + @param[in] ManFormatHelp The HII locator for the help text. + + @retval RETURN_SUCCESS The handlers were registered. + @retval RETURN_OUT_OF_RESOURCES There are not enough resources available to + register the shell command. + @retval RETURN_UNSUPPORTED The ShellMinSupportLevel was higher than the + currently allowed support level. + @retval RETURN_ALREADY_STARTED The CommandString represents a command that + is already registered. Only one handler set for + a given command is allowed. + @sa SHELL_GET_MAN_FILENAME + @sa SHELL_RUN_COMMAND +**/ +RETURN_STATUS +EFIAPI +ShellCommandRegisterCommandName ( + IN CONST CHAR16 *CommandString, + IN SHELL_RUN_COMMAND CommandHandler, + IN SHELL_GET_MAN_FILENAME GetManFileName, + IN UINT32 ShellMinSupportLevel, + IN CONST CHAR16 *ProfileName, + IN CONST BOOLEAN CanAffectLE, + IN CONST EFI_HII_HANDLE HiiHandle, + IN CONST EFI_STRING_ID ManFormatHelp + ); + +/** + Checks if a command string has been registered for CommandString, and if so, it runs + the previously registered handler for that command with the command line. + + If CommandString is NULL, then ASSERT(). + + If Sections is specified, then each section name listed will be compared in a case sensitive + manner to the section names described in Appendix B UEFI Shell 2.0 Specification. If the section exists, + it is appended to the returned help text. If the section does not exist, no + information is returned. If Sections is NULL, then all help text information + available is returned. + + @param[in] CommandString The pointer to the command name. This is the name + found on the command line in the shell. + @param[in, out] RetVal The pointer to the return value from the command handler. + + @param[in, out] CanAffectLE Indicates whether this command's return value + needs to be placed into LASTERROR environment variable. + + @retval RETURN_SUCCESS The handler was run. + @retval RETURN_NOT_FOUND The CommandString did not match a registered + command name. + @sa SHELL_RUN_COMMAND +**/ +RETURN_STATUS +EFIAPI +ShellCommandRunCommandHandler ( + IN CONST CHAR16 *CommandString, + IN OUT SHELL_STATUS *RetVal, + IN OUT BOOLEAN *CanAffectLE OPTIONAL + ); + +/** + Checks if a command string has been registered for CommandString, and if so, it + returns the MAN filename specified for that command. + + If CommandString is NULL, then ASSERT(). + + @param[in] CommandString The pointer to the command name. This is the name + found on the command line in the shell. + + @retval NULL The CommandString was not a registered command. + @retval other The name of the MAN file. + @sa SHELL_GET_MAN_FILENAME +**/ +CONST CHAR16* +EFIAPI +ShellCommandGetManFileNameHandler ( + IN CONST CHAR16 *CommandString + ); + + +typedef struct { + LIST_ENTRY Link; + CHAR16 *CommandString; +} COMMAND_LIST; + +/** + Get the list of all available shell internal commands. This is a linked list, + via the LIST_ENTRY structure. Enumerate through it using the BaseLib linked + list functions. Do not modify the values. + + @param[in] Sort TRUE to alphabetically sort the values first. FALSE otherwise. + + @return A linked list of all available shell commands. +**/ +CONST COMMAND_LIST* +EFIAPI +ShellCommandGetCommandList ( + IN CONST BOOLEAN Sort + ); + +typedef struct { + LIST_ENTRY Link; + CHAR16 *CommandString; + CHAR16 *Alias; +} ALIAS_LIST; + +/** + Registers aliases to be set as part of the initialization of the shell application. + + If Command is NULL, then ASSERT(). + If Alias is NULL, then ASSERT(). + + @param[in] Command The pointer to the Command. + @param[in] Alias The pointer to Alias. + + @retval RETURN_SUCCESS The handlers were registered. + @retval RETURN_OUT_OF_RESOURCES There are not enough resources available to + register the shell command. +**/ +RETURN_STATUS +EFIAPI +ShellCommandRegisterAlias ( + IN CONST CHAR16 *Command, + IN CONST CHAR16 *Alias + ); + +/** + Get the list of all shell alias commands. This is a linked list, + via LIST_ENTRY structure. Enumerate through it using the BaseLib linked + list functions. Do not modify the values. + + @return A linked list of all requested shell aliases. +**/ +CONST ALIAS_LIST* +EFIAPI +ShellCommandGetInitAliasList ( + VOID + ); + +/** + Determine if a given alias is on the list of built in aliases. + + @param[in] Alias The alias to test for. + + @retval TRUE The alias is a built in alias. + @retval FALSE The alias is not a built in alias. +**/ +BOOLEAN +EFIAPI +ShellCommandIsOnAliasList ( + IN CONST CHAR16 *Alias + ); + +/** + Checks if a command is already on the list. + + @param[in] CommandString The command string to check for on the list. + + @retval TRUE CommandString represents a registered command. + @retval FALSE CommandString does not represent a registered command. +**/ +BOOLEAN +EFIAPI +ShellCommandIsCommandOnList ( + IN CONST CHAR16 *CommandString + ); + +/** + Get the help text for a command. + + @param[in] CommandString The command name. + + @retval NULL No help text was found. + @return The string of the help text. The caller required to free. +**/ +CHAR16* +EFIAPI +ShellCommandGetCommandHelp ( + IN CONST CHAR16 *CommandString + ); + +/** + Function to make sure that the above pointers are valid. +**/ +EFI_STATUS +EFIAPI +CommandInit ( + VOID + ); + +/** + Function to determine current state of ECHO. Echo determines if lines from scripts + and ECHO commands are enabled. + + @retval TRUE Echo is currently enabled. + @retval FALSE Echo is currently disabled. +**/ +BOOLEAN +EFIAPI +ShellCommandGetEchoState ( + VOID + ); + +/** + Function to set current state of ECHO. Echo determines if lines from scripts + and ECHO commands are enabled. + + @param[in] State TRUE to enable Echo, FALSE otherwise. +**/ +VOID +EFIAPI +ShellCommandSetEchoState ( + IN BOOLEAN State + ); + + + +/** + Indicate that the current shell or script should exit. + + @param[in] ScriptOnly TRUE if exiting a script; FALSE otherwise. + @param[in] ErrorCode The 64 bit error code to return. +**/ +VOID +EFIAPI +ShellCommandRegisterExit ( + IN BOOLEAN ScriptOnly, + IN CONST UINT64 ErrorCode + ); + +/** + Retrieve the Exit code. + + @return the value passed into RegisterExit. +**/ +UINT64 +EFIAPI +ShellCommandGetExitCode ( + VOID + ); + +/** + Retrieve the Exit indicator. + + @retval TRUE Exit was indicated. + @retval FALSE Exit was not indicated. +**/ +BOOLEAN +EFIAPI +ShellCommandGetExit ( + VOID + ); + +/** + Retrieve the Exit script indicator. + + If ShellCommandGetExit returns FALSE, then the return from this is undefined. + + @retval TRUE ScriptOnly was indicated. + @retval FALSE ScriptOnly was not indicated. +**/ +BOOLEAN +EFIAPI +ShellCommandGetScriptExit ( + VOID + ); + +typedef struct { + LIST_ENTRY Link; ///< List enumerator items. + UINTN Line; ///< What line of the script file this was on. + CHAR16 *Cl; ///< The original command line. + VOID *Data; ///< The data structure format dependant upon Command. (not always used) + BOOLEAN Reset; ///< Reset the command (it must be treated like a initial run (but it may have data already)) +} SCRIPT_COMMAND_LIST; + +typedef struct { + CHAR16 *ScriptName; ///< The filename of this script. + CHAR16 **Argv; ///< The parmameters to the script file. + UINTN Argc; ///< The count of parameters. + LIST_ENTRY CommandList; ///< The script converted to a list of commands (SCRIPT_COMMAND_LIST objects). + SCRIPT_COMMAND_LIST *CurrentCommand; ///< The command currently being operated. If !=NULL must be a member of CommandList. + LIST_ENTRY SubstList; ///< A list of current script loop alias' (ALIAS_LIST objects) (Used for the for %-based replacement). +} SCRIPT_FILE; + +/** + Function to return a pointer to the currently running script file object. + + @retval NULL A script file is not currently running. + @return A pointer to the current script file object. +**/ +SCRIPT_FILE* +EFIAPI +ShellCommandGetCurrentScriptFile ( + VOID + ); + +/** + Function to set a new script as the currently running one. + + This function will correctly stack and unstack nested scripts. + + @param[in] Script The pointer to new script information structure. If NULL, + it removes and de-allocates the topmost Script structure. + + @return A pointer to the current running script file after this + change. It is NULL if removing the final script. +**/ +SCRIPT_FILE* +EFIAPI +ShellCommandSetNewScript ( + IN SCRIPT_FILE *Script OPTIONAL + ); + +/** + Function to cleanup all memory from a SCRIPT_FILE structure. + + @param[in] Script The pointer to the structure to cleanup. +**/ +VOID +EFIAPI +DeleteScriptFileStruct ( + IN SCRIPT_FILE *Script + ); + +/** + Function to get the current Profile string. + + This is used to retrieve what profiles were installed. + + @retval NULL There are no installed profiles. + @return A semicolon-delimited list of profiles. +**/ +CONST CHAR16 * +EFIAPI +ShellCommandGetProfileList ( + VOID + ); + +typedef enum { + MappingTypeFileSystem, + MappingTypeBlockIo, + MappingTypeMax +} SHELL_MAPPING_TYPE; + +/** + Function to generate the next default mapping name. + + If the return value is not NULL then it must be callee freed. + + @param Type What kind of mapping name to make. + + @retval NULL a memory allocation failed. + @return a new map name string +**/ +CHAR16* +EFIAPI +ShellCommandCreateNewMappingName( + IN CONST SHELL_MAPPING_TYPE Type + ); + +/** + Function to initialize the table for creating consistent map names. + + @param[out] Table The pointer to pointer to pointer to DevicePathProtocol object. + + @retval EFI_SUCCESS The table was created successfully. +**/ +EFI_STATUS +EFIAPI +ShellCommandConsistMappingInitialize ( + EFI_DEVICE_PATH_PROTOCOL ***Table + ); + +/** + Function to uninitialize the table for creating consistent map names. + + The parameter must have been received from ShellCommandConsistMappingInitialize. + + @param[out] Table The pointer to pointer to DevicePathProtocol object. + + @retval EFI_SUCCESS The table was deleted successfully. +**/ +EFI_STATUS +EFIAPI +ShellCommandConsistMappingUnInitialize ( + EFI_DEVICE_PATH_PROTOCOL **Table + ); + +/** + Create a consistent mapped name for the device specified by DevicePath + based on the Table. + + This must be called after ShellCommandConsistMappingInitialize() and + before ShellCommandConsistMappingUnInitialize() is called. + + @param[in] DevicePath The pointer to the dev path for the device. + @param[in] Table The Table of mapping information. + + @retval NULL A consistent mapped name could not be created. + @return A pointer to a string allocated from pool with the device name. +**/ +CHAR16* +EFIAPI +ShellCommandConsistMappingGenMappingName ( + IN EFI_DEVICE_PATH_PROTOCOL *DevicePath, + IN EFI_DEVICE_PATH_PROTOCOL **Table + ); + +/** + Function to search the list of mappings for the first matching node on the + list based on the MapKey. + + @param[in] MapKey The pointer to the string key to search for in the map. + + @return the node on the list. +**/ +SHELL_MAP_LIST* +EFIAPI +ShellCommandFindMapItem ( + IN CONST CHAR16 *MapKey + ); + +/** + Function to add a map node to the list of map items and update the "path" environment variable (optionally). + + If Path is TRUE (during initialization only), the path environment variable will also be updated to include + default paths on the new map name... + + Path should be FALSE when this function is called from the protocol SetMap function. + + @param[in] Name The human readable mapped name. + @param[in] DevicePath The Device Path for this map. + @param[in] Flags The Flags attribute for this map item. + @param[in] Path TRUE to update path, FALSE to skip this step (should only be TRUE during initialization). + + @retval EFI_SUCCESS The addition was sucessful. + @retval EFI_OUT_OF_RESOURCES A memory allocation failed. + @retval EFI_INVALID_PARAMETER A parameter was invalid. +**/ +EFI_STATUS +EFIAPI +ShellCommandAddMapItemAndUpdatePath( + IN CONST CHAR16 *Name, + IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, + IN CONST UINT64 Flags, + IN CONST BOOLEAN Path + ); + +/** + Creates the default map names for each device path in the system with + a protocol depending on the Type. + + Also sets up the default path environment variable if Type is FileSystem. + + @retval EFI_SUCCESS All map names were created sucessfully. + @retval EFI_NOT_FOUND No protocols were found in the system. + @return Error returned from gBS->LocateHandle(). + + @sa LocateHandle +**/ +EFI_STATUS +EFIAPI +ShellCommandCreateInitialMappingsAndPaths( + VOID + ); + +/** + Add mappings for any devices without one. Do not change any existing maps. + + @retval EFI_SUCCESS The operation was successful. +**/ +EFI_STATUS +EFIAPI +ShellCommandUpdateMapping ( + VOID + ); + +/** + Converts a SHELL_FILE_HANDLE to an EFI_FILE_PROTOCOL*. + + @param[in] Handle The SHELL_FILE_HANDLE to convert. + + @return a EFI_FILE_PROTOCOL* representing the same file. +**/ +EFI_FILE_PROTOCOL* +EFIAPI +ConvertShellHandleToEfiFileProtocol( + IN CONST SHELL_FILE_HANDLE Handle + ); + +/** + Remove a SHELL_FILE_HANDLE frmo the list of SHELL_FILE_HANDLES. + + @param[in] Handle The SHELL_FILE_HANDLE to remove. + + @retval TRUE The item was removed. + @retval FALSE The item was not found. +**/ +BOOLEAN +EFIAPI +ShellFileHandleRemove( + IN CONST SHELL_FILE_HANDLE Handle + ); + +/** + Converts a EFI_FILE_PROTOCOL* to an SHELL_FILE_HANDLE. + + @param[in] Handle The pointer to EFI_FILE_PROTOCOL to convert. + @param[in] Path The path to the file for verification. + + @return a SHELL_FILE_HANDLE representing the same file. +**/ +SHELL_FILE_HANDLE +EFIAPI +ConvertEfiFileProtocolToShellHandle( + IN CONST EFI_FILE_PROTOCOL *Handle, + IN CONST CHAR16 *Path + ); + +/** + Find the path that was logged with the specified SHELL_FILE_HANDLE. + + @param[in] Handle The SHELL_FILE_HANDLE to query on. + + @return A pointer to the path for the file. +**/ +CONST CHAR16* +EFIAPI +ShellFileHandleGetPath( + IN CONST SHELL_FILE_HANDLE Handle + ); + + +/** + Function to determine if a SHELL_FILE_HANDLE is at the end of the file. + + This will NOT work on directories. + + If Handle is NULL, then ASSERT. + + @param[in] Handle the file handle + + @retval TRUE the position is at the end of the file + @retval FALSE the position is not at the end of the file +**/ +BOOLEAN +EFIAPI +ShellFileHandleEof( + IN SHELL_FILE_HANDLE Handle + ); + +typedef struct { + LIST_ENTRY Link; + void *Buffer; +} BUFFER_LIST; + +/** + Frees any BUFFER_LIST defined type. + + @param[in] List The pointer to the list head. +**/ +VOID +EFIAPI +FreeBufferList ( + IN BUFFER_LIST *List + ); + +/** + Function printing hex output to the console. + + @param[in] Indent Number of spaces to indent. + @param[in] Offset Offset to start with. + @param[in] DataSize Length of data. + @param[in] UserData Pointer to some data. +**/ +VOID +EFIAPI +DumpHex ( + IN UINTN Indent, + IN UINTN Offset, + IN UINTN DataSize, + IN VOID *UserData + ); + +/** + Dump HEX data into buffer. + + @param[in] Buffer HEX data to be dumped in Buffer. + @param[in] Indent How many spaces to indent the output. + @param[in] Offset The offset of the printing. + @param[in] DataSize The size in bytes of UserData. + @param[in] UserData The data to print out. +**/ +CHAR16* +EFIAPI +CatSDumpHex ( + IN CHAR16 *Buffer, + IN UINTN Indent, + IN UINTN Offset, + IN UINTN DataSize, + IN VOID *UserData + ); + +// +// Determines the ordering operation for ShellSortFileList(). +// +typedef enum { + // + // Sort the EFI_SHELL_FILE_INFO objects by the FileName field, in increasing + // order, using gUnicodeCollation->StriColl(). + // + ShellSortFileListByFileName, + // + // Sort the EFI_SHELL_FILE_INFO objects by the FullName field, in increasing + // order, using gUnicodeCollation->StriColl(). + // + ShellSortFileListByFullName, + ShellSortFileListMax +} SHELL_SORT_FILE_LIST; + +/** + Sort an EFI_SHELL_FILE_INFO list, optionally moving duplicates to a separate + list. + + @param[in,out] FileList The list of EFI_SHELL_FILE_INFO objects to sort. + + If FileList is NULL on input, then FileList is + considered an empty, hence already sorted, list. + + Otherwise, if (*FileList) is NULL on input, then + EFI_INVALID_PARAMETER is returned. + + Otherwise, the caller is responsible for having + initialized (*FileList)->Link with + InitializeListHead(). No other fields in the + (**FileList) head element are accessed by this + function. + + On output, (*FileList) is sorted according to Order. + If Duplicates is NULL on input, then duplicate + elements are preserved, sorted stably, on + (*FileList). If Duplicates is not NULL on input, + then duplicates are moved (stably sorted) to the + new, dynamically allocated (*Duplicates) list. + + @param[out] Duplicates If Duplicates is NULL on input, (*FileList) will be + a monotonically ordered list on output, with + duplicates stably sorted. + + If Duplicates is not NULL on input, (*FileList) will + be a strictly monotonically oredered list on output, + with duplicates separated (stably sorted) to + (*Duplicates). All fields except Link will be + zero-initialized in the (**Duplicates) head element. + If no duplicates exist, then (*Duplicates) is set to + NULL on output. + + @param[in] Order Determines the comparison operation between + EFI_SHELL_FILE_INFO objects. + + @retval EFI_INVALID_PARAMETER (UINTN)Order is greater than or equal to + (UINTN)ShellSortFileListMax. Neither the + (*FileList) nor the (*Duplicates) list has + been modified. + + @retval EFI_INVALID_PARAMETER (*FileList) was NULL on input. Neither the + (*FileList) nor the (*Duplicates) list has + been modified. + + @retval EFI_OUT_OF_RESOURCES Memory allocation failed. Neither the + (*FileList) nor the (*Duplicates) list has + been modified. + + @retval EFI_SUCCESS Sorting successful, including the case when + FileList is NULL on input. +**/ +EFI_STATUS +EFIAPI +ShellSortFileList ( + IN OUT EFI_SHELL_FILE_INFO **FileList, + OUT EFI_SHELL_FILE_INFO **Duplicates OPTIONAL, + IN SHELL_SORT_FILE_LIST Order + ); +#endif //_SHELL_COMMAND_LIB_ diff --git a/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Library/ShellLib.h b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Library/ShellLib.h new file mode 100644 index 00000000..94e4994d --- /dev/null +++ b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Library/ShellLib.h @@ -0,0 +1,1432 @@ +/** @file + Provides interface to shell functionality for shell commands and applications. + + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + Copyright 2018 Dell Technologies.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef __SHELL_LIB__ +#define __SHELL_LIB__ + +#include <Uefi.h> +#include <Guid/FileInfo.h> +#include <Protocol/SimpleFileSystem.h> +#include <Protocol/LoadedImage.h> +#include <Protocol/EfiShellInterface.h> +#include <Protocol/EfiShellEnvironment2.h> +#include <Protocol/Shell.h> +#include <Protocol/ShellParameters.h> + +#define SHELL_FREE_NON_NULL(Pointer) \ + do { \ + if ((Pointer) != NULL) { \ + FreePool((Pointer)); \ + (Pointer) = NULL; \ + } \ + } while(FALSE) + +extern EFI_SHELL_PARAMETERS_PROTOCOL *gEfiShellParametersProtocol; +extern EFI_SHELL_PROTOCOL *gEfiShellProtocol; + +/** + Return a clean, fully-qualified version of an input path. If the return value + is non-NULL the caller must free the memory when it is no longer needed. + + If asserts are disabled, and if the input parameter is NULL, NULL is returned. + + If there is not enough memory available to create the fully-qualified path or + a copy of the input path, NULL is returned. + + If there is no working directory, a clean copy of Path is returned. + + Otherwise, the current file system or working directory (as appropriate) is + prepended to Path and the resulting path is cleaned and returned. + + NOTE: If the input path is an empty string, then the current working directory + (if it exists) is returned. In other words, an empty input path is treated + exactly the same as ".". + + @param[in] Path A pointer to some file or directory path. + + @retval NULL The input path is NULL or out of memory. + + @retval non-NULL A pointer to a clean, fully-qualified version of Path. + If there is no working directory, then a pointer to a + clean, but not necessarily fully-qualified version of + Path. The caller must free this memory when it is no + longer needed. +**/ +CHAR16* +EFIAPI +FullyQualifyPath( + IN CONST CHAR16 *Path + ); + +/** + This function will retrieve the information about the file for the handle + specified and store it in allocated pool memory. + + This function allocates a buffer to store the file's information. It is the + caller's responsibility to free the buffer. + + @param[in] FileHandle The file handle of the file for which information is + being requested. + + @retval NULL Information could not be retrieved. + + @return The information about the file. +**/ +EFI_FILE_INFO* +EFIAPI +ShellGetFileInfo ( + IN SHELL_FILE_HANDLE FileHandle + ); + +/** + This function sets the information about the file for the opened handle + specified. + + @param[in] FileHandle The file handle of the file for which information + is being set. + + @param[in] FileInfo The information to set. + + @retval EFI_SUCCESS The information was set. + @retval EFI_INVALID_PARAMETER A parameter was out of range or invalid. + @retval EFI_UNSUPPORTED The FileHandle does not support FileInfo. + @retval EFI_NO_MEDIA The device has no medium. + @retval EFI_DEVICE_ERROR The device reported an error. + @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + @retval EFI_WRITE_PROTECTED The file or medium is write protected. + @retval EFI_ACCESS_DENIED The file was opened read only. + @retval EFI_VOLUME_FULL The volume is full. +**/ +EFI_STATUS +EFIAPI +ShellSetFileInfo ( + IN SHELL_FILE_HANDLE FileHandle, + IN EFI_FILE_INFO *FileInfo + ); + +/** + This function will open a file or directory referenced by DevicePath. + + This function opens a file with the open mode according to the file path. The + Attributes is valid only for EFI_FILE_MODE_CREATE. + + @param[in, out] FilePath On input, the device path to the file. On output, + the remaining device path. + @param[out] FileHandle Pointer to the file handle. + @param[in] OpenMode The mode to open the file with. + @param[in] Attributes The file's file attributes. + + @retval EFI_SUCCESS The information was set. + @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. + @retval EFI_UNSUPPORTED Could not open the file path. + @retval EFI_NOT_FOUND The specified file could not be found on the + device or the file system could not be found on + the device. + @retval EFI_NO_MEDIA The device has no medium. + @retval EFI_MEDIA_CHANGED The device has a different medium in it or the + medium is no longer supported. + @retval EFI_DEVICE_ERROR The device reported an error. + @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + @retval EFI_WRITE_PROTECTED The file or medium is write protected. + @retval EFI_ACCESS_DENIED The file was opened read only. + @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the + file. + @retval EFI_VOLUME_FULL The volume is full. +**/ +EFI_STATUS +EFIAPI +ShellOpenFileByDevicePath( + IN OUT EFI_DEVICE_PATH_PROTOCOL **FilePath, + OUT SHELL_FILE_HANDLE *FileHandle, + IN UINT64 OpenMode, + IN UINT64 Attributes + ); + +/** + This function will open a file or directory referenced by filename. + + If return is EFI_SUCCESS, the Filehandle is the opened file's handle; + otherwise, the Filehandle is NULL. Attributes is valid only for + EFI_FILE_MODE_CREATE. + + @param[in] FileName The pointer to file name. + @param[out] FileHandle The pointer to the file handle. + @param[in] OpenMode The mode to open the file with. + @param[in] Attributes The file's file attributes. + + @retval EFI_SUCCESS The information was set. + @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. + @retval EFI_UNSUPPORTED Could not open the file path. + @retval EFI_NOT_FOUND The specified file could not be found on the + device or the file system could not be found + on the device. + @retval EFI_NO_MEDIA The device has no medium. + @retval EFI_MEDIA_CHANGED The device has a different medium in it or the + medium is no longer supported. + @retval EFI_DEVICE_ERROR The device reported an error. + @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + @retval EFI_WRITE_PROTECTED The file or medium is write protected. + @retval EFI_ACCESS_DENIED The file was opened read only. + @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the + file. + @retval EFI_VOLUME_FULL The volume is full. +**/ +EFI_STATUS +EFIAPI +ShellOpenFileByName( + IN CONST CHAR16 *FileName, + OUT SHELL_FILE_HANDLE *FileHandle, + IN UINT64 OpenMode, + IN UINT64 Attributes + ); + +/** + This function creates a directory. + + If return is EFI_SUCCESS, the Filehandle is the opened directory's handle; + otherwise, the Filehandle is NULL. If the directory already existed, this + function opens the existing directory. + + @param[in] DirectoryName The pointer to Directory name. + @param[out] FileHandle The pointer to the file handle. + + @retval EFI_SUCCESS The information was set. + @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. + @retval EFI_UNSUPPORTED Could not open the file path. + @retval EFI_NOT_FOUND The specified file could not be found on the + device, or the file system could not be found + on the device. + @retval EFI_NO_MEDIA The device has no medium. + @retval EFI_MEDIA_CHANGED The device has a different medium in it or the + medium is no longer supported. + @retval EFI_DEVICE_ERROR The device reported an error. + @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + @retval EFI_WRITE_PROTECTED The file or medium is write protected. + @retval EFI_ACCESS_DENIED The file was opened read only. + @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the + file. + @retval EFI_VOLUME_FULL The volume is full. +**/ +EFI_STATUS +EFIAPI +ShellCreateDirectory( + IN CONST CHAR16 *DirectoryName, + OUT SHELL_FILE_HANDLE *FileHandle + ); + +/** + This function reads information from an opened file. + + If FileHandle is not a directory, the function reads the requested number of + bytes from the file at the file's current position and returns them in Buffer. + If the read goes beyond the end of the file, the read length is truncated to the + end of the file. The file's current position is increased by the number of bytes + returned. If FileHandle is a directory, the function reads the directory entry + at the file's current position and returns the entry in Buffer. If the Buffer + is not large enough to hold the current directory entry, 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 current position is updated to the next directory entry. If there + are no more directory entries, the read returns a zero-length buffer. + EFI_FILE_INFO is the structure returned as the directory entry. + + @param[in] FileHandle The opened file handle. + @param[in, out] ReadSize On input the size of buffer in bytes. On return + the number of bytes written. + @param[out] Buffer The buffer to put read data into. + + @retval EFI_SUCCESS Data was read. + @retval EFI_NO_MEDIA The device has no media. + @retval EFI_DEVICE_ERROR The device reported an error. + @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + @retval EFI_BUFFER_TO_SMALL Buffer is too small. ReadSize contains required + size. + +**/ +EFI_STATUS +EFIAPI +ShellReadFile( + IN SHELL_FILE_HANDLE FileHandle, + IN OUT UINTN *ReadSize, + OUT VOID *Buffer + ); + +/** + Write data to a file. + + This function writes the specified number of bytes to the file at the current + file position. The current file 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 to + opened directories are not supported. + + @param[in] FileHandle The opened file for writing. + + @param[in, out] BufferSize On input the number of bytes in Buffer. On output + the number of bytes written. + + @param[in] Buffer The buffer containing data to write is stored. + + @retval EFI_SUCCESS Data was written. + @retval EFI_UNSUPPORTED Writes to an open directory are not supported. + @retval EFI_NO_MEDIA The device has no media. + @retval EFI_DEVICE_ERROR The device reported an error. + @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + @retval EFI_WRITE_PROTECTED The device is write-protected. + @retval EFI_ACCESS_DENIED The file was open for read only. + @retval EFI_VOLUME_FULL The volume is full. +**/ +EFI_STATUS +EFIAPI +ShellWriteFile( + IN SHELL_FILE_HANDLE FileHandle, + IN OUT UINTN *BufferSize, + IN VOID *Buffer + ); + +/** + Close an open file handle. + + This function closes a specified file handle. All "dirty" cached file data is + flushed to the device, and the file is closed. In all cases the handle is + closed. + + @param[in] FileHandle The file handle to close. + + @retval EFI_SUCCESS The file handle was closed sucessfully. + @retval INVALID_PARAMETER One of the parameters has an invalid value. +**/ +EFI_STATUS +EFIAPI +ShellCloseFile ( + IN SHELL_FILE_HANDLE *FileHandle + ); + +/** + Delete a file and close the handle + + This function closes and deletes a file. In all cases the file handle is closed. + If the file cannot be deleted, the warning code EFI_WARN_DELETE_FAILURE is + returned, but the handle is still closed. + + @param[in] FileHandle The file handle to delete. + + @retval EFI_SUCCESS The file was closed sucessfully. + @retval EFI_WARN_DELETE_FAILURE The handle was closed, but the file was not + deleted. + @retval INVALID_PARAMETER One of the parameters has an invalid value. +**/ +EFI_STATUS +EFIAPI +ShellDeleteFile ( + IN SHELL_FILE_HANDLE *FileHandle + ); + +/** + Set the current position in a file. + + This function sets the current file position for the handle to the position + supplied. With the exception of seeking to position 0xFFFFFFFFFFFFFFFF, only + absolute positioning is supported, and moving past the end of the file is + allowed (a subsequent write would grow the file). Moving to position + 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 of starting the read process of the directory entries over. + + @param[in] FileHandle The file handle on which the position is being set. + + @param[in] Position The byte position from the begining of the file. + + @retval EFI_SUCCESS Operation completed sucessfully. + @retval EFI_UNSUPPORTED The seek request for non-zero is not valid on + directories. + @retval INVALID_PARAMETER One of the parameters has an invalid value. +**/ +EFI_STATUS +EFIAPI +ShellSetFilePosition ( + IN SHELL_FILE_HANDLE FileHandle, + IN UINT64 Position + ); + +/** + Gets a file's current position + + This function retrieves the current file position for the file handle. For + directories, the current file position 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. + + @param[in] FileHandle The open file handle on which to get the position. + @param[out] Position The byte position from the begining of the file. + + @retval EFI_SUCCESS The operation completed sucessfully. + @retval INVALID_PARAMETER One of the parameters has an invalid value. + @retval EFI_UNSUPPORTED The request is not valid on directories. +**/ +EFI_STATUS +EFIAPI +ShellGetFilePosition ( + IN SHELL_FILE_HANDLE FileHandle, + OUT UINT64 *Position + ); + +/** + Flushes data on a file + + This function flushes all modified data associated with a file to a device. + + @param[in] FileHandle The file handle on which to flush data. + + @retval EFI_SUCCESS The data was flushed. + @retval EFI_NO_MEDIA The device has no media. + @retval EFI_DEVICE_ERROR The device reported an error. + @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + @retval EFI_WRITE_PROTECTED The file or medium is write protected. + @retval EFI_ACCESS_DENIED The file was opened for read only. +**/ +EFI_STATUS +EFIAPI +ShellFlushFile ( + IN SHELL_FILE_HANDLE FileHandle + ); + +/** Retrieve first entry from a directory. + + This function takes an open directory handle and gets information from the + first entry in the directory. A buffer is allocated to contain + the information and a pointer to the buffer is returned in *Buffer. The + caller can use ShellFindNextFile() to get subsequent directory entries. + + The buffer will be freed by ShellFindNextFile() when the last directory + entry is read. Otherwise, the caller must free the buffer, using FreePool, + when finished with it. + + @param[in] DirHandle The file handle of the directory to search. + @param[out] Buffer The pointer to the buffer for the file's information. + + @retval EFI_SUCCESS Found the first file. + @retval EFI_NOT_FOUND Cannot find the directory. + @retval EFI_NO_MEDIA The device has no media. + @retval EFI_DEVICE_ERROR The device reported an error. + @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + @return Others Status of ShellGetFileInfo, ShellSetFilePosition, + or ShellReadFile. + + @sa ShellReadFile +**/ +EFI_STATUS +EFIAPI +ShellFindFirstFile ( + IN SHELL_FILE_HANDLE DirHandle, + OUT EFI_FILE_INFO **Buffer + ); + +/** Retrieve next entries from a directory. + + To use this function, the caller must first call the ShellFindFirstFile() + function to get the first directory entry. Subsequent directory entries are + retrieved by using the ShellFindNextFile() function. This function can + be called several times to get each entry from the directory. If the call of + ShellFindNextFile() retrieved the last directory entry, the next call of + this function will set *NoFile to TRUE and free the buffer. + + @param[in] DirHandle The file handle of the directory. + @param[in, out] Buffer The pointer to buffer for file's information. + @param[in, out] NoFile The pointer to boolean when last file is found. + + @retval EFI_SUCCESS Found the next file. + @retval EFI_NO_MEDIA The device has no media. + @retval EFI_DEVICE_ERROR The device reported an error. + @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + + @sa ShellReadFile +**/ +EFI_STATUS +EFIAPI +ShellFindNextFile( + IN SHELL_FILE_HANDLE DirHandle, + IN OUT EFI_FILE_INFO *Buffer, + IN OUT BOOLEAN *NoFile + ); + +/** + Retrieve the size of a file. + + This function extracts the file size info from the FileHandle's EFI_FILE_INFO + data. + + @param[in] FileHandle The file handle from which size is retrieved. + @param[out] Size The pointer to size. + + @retval EFI_SUCCESS The operation was completed sucessfully. + @retval EFI_DEVICE_ERROR Cannot access the file. +**/ +EFI_STATUS +EFIAPI +ShellGetFileSize ( + IN SHELL_FILE_HANDLE FileHandle, + OUT UINT64 *Size + ); + +/** + Retrieves the status of the break execution flag + + This function is useful to check whether the application is being asked to halt by the shell. + + @retval TRUE The execution break is enabled. + @retval FALSE The execution break is not enabled. +**/ +BOOLEAN +EFIAPI +ShellGetExecutionBreakFlag( + VOID + ); + +/** + Return the value of an environment variable. + + This function gets the value of the environment variable set by the + ShellSetEnvironmentVariable function. + + @param[in] EnvKey The key name of the environment variable. + + @retval NULL The named environment variable does not exist. + @return != NULL The pointer to the value of the environment variable. +**/ +CONST CHAR16* +EFIAPI +ShellGetEnvironmentVariable ( + IN CONST CHAR16 *EnvKey + ); + +/** + Set the value of an environment variable. + + This function changes the current value of the specified environment variable. If the + environment variable exists and the Value is an empty string, then the environment + variable is deleted. If the environment variable exists and the Value is not an empty + string, then the value of the environment variable is changed. If the environment + variable does not exist and the Value is an empty string, there is no action. If the + environment variable does not exist and the Value is a non-empty string, then the + environment variable is created and assigned the specified value. + + This is not supported pre-UEFI Shell 2.0. + + @param[in] EnvKey The key name of the environment variable. + @param[in] EnvVal The Value of the environment variable + @param[in] Volatile Indicates whether the variable is non-volatile (FALSE) or volatile (TRUE). + + @retval EFI_SUCCESS The operation completed sucessfully + @retval EFI_UNSUPPORTED This operation is not allowed in pre-UEFI 2.0 Shell environments. +**/ +EFI_STATUS +EFIAPI +ShellSetEnvironmentVariable ( + IN CONST CHAR16 *EnvKey, + IN CONST CHAR16 *EnvVal, + IN BOOLEAN Volatile + ); + +/** + Cause the shell to parse and execute a command line. + + This function creates a nested instance of the shell and executes the specified + command (CommandLine) with the specified environment (Environment). Upon return, + the status code returned by the specified command is placed in StatusCode. + If Environment is NULL, then the current environment is used and all changes made + by the commands executed will be reflected in the current environment. If the + Environment is non-NULL, then the changes made will be discarded. + The CommandLine is executed from the current working directory on the current + device. + + The EnvironmentVariables and Status parameters are ignored in a pre-UEFI Shell 2.0 + environment. The values pointed to by the parameters will be unchanged by the + ShellExecute() function. The Output parameter has no effect in a + UEFI Shell 2.0 environment. + + @param[in] ParentHandle The parent image starting the operation. + @param[in] CommandLine The pointer to a NULL terminated command line. + @param[in] Output True to display debug output. False to hide it. + @param[in] EnvironmentVariables Optional pointer to array of environment variables + in the form "x=y". If NULL, the current set is used. + @param[out] Status The status of the run command line. + + @retval EFI_SUCCESS The operation completed sucessfully. Status + contains the status code returned. + @retval EFI_INVALID_PARAMETER A parameter contains an invalid value. + @retval EFI_OUT_OF_RESOURCES Out of resources. + @retval EFI_UNSUPPORTED The operation is not allowed. +**/ +EFI_STATUS +EFIAPI +ShellExecute ( + IN EFI_HANDLE *ParentHandle, + IN CHAR16 *CommandLine, + IN BOOLEAN Output, + IN CHAR16 **EnvironmentVariables, + OUT EFI_STATUS *Status + ); + +/** + Retreives the current directory path. + + If the DeviceName is NULL, it returns the current device's current directory + name. If the DeviceName is not NULL, it returns the current directory name + on specified drive. + + Note that the current directory string should exclude the tailing backslash character. + + @param[in] DeviceName The name of the file system to get directory on. + + @retval NULL The directory does not exist. + @retval != NULL The directory. +**/ +CONST CHAR16* +EFIAPI +ShellGetCurrentDir ( + IN CHAR16 * CONST DeviceName OPTIONAL + ); + +/** + Sets (enabled or disabled) the page break mode. + + When page break mode is enabled the screen will stop scrolling + and wait for operator input before scrolling a subsequent screen. + + @param[in] CurrentState TRUE to enable and FALSE to disable. +**/ +VOID +EFIAPI +ShellSetPageBreakMode ( + IN BOOLEAN CurrentState + ); + +/** + Opens a group of files based on a path. + + This function uses the Arg to open all the matching files. Each matched + file has a SHELL_FILE_ARG structure to record the file information. These + structures are placed on the list ListHead. Users can get the SHELL_FILE_ARG + structures from ListHead to access each file. This function supports wildcards + and will process '?' and '*' as such. The list must be freed with a call to + ShellCloseFileMetaArg(). + + If you are NOT appending to an existing list *ListHead must be NULL. If + *ListHead is NULL then it must be callee freed. + + @param[in] Arg The pointer to path string. + @param[in] OpenMode Mode to open files with. + @param[in, out] ListHead Head of linked list of results. + + @retval EFI_SUCCESS The operation was sucessful and the list head + contains the list of opened files. + @retval != EFI_SUCCESS The operation failed. + + @sa InternalShellConvertFileListType +**/ +EFI_STATUS +EFIAPI +ShellOpenFileMetaArg ( + IN CHAR16 *Arg, + IN UINT64 OpenMode, + IN OUT EFI_SHELL_FILE_INFO **ListHead + ); + +/** + Free the linked list returned from ShellOpenFileMetaArg. + + @param[in, out] ListHead The pointer to free. + + @retval EFI_SUCCESS The operation was sucessful. + @retval EFI_INVALID_PARAMETER A parameter was invalid. +**/ +EFI_STATUS +EFIAPI +ShellCloseFileMetaArg ( + IN OUT EFI_SHELL_FILE_INFO **ListHead + ); + +/** + Find a file by searching the CWD and then the path. + + If FileName is NULL, then ASSERT. + + If the return value is not NULL then the memory must be caller freed. + + @param[in] FileName Filename string. + + @retval NULL The file was not found. + @retval !NULL The path to the file. +**/ +CHAR16 * +EFIAPI +ShellFindFilePath ( + IN CONST CHAR16 *FileName + ); + +/** + Find a file by searching the CWD and then the path with a variable set of file + extensions. If the file is not found it will append each extension in the list + in the order provided and return the first one that is successful. + + If FileName is NULL, then ASSERT. + If FileExtension is NULL, then the behavior is identical to ShellFindFilePath. + + If the return value is not NULL then the memory must be caller freed. + + @param[in] FileName The filename string. + @param[in] FileExtension Semicolon delimited list of possible extensions. + + @retval NULL The file was not found. + @retval !NULL The path to the file. +**/ +CHAR16 * +EFIAPI +ShellFindFilePathEx ( + IN CONST CHAR16 *FileName, + IN CONST CHAR16 *FileExtension + ); + +typedef enum { + TypeFlag = 0, ///< A flag that is present or not present only (IE "-a"). + TypeValue, ///< A flag that has some data following it with a space (IE "-a 1"). + TypePosition, ///< Some data that did not follow a parameter (IE "filename.txt"). + TypeStart, ///< A flag that has variable value appended to the end (IE "-ad", "-afd", "-adf", etc...). + TypeDoubleValue, ///< A flag that has 2 space seperated value data following it (IE "-a 1 2"). + TypeMaxValue, ///< A flag followed by all the command line data before the next flag. + TypeTimeValue, ///< A flag that has a time value following it (IE "-a -5:00"). + TypeMax, +} SHELL_PARAM_TYPE; + +typedef struct { + CHAR16 *Name; + SHELL_PARAM_TYPE Type; +} SHELL_PARAM_ITEM; + + +/// Helper structure for no parameters (besides -? and -b) +extern SHELL_PARAM_ITEM EmptyParamList[]; + +/// Helper structure for -sfo only (besides -? and -b) +extern SHELL_PARAM_ITEM SfoParamList[]; + +/** + Checks the command line arguments passed against the list of valid ones. + Optionally removes NULL values first. + + If no initialization is required, then return RETURN_SUCCESS. + + @param[in] CheckList The pointer to list of parameters to check. + @param[out] CheckPackage The package of checked values. + @param[out] ProblemParam Optional pointer to pointer to unicode string for + the paramater that caused failure. + @param[in] AutoPageBreak Will automatically set PageBreakEnabled. + @param[in] AlwaysAllowNumbers Will never fail for number based flags. + + @retval EFI_SUCCESS The operation completed sucessfully. + @retval EFI_OUT_OF_RESOURCES A memory allocation failed. + @retval EFI_INVALID_PARAMETER A parameter was invalid. + @retval EFI_VOLUME_CORRUPTED The command line was corrupt. + @retval EFI_DEVICE_ERROR The commands contained 2 opposing arguments. One + of the command line arguments was returned in + ProblemParam if provided. + @retval EFI_NOT_FOUND A argument required a value that was missing. + The invalid command line argument was returned in + ProblemParam if provided. +**/ +EFI_STATUS +EFIAPI +ShellCommandLineParseEx ( + IN CONST SHELL_PARAM_ITEM *CheckList, + OUT LIST_ENTRY **CheckPackage, + OUT CHAR16 **ProblemParam OPTIONAL, + IN BOOLEAN AutoPageBreak, + IN BOOLEAN AlwaysAllowNumbers + ); + +/// Make it easy to upgrade from older versions of the shell library. +#define ShellCommandLineParse(CheckList,CheckPackage,ProblemParam,AutoPageBreak) ShellCommandLineParseEx(CheckList,CheckPackage,ProblemParam,AutoPageBreak,FALSE) + +/** + Frees shell variable list that was returned from ShellCommandLineParse. + + This function will free all the memory that was used for the CheckPackage + list of postprocessed shell arguments. + + If CheckPackage is NULL, then return. + + @param[in] CheckPackage The list to de-allocate. + **/ +VOID +EFIAPI +ShellCommandLineFreeVarList ( + IN LIST_ENTRY *CheckPackage + ); + +/** + Checks for presence of a flag parameter. + + Flag arguments are in the form of "-<Key>" or "/<Key>", but do not have a value following the key. + + If CheckPackage is NULL then return FALSE. + If KeyString is NULL then ASSERT(). + + @param[in] CheckPackage The package of parsed command line arguments. + @param[in] KeyString The Key of the command line argument to check for. + + @retval TRUE The flag is on the command line. + @retval FALSE The flag is not on the command line. +**/ +BOOLEAN +EFIAPI +ShellCommandLineGetFlag ( + IN CONST LIST_ENTRY * CONST CheckPackage, + IN CONST CHAR16 * CONST KeyString + ); + +/** + Returns value from command line argument. + + Value parameters are in the form of "-<Key> value" or "/<Key> value". + + If CheckPackage is NULL, then return NULL. + + @param[in] CheckPackage The package of parsed command line arguments. + @param[in] KeyString The Key of the command line argument to check for. + + @retval NULL The flag is not on the command line. + @retval !=NULL The pointer to unicode string of the value. +**/ +CONST CHAR16* +EFIAPI +ShellCommandLineGetValue ( + IN CONST LIST_ENTRY *CheckPackage, + IN CHAR16 *KeyString + ); + +/** + Returns raw value from command line argument. + + Raw value parameters are in the form of "value" in a specific position in the list. + + If CheckPackage is NULL, then return NULL. + + @param[in] CheckPackage The package of parsed command line arguments. + @param[in] Position The position of the value. + + @retval NULL The flag is not on the command line. + @retval !=NULL The pointer to unicode string of the value. +**/ +CONST CHAR16* +EFIAPI +ShellCommandLineGetRawValue ( + IN CONST LIST_ENTRY * CONST CheckPackage, + IN UINTN Position + ); + +/** + Returns the number of command line value parameters that were parsed. + + This will not include flags. + + @param[in] CheckPackage The package of parsed command line arguments. + + @retval (UINTN)-1 No parsing has occurred. + @retval other The number of value parameters found. +**/ +UINTN +EFIAPI +ShellCommandLineGetCount( + IN CONST LIST_ENTRY *CheckPackage + ); + +/** + Determines if a parameter is duplicated. + + If Param is not NULL, then it will point to a callee-allocated string buffer + with the parameter value, if a duplicate is found. + + If CheckPackage is NULL, then ASSERT. + + @param[in] CheckPackage The package of parsed command line arguments. + @param[out] Param Upon finding one, a pointer to the duplicated parameter. + + @retval EFI_SUCCESS No parameters were duplicated. + @retval EFI_DEVICE_ERROR A duplicate was found. + **/ +EFI_STATUS +EFIAPI +ShellCommandLineCheckDuplicate ( + IN CONST LIST_ENTRY *CheckPackage, + OUT CHAR16 **Param + ); + +/** + This function causes the shell library to initialize itself. If the shell library + is already initialized it will de-initialize all the current protocol pointers and + re-populate them again. + + When the library is used with PcdShellLibAutoInitialize set to true this function + will return EFI_SUCCESS and perform no actions. + + This function is intended for internal access for shell commands only. + + @retval EFI_SUCCESS The initialization was complete sucessfully. + +**/ +EFI_STATUS +EFIAPI +ShellInitialize ( + VOID + ); + +/** + Print at a specific location on the screen. + + This function will move the cursor to a given screen location and print the specified string. + + If -1 is specified for either the Row or Col the current screen location for BOTH + will be used. + + If either Row or Col is out of range for the current console, then ASSERT. + If Format is NULL, then ASSERT. + + In addition to the standard %-based flags as supported by UefiLib Print() this supports + the following additional flags: + %N - Set output attribute to normal + %H - Set output attribute to highlight + %E - Set output attribute to error + %B - Set output attribute to blue color + %V - Set output attribute to green color + + Note: The background color is controlled by the shell command cls. + + @param[in] Col The column to print at. + @param[in] Row The row to print at. + @param[in] Format The format string. + @param[in] ... The variable argument list. + + @return EFI_SUCCESS The printing was successful. + @return EFI_DEVICE_ERROR The console device reported an error. +**/ +EFI_STATUS +EFIAPI +ShellPrintEx( + IN INT32 Col OPTIONAL, + IN INT32 Row OPTIONAL, + IN CONST CHAR16 *Format, + ... + ); + +/** + Print at a specific location on the screen. + + This function will move the cursor to a given screen location and print the specified string. + + If -1 is specified for either the Row or Col the current screen location for BOTH + will be used. + + If either Row or Col is out of range for the current console, then ASSERT. + If Format is NULL, then ASSERT. + + In addition to the standard %-based flags as supported by UefiLib Print() this supports + the following additional flags: + %N - Set output attribute to normal. + %H - Set output attribute to highlight. + %E - Set output attribute to error. + %B - Set output attribute to blue color. + %V - Set output attribute to green color. + + Note: The background color is controlled by the shell command cls. + + @param[in] Col The column to print at. + @param[in] Row The row to print at. + @param[in] Language The language of the string to retrieve. If this parameter + is NULL, then the current platform language is used. + @param[in] HiiFormatStringId The format string Id for getting from Hii. + @param[in] HiiFormatHandle The format string Handle for getting from Hii. + @param[in] ... The variable argument list. + + @return EFI_SUCCESS The printing was successful. + @return EFI_DEVICE_ERROR The console device reported an error. +**/ +EFI_STATUS +EFIAPI +ShellPrintHiiEx( + IN INT32 Col OPTIONAL, + IN INT32 Row OPTIONAL, + IN CONST CHAR8 *Language OPTIONAL, + IN CONST EFI_STRING_ID HiiFormatStringId, + IN CONST EFI_HII_HANDLE HiiFormatHandle, + ... + ); + +/** + Function to determine if a given filename represents a directory. + + If DirName is NULL, then ASSERT. + + @param[in] DirName Path to directory to test. + + @retval EFI_SUCCESS The Path represents a directory. + @retval EFI_NOT_FOUND The Path does not represent a directory. + @retval other The path failed to open. +**/ +EFI_STATUS +EFIAPI +ShellIsDirectory( + IN CONST CHAR16 *DirName + ); + +/** + Function to determine if a given filename represents a file. + + This will search the CWD only. + + If Name is NULL, then ASSERT. + + @param[in] Name Path to file to test. + + @retval EFI_SUCCESS The Path represents a file. + @retval EFI_NOT_FOUND The Path does not represent a file. + @retval other The path failed to open. +**/ +EFI_STATUS +EFIAPI +ShellIsFile( + IN CONST CHAR16 *Name + ); + +/** + Function to determine if a given filename represents a file. + + This will search the CWD and then the Path. + + If Name is NULL, then ASSERT. + + @param[in] Name Path to file to test. + + @retval EFI_SUCCESS The Path represents a file. + @retval EFI_NOT_FOUND The Path does not represent a file. + @retval other The path failed to open. +**/ +EFI_STATUS +EFIAPI +ShellIsFileInPath( + IN CONST CHAR16 *Name + ); + +/** + Function to determine whether a string is decimal or hex representation of a number + and return the number converted from the string. + + Note: this function cannot be used when (UINTN)(-1), (0xFFFFFFFF) may be a valid + result. Use ShellConvertStringToUint64 instead. + + @param[in] String String representation of a number. + + @return The unsigned integer result of the conversion. + @retval (UINTN)(-1) An error occurred. +**/ +UINTN +EFIAPI +ShellStrToUintn( + IN CONST CHAR16 *String + ); + +/** + Function return the number converted from a hex representation of a number. + + Note: this function cannot be used when (UINTN)(-1), (0xFFFFFFFF) may be a valid + result. Use ShellConvertStringToUint64 instead. + + @param[in] String String representation of a number. + + @return The unsigned integer result of the conversion. + @retval (UINTN)(-1) An error occurred. +**/ +UINTN +EFIAPI +ShellHexStrToUintn( + IN CONST CHAR16 *String + ); + +/** + Safely append with automatic string resizing given length of Destination and + desired length of copy from Source. + + Append the first D characters of Source to the end of Destination, where D is + the lesser of Count and the StrLen() of Source. If appending those D characters + will fit within Destination (whose Size is given as CurrentSize) and + still leave room for a NULL terminator, then those characters are appended, + starting at the original terminating NULL of Destination, and a new terminating + NULL is appended. + + If appending D characters onto Destination will result in a overflow of the size + given in CurrentSize the string will be grown such that the copy can be performed + and CurrentSize will be updated to the new size. + + If Source is NULL, there is nothing to append, so return the current buffer in + Destination. + + If Destination is NULL, then ASSERT(). + If Destination's current length (including NULL terminator) is already more than + CurrentSize, then ASSERT(). + + @param[in, out] Destination The String to append onto. + @param[in, out] CurrentSize On call, the number of bytes in Destination. On + return, possibly the new size (still in bytes). If NULL, + then allocate whatever is needed. + @param[in] Source The String to append from. + @param[in] Count The maximum number of characters to append. If 0, then + all are appended. + + @return The Destination after appending the Source. +**/ +CHAR16* +EFIAPI +StrnCatGrow ( + IN OUT CHAR16 **Destination, + IN OUT UINTN *CurrentSize, + IN CONST CHAR16 *Source, + IN UINTN Count + ); + +/** + This is a find and replace function. Upon successful return the NewString is a copy of + SourceString with each instance of FindTarget replaced with ReplaceWith. + + If SourceString and NewString overlap the behavior is undefined. + + If the string would grow bigger than NewSize it will halt and return error. + + @param[in] SourceString The string with source buffer. + @param[in, out] NewString The string with resultant buffer. + @param[in] NewSize The size in bytes of NewString. + @param[in] FindTarget The string to look for. + @param[in] ReplaceWith The string to replace FindTarget with. + @param[in] SkipPreCarrot If TRUE will skip a FindTarget that has a '^' + immediately before it. + @param[in] ParameterReplacing If TRUE will add "" around items with spaces. + + @retval EFI_INVALID_PARAMETER SourceString was NULL. + @retval EFI_INVALID_PARAMETER NewString was NULL. + @retval EFI_INVALID_PARAMETER FindTarget was NULL. + @retval EFI_INVALID_PARAMETER ReplaceWith was NULL. + @retval EFI_INVALID_PARAMETER FindTarget had length < 1. + @retval EFI_INVALID_PARAMETER SourceString had length < 1. + @retval EFI_BUFFER_TOO_SMALL NewSize was less than the minimum size to hold + the new string (truncation occurred). + @retval EFI_SUCCESS The string was successfully copied with replacement. +**/ +EFI_STATUS +EFIAPI +ShellCopySearchAndReplace( + IN CHAR16 CONST *SourceString, + IN OUT CHAR16 *NewString, + IN UINTN NewSize, + IN CONST CHAR16 *FindTarget, + IN CONST CHAR16 *ReplaceWith, + IN CONST BOOLEAN SkipPreCarrot, + IN CONST BOOLEAN ParameterReplacing + ); + +/** + Check if a Unicode character is a hexadecimal character. + + This internal function checks if a Unicode character is a + numeric character. The valid hexadecimal characters are + L'0' to L'9', L'a' to L'f', or L'A' to L'F'. + + + @param Char The character to check against. + + @retval TRUE The Char is a hexadecmial character. + @retval FALSE The Char is not a hexadecmial character. + +**/ +BOOLEAN +EFIAPI +ShellIsHexaDecimalDigitCharacter ( + IN CHAR16 Char + ); + +/** + Check if a Unicode character is a decimal character. + + This internal function checks if a Unicode character is a + decimal character. The valid characters are + L'0' to L'9'. + + + @param Char The character to check against. + + @retval TRUE The Char is a hexadecmial character. + @retval FALSE The Char is not a hexadecmial character. + +**/ +BOOLEAN +EFIAPI +ShellIsDecimalDigitCharacter ( + IN CHAR16 Char + ); + +/// +/// What type of answer is requested. +/// +typedef enum { + ShellPromptResponseTypeYesNo, + ShellPromptResponseTypeYesNoCancel, + ShellPromptResponseTypeFreeform, + ShellPromptResponseTypeQuitContinue, + ShellPromptResponseTypeYesNoAllCancel, + ShellPromptResponseTypeEnterContinue, + ShellPromptResponseTypeAnyKeyContinue, + ShellPromptResponseTypeMax +} SHELL_PROMPT_REQUEST_TYPE; + +/// +/// What answer was given. +/// +typedef enum { + ShellPromptResponseYes, + ShellPromptResponseNo, + ShellPromptResponseCancel, + ShellPromptResponseQuit, + ShellPromptResponseContinue, + ShellPromptResponseAll, + ShellPromptResponseMax +} SHELL_PROMPT_RESPONSE; + +/** + Prompt the user and return the resultant answer to the requestor. + + This function will display the requested question on the shell prompt and then + wait for an appropriate answer to be input from the console. + + If the SHELL_PROMPT_REQUEST_TYPE is SHELL_PROMPT_REQUEST_TYPE_YESNO, ShellPromptResponseTypeQuitContinue + or SHELL_PROMPT_REQUEST_TYPE_YESNOCANCEL then *Response is of type SHELL_PROMPT_RESPONSE. + + If the SHELL_PROMPT_REQUEST_TYPE is ShellPromptResponseTypeFreeform then *Response is of type + CHAR16*. + + In either case *Response must be callee freed if Response was not NULL; + + @param Type What type of question is asked. This is used to filter the input + to prevent invalid answers to question. + @param Prompt The pointer to a string prompt used to request input. + @param Response The pointer to Response, which will be populated upon return. + + @retval EFI_SUCCESS The operation was successful. + @retval EFI_UNSUPPORTED The operation is not supported as requested. + @retval EFI_INVALID_PARAMETER A parameter was invalid. + @return other The operation failed. +**/ +EFI_STATUS +EFIAPI +ShellPromptForResponse ( + IN SHELL_PROMPT_REQUEST_TYPE Type, + IN CHAR16 *Prompt OPTIONAL, + IN OUT VOID **Response OPTIONAL + ); + +/** + Prompt the user and return the resultant answer to the requestor. + + This function is the same as ShellPromptForResponse, except that the prompt is + automatically pulled from HII. + + @param[in] Type What type of question is asked. This is used to filter the input + to prevent invalid answers to question. + @param[in] HiiFormatStringId The format string Id for getting from Hii. + @param[in] HiiFormatHandle The format string Handle for getting from Hii. + @param[in, out] Response The pointer to Response, which will be populated upon return. + + @retval EFI_SUCCESS The operation was sucessful. + @return other The operation failed. + + @sa ShellPromptForResponse +**/ +EFI_STATUS +EFIAPI +ShellPromptForResponseHii ( + IN SHELL_PROMPT_REQUEST_TYPE Type, + IN CONST EFI_STRING_ID HiiFormatStringId, + IN CONST EFI_HII_HANDLE HiiFormatHandle, + IN OUT VOID **Response + ); + +/** + Function to determin if an entire string is a valid number. + + If Hex it must be preceeded with a 0x, 0X, or has ForceHex set TRUE. + + @param[in] String The string to evaluate. + @param[in] ForceHex TRUE - always assume hex. + @param[in] StopAtSpace TRUE to halt upon finding a space, FALSE to keep going. + + @retval TRUE It is all numeric (dec/hex) characters. + @retval FALSE There is a non-numeric character. +**/ +BOOLEAN +EFIAPI +ShellIsHexOrDecimalNumber ( + IN CONST CHAR16 *String, + IN CONST BOOLEAN ForceHex, + IN CONST BOOLEAN StopAtSpace + ); + +/** + Function to verify and convert a string to its numerical 64 bit representation. + + If Hex it must be preceeded with a 0x, 0X, or has ForceHex set TRUE. + + @param[in] String The string to evaluate. + @param[out] Value Upon a successful return the value of the conversion. + @param[in] ForceHex TRUE - always assume hex. + @param[in] StopAtSpace TRUE to halt upon finding a space, FALSE to + process the entire String. + + @retval EFI_SUCCESS The conversion was successful. + @retval EFI_INVALID_PARAMETER String contained an invalid character. + @retval EFI_NOT_FOUND String was a number, but Value was NULL. +**/ +EFI_STATUS +EFIAPI +ShellConvertStringToUint64( + IN CONST CHAR16 *String, + OUT UINT64 *Value, + IN CONST BOOLEAN ForceHex, + IN CONST BOOLEAN StopAtSpace + ); + +/** + Function to determine if a given filename exists. + + @param[in] Name Path to test. + + @retval EFI_SUCCESS The Path represents a file. + @retval EFI_NOT_FOUND The Path does not represent a file. + @retval other The path failed to open. +**/ +EFI_STATUS +EFIAPI +ShellFileExists( + IN CONST CHAR16 *Name + ); + +/** + Function to read a single line from a SHELL_FILE_HANDLE. The \n is not included in the returned + buffer. The returned buffer must be callee freed. + + If the position upon start is 0, then the Ascii Boolean will be set. This should be + maintained and not changed for all operations with the same file. + + @param[in] Handle SHELL_FILE_HANDLE to read from. + @param[in, out] Ascii Boolean value for indicating whether the file is + Ascii (TRUE) or UCS2 (FALSE). + + @return The line of text from the file. + + @sa ShellFileHandleReadLine +**/ +CHAR16* +EFIAPI +ShellFileHandleReturnLine( + IN SHELL_FILE_HANDLE Handle, + IN OUT BOOLEAN *Ascii + ); + +/** + Function to read a single line (up to but not including the \n) from a SHELL_FILE_HANDLE. + + If the position upon start is 0, then the Ascii Boolean will be set. This should be + maintained and not changed for all operations with the same file. + + @param[in] Handle SHELL_FILE_HANDLE to read from. + @param[in, out] Buffer The pointer to buffer to read into. + @param[in, out] Size The pointer to number of bytes in Buffer. + @param[in] Truncate If the buffer is large enough, this has no effect. + If the buffer is is too small and Truncate is TRUE, + the line will be truncated. + If the buffer is is too small and Truncate is FALSE, + then no read will occur. + + @param[in, out] Ascii Boolean value for indicating whether the file is + Ascii (TRUE) or UCS2 (FALSE). + + @retval EFI_SUCCESS The operation was successful. The line is stored in + Buffer. + @retval EFI_END_OF_FILE There are no more lines in the file. + @retval EFI_INVALID_PARAMETER Handle was NULL. + @retval EFI_INVALID_PARAMETER Size was NULL. + @retval EFI_BUFFER_TOO_SMALL Size was not large enough to store the line. + Size was updated to the minimum space required. +**/ +EFI_STATUS +EFIAPI +ShellFileHandleReadLine( + IN SHELL_FILE_HANDLE Handle, + IN OUT CHAR16 *Buffer, + IN OUT UINTN *Size, + IN BOOLEAN Truncate, + IN OUT BOOLEAN *Ascii + ); + +/** + Function to delete a file by name + + @param[in] FileName Pointer to file name to delete. + + @retval EFI_SUCCESS the file was deleted sucessfully + @retval EFI_WARN_DELETE_FAILURE the handle was closed, but the file was not + deleted + @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. + @retval EFI_NOT_FOUND The specified file could not be found on the + device or the file system could not be found + on the device. + @retval EFI_NO_MEDIA The device has no medium. + @retval EFI_MEDIA_CHANGED The device has a different medium in it or the + medium is no longer supported. + @retval EFI_DEVICE_ERROR The device reported an error. + @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + @retval EFI_WRITE_PROTECTED The file or medium is write protected. + @retval EFI_ACCESS_DENIED The file was opened read only. + @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the + file. + @retval other The file failed to open +**/ +EFI_STATUS +EFIAPI +ShellDeleteFileByName( + IN CONST CHAR16 *FileName + ); + +/** + Function to print help file / man page content in the spec from the UEFI Shell protocol GetHelpText function. + + @param[in] CommandToGetHelpOn Pointer to a string containing the command name of help file to be printed. + @param[in] SectionToGetHelpOn Pointer to the section specifier(s). + @param[in] PrintCommandText If TRUE, prints the command followed by the help content, otherwise prints + the help content only. + @retval EFI_DEVICE_ERROR The help data format was incorrect. + @retval EFI_NOT_FOUND The help data could not be found. + @retval EFI_SUCCESS The operation was successful. +**/ +EFI_STATUS +EFIAPI +ShellPrintHelp ( + IN CONST CHAR16 *CommandToGetHelpOn, + IN CONST CHAR16 *SectionToGetHelpOn, + IN BOOLEAN PrintCommandText + ); + +#endif // __SHELL_LIB__ diff --git a/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Protocol/EfiShellEnvironment2.h b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Protocol/EfiShellEnvironment2.h new file mode 100644 index 00000000..c6a9a60f --- /dev/null +++ b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Protocol/EfiShellEnvironment2.h @@ -0,0 +1,969 @@ +/** @file + Defines for EFI shell environment 2 ported to EDK II build environment. (no spec) + + Copyright (c) 2005 - 2010, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + + +#ifndef _SHELL_ENVIRONMENT_2_PROTOCOL_H_ +#define _SHELL_ENVIRONMENT_2_PROTOCOL_H_ + +#define DEFAULT_INIT_ROW 1 +#define DEFAULT_AUTO_LF FALSE + +/** + This function is a prototype for a function that dumps information on a protocol + to a given location. The location is dependant on the implementation. This is + used when programatically adding shell commands. + + @param[in] Handle The handle the protocol is on. + @param[in] Interface The interface to the protocol. + +**/ +typedef +VOID +(EFIAPI *SHELLENV_DUMP_PROTOCOL_INFO) ( + IN EFI_HANDLE Handle, + IN VOID *Interface + ); + +/** + This function is a prototype for each command internal to the EFI shell + implementation. The specific command depends on the implementation. This is + used when programatically adding shell commands. + + @param[in] ImageHandle The handle to the binary shell. + @param[in] SystemTable The pointer to the system table. + + @retval EFI_SUCCESS The command completed. + @retval other An error occurred. Any error is possible + depending on the implementation of the shell + command. + +**/ +typedef +EFI_STATUS +(EFIAPI *SHELLENV_INTERNAL_COMMAND) ( + IN EFI_HANDLE ImageHandle, + IN EFI_SYSTEM_TABLE *SystemTable + ); + +/** + This function is a prototype for one that gets a help string for a given command. + This is used when programatically adding shell commands. Upon successful return + the memory allocated is up to the caller to free. + + @param[in, out] Str Pointer to pointer to string to display for help. + + @retval EFI_SUCCESS The help string is in the parameter Str. + +**/ +typedef +EFI_STATUS +(EFIAPI *SHELLCMD_GET_LINE_HELP) ( + IN OUT CHAR16 **Str + ); + +/** +Structure returned from functions that open multiple files. +**/ +typedef struct { + UINT32 Signature; ///< SHELL_FILE_ARG_SIGNATURE. + LIST_ENTRY Link; ///< Linked list helper. + EFI_STATUS Status; ///< File's status. + + EFI_FILE_HANDLE Parent; ///< What is the Parent file of this file. + UINT64 OpenMode; ///< How was the file opened. + CHAR16 *ParentName; ///< String representation of parent. + EFI_DEVICE_PATH_PROTOCOL *ParentDevicePath; ///< DevicePath for Parent. + + CHAR16 *FullName; ///< Path and file name for this file. + CHAR16 *FileName; ///< File name for this file. + + EFI_FILE_HANDLE Handle; ///< Handle to this file. + EFI_FILE_INFO *Info; ///< Pointer to file info for this file. +} SHELL_FILE_ARG; + +/// Signature for SHELL_FILE_ARG. +#define SHELL_FILE_ARG_SIGNATURE SIGNATURE_32 ('g', 'r', 'a', 'f') + +/** +GUID for the shell environment2 and shell environment. +**/ +#define SHELL_ENVIRONMENT_PROTOCOL_GUID \ + { \ + 0x47c7b221, 0xc42a, 0x11d2, {0x8e, 0x57, 0x0, 0xa0, 0xc9, 0x69, 0x72, 0x3b} \ + } + +/** +GUID for the shell environment2 extension (main GUID above). +**/ +#define EFI_SE_EXT_SIGNATURE_GUID \ + { \ + 0xd2c18636, 0x40e5, 0x4eb5, {0xa3, 0x1b, 0x36, 0x69, 0x5f, 0xd4, 0x2c, 0x87} \ + } + +#define EFI_SHELL_MAJOR_VER 0x00000001 ///< Major version of the EFI_SHELL_ENVIRONMENT2. +#define EFI_SHELL_MINOR_VER 0x00000000 ///< Minor version of the EFI_SHELL_ENVIRONMENT2. + +/** + Execute a command line. + + This function will run the CommandLine. This includes loading any required images, + parsing any requires scripts, and if DebugOutput is TRUE printing errors + encountered directly to the screen. + + @param[in] ParentImageHandle Handle of the image executing this operation. + @param[in] CommandLine The string command line to execute. + @param[in] DebugOutput TRUE indicates that errors should be printed directly. + FALSE suppresses error messages. + + @retval EFI_SUCCESS The command line executed and completed. + @retval EFI_ABORTED The operation aborted. + @retval EFI_INVALID_PARAMETER A parameter did not have a valid value. + @retval EFI_OUT_OF_RESOURCES A required memory allocation failed. + +@sa HandleProtocol +**/ +typedef +EFI_STATUS +(EFIAPI *SHELLENV_EXECUTE) ( + IN EFI_HANDLE *ParentImageHandle, + IN CHAR16 *CommandLine, + IN BOOLEAN DebugOutput + ); + +/** + This function returns a shell environment variable value. + + @param[in] Name The pointer to the string with the shell environment + variable name. + + @retval NULL The shell environment variable's value could not be found. + @retval !=NULL The value of the shell environment variable Name. + +**/ +typedef +CHAR16 * +(EFIAPI *SHELLENV_GET_ENV) ( + IN CHAR16 *Name + ); + +/** + This function returns a shell environment map value. + + @param[in] Name The pointer to the string with the shell environment + map name. + + @retval NULL The shell environment map's value could not be found. + @retval !=NULL The value of the shell environment map Name. + +**/ +typedef +CHAR16 * +(EFIAPI *SHELLENV_GET_MAP) ( + IN CHAR16 *Name + ); + +/** + This function will add an internal command to the shell interface. + + This will allocate all required memory, put the new command on the command + list in the correct location. + + @param[in] Handler The handler function to call when the command gets called. + @param[in] Cmd The command name. + @param[in] GetLineHelp The function to call of type "get help" for this command. + + @retval EFI_SUCCESS The command is now part of the command list. + @retval EFI_OUT_OF_RESOURCES A memory allocation failed. + @sa SHELLENV_INTERNAL_COMMAND + @sa SHELLCMD_GET_LINE_HELP +**/ +typedef +EFI_STATUS +(EFIAPI *SHELLENV_ADD_CMD) ( + IN SHELLENV_INTERNAL_COMMAND Handler, + IN CHAR16 *Cmd, + IN SHELLCMD_GET_LINE_HELP GetLineHelp + ); + +/** + Internal interface to add protocol handlers. + + This function is for internal shell use only. This is how protocol handlers are added. + This will get the current protocol info and add the new info or update existing info + and then resave the info. + + @param[in] Protocol The pointer to the protocol's GUID. + @param[in] DumpToken The function pointer to dump token function or + NULL. + @param[in] DumpInfo The function pointer to dump infomation function + or NULL. + @param[in] IdString The English name of the protocol. +**/ +typedef +VOID +(EFIAPI *SHELLENV_ADD_PROT) ( + IN EFI_GUID *Protocol, + IN SHELLENV_DUMP_PROTOCOL_INFO DumpToken OPTIONAL, + IN SHELLENV_DUMP_PROTOCOL_INFO DumpInfo OPTIONAL, + IN CHAR16 *IdString + ); + +/** + This function finds a protocol handle by a GUID. + + This function will check for already known protocols by GUID and if one is + found it will return the name of that protocol. If no name is found and + GenId is TRUE it will generate ths string. + + @param[in] Protocol The GUID of the protocol to look for. + @param[in] GenId Whether to generate a name string if it is not found. + + @return !NULL The Name of the protocol. + @retval NULL The Name was not found, and GenId was not TRUE. +**/ +typedef +CHAR16* +(EFIAPI *SHELLENV_GET_PROT) ( + IN EFI_GUID *Protocol, + IN BOOLEAN GenId + ); + +/** + This function returns a string array containing the current directory on + a given device. + + If DeviceName is specified, then return the current shell directory on that + device. If DeviceName is NULL, then return the current directory on the + current device. The caller us responsible to free the returned string when + no longer required. + + @param[in] DeviceName The name of the device to get the current + directory on, or NULL for current device. + + @return String array with the current directory on the current or specified device. + +**/ +typedef +CHAR16* +(EFIAPI *SHELLENV_CUR_DIR) ( + IN CHAR16 *DeviceName OPTIONAL + ); + +/** + This function will open a group of files that match the Arg path, including + support for wildcard characters ('?' and '*') in the Arg path. If there are + any wildcard characters in the path this function will find any and all files + that match the wildcards. It returns a double linked list based on the + LIST_ENTRY linked list structure. Use this in conjunction with the + SHELL_FILE_ARG_SIGNATURE to get the SHELL_FILE_ARG structures that are returned. + The memory allocated by the callee for this list is freed by making a call to + SHELLENV_FREE_FILE_LIST. + + @param[in] Arg The pointer Path to files to open. + @param[in, out] ListHead The pointer to the allocated and initialized list head + upon which to append all opened file structures. + + @retval EFI_SUCCESS One or more files was opened and a struct of each file's + information was appended to ListHead. + @retval EFI_OUT_OF_RESOURCES A memory allocation failed. + @retval EFI_NOT_FOUND No matching files could be found. + @sa SHELLENV_FREE_FILE_LIST +**/typedef +EFI_STATUS +(EFIAPI *SHELLENV_FILE_META_ARG) ( + IN CHAR16 *Arg, + IN OUT LIST_ENTRY *ListHead + ); + +/** + This frees all of the nodes under the ListHead, but not ListHead itself. + + @param[in, out] ListHead Pointer to list to free all nodes of. + + @retval EFI_SUCCESS This function always returns EFI_SUCCESS. +**/ +typedef +EFI_STATUS +(EFIAPI *SHELLENV_FREE_FILE_LIST) ( + IN OUT LIST_ENTRY *ListHead + ); + +/** + This function creates a new instance of the ShellInterface protocol for use on + the ImageHandle. + + This function is for internal shell usage. This will allocate and then populate + EFI_SHELL_INTERFACE protocol. It is the caller's responsibility to free the + memory. + + @param[in] ImageHandle The handle which will use the new ShellInterface + protocol. + + @return The newly allocated shell interface protocol. + +**/ +typedef +EFI_SHELL_INTERFACE* +(EFIAPI *SHELLENV_NEW_SHELL) ( + IN EFI_HANDLE ImageHandle + ); + +/** + This function determines whether a script file is currently being processed. + + A script file (.nsh file) can contain a series of commands and this is useful to + know for some shell commands whether they are being run manually or as part of a + script. + + @retval TRUE A script file is being processed. + @retval FALSE A script file is not being processed. +**/ +typedef +BOOLEAN +(EFIAPI *SHELLENV_BATCH_IS_ACTIVE) ( + VOID + ); + +/** + This is an internal shell function to free any and all allocated resources. + This should be called immediately prior to closing the shell. +**/ +typedef +VOID +(EFIAPI *SHELLENV_FREE_RESOURCES) ( + VOID + ); + +/** + This function enables the page break mode. + + This mode causes the output to pause after each complete screen to enable a + user to more easily read it. If AutoWrap is TRUE, then rows with too many + characters will be chopped and divided into 2 rows. If FALSE, then rows with + too many characters may not be fully visible to the user on the screen. + + @param[in] StartRow The row number to start this on. + @param[in] AutoWrap Whether to auto wrap rows that are too long. +**/ +typedef +VOID +(EFIAPI *SHELLENV_ENABLE_PAGE_BREAK) ( + IN INT32 StartRow, + IN BOOLEAN AutoWrap + ); + +/** + This function disables the page break mode. + + Disabling this causes the output to print out exactly as coded, with no breaks + for readability. +**/ +typedef +VOID +(EFIAPI *SHELLENV_DISABLE_PAGE_BREAK) ( + VOID + ); + +/** + Get the status of the page break output mode. + + @retval FALSE Page break output mode is not enabled. + @retval TRUE Page break output mode is enabled. +**/ +typedef +BOOLEAN +(EFIAPI *SHELLENV_GET_PAGE_BREAK) ( + VOID + ); + +/** + This function sets the keys to filter for for the console in. The valid + values to set are: + + #define EFI_OUTPUT_SCROLL 0x00000001 + #define EFI_OUTPUT_PAUSE 0x00000002 + #define EFI_EXECUTION_BREAK 0x00000004 + + @param[in] KeyFilter The new key filter to use. +**/ +typedef +VOID +(EFIAPI *SHELLENV_SET_KEY_FILTER) ( + IN UINT32 KeyFilter + ); + +/** + This function gets the keys to filter for for the console in. + + The valid values to get are: + #define EFI_OUTPUT_SCROLL 0x00000001 + #define EFI_OUTPUT_PAUSE 0x00000002 + #define EFI_EXECUTION_BREAK 0x00000004 + + @retval The current filter mask. +**/ +typedef +UINT32 +(EFIAPI *SHELLENV_GET_KEY_FILTER) ( + VOID + ); + +/** + This function determines if the shell application should break. + + This is used to inform a shell application that a break condition has been + initiated. Long loops should check this to prevent delays to the break. + + @retval TRUE A break has been signaled. The application + should exit with EFI_ABORTED as soon as possible. + @retval FALSE Continue as normal. +**/ +typedef +BOOLEAN +(EFIAPI *SHELLENV_GET_EXECUTION_BREAK) ( + VOID + ); + +/** + This is an internal shell function used to increment the shell nesting level. + +**/ +typedef +VOID +(EFIAPI *SHELLENV_INCREMENT_SHELL_NESTING_LEVEL) ( + VOID + ); + +/** + This is an internal shell function used to decrement the shell nesting level. +**/ +typedef +VOID +(EFIAPI *SHELLENV_DECREMENT_SHELL_NESTING_LEVEL) ( + VOID + ); + +/** + This function determines if the caller is running under the root shell. + + @retval TRUE The caller is running under the root shell. + @retval FALSE The caller is not running under the root shell. + +**/ +typedef +BOOLEAN +(EFIAPI *SHELLENV_IS_ROOT_SHELL) ( + VOID + ); + +/** + Close the console proxy to restore the original console. + + This is an internal shell function to handle shell cascading. It restores the + original set of console protocols. + + @param[in] ConInHandle The handle of ConIn. + @param[in, out] ConIn The pointer to the location to return the pointer to + the original console input. + @param[in] ConOutHandle The handle of ConOut + @param[in, out] ConOut The pointer to the location to return the pointer to + the original console output. +**/ +typedef +VOID +(EFIAPI *SHELLENV_CLOSE_CONSOLE_PROXY) ( + IN EFI_HANDLE ConInHandle, + IN OUT EFI_SIMPLE_TEXT_INPUT_PROTOCOL **ConIn, + IN EFI_HANDLE ConOutHandle, + IN OUT EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL **ConOut + ); + +// +// declarations of handle enumerator +// +/** + For ease of use the shell maps handle #'s to short numbers. + This is only done on request for various internal commands and the references + are immediately freed when the internal command completes. +**/ +typedef +VOID +(EFIAPI *INIT_HANDLE_ENUMERATOR) ( + VOID + ); + +/** + This is an internal shell function to enumerate the handle database. + + This function gets the next handle in the handle database. If no handles are + found, EFI_NOT_FOUND is returned. If the previous Handle was the last handle, + it is set to NULL before returning. + + This must be called after INIT_HANDLE_ENUMERATOR and before CLOSE_HANDLE_ENUMERATOR. + + @param[in, out] Handle The pointer to pointer to Handle. It is set + on a sucessful return. + + @retval EFI_SUCCESS The next handle in the handle database is *Handle. + @retval EFI_NOT_FOUND There is not another handle. +**/ +typedef +EFI_STATUS +(EFIAPI *NEXT_HANDLE) ( + IN OUT EFI_HANDLE **Handle + ); + +/** + This is an internal shell function to enumerate the handle database. + + This function skips the next SkipNum handles in the handle database. If there + are not enough handles left to skip that many EFI_ACCESS_DENIED is returned and + no skip is performed. + + This must be called after INIT_HANDLE_ENUMERATOR and before CLOSE_HANDLE_ENUMERATOR. + + @param[in] SkipNum How many handles to skip + + @retval EFI_SUCCESS The next handle in the handle database is *Handle + @retval EFI_ACCESS_DENIED There are not SkipNum handles left in the database +**/ +typedef +EFI_STATUS +(EFIAPI *SKIP_HANDLE) ( + IN UINTN SkipNum + ); + +/** + This is an internal shell function to enumerate the handle database. + + This function resets the the handle database so that NEXT_HANDLE and SKIP_HANDLE + will start from EnumIndex on the next call. + + This must be called after INIT_HANDLE_ENUMERATOR and before CLOSE_HANDLE_ENUMERATOR. + + @param[in] EnumIndex Where to start. + + @return The number of handles either read out or skipped before this reset. +**/ +typedef +UINTN +(EFIAPI *RESET_HANDLE_ENUMERATOR) ( + IN UINTN EnumIndex + ); + +/** + This is an internal shell function to enumerate the handle database. + + This must be called after INIT_HANDLE_ENUMERATOR. + + This function releases all memory and resources associated with the handle database. + After this no other handle enumerator functions except INIT_HANDLE_ENUMERATOR will + function properly. +**/ +typedef +VOID +(EFIAPI *CLOSE_HANDLE_ENUMERATOR) ( + VOID + ); + +/** + This is an internal shell function to enumerate the handle database. + + This function returns the number of handles in the handle database. + + This must be called after INIT_HANDLE_ENUMERATOR and before CLOSE_HANDLE_ENUMERATOR. + + @return The number of handles in the handle database. +**/ +typedef +UINTN +(EFIAPI *GET_NUM) ( + VOID + ); + +/** +Handle Enumerator structure. +**/ +typedef struct { + INIT_HANDLE_ENUMERATOR Init; ///< The pointer to INIT_HANDLE_ENUMERATOR function. + NEXT_HANDLE Next; ///< The pointer to NEXT_HANDLE function. + SKIP_HANDLE Skip; ///< The pointer to SKIP_HANDLE function. + RESET_HANDLE_ENUMERATOR Reset; ///< The pointer to RESET_HANDLE_ENUMERATOR function. + CLOSE_HANDLE_ENUMERATOR Close; ///< The pointer to CLOSE_HANDLE_ENUMERATOR function. + GET_NUM GetNum; ///< The pointer to GET_NUM function. +} HANDLE_ENUMERATOR; + +/** + Signature for the PROTOCOL_INFO structure. +**/ +#define PROTOCOL_INFO_SIGNATURE SIGNATURE_32 ('s', 'p', 'i', 'n') + +/** + PROTOCOL_INFO structure for protocol enumerator functions. +**/ +typedef struct { + UINTN Signature; ///< PROTOCOL_INFO_SIGNATURE. + LIST_ENTRY Link; ///< Standard linked list helper member. + // + // The parsing info for the protocol. + // + EFI_GUID ProtocolId; ///< The GUID for the protocol. + CHAR16 *IdString; ///< The name of the protocol. + SHELLENV_DUMP_PROTOCOL_INFO DumpToken; ///< The pointer to DumpToken function for the protocol. + SHELLENV_DUMP_PROTOCOL_INFO DumpInfo; ///< The pointer to DumpInfo function for the protocol. + // + // Patabase info on which handles are supporting this protocol. + // + UINTN NoHandles; ///< The number of handles producing this protocol. + EFI_HANDLE *Handles; ///< The array of handles. + +} PROTOCOL_INFO; + +// +// Declarations of protocol info enumerator. +// +/** + This is an internal shell function to initialize the protocol enumerator. + + This must be called before NEXT_PROTOCOL_INFO, SKIP_PROTOCOL_INFO, + RESET_PROTOCOL_INFO_ENUMERATOR, and CLOSE_PROTOCOL_INFO_ENUMERATOR are + called. +**/ +typedef +VOID +(EFIAPI *INIT_PROTOCOL_INFO_ENUMERATOR) ( + VOID + ); + +/** + This function is an internal shell function for enumeration of protocols. + + This function returns the next protocol on the list. If this is called + immediately after initialization, it will return the first protocol on the list. + If this is called immediately after reset, it will return the first protocol again. + + This cannot be called after CLOSE_PROTOCOL_INFO_ENUMERATOR, but it must be + called after INIT_PROTOCOL_INFO_ENUMERATOR. + + @param[in, out] ProtocolInfo The pointer to pointer to protocol information structure. + + @retval EFI_SUCCESS The next protocol's information was sucessfully returned. + @retval NULL There are no more protocols. +**/ +typedef +EFI_STATUS +(EFIAPI *NEXT_PROTOCOL_INFO) ( + IN OUT PROTOCOL_INFO **ProtocolInfo + ); + +/** + This function is an internal shell function for enumeration of protocols. + + This cannot be called after CLOSE_PROTOCOL_INFO_ENUMERATOR, but it must be + called after INIT_PROTOCOL_INFO_ENUMERATOR. + + This function does nothing and always returns EFI_SUCCESS. + + @retval EFI_SUCCESS Always returned (see above). +**/ +typedef +EFI_STATUS +(EFIAPI *SKIP_PROTOCOL_INFO) ( + IN UINTN SkipNum + ); + +/** + This function is an internal shell function for enumeration of protocols. + + This cannot be called after CLOSE_PROTOCOL_INFO_ENUMERATOR, but it must be + called after INIT_PROTOCOL_INFO_ENUMERATOR. + + This function resets the list of protocols such that the next one in the + list is the begining of the list. +**/ +typedef +VOID +(EFIAPI *RESET_PROTOCOL_INFO_ENUMERATOR) ( + VOID + ); + + +/** + This function is an internal shell function for enumeration of protocols. + + This must be called after INIT_PROTOCOL_INFO_ENUMERATOR. After this call + no protocol enumerator calls except INIT_PROTOCOL_INFO_ENUMERATOR may be made. + + This function frees any memory or resources associated with the protocol + enumerator. +**/ +typedef +VOID +(EFIAPI *CLOSE_PROTOCOL_INFO_ENUMERATOR) ( + VOID + ); + +/** + Protocol enumerator structure of function pointers. +**/ +typedef struct { + INIT_PROTOCOL_INFO_ENUMERATOR Init; ///< The pointer to INIT_PROTOCOL_INFO_ENUMERATOR function. + NEXT_PROTOCOL_INFO Next; ///< The pointer to NEXT_PROTOCOL_INFO function. + SKIP_PROTOCOL_INFO Skip; ///< The pointer to SKIP_PROTOCOL_INFO function. + RESET_PROTOCOL_INFO_ENUMERATOR Reset; ///< The pointer to RESET_PROTOCOL_INFO_ENUMERATOR function. + CLOSE_PROTOCOL_INFO_ENUMERATOR Close; ///< The pointer to CLOSE_PROTOCOL_INFO_ENUMERATOR function. +} PROTOCOL_INFO_ENUMERATOR; + +/** + This function is used to retrieve a user-friendly display name for a handle. + + If UseComponentName is TRUE then the component name protocol for this device + or it's parent device (if required) will be used to obtain the name of the + device. If UseDevicePath is TRUE it will get the human readable device path + and return that. If both are TRUE it will try to use component name first + and device path if that fails. + + It will use either ComponentName or ComponentName2 protocol, depending on + what is present. + + This function will furthur verify whether the handle in question produced either + EFI_DRIVER_CONFIGRATION_PROTOCOL or EFI_DRIVER_CONFIGURATION2_PROTOCOL and also + whether the handle in question produced either EFI_DRIVER_DIAGNOSTICS_PROTOCOL or + EFI_DRIVER_DIAGNOSTICS2_PROTOCOL. + + Upon successful return, the memory for *BestDeviceName is up to the caller to free. + + @param[in] DeviceHandle The device handle whose name is desired. + @param[in] UseComponentName Whether to use the ComponentName protocol at all. + @param[in] UseDevicePath Whether to use the DevicePath protocol at all. + @param[in] Language The pointer to the language string to use. + @param[in, out] BestDeviceName The pointer to pointer to string allocated with the name. + @param[out] ConfigurationStatus The pointer to status for opening a Configuration protocol. + @param[out] DiagnosticsStatus The pointer to status for opening a Diagnostics protocol. + @param[in] Display Whether to Print this out to default Print location. + @param[in] Indent How many characters to indent the printing. + + @retval EFI_SUCCESS This function always returns EFI_SUCCESS. +**/ +typedef +EFI_STATUS +(EFIAPI *GET_DEVICE_NAME) ( + IN EFI_HANDLE DeviceHandle, + IN BOOLEAN UseComponentName, + IN BOOLEAN UseDevicePath, + IN CHAR8 *Language, + IN OUT CHAR16 **BestDeviceName, + OUT EFI_STATUS *ConfigurationStatus, + OUT EFI_STATUS *DiagnosticsStatus, + IN BOOLEAN Display, + IN UINTN Indent + ); + +#define EFI_SHELL_COMPATIBLE_MODE_VER L"1.1.1" ///< The string for lowest version this shell supports. +#define EFI_SHELL_ENHANCED_MODE_VER L"1.1.2" ///< The string for highest version this shell supports. + +/** + This function gets the shell mode as stored in the shell environment + "efishellmode". It will not fail. + + @param[out] Mode Returns a string representing one of the + 2 supported modes of the shell. + + @retval EFI_SUCCESS This function always returns success. +**/ +typedef +EFI_STATUS +(EFIAPI *GET_SHELL_MODE) ( + OUT CHAR16 **Mode + ); + +/** + Convert a file system style name to a device path. + + This function will convert a shell path name to a Device Path Protocol path. + This function will allocate any required memory for this operation and it + is the responsibility of the caller to free that memory when no longer required. + + If anything prevents the complete conversion free any allocated memory and + return NULL. + + @param[in] Path The path to convert. + + @retval !NULL A pointer to the callee allocated Device Path. + @retval NULL The operation could not be completed. +**/ +typedef +EFI_DEVICE_PATH_PROTOCOL* +(EFIAPI *SHELLENV_NAME_TO_PATH) ( + IN CHAR16 *Path + ); + +/** + Converts a device path into a file system map name. + + If DevPath is NULL, then ASSERT. + + This function looks through the shell environment map for a map whose device + path matches the DevPath parameter. If one is found the Name is returned via + Name parameter. If sucessful the caller must free the memory allocated for + Name. + + This function will use the internal lock to prevent changes to the map during + the lookup operation. + + @param[in] DevPath The device path to search for a name for. + @param[in] ConsistMapping What state to verify map flag VAR_ID_CONSIST. + @param[out] Name On sucessful return the name of that device path. + + @retval EFI_SUCCESS The DevPath was found and the name returned + in Name. + @retval EFI_OUT_OF_RESOURCES A required memory allocation failed. + @retval EFI_UNSUPPORTED The DevPath was not found in the map. +**/ +typedef +EFI_STATUS +(EFIAPI *SHELLENV_GET_FS_NAME) ( + IN EFI_DEVICE_PATH_PROTOCOL * DevPath, + IN BOOLEAN ConsistMapping, + OUT CHAR16 **Name + ); + +/** + This function will open a group of files that match the Arg path, but will not + support the wildcard characters ('?' and '*') in the Arg path. If there are + any wildcard characters in the path this function will return + EFI_INVALID_PARAMETER. The return is a double linked list based on the + LIST_ENTRY linked list structure. Use this in conjunction with the + SHELL_FILE_ARG_SIGNATURE to get the SHELL_FILE_ARG structures that are returned. + The memory allocated by the callee for this list is freed by making a call to + SHELLENV_FREE_FILE_LIST. + + @param[in] Arg The pointer to the path of the files to be opened. + @param[in, out] ListHead The pointer to allocated and initialized list head + upon which to append all the opened file structures. + + @retval EFI_SUCCESS One or more files was opened and a struct of each file's + information was appended to ListHead. + @retval EFI_OUT_OF_RESOURCES A memory allocation failed. + @retval EFI_NOT_FOUND No matching files could be found. + @sa SHELLENV_FREE_FILE_LIST +**/ +typedef +EFI_STATUS +(EFIAPI *SHELLENV_FILE_META_ARG_NO_WILDCARD) ( + IN CHAR16 *Arg, + IN OUT LIST_ENTRY *ListHead + ); + +/** + This function removes duplicate file listings from lists. + + This is a function for use with SHELLENV_FILE_META_ARG_NO_WILDCARD and + SHELLENV_FILE_META_ARG. This function will verify that there are no duplicate + files in the list of returned files. Any file listed twice will have one of its + instances removed. + + @param[in] ListHead The pointer to linked list head that was returned from + SHELLENV_FILE_META_ARG_NO_WILDCARD or + SHELLENV_FILE_META_ARG. + + @retval EFI_SUCCESS This function always returns success. + +**/ +typedef +EFI_STATUS +(EFIAPI *SHELLENV_DEL_DUP_FILE) ( + IN LIST_ENTRY * ListHead + ); + +/** + Converts a File System map name to a device path. + + If DevPath is NULL, then ASSERT(). + + This function looks through the shell environment map for a map whose Name + matches the Name parameter. If one is found, the device path pointer is + updated to point to that file systems device path. The caller should not + free the memory from that device path. + + This function will use the internal lock to prevent changes to the map during + the lookup operation. + + @param[in] Name The pointer to the NULL terminated UNICODE string of the + file system name. + @param[out] DevPath The pointer to pointer to DevicePath. Only valid on + successful return. + + @retval EFI_SUCCESS The conversion was successful, and the device + path was returned. + @retval EFI_NOT_FOUND The file system could not be found in the map. +**/ +typedef +EFI_STATUS +(EFIAPI *SHELLENV_GET_FS_DEVICE_PATH) ( + IN CHAR16 *Name, + OUT EFI_DEVICE_PATH_PROTOCOL **DevPath + ); + +/// EFI_SHELL_ENVIRONMENT2 protocol structure. +typedef struct { + SHELLENV_EXECUTE Execute; + SHELLENV_GET_ENV GetEnv; + SHELLENV_GET_MAP GetMap; + SHELLENV_ADD_CMD AddCmd; + SHELLENV_ADD_PROT AddProt; + SHELLENV_GET_PROT GetProt; + SHELLENV_CUR_DIR CurDir; + SHELLENV_FILE_META_ARG FileMetaArg; + SHELLENV_FREE_FILE_LIST FreeFileList; + + // + // The following services are only used by the shell itself. + // + SHELLENV_NEW_SHELL NewShell; + SHELLENV_BATCH_IS_ACTIVE BatchIsActive; + + SHELLENV_FREE_RESOURCES FreeResources; + + // + // GUID to differentiate ShellEnvironment2 from ShellEnvironment. + // + EFI_GUID SESGuid; + // + // Major Version grows if shell environment interface has been changes. + // + UINT32 MajorVersion; + UINT32 MinorVersion; + SHELLENV_ENABLE_PAGE_BREAK EnablePageBreak; + SHELLENV_DISABLE_PAGE_BREAK DisablePageBreak; + SHELLENV_GET_PAGE_BREAK GetPageBreak; + + SHELLENV_SET_KEY_FILTER SetKeyFilter; + SHELLENV_GET_KEY_FILTER GetKeyFilter; + + SHELLENV_GET_EXECUTION_BREAK GetExecutionBreak; + SHELLENV_INCREMENT_SHELL_NESTING_LEVEL IncrementShellNestingLevel; + SHELLENV_DECREMENT_SHELL_NESTING_LEVEL DecrementShellNestingLevel; + SHELLENV_IS_ROOT_SHELL IsRootShell; + + SHELLENV_CLOSE_CONSOLE_PROXY CloseConsoleProxy; + HANDLE_ENUMERATOR HandleEnumerator; + PROTOCOL_INFO_ENUMERATOR ProtocolInfoEnumerator; + GET_DEVICE_NAME GetDeviceName; + GET_SHELL_MODE GetShellMode; + SHELLENV_NAME_TO_PATH NameToPath; + SHELLENV_GET_FS_NAME GetFsName; + SHELLENV_FILE_META_ARG_NO_WILDCARD FileMetaArgNoWildCard; + SHELLENV_DEL_DUP_FILE DelDupFileArg; + SHELLENV_GET_FS_DEVICE_PATH GetFsDevicePath; +} EFI_SHELL_ENVIRONMENT2; + +extern EFI_GUID gEfiShellEnvironment2Guid; +extern EFI_GUID gEfiShellEnvironment2ExtGuid; + +#endif // _SHELL_ENVIRONMENT_2_PROTOCOL_H_ diff --git a/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Protocol/EfiShellInterface.h b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Protocol/EfiShellInterface.h new file mode 100644 index 00000000..7a1f2fa1 --- /dev/null +++ b/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Protocol/EfiShellInterface.h @@ -0,0 +1,88 @@ +/** @file + EFI Shell Interface protocol from EDK shell (no spec). + + Shell Interface - additional information (over image_info) provided + to an application started by the shell. + + ConIo provides a file-style interface to the console. + + The shell interface's and data (including ConIo) are only valid during + the applications Entry Point. Once the application returns from it's + entry point the data is freed by the invoking shell. + + Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _SHELLINTERFACE_H_ +#define _SHELLINTERFACE_H_ + +#include <Protocol/SimpleFileSystem.h> + +#define SHELL_INTERFACE_PROTOCOL_GUID \ + { \ + 0x47c7b223, 0xc42a, 0x11d2, {0x8e, 0x57, 0x0, 0xa0, 0xc9, 0x69, 0x72, 0x3b} \ + } + +/// +/// Bit definitions for EFI_SHELL_ARG_INFO +/// +typedef enum { + ARG_NO_ATTRIB = 0x0, + ARG_IS_QUOTED = BIT0, + ARG_PARTIALLY_QUOTED = BIT1, + ARG_FIRST_HALF_QUOTED = BIT2, + ARG_FIRST_CHAR_IS_ESC = BIT3 +} EFI_SHELL_ARG_INFO_TYPES; + +/// +/// Attributes for an argument. +/// +typedef struct _EFI_SHELL_ARG_INFO { + UINT32 Attributes; +} EFI_SHELL_ARG_INFO; + +/// +/// This protocol provides access to additional information about a shell application. +/// +typedef struct { + /// + /// Handle back to original image handle & image information. + /// + EFI_HANDLE ImageHandle; + EFI_LOADED_IMAGE_PROTOCOL *Info; + + /// + /// Parsed arg list converted more C-like format. + /// + CHAR16 **Argv; + UINTN Argc; + + /// + /// Storage for file redirection args after parsing. + /// + CHAR16 **RedirArgv; + UINTN RedirArgc; + + /// + /// A file style handle for console io. + /// + EFI_FILE_PROTOCOL *StdIn; + EFI_FILE_PROTOCOL *StdOut; + EFI_FILE_PROTOCOL *StdErr; + + /// + /// List of attributes for each argument. + /// + EFI_SHELL_ARG_INFO *ArgInfo; + + /// + /// Whether we are echoing. + /// + BOOLEAN EchoOn; +} EFI_SHELL_INTERFACE; + +extern EFI_GUID gEfiShellInterfaceGuid; + +#endif |