1bd0bf153e
The "SPLIT_LIST.SplitStdOut" and "SPLIT_LIST.SplitStdIn" members currently
have type (SHELL_FILE_HANDLE *). This is wrong; SHELL_FILE_HANDLE is
already a pointer, there's no need to store a pointer to a pointer.
The error is obvious if we check where and how these members are used:
- In the RunSplitCommand() function, these members are used (populated)
extensively; this function has to be updated in sync.
ConvertEfiFileProtocolToShellHandle() already returns the temporary
memory file created with CreateFileInterfaceMem() as SHELL_FILE_HANDLE,
not as (SHELL_FILE_HANDLE *).
- In particular, the ConvertShellHandleToEfiFileProtocol() calls need to
be dropped as well in RunSplitCommand(), since
EFI_SHELL_PROTOCOL.SetFilePosition() and EFI_SHELL_PROTOCOL.CloseFile()
take SHELL_FILE_HANDLE parameters, not (EFI_FILE_PROTOCOL *).
Given that ConvertShellHandleToEfiFileProtocol() only performs a
type-cast (it does not adjust any pointer values), *and*
SHELL_FILE_HANDLE -- taken by EFI_SHELL_PROTOCOL member functions -- is
actually a typedef to (VOID *) -- see more on this later --, this
conversion error hasn't been caught by compilers.
- In the ProcessNewSplitCommandLine() function, RunSplitCommand() is
called either initially (passing in NULL / NULL; no update needed), or
recursively (passing in Split->SplitStdIn / Split->SplitStdOut; again no
update is necessary beyond the RunSplitCommand() modification above).
- In the UpdateStdInStdOutStdErr() and RestoreStdInStdOutStdErr()
functions, said structure members are compared and assigned to
"EFI_SHELL_PARAMETERS_PROTOCOL.StdIn" and
"EFI_SHELL_PARAMETERS_PROTOCOL.StdOut", both of which have type
SHELL_FILE_HANDLE, *not* (SHELL_FILE_HANDLE *).
The compiler hasn't caught this error because of the fatally flawed type
definition of SHELL_FILE_HANDLE, namely
typedef VOID *SHELL_FILE_HANDLE;
Pointer-to-void silently converts to and from most other pointer types;
among them, pointer-to-pointer-to-void. That is also why no update is
necessary for UpdateStdInStdOutStdErr() and RestoreStdInStdOutStdErr()
in this fix.
(
Generally speaking, using (VOID *) typedefs for opaque handles is a tragic
mistake in all of the UEFI-related specifications; this practice defeats
any type checking that compilers might help programmers with. The right
way to define an opaque handle is as follows:
//
// Introduce the incomplete structure type, and the derived pointer
// type, in both the specification and the public edk2 headers. Note
// that the derived pointer type itself is a complete type, and it can
// be used freely by client code.
//
typedef struct SHELL_FILE *SHELL_FILE_HANDLE;
//
// Complete the structure type in the edk2 internal C source files.
//
struct SHELL_FILE {
//
// list fields
//
};
This way the structure size and members remain hidden from client code,
but the C compiler can nonetheless catch any invalid conversions between
incompatible XXX_HANDLE types.
)
Cc: Jaben Carsey <jaben.carsey@intel.com>
Cc: Marvin Häuser <Marvin.Haeuser@outlook.com>
Cc: Qiu Shumin <shumin.qiu@intel.com>
Cc: Ruiyu Ni <ruiyu.ni@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Laszlo Ersek <lersek@redhat.com>
Reviewed-by: Jaben Carsey <jaben.carsey@intel.com>
============================================================================
OVERVIEW
============================================================================
The UEFI 2.0 shell provides a standard pre-boot command line processor.
It is similar to the EDK EFI Shell or a *nix command line parser.
============================================================================
HOW TO INCORPORATE THIS SHELL INTO NT32
============================================================================
The instructions below are included as a sample and template on how a
developer may integrate this code into an existing platform:
1. Add this shell build to the NT32 build:
Add the shell.inf to the [components] section as it is in the ShellPkg.dsc.
2. Update system PCDs to support this new module
Update the PCD as follows using the Shell's PCD:
gEfiIntelFrameworkModulePkgTokenSpaceGuid.PcdShellFile|{ 0x83, 0xA5, 0x04, 0x7C, 0x3E, 0x9E, 0x1C, 0x4F, 0xAD, 0x65, 0xE0, 0x52, 0x68, 0xD0, 0xB4, 0xD1 }
3. Remove the old shell from the NT32 Firmware list
Remove the FILE APPLICATION section for the old shell.
4. Add this shell to the NT32 firmware list
Add the Shell.INF to the end of the list of DXE modules.
5. Build NT32
============================================================================