aboutsummaryrefslogtreecommitdiffstats
path: root/Lessons
diff options
context:
space:
mode:
authorKonstantin Aladyshev <aladyshev22@gmail.com>2021-07-13 11:20:31 +0300
committerKonstantin Aladyshev <aladyshev22@gmail.com>2021-07-13 11:20:31 +0300
commit20a2298b393807c2eba0f6768b2fde5bf2036eb0 (patch)
tree4540ae72d4fea05b0cac945dc91194330c682d12 /Lessons
parent9bcc17aacdb406d44e5e3eb905a391d46f06c5b4 (diff)
downloadUEFI-Lessons-20a2298b393807c2eba0f6768b2fde5bf2036eb0.tar.gz
UEFI-Lessons-20a2298b393807c2eba0f6768b2fde5bf2036eb0.tar.bz2
UEFI-Lessons-20a2298b393807c2eba0f6768b2fde5bf2036eb0.zip
Reorder library lessons
Signed-off-by: Konstantin Aladyshev <aladyshev22@gmail.com>
Diffstat (limited to 'Lessons')
-rw-r--r--Lessons/Lesson_35/README.md416
-rw-r--r--Lessons/Lesson_35/UefiLessonsPkg/Include/Library/SimpleLibrary.h (renamed from Lessons/Lesson_37/UefiLessonsPkg/Include/Library/SimpleLibrary.h)0
-rw-r--r--Lessons/Lesson_35/UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.c (renamed from Lessons/Lesson_37/UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.c)0
-rw-r--r--Lessons/Lesson_35/UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf (renamed from Lessons/Lesson_37/UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf)0
-rw-r--r--Lessons/Lesson_35/UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.c (renamed from Lessons/Lesson_37/UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.c)0
-rw-r--r--Lessons/Lesson_35/UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.inf (renamed from Lessons/Lesson_37/UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.inf)0
-rw-r--r--Lessons/Lesson_35/UefiLessonsPkg/UefiLessonsPkg.dec (renamed from Lessons/Lesson_37/UefiLessonsPkg/UefiLessonsPkg.dec)0
-rw-r--r--Lessons/Lesson_35/UefiLessonsPkg/UefiLessonsPkg.dsc (renamed from Lessons/Lesson_37/UefiLessonsPkg/UefiLessonsPkg.dsc)5
-rw-r--r--Lessons/Lesson_36/README.md254
-rw-r--r--Lessons/Lesson_36/UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.c (renamed from Lessons/Lesson_37/UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.c)0
-rw-r--r--Lessons/Lesson_36/UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.inf (renamed from Lessons/Lesson_37/UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.inf)0
-rw-r--r--Lessons/Lesson_36/UefiLessonsPkg/Library/SimpleLibraryWithConstructorAndDestructor/SimpleLibraryWithConstructorAndDestructor.c (renamed from Lessons/Lesson_37/UefiLessonsPkg/Library/SimpleLibraryWithConstructorAndDestructor/SimpleLibraryWithConstructorAndDestructor.c)0
-rw-r--r--Lessons/Lesson_36/UefiLessonsPkg/Library/SimpleLibraryWithConstructorAndDestructor/SimpleLibraryWithConstructorAndDestructor.inf (renamed from Lessons/Lesson_37/UefiLessonsPkg/Library/SimpleLibraryWithConstructorAndDestructor/SimpleLibraryWithConstructorAndDestructor.inf)0
-rw-r--r--Lessons/Lesson_36/UefiLessonsPkg/UefiLessonsPkg.dsc5
-rw-r--r--Lessons/Lesson_37/README.md456
15 files changed, 568 insertions, 568 deletions
diff --git a/Lessons/Lesson_35/README.md b/Lessons/Lesson_35/README.md
index def1314..f6d64ad 100644
--- a/Lessons/Lesson_35/README.md
+++ b/Lessons/Lesson_35/README.md
@@ -1,383 +1,157 @@
-If you'll search through ShellPkg library (https://github.com/tianocore/edk2/tree/master/ShellPkg/Library) you can notice that there is a folder `UefiShellAcpiViewCommandLib` (https://github.com/tianocore/edk2/tree/master/ShellPkg/Library/UefiShellAcpiViewCommandLib).
-This folder provides a library for the support of in-shell `acpiview` command. If you check the INF file, you'll see
-https://github.com/tianocore/edk2/blob/master/ShellPkg/Library/UefiShellAcpiViewCommandLib/UefiShellAcpiViewCommandLib.inf:
-```
-# Provides Shell 'acpiview' command functions
-```
-But if you try to execute `acpiview` in our current OVMF build, you'll notice that this command is not recognized:
-```
-FS0:\> acpiview
-'acpiview' is not recognized as an internal or external command, operable program, or script file.
-```
-We have 3 ways to use this 'acpiview' command functionality:
-- compile `acpiview` as a separate app and run it as an ordinary UEFI shell application
-- compile shell with 'acpiview' command in itself and run it under OVMF
-- update OVMF image with a shell that actually includes 'acpiview' command in itself
-
-# Compile `acpiview` as a separate app
+In this lesson we will try to create the most simple library.
-I guess it is the most easy way.
-
-It is possible to perform such thing with a help of https://github.com/tianocore/edk2/tree/master/ShellPkg/Application/AcpiViewApp
-
-If you look at the source file, you'll see that it is pretty simple, the main function just makes a library call to `ShellCommandRunAcpiView` function:
+Usually libraries are present in these directories:
```
-EFI_STATUS
-EFIAPI
-AcpiViewAppMain (
- IN EFI_HANDLE ImageHandle,
- IN EFI_SYSTEM_TABLE *SystemTable
- )
-{
- return ShellCommandRunAcpiView (gImageHandle, SystemTable);
-}
+<Pkg Name>/Library/<Library Name>/ <---- inf and source files for the library (=library implementation)
+<Pkg Name>/Include/Library/ <---- library headers (=library interface)
```
-To build this application issue:
+Create folders for our `SimpleLibrary`:
```
-build --platform=ShellPkg/ShellPkg.dsc --module=ShellPkg/Application/AcpiViewApp/AcpiViewApp.inf --arch=X64 --buildtarget=RELEASE --tagname=GCC5
+$ mkdir -p UefiLessonsPkg/Library/SimpleLibrary/
+$ mkdir -p UefiLessonsPkg/Include/Library/
```
-Copy image to the QEMU shared folder:
+First let's implement the header file, the interface for our library. Our `SimpleLibrary` would contain the only function `Plus2` that would receive a `number` and return a `number+2`.
+Therefore the content in the header file (`UefiLessonsPkg/Include/Library/SimpleLibrary.h`) would look like this:
```
-cp Build/Shell/RELEASE_GCC5/X64/AcpiViewApp.efi ~/UEFI_disk/
+UINTN Plus2(UINTN number);
```
-You can see application help with a:
+No harder the library implementation file `UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.c`:
```
-FS0:\> AcpiViewApp.efi -?
-Display ACPI Table information.
-
-ACPIVIEWAPP.EFI [[-?] | [[[[-l] | [-s AcpiTable [-d]]] [-q] [-h]] [-r Spec]]]
-
-
- -l - Display list of installed ACPI Tables.
- -s - Display only the specified AcpiTable type and only support single
- invocation option.
- AcpiTable : The required ACPI Table type.
- -d - Generate a binary file dump of the specified AcpiTable.
- -q - Quiet. Suppress errors and warnings. Disables consistency checks.
- -h - Enable colour highlighting.
- -r - Validate that all required ACPI tables are installed
- Spec : Specification to validate against.
- For Arm, the possible values are:
- 0 - Server Base Boot Requirements v1.0
- 1 - Server Base Boot Requirements v1.1
- 2 - Server Base Boot Requirements v1.2
- -? - Show help.
-
+#include <Library/SimpleLibrary.h>
- This program is provided to allow examination of ACPI table values from the
- UEFI Shell. This can help with investigations, especially at that stage
- where the tables are not enabling an OS to boot.
- The program is not exhaustive, and only encapsulates detailed knowledge of a
- limited number of table types.
-
- Default behaviour is to display the content of all tables installed.
- 'Known' table types (listed in NOTES below) will be parsed and displayed
- with descriptions and field values. Where appropriate a degree of
- consistency checking is done and errors may be reported in the output.
- Other table types will be displayed as an array of Hexadecimal bytes.
-
- To facilitate debugging, the -s and -d options can be used to generate a
- binary file image of a table that can be copied elsewhere for investigation
- using tools such as those provided by acpica.org. This is especially
- relevant for AML type tables like DSDT and SSDT.
-
-NOTES:
- 1. The AcpiTable parameter can match any installed table type.
- Tables without specific handling will be displayed as a raw hex dump (or
- dumped to a file if -d is used).
- 2. -s option supports to display the specified AcpiTable type that is present
- in the system. For normal type AcpiTable, it would display the data of the
- AcpiTable and AcpiTable header. The following type may contain header type
- other than AcpiTable header. The actual header can refer to the ACPI spec
- 6.3
- Extra A. Particular types:
- APIC - Multiple APIC Description Table (MADT)
- BGRT - Boot Graphics Resource Table
- DBG2 - Debug Port Table 2
- DSDT - Differentiated System Description Table
- FACP - Fixed ACPI Description Table (FADT)
- GTDT - Generic Timer Description Table
- IORT - IO Remapping Table
- MCFG - Memory Mapped Config Space Base Address Description Table
- PPTT - Processor Properties Topology Table
- RSDP - Root System Description Pointer
- SLIT - System Locality Information Table
- SPCR - Serial Port Console Redirection Table
- SRAT - System Resource Affinity Table
- SSDT - Secondary SystemDescription Table
- XSDT - Extended System Description Table
-
-
-
-EXAMPLES:
- * To display a list of the installed table types:
- fs0:\> acpiviewapp.efi -l
+UINTN Plus2(UINTN number) {
+ return number+2;
+}
+```
- * To parse and display a specific table type:
- fs0:\> acpiviewapp.efi -s GTDT
+This is really a simple library, it stands to its name!
- * To save a binary dump of the contents of a table to a file
- in the current working directory:
- fs0:\> acpiviewapp.efi -s DSDT -d
+Now we need to create an INF file for the library `UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf`:
+```
+[Defines]
+ INF_VERSION = 1.25
+ BASE_NAME = SimpleLibrary
+ FILE_GUID = 826c8951-5bd2-4d72-a9d9-f7ab48684117
+ MODULE_TYPE = UEFI_APPLICATION
+ VERSION_STRING = 1.0
+ LIBRARY_CLASS = SimpleLibrary | UEFI_APPLICATION
- * To display contents of all ACPI tables:
- fs0:\> acpiviewapp.efi
+[Sources]
+ SimpleLibrary.c
- * To check if all Server Base Boot Requirements (SBBR) v1.2 mandatory
- ACPI tables are installed (Arm only):
- fs0:\> acpiviewapp.efi -r 2
+[Packages]
+ MdePkg/MdePkg.dec
```
-With this program you can list ACPI tables in system:
+The interesting string here is the:
```
-FS0:\> AcpiViewApp.efi -l
-
-Installed Table(s):
- 1. RSDP
- 2. XSDT
- 3. FACP
- 4. FACS
- 5. DSDT
- 6. APIC
- 7. HPET
- 8. BGRT
+LIBRARY_CLASS = SimpleLibrary | UEFI_APPLICATION
```
-
-Show the content of any table:
+It says that this library can only be used in modules with a type `UEFI_APPLICATION`. If you would say here `DXE_DRIVER` and try to link it to some of you UEFI applications, build process would fail. The error message would look like this:
+```
+build.py...
+/home/kostr/tiano/edk2/UefiLessonsPkg/UefiLessonsPkg.dsc(...): error 1001: Module type [UEFI_APPLICATION] is not supported by library instance [/home/kostr/tiano/edk2/UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf]
+ consumed by [/home/kostr/tiano/edk2/UefiLessonsPkg/<path to your app inf file>]
```
-FS0:\> AcpiViewApp.efi -s BGRT
-
-
- --------------- BGRT Table ---------------
-
-Address : 0x7B77000
-Length : 56
-
-00000000 : 42 47 52 54 38 00 00 00 - 01 C5 49 4E 54 45 4C 20 BGRT8.....INTEL
-00000010 : 45 44 4B 32 20 20 20 20 - 02 00 00 00 20 20 20 20 EDK2 ....
-00000020 : 13 00 00 01 01 00 01 00 - 18 30 8B 06 00 00 00 00 .........0......
-00000030 : 2F 01 00 00 0F 01 00 00 /.......
-
-Table Checksum : OK
-
-BGRT :
- Signature : BGRT
- Length : 56
- Revision : 1
- Checksum : 0xC5
- Oem ID : INTEL
- Oem Table ID : EDK2
- Oem Revision : 0x2
- Creator ID :
- Creator Revision : 0x1000013
- Version : 0x1
- Status : 0x1
- Image Type : 0x0
- Image Address : 0x68B3018
- Image Offset X : 303
- Image Offset Y : 271
-Table Statistics:
- 0 Error(s)
- 0 Warning(s)
+Now we need to include our library to our package DSC file `UefiLessonsPkg/UefiLessonsPkg.dsc`, so it would get build on a package build:
+```
+[Components]
+ ...
+ UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf
```
-Or dump any ACPI table:
+But if you try to build our package now build would fail with a message:
```
-FS0:\> acpiview -s APIC -d
-Dumping ACPI table to : .\APIC0000.bin ... DONE.
+/home/kostr/tiano/edk2/UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.c:1:10: fatal error: Library/SimpleLibrary.h: No such file or directory
+ 1 | #include <Library/SimpleLibrary.h>
+ | ^~~~~~~~~~~~~~~~~~~~~~~~~
+compilation terminated.
```
-You can disassemble this image with `iasl -d <file>` like we did earlier.
+The reason of that is a fact that our `UefiLessonsPkg/Include/Library/` folder is not recognized by a build system as a place where headers might be.
+To fix it we need to add to our `UefiLessonsPkg/UefiLessonsPkg.dec` file `[Includes]` section:
+```
+[Includes]
+ Include
+```
-# Compile shell with 'acpiview' command in itself and run it under OVMF
+And include this `UefiLessonsPkg/UefiLessonsPkg.dec` file to the library module INF file section `[Packages]`:
+```
+[Packages]
+ MdePkg/MdePkg.dec
+ UefiLessonsPkg/UefiLessonsPkg.dec
+```
-This case is a little bit crazy, we would be running a shell applicaion inside the shell application.
+Now we are good, build would succeed.
-I guess this is not the usual case, but it will help you to know how to compile the shell image that you can actually use in your projects.
+# SimpleLibraryUser
-If you'll look at the https://github.com/tianocore/edk2/blob/master/ShellPkg/ShellPkg.dsc you'll see that if you build `ShellPkg`, you'll actually build two versions of the `Shell.inf`:
-- one would have general commands
-- another one would have all the commands
-```
-ShellPkg/Application/Shell/Shell.inf {
- <PcdsFixedAtBuild>
- gEfiShellPkgTokenSpaceGuid.PcdShellLibAutoInitialize|FALSE
- <LibraryClasses>
- NULL|ShellPkg/Library/UefiShellLevel2CommandsLib/UefiShellLevel2CommandsLib.inf
- NULL|ShellPkg/Library/UefiShellLevel1CommandsLib/UefiShellLevel1CommandsLib.inf
- NULL|ShellPkg/Library/UefiShellLevel3CommandsLib/UefiShellLevel3CommandsLib.inf
-fndef $(NO_SHELL_PROFILES)
- NULL|ShellPkg/Library/UefiShellDriver1CommandsLib/UefiShellDriver1CommandsLib.inf
- NULL|ShellPkg/Library/UefiShellInstall1CommandsLib/UefiShellInstall1CommandsLib.inf
- NULL|ShellPkg/Library/UefiShellDebug1CommandsLib/UefiShellDebug1CommandsLib.inf
- NULL|ShellPkg/Library/UefiShellNetwork1CommandsLib/UefiShellNetwork1CommandsLib.inf
- NULL|ShellPkg/Library/UefiShellNetwork2CommandsLib/UefiShellNetwork2CommandsLib.inf
-ndif #$(NO_SHELL_PROFILES)
-}
+Now let's create an application that would use our library.
-#
-# Build a second version of the shell with all commands integrated
-#
-ShellPkg/Application/Shell/Shell.inf {
- <Defines>
- FILE_GUID = EA4BB293-2D7F-4456-A681-1F22F42CD0BC
- <PcdsFixedAtBuild>
- gEfiShellPkgTokenSpaceGuid.PcdShellLibAutoInitialize|FALSE
- <LibraryClasses>
- NULL|ShellPkg/Library/UefiShellLevel2CommandsLib/UefiShellLevel2CommandsLib.inf
- NULL|ShellPkg/Library/UefiShellLevel1CommandsLib/UefiShellLevel1CommandsLib.inf
- NULL|ShellPkg/Library/UefiShellLevel3CommandsLib/UefiShellLevel3CommandsLib.inf
- NULL|ShellPkg/Library/UefiShellDriver1CommandsLib/UefiShellDriver1CommandsLib.inf
- NULL|ShellPkg/Library/UefiShellInstall1CommandsLib/UefiShellInstall1CommandsLib.inf
- NULL|ShellPkg/Library/UefiShellDebug1CommandsLib/UefiShellDebug1CommandsLib.inf
- NULL|ShellPkg/Library/UefiShellNetwork1CommandsLib/UefiShellNetwork1CommandsLib.inf
- NULL|ShellPkg/Library/UefiShellNetwork2CommandsLib/UefiShellNetwork2CommandsLib.inf
- NULL|ShellPkg/Library/UefiShellAcpiViewCommandLib/UefiShellAcpiViewCommandLib.inf <------- acpiview is present in this Shell version
-}
+UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.c:
```
+#include <Library/UefiBootServicesTableLib.h>
+#include <Library/UefiLib.h>
-In case you wonder how `UefiShellAcpiViewCommandLib.inf` registers new command take a look at its sources:
-
-https://github.com/tianocore/edk2/blob/master/ShellPkg/Library/UefiShellAcpiViewCommandLib/UefiShellAcpiViewCommandLib.inf
-```
-[Defines]
- INF_VERSION = 0x00010019
- BASE_NAME = UefiShellAcpiViewCommandLib
- FILE_GUID = FB5B305E-84F5-461F-940D-82D345757AFA
- MODULE_TYPE = UEFI_APPLICATION
- VERSION_STRING = 1.0
- LIBRARY_CLASS = AcpiViewCommandLib|UEFI_APPLICATION UEFI_DRIVER
- CONSTRUCTOR = UefiShellAcpiViewCommandLibConstructor
- DESTRUCTOR = UefiShellAcpiViewCommandLibDestructor
+#include <Library/SimpleLibrary.h>
- ...
-```
-https://github.com/tianocore/edk2/blob/master/ShellPkg/Library/UefiShellAcpiViewCommandLib/UefiShellAcpiViewCommandLib.c
-```
EFI_STATUS
EFIAPI
-UefiShellAcpiViewCommandLibConstructor (
+UefiMain (
IN EFI_HANDLE ImageHandle,
IN EFI_SYSTEM_TABLE *SystemTable
)
{
- ...
- // Install our Shell command handler
- ShellCommandRegisterCommandName (
- L"acpiview",
- ShellCommandRunAcpiView,
- ShellCommandGetManFileNameAcpiView,
- 0,
- L"acpiview",
- TRUE,
- gShellAcpiViewHiiHandle,
- STRING_TOKEN (STR_GET_HELP_ACPIVIEW)
- );
+ Print(L"%d\n", Plus2(3));
return EFI_SUCCESS;
}
```
-It doesn't look too scary, so you can even try to add your command to the shell. Maybe will try that in later lessons.
-Now execute this command to build the Shell application:
-```
-build --platform=ShellPkg/ShellPkg.dsc --module=ShellPkg/Application/Shell/Shell.inf --arch=X64 --buildtarget=RELEASE --tagname=GCC5
+UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.inf
```
+[Defines]
+ INF_VERSION = 1.25
+ BASE_NAME = SimpleLibraryUser
+ FILE_GUID = 22a1f57c-21ca-4011-9133-e3df0d01dace
+ MODULE_TYPE = UEFI_APPLICATION
+ VERSION_STRING = 1.0
+ ENTRY_POINT = UefiMain
-After the build there would be two files in the build folder:
-```
-$ ls Build/Shell/RELEASE_GCC5/X64/Shell*.efi
-Build/Shell/RELEASE_GCC5/X64/Shell_7C04A583-9E3E-4f1c-AD65-E05268D0B4D1.efi
-Build/Shell/RELEASE_GCC5/X64/Shell_EA4BB293-2D7F-4456-A681-1F22F42CD0BC.efi
-```
+[Sources]
+ SimpleLibraryUser.c
-If you look closely to the code from the `ShellPkg/ShellPkg.dsc` that I've pasted earlier, you can notice that the image that we need is an image with a `EA4BB293-2D7F-4456-A681-1F22F42CD0BC` guid.
+[Packages]
+ MdePkg/MdePkg.dec
+ UefiLessonsPkg/UefiLessonsPkg.dec <--- we need to include this for the same reason as in library INF file (for the header search)
-Copy it to the QEMU shared folder:
+[LibraryClasses]
+ UefiApplicationEntryPoint
+ UefiLib
+ SimpleLibrary <--- library is included as usual
```
-$ cp Build/Shell/RELEASE_GCC5/X64/Shell_EA4BB293-2D7F-4456-A681-1F22F42CD0BC.efi ~/UEFI_disk/
-```
-In your default shell there wouldn't be any `acpiview` command, but when as you'll move to the `Shell_EA4BB293-2D7F-4456-A681-1F22F42CD0BC.efi` this `acpiview` command would became present in the shell.
-```
-FS0:\> acpiview -l
-'acpiview' is not recognized as an internal or external command, operable program, or script file.
-FS0:\> Shell_EA4BB293-2D7F-4456-A681-1F22F42CD0BC.efi
-UEFI Interactive Shell v2.2
-EDK II
-UEFI v2.70 (EDK II, 0x00010000)
-Mapping table
- FS0: Alias(s):HD0a1:;BLK1:
- PciRoot(0x0)/Pci(0x1,0x1)/Ata(0x0)/HD(1,MBR,0xBE1AFDFA,0x3F,0xFBFC1)
- BLK0: Alias(s):
- PciRoot(0x0)/Pci(0x1,0x1)/Ata(0x0)
- BLK2: Alias(s):
- PciRoot(0x0)/Pci(0x1,0x1)/Ata(0x0)
-Press ESC in 4 seconds to skip startup.nsh or any other key to continue.
-FS0:\> acpiview -l
-Installed Table(s):
- 1. RSDP
- 2. XSDT
- 3. FACP
- 4. FACS
- 5. DSDT
- 6. APIC
- 7. HPET
- 8. BGRT
+Now add modifications to the `UefiLessonsPkg/UefiLessonsPkg.dsc`:
```
+[LibraryClasses]
+ ...
+ SimpleLibrary|UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf
-# Update OVMF image with a shell that actually includes 'acpiview' command in itself
-
-Correct `OvmfPkg/OvmfPkgX64.dsc`. You'll need to add `UefiShellAcpiViewCommandLib.inf` to the `Shell.inf` library classes:
-```
[Components]
...
- ShellPkg/Application/Shell/Shell.inf {
- <LibraryClasses>
- ShellCommandLib|ShellPkg/Library/UefiShellCommandLib/UefiShellCommandLib.inf
- NULL|ShellPkg/Library/UefiShellLevel2CommandsLib/UefiShellLevel2CommandsLib.inf
- NULL|ShellPkg/Library/UefiShellLevel1CommandsLib/UefiShellLevel1CommandsLib.inf
- NULL|ShellPkg/Library/UefiShellLevel3CommandsLib/UefiShellLevel3CommandsLib.inf
- NULL|ShellPkg/Library/UefiShellDriver1CommandsLib/UefiShellDriver1CommandsLib.inf
- NULL|ShellPkg/Library/UefiShellDebug1CommandsLib/UefiShellDebug1CommandsLib.inf
- NULL|ShellPkg/Library/UefiShellInstall1CommandsLib/UefiShellInstall1CommandsLib.inf
- NULL|ShellPkg/Library/UefiShellNetwork1CommandsLib/UefiShellNetwork1CommandsLib.inf
- NULL|ShellPkg/Library/UefiShellAcpiViewCommandLib/UefiShellAcpiViewCommandLib.inf <-----------
-!if $(NETWORK_IP6_ENABLE) == TRUE
- NULL|ShellPkg/Library/UefiShellNetwork2CommandsLib/UefiShellNetwork2CommandsLib.inf
-!endif
- HandleParsingLib|ShellPkg/Library/UefiHandleParsingLib/UefiHandleParsingLib.inf
- PrintLib|MdePkg/Library/BasePrintLib/BasePrintLib.inf
- BcfgCommandLib|ShellPkg/Library/UefiShellBcfgCommandLib/UefiShellBcfgCommandLib.inf
-
- <PcdsFixedAtBuild>
- gEfiMdePkgTokenSpaceGuid.PcdDebugPropertyMask|0xFF
- gEfiShellPkgTokenSpaceGuid.PcdShellLibAutoInitialize|FALSE
- gEfiMdePkgTokenSpaceGuid.PcdUefiLibMaxPrintBufferSize|8000
- }
+ UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.inf
```
+Here we've added implementation for our library class and added our new module to the package components.
-Rebuild OVMF:
-```
-build --platform=OvmfPkg/OvmfPkgX64.dsc --arch=X64 --buildtarget=RELEASE --tagname=GCC5
+If you build everything now and execute it under OVMF, you would get:
```
-
-You can test that this OVMF image has a shell that includes `acpiview` command in itself:
+FS0:\> SimpleLibraryUser.efi
+5
```
-FS0:\> acpiview -l
-Installed Table(s):
- 1. RSDP
- 2. XSDT
- 3. FACP
- 4. FACS
- 5. DSDT
- 6. APIC
- 7. HPET
- 8. BGRT
-```
+`3+2` is indeed `5`, so our library works correctly!
diff --git a/Lessons/Lesson_37/UefiLessonsPkg/Include/Library/SimpleLibrary.h b/Lessons/Lesson_35/UefiLessonsPkg/Include/Library/SimpleLibrary.h
index 105bc87..105bc87 100644
--- a/Lessons/Lesson_37/UefiLessonsPkg/Include/Library/SimpleLibrary.h
+++ b/Lessons/Lesson_35/UefiLessonsPkg/Include/Library/SimpleLibrary.h
diff --git a/Lessons/Lesson_37/UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.c b/Lessons/Lesson_35/UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.c
index acffba4..acffba4 100644
--- a/Lessons/Lesson_37/UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.c
+++ b/Lessons/Lesson_35/UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.c
diff --git a/Lessons/Lesson_37/UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf b/Lessons/Lesson_35/UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf
index 92027a4..92027a4 100644
--- a/Lessons/Lesson_37/UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf
+++ b/Lessons/Lesson_35/UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf
diff --git a/Lessons/Lesson_37/UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.c b/Lessons/Lesson_35/UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.c
index 9747b97..9747b97 100644
--- a/Lessons/Lesson_37/UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.c
+++ b/Lessons/Lesson_35/UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.c
diff --git a/Lessons/Lesson_37/UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.inf b/Lessons/Lesson_35/UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.inf
index d7e5be8..d7e5be8 100644
--- a/Lessons/Lesson_37/UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.inf
+++ b/Lessons/Lesson_35/UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.inf
diff --git a/Lessons/Lesson_37/UefiLessonsPkg/UefiLessonsPkg.dec b/Lessons/Lesson_35/UefiLessonsPkg/UefiLessonsPkg.dec
index cc355aa..cc355aa 100644
--- a/Lessons/Lesson_37/UefiLessonsPkg/UefiLessonsPkg.dec
+++ b/Lessons/Lesson_35/UefiLessonsPkg/UefiLessonsPkg.dec
diff --git a/Lessons/Lesson_37/UefiLessonsPkg/UefiLessonsPkg.dsc b/Lessons/Lesson_35/UefiLessonsPkg/UefiLessonsPkg.dsc
index cdd60c9..c42b57d 100644
--- a/Lessons/Lesson_37/UefiLessonsPkg/UefiLessonsPkg.dsc
+++ b/Lessons/Lesson_35/UefiLessonsPkg/UefiLessonsPkg.dsc
@@ -29,9 +29,7 @@
HiiLib|MdeModulePkg/Library/UefiHiiLib/UefiHiiLib.inf
SortLib|MdeModulePkg/Library/UefiSortLib/UefiSortLib.inf
UefiHiiServicesLib|MdeModulePkg/Library/UefiHiiServicesLib/UefiHiiServicesLib.inf
- #SimpleLibrary|UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf
- #SimpleLibrary|UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.inf
- SimpleLibrary|UefiLessonsPkg/Library/SimpleLibraryWithConstructorAndDestructor/SimpleLibraryWithConstructorAndDestructor.inf
+ SimpleLibrary|UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf
[Components]
UefiLessonsPkg/SimplestApp/SimplestApp.inf
@@ -54,7 +52,6 @@
UefiLessonsPkg/ListPCI/ListPCI.inf
UefiLessonsPkg/PCIRomInfo/PCIRomInfo.inf
UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf
- UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.inf
UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.inf
[PcdsFixedAtBuild]
diff --git a/Lessons/Lesson_36/README.md b/Lessons/Lesson_36/README.md
index f6d64ad..8f73957 100644
--- a/Lessons/Lesson_36/README.md
+++ b/Lessons/Lesson_36/README.md
@@ -1,157 +1,227 @@
-In this lesson we will try to create the most simple library.
+In this lesson we'll learn about library constructor and destructor.
-Usually libraries are present in these directories:
-```
-<Pkg Name>/Library/<Library Name>/ <---- inf and source files for the library (=library implementation)
-<Pkg Name>/Include/Library/ <---- library headers (=library interface)
-```
-
-Create folders for our `SimpleLibrary`:
-```
-$ mkdir -p UefiLessonsPkg/Library/SimpleLibrary/
-$ mkdir -p UefiLessonsPkg/Include/Library/
-```
-
-First let's implement the header file, the interface for our library. Our `SimpleLibrary` would contain the only function `Plus2` that would receive a `number` and return a `number+2`.
-Therefore the content in the header file (`UefiLessonsPkg/Include/Library/SimpleLibrary.h`) would look like this:
-```
-UINTN Plus2(UINTN number);
-```
-
-No harder the library implementation file `UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.c`:
-```
-#include <Library/SimpleLibrary.h>
-
-UINTN Plus2(UINTN number) {
- return number+2;
-}
-```
-
-This is really a simple library, it stands to its name!
-
-Now we need to create an INF file for the library `UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf`:
+Create a new library module `UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.inf`:
```
[Defines]
INF_VERSION = 1.25
- BASE_NAME = SimpleLibrary
- FILE_GUID = 826c8951-5bd2-4d72-a9d9-f7ab48684117
+ BASE_NAME = SimpleLibraryWithConstructor
+ FILE_GUID = 96952c1e-86a6-4700-96b0-e7303ac3f92d
MODULE_TYPE = UEFI_APPLICATION
VERSION_STRING = 1.0
LIBRARY_CLASS = SimpleLibrary | UEFI_APPLICATION
+ CONSTRUCTOR = SimpleLibraryConstructor <--------
[Sources]
- SimpleLibrary.c
+ SimpleLibraryWithConstructor.c
[Packages]
MdePkg/MdePkg.dec
+ UefiLessonsPkg/UefiLessonsPkg.dec
```
+Here we've added `CONSTRUCTOR` statement with a name of constructor function. Let's add `Print` statement to it, to know when it is executed.
-The interesting string here is the:
-```
-LIBRARY_CLASS = SimpleLibrary | UEFI_APPLICATION
-```
-It says that this library can only be used in modules with a type `UEFI_APPLICATION`. If you would say here `DXE_DRIVER` and try to link it to some of you UEFI applications, build process would fail. The error message would look like this:
-```
-build.py...
-/home/kostr/tiano/edk2/UefiLessonsPkg/UefiLessonsPkg.dsc(...): error 1001: Module type [UEFI_APPLICATION] is not supported by library instance [/home/kostr/tiano/edk2/UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf]
- consumed by [/home/kostr/tiano/edk2/UefiLessonsPkg/<path to your app inf file>]
+`UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.c`:
```
+#include <Library/UefiLib.h>
+#include <Library/SimpleLibrary.h>
-Now we need to include our library to our package DSC file `UefiLessonsPkg/UefiLessonsPkg.dsc`, so it would get build on a package build:
-```
-[Components]
- ...
- UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf
-```
+UINTN Plus2(UINTN number) {
+ return number+2;
+}
-But if you try to build our package now build would fail with a message:
-```
-/home/kostr/tiano/edk2/UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.c:1:10: fatal error: Library/SimpleLibrary.h: No such file or directory
- 1 | #include <Library/SimpleLibrary.h>
- | ^~~~~~~~~~~~~~~~~~~~~~~~~
-compilation terminated.
+EFI_STATUS
+EFIAPI
+SimpleLibraryConstructor(
+ IN EFI_HANDLE ImageHandle,
+ IN EFI_SYSTEM_TABLE *SystemTable
+ )
+{
+ Print(L"Hello from library constructor!\n");
+ return EFI_SUCCESS;
+}
```
-The reason of that is a fact that our `UefiLessonsPkg/Include/Library/` folder is not recognized by a build system as a place where headers might be.
-To fix it we need to add to our `UefiLessonsPkg/UefiLessonsPkg.dec` file `[Includes]` section:
+Now we don't need to create another app that would use our new lib, we can simply change library implementation in the `UefiLessonsPkg/UefiLessonsPkg.dsc` and our `SimpleLibraryUser` would be recompiled with our new library version:
```
-[Includes]
- Include
+[LibraryClasses]
+ ...
+ #SimpleLibrary|UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf
+ SimpleLibrary|UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.inf
```
-And include this `UefiLessonsPkg/UefiLessonsPkg.dec` file to the library module INF file section `[Packages]`:
+If you build our app and execute it under OVMF now you would get:
```
-[Packages]
- MdePkg/MdePkg.dec
- UefiLessonsPkg/UefiLessonsPkg.dec
+FS0:\> SimpleLibraryUser.efi
+Hello from library constructor!
+5
```
-Now we are good, build would succeed.
+An example of a library that uses constructor would be `UefiBootServicesTableLib` library https://github.com/tianocore/edk2/blob/master/MdePkg/Library/UefiBootServicesTableLib/UefiBootServicesTableLib.inf. We've used it all over in our lessons, so let's take a look at it.
-# SimpleLibraryUser
+As a matter of fact, constructor is the only thing that this library has.
-Now let's create an application that would use our library.
+To understand how this library works take a look at its *.c and *.h files:
-UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.c:
+https://github.com/tianocore/edk2/blob/master/MdePkg/Library/UefiBootServicesTableLib/UefiBootServicesTableLib.c
```
-#include <Library/UefiBootServicesTableLib.h>
-#include <Library/UefiLib.h>
-
-#include <Library/SimpleLibrary.h>
+EFI_HANDLE gImageHandle = NULL;
+EFI_SYSTEM_TABLE *gST = NULL;
+EFI_BOOT_SERVICES *gBS = NULL;
EFI_STATUS
EFIAPI
-UefiMain (
+UefiBootServicesTableLibConstructor (
IN EFI_HANDLE ImageHandle,
IN EFI_SYSTEM_TABLE *SystemTable
)
{
- Print(L"%d\n", Plus2(3));
+ gImageHandle = ImageHandle;
+ gST = SystemTable;
+ gBS = SystemTable->BootServices;
return EFI_SUCCESS;
}
```
+https://github.com/tianocore/edk2/blob/master/MdePkg/Include/Library/UefiBootServicesTableLib.h:
+```
+extern EFI_HANDLE gImageHandle;
+extern EFI_SYSTEM_TABLE *gST;
+extern EFI_BOOT_SERVICES *gBS;
+```
+
+So as you can see this library just sets some global variables - shortcuts for the UEFI main parts. As the library constructors execute before the main app code, with this library you can access `gImageHandle`/`gST`/`gBS` anywhere in your app code from the very start.
-UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.inf
+# DESTRUCTOR
+
+Similar we can create another version of a `SimpleLibrary` that would have both constructor and destructor.
+
+`UefiLessonsPkg/Library/SimpleLibraryWithConstructorAndDestructor/SimpleLibraryWithConstructorAndDestructor.inf`:
```
[Defines]
INF_VERSION = 1.25
- BASE_NAME = SimpleLibraryUser
- FILE_GUID = 22a1f57c-21ca-4011-9133-e3df0d01dace
+ BASE_NAME = SimpleLibraryWithConstructorAndDestructor
+ FILE_GUID = 96952c1e-86a6-4700-96b0-e7303ac3f92d
MODULE_TYPE = UEFI_APPLICATION
VERSION_STRING = 1.0
- ENTRY_POINT = UefiMain
+ LIBRARY_CLASS = SimpleLibrary | UEFI_APPLICATION
+ CONSTRUCTOR = SimpleLibraryConstructor
+ DESTRUCTOR = SimpleLibraryDestructor <-----------
[Sources]
- SimpleLibraryUser.c
+ SimpleLibraryWithConstructorAndDestructor.c
[Packages]
MdePkg/MdePkg.dec
- UefiLessonsPkg/UefiLessonsPkg.dec <--- we need to include this for the same reason as in library INF file (for the header search)
+ UefiLessonsPkg/UefiLessonsPkg.dec
+```
+`UefiLessonsPkg/Library/SimpleLibraryWithConstructorAndDestructor/SimpleLibraryWithConstructorAndDestructor.c`:
+```
+#include <Library/UefiLib.h>
+#include <Library/SimpleLibrary.h>
-[LibraryClasses]
- UefiApplicationEntryPoint
- UefiLib
- SimpleLibrary <--- library is included as usual
+UINTN Plus2(UINTN number) {
+ return number+2;
+}
+
+EFI_STATUS
+EFIAPI
+SimpleLibraryConstructor(
+ IN EFI_HANDLE ImageHandle,
+ IN EFI_SYSTEM_TABLE *SystemTable
+ )
+{
+ Print(L"Hello from library constructor!\n");
+ return EFI_SUCCESS;
+}
+
+EFI_STATUS
+EFIAPI
+SimpleLibraryDestructor(
+ IN EFI_HANDLE ImageHandle,
+ IN EFI_SYSTEM_TABLE *SystemTable
+ )
+{
+ Print(L"Hello from library destructor!\n");
+ return EFI_SUCCESS;
+}
```
-Now add modifications to the `UefiLessonsPkg/UefiLessonsPkg.dsc`:
+Don't forget to change the library backend in the `UefiLessonsPkg/UefiLessonsPkg.dsc`:
```
[LibraryClasses]
...
- SimpleLibrary|UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf
-
-[Components]
- ...
- UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.inf
+ #SimpleLibrary|UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf
+ #SimpleLibrary|UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.inf
+ SimpleLibrary|UefiLessonsPkg/Library/SimpleLibraryWithConstructorAndDestructor/SimpleLibraryWithConstructorAndDestructor.inf
```
-Here we've added implementation for our library class and added our new module to the package components.
-If you build everything now and execute it under OVMF, you would get:
+Now our app would have print strings both at the beginning and in the end:
```
FS0:\> SimpleLibraryUser.efi
+Hello from library constructor!
5
+Hello from library destructor!
```
-`3+2` is indeed `5`, so our library works correctly!
+
+As an example of a library with both CONSTRUCTOR and DESTRUCTOR take a look at the https://github.com/tianocore/edk2/blob/master/MdePkg/Library/UefiDebugLibConOut/DebugLibConstructor.c, it uses `CreateEvent` in a constructor, and closes it in a desctrutor with a `CloseEvent`.
+
+
+# `NULL` library
+
+
+As you already know OVMF includes `Shell` app in itself. For its compilation OVMF package DSC file (https://github.com/tianocore/edk2/blob/master/OvmfPkg/OvmfPkgX64.dsc) contains these strings:
+```
+[Components]
+ ...
+ ShellPkg/Application/Shell/Shell.inf {
+ <LibraryClasses>
+ ShellCommandLib|ShellPkg/Library/UefiShellCommandLib/UefiShellCommandLib.inf
+ NULL|ShellPkg/Library/UefiShellLevel2CommandsLib/UefiShellLevel2CommandsLib.inf
+ NULL|ShellPkg/Library/UefiShellLevel1CommandsLib/UefiShellLevel1CommandsLib.inf
+ NULL|ShellPkg/Library/UefiShellLevel3CommandsLib/UefiShellLevel3CommandsLib.inf
+ NULL|ShellPkg/Library/UefiShellDriver1CommandsLib/UefiShellDriver1CommandsLib.inf
+ NULL|ShellPkg/Library/UefiShellDebug1CommandsLib/UefiShellDebug1CommandsLib.inf
+ NULL|ShellPkg/Library/UefiShellInstall1CommandsLib/UefiShellInstall1CommandsLib.inf
+ NULL|ShellPkg/Library/UefiShellNetwork1CommandsLib/UefiShellNetwork1CommandsLib.inf
+ ...
+ HandleParsingLib|ShellPkg/Library/UefiHandleParsingLib/UefiHandleParsingLib.inf
+ PrintLib|MdePkg/Library/BasePrintLib/BasePrintLib.inf
+ BcfgCommandLib|ShellPkg/Library/UefiShellBcfgCommandLib/UefiShellBcfgCommandLib.inf
+
+ ...
+ }
+```
+
+Here you can notice that some of the library classes have `NULL` class.
+
+`NULL` library classes are conceptually an "anonymous library". It enables one to statically link code into a module even if the module doesn't directly call functions in that library.
+
+It can be useful if we don't need to call library API in our app, but just need library constructor/destructor functions.
+
+If you'll take a look at the file https://github.com/tianocore/edk2/blob/master/ShellPkg/Library/UefiShellLevel1CommandsLib/UefiShellLevel1CommandsLib.c you'll see that this module constructor is used to add additional commands to the Shell:
+```
+EFI_STATUS
+EFIAPI
+ShellLevel1CommandsLibConstructor (
+ IN EFI_HANDLE ImageHandle,
+ IN EFI_SYSTEM_TABLE *SystemTable
+ )
+{
+ ...
+ ShellCommandRegisterCommandName(L"stall", ShellCommandRunStall , ShellCommandGetManFileNameLevel1, 1, L"", FALSE, gShellLevel1HiiHandle, (EFI_STRING_ID)(PcdGet8(PcdShellSupportLevel) < 3 ? 0 : STRING_TOKEN(STR_GET_HELP_STALL) ));
+ ShellCommandRegisterCommandName(L"for", ShellCommandRunFor , ShellCommandGetManFileNameLevel1, 1, L"", FALSE, gShellLevel1HiiHandle, (EFI_STRING_ID)(PcdGet8(PcdShellSupportLevel) < 3 ? 0 : STRING_TOKEN(STR_GET_HELP_FOR) ));
+ ShellCommandRegisterCommandName(L"goto", ShellCommandRunGoto , ShellCommandGetManFileNameLevel1, 1, L"", FALSE, gShellLevel1HiiHandle, (EFI_STRING_ID)(PcdGet8(PcdShellSupportLevel) < 3 ? 0 : STRING_TOKEN(STR_GET_HELP_GOTO) ));
+ ShellCommandRegisterCommandName(L"if", ShellCommandRunIf , ShellCommandGetManFileNameLevel1, 1, L"", FALSE, gShellLevel1HiiHandle, (EFI_STRING_ID)(PcdGet8(PcdShellSupportLevel) < 3 ? 0 : STRING_TOKEN(STR_GET_HELP_IF) ));
+ ShellCommandRegisterCommandName(L"shift", ShellCommandRunShift , ShellCommandGetManFileNameLevel1, 1, L"", FALSE, gShellLevel1HiiHandle, (EFI_STRING_ID)(PcdGet8(PcdShellSupportLevel) < 3 ? 0 : STRING_TOKEN(STR_GET_HELP_SHIFT) ));
+ ShellCommandRegisterCommandName(L"exit", ShellCommandRunExit , ShellCommandGetManFileNameLevel1, 1, L"", TRUE , gShellLevel1HiiHandle, (EFI_STRING_ID)(PcdGet8(PcdShellSupportLevel) < 3 ? 0 : STRING_TOKEN(STR_GET_HELP_EXIT) ));
+ ShellCommandRegisterCommandName(L"else", ShellCommandRunElse , ShellCommandGetManFileNameLevel1, 1, L"", FALSE, gShellLevel1HiiHandle, (EFI_STRING_ID)(PcdGet8(PcdShellSupportLevel) < 3 ? 0 : STRING_TOKEN(STR_GET_HELP_ELSE) ));
+ ShellCommandRegisterCommandName(L"endif", ShellCommandRunEndIf , ShellCommandGetManFileNameLevel1, 1, L"", FALSE, gShellLevel1HiiHandle, (EFI_STRING_ID)(PcdGet8(PcdShellSupportLevel) < 3 ? 0 : STRING_TOKEN(STR_GET_HELP_ENDIF) ));
+ ShellCommandRegisterCommandName(L"endfor", ShellCommandRunEndFor , ShellCommandGetManFileNameLevel1, 1, L"", FALSE, gShellLevel1HiiHandle, (EFI_STRING_ID)(PcdGet8(PcdShellSupportLevel) < 3 ? 0 : STRING_TOKEN(STR_GET_HELP_ENDFOR)));
+
+ return (EFI_SUCCESS);
+```
+
+This is an elegant way to split shell command support to different modules.
+With this functionality you can easily compile your image of `Shell` with a necessary commands support.
diff --git a/Lessons/Lesson_37/UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.c b/Lessons/Lesson_36/UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.c
index 5ade80e..5ade80e 100644
--- a/Lessons/Lesson_37/UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.c
+++ b/Lessons/Lesson_36/UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.c
diff --git a/Lessons/Lesson_37/UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.inf b/Lessons/Lesson_36/UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.inf
index fc56624..fc56624 100644
--- a/Lessons/Lesson_37/UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.inf
+++ b/Lessons/Lesson_36/UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.inf
diff --git a/Lessons/Lesson_37/UefiLessonsPkg/Library/SimpleLibraryWithConstructorAndDestructor/SimpleLibraryWithConstructorAndDestructor.c b/Lessons/Lesson_36/UefiLessonsPkg/Library/SimpleLibraryWithConstructorAndDestructor/SimpleLibraryWithConstructorAndDestructor.c
index f903e99..f903e99 100644
--- a/Lessons/Lesson_37/UefiLessonsPkg/Library/SimpleLibraryWithConstructorAndDestructor/SimpleLibraryWithConstructorAndDestructor.c
+++ b/Lessons/Lesson_36/UefiLessonsPkg/Library/SimpleLibraryWithConstructorAndDestructor/SimpleLibraryWithConstructorAndDestructor.c
diff --git a/Lessons/Lesson_37/UefiLessonsPkg/Library/SimpleLibraryWithConstructorAndDestructor/SimpleLibraryWithConstructorAndDestructor.inf b/Lessons/Lesson_36/UefiLessonsPkg/Library/SimpleLibraryWithConstructorAndDestructor/SimpleLibraryWithConstructorAndDestructor.inf
index 3fc3bbe..3fc3bbe 100644
--- a/Lessons/Lesson_37/UefiLessonsPkg/Library/SimpleLibraryWithConstructorAndDestructor/SimpleLibraryWithConstructorAndDestructor.inf
+++ b/Lessons/Lesson_36/UefiLessonsPkg/Library/SimpleLibraryWithConstructorAndDestructor/SimpleLibraryWithConstructorAndDestructor.inf
diff --git a/Lessons/Lesson_36/UefiLessonsPkg/UefiLessonsPkg.dsc b/Lessons/Lesson_36/UefiLessonsPkg/UefiLessonsPkg.dsc
index c42b57d..cdd60c9 100644
--- a/Lessons/Lesson_36/UefiLessonsPkg/UefiLessonsPkg.dsc
+++ b/Lessons/Lesson_36/UefiLessonsPkg/UefiLessonsPkg.dsc
@@ -29,7 +29,9 @@
HiiLib|MdeModulePkg/Library/UefiHiiLib/UefiHiiLib.inf
SortLib|MdeModulePkg/Library/UefiSortLib/UefiSortLib.inf
UefiHiiServicesLib|MdeModulePkg/Library/UefiHiiServicesLib/UefiHiiServicesLib.inf
- SimpleLibrary|UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf
+ #SimpleLibrary|UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf
+ #SimpleLibrary|UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.inf
+ SimpleLibrary|UefiLessonsPkg/Library/SimpleLibraryWithConstructorAndDestructor/SimpleLibraryWithConstructorAndDestructor.inf
[Components]
UefiLessonsPkg/SimplestApp/SimplestApp.inf
@@ -52,6 +54,7 @@
UefiLessonsPkg/ListPCI/ListPCI.inf
UefiLessonsPkg/PCIRomInfo/PCIRomInfo.inf
UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf
+ UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.inf
UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.inf
[PcdsFixedAtBuild]
diff --git a/Lessons/Lesson_37/README.md b/Lessons/Lesson_37/README.md
index 8f73957..def1314 100644
--- a/Lessons/Lesson_37/README.md
+++ b/Lessons/Lesson_37/README.md
@@ -1,176 +1,338 @@
-In this lesson we'll learn about library constructor and destructor.
-
-Create a new library module `UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.inf`:
+If you'll search through ShellPkg library (https://github.com/tianocore/edk2/tree/master/ShellPkg/Library) you can notice that there is a folder `UefiShellAcpiViewCommandLib` (https://github.com/tianocore/edk2/tree/master/ShellPkg/Library/UefiShellAcpiViewCommandLib).
+This folder provides a library for the support of in-shell `acpiview` command. If you check the INF file, you'll see
+https://github.com/tianocore/edk2/blob/master/ShellPkg/Library/UefiShellAcpiViewCommandLib/UefiShellAcpiViewCommandLib.inf:
```
-[Defines]
- INF_VERSION = 1.25
- BASE_NAME = SimpleLibraryWithConstructor
- FILE_GUID = 96952c1e-86a6-4700-96b0-e7303ac3f92d
- MODULE_TYPE = UEFI_APPLICATION
- VERSION_STRING = 1.0
- LIBRARY_CLASS = SimpleLibrary | UEFI_APPLICATION
- CONSTRUCTOR = SimpleLibraryConstructor <--------
-
-[Sources]
- SimpleLibraryWithConstructor.c
-
-[Packages]
- MdePkg/MdePkg.dec
- UefiLessonsPkg/UefiLessonsPkg.dec
+# Provides Shell 'acpiview' command functions
```
-Here we've added `CONSTRUCTOR` statement with a name of constructor function. Let's add `Print` statement to it, to know when it is executed.
-
-`UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.c`:
+But if you try to execute `acpiview` in our current OVMF build, you'll notice that this command is not recognized:
+```
+FS0:\> acpiview
+'acpiview' is not recognized as an internal or external command, operable program, or script file.
```
-#include <Library/UefiLib.h>
-#include <Library/SimpleLibrary.h>
+We have 3 ways to use this 'acpiview' command functionality:
+- compile `acpiview` as a separate app and run it as an ordinary UEFI shell application
+- compile shell with 'acpiview' command in itself and run it under OVMF
+- update OVMF image with a shell that actually includes 'acpiview' command in itself
-UINTN Plus2(UINTN number) {
- return number+2;
-}
+# Compile `acpiview` as a separate app
+
+I guess it is the most easy way.
+It is possible to perform such thing with a help of https://github.com/tianocore/edk2/tree/master/ShellPkg/Application/AcpiViewApp
+
+If you look at the source file, you'll see that it is pretty simple, the main function just makes a library call to `ShellCommandRunAcpiView` function:
+```
EFI_STATUS
EFIAPI
-SimpleLibraryConstructor(
- IN EFI_HANDLE ImageHandle,
- IN EFI_SYSTEM_TABLE *SystemTable
+AcpiViewAppMain (
+ IN EFI_HANDLE ImageHandle,
+ IN EFI_SYSTEM_TABLE *SystemTable
)
{
- Print(L"Hello from library constructor!\n");
- return EFI_SUCCESS;
+ return ShellCommandRunAcpiView (gImageHandle, SystemTable);
}
```
-Now we don't need to create another app that would use our new lib, we can simply change library implementation in the `UefiLessonsPkg/UefiLessonsPkg.dsc` and our `SimpleLibraryUser` would be recompiled with our new library version:
+To build this application issue:
```
-[LibraryClasses]
- ...
- #SimpleLibrary|UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf
- SimpleLibrary|UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.inf
+build --platform=ShellPkg/ShellPkg.dsc --module=ShellPkg/Application/AcpiViewApp/AcpiViewApp.inf --arch=X64 --buildtarget=RELEASE --tagname=GCC5
```
-If you build our app and execute it under OVMF now you would get:
+Copy image to the QEMU shared folder:
```
-FS0:\> SimpleLibraryUser.efi
-Hello from library constructor!
-5
+cp Build/Shell/RELEASE_GCC5/X64/AcpiViewApp.efi ~/UEFI_disk/
```
-An example of a library that uses constructor would be `UefiBootServicesTableLib` library https://github.com/tianocore/edk2/blob/master/MdePkg/Library/UefiBootServicesTableLib/UefiBootServicesTableLib.inf. We've used it all over in our lessons, so let's take a look at it.
-
-As a matter of fact, constructor is the only thing that this library has.
-
-To understand how this library works take a look at its *.c and *.h files:
-
-https://github.com/tianocore/edk2/blob/master/MdePkg/Library/UefiBootServicesTableLib/UefiBootServicesTableLib.c
+You can see application help with a:
+```
+FS0:\> AcpiViewApp.efi -?
+Display ACPI Table information.
+
+ACPIVIEWAPP.EFI [[-?] | [[[[-l] | [-s AcpiTable [-d]]] [-q] [-h]] [-r Spec]]]
+
+
+ -l - Display list of installed ACPI Tables.
+ -s - Display only the specified AcpiTable type and only support single
+ invocation option.
+ AcpiTable : The required ACPI Table type.
+ -d - Generate a binary file dump of the specified AcpiTable.
+ -q - Quiet. Suppress errors and warnings. Disables consistency checks.
+ -h - Enable colour highlighting.
+ -r - Validate that all required ACPI tables are installed
+ Spec : Specification to validate against.
+ For Arm, the possible values are:
+ 0 - Server Base Boot Requirements v1.0
+ 1 - Server Base Boot Requirements v1.1
+ 2 - Server Base Boot Requirements v1.2
+ -? - Show help.
+
+
+ This program is provided to allow examination of ACPI table values from the
+ UEFI Shell. This can help with investigations, especially at that stage
+ where the tables are not enabling an OS to boot.
+ The program is not exhaustive, and only encapsulates detailed knowledge of a
+ limited number of table types.
+
+ Default behaviour is to display the content of all tables installed.
+ 'Known' table types (listed in NOTES below) will be parsed and displayed
+ with descriptions and field values. Where appropriate a degree of
+ consistency checking is done and errors may be reported in the output.
+ Other table types will be displayed as an array of Hexadecimal bytes.
+
+ To facilitate debugging, the -s and -d options can be used to generate a
+ binary file image of a table that can be copied elsewhere for investigation
+ using tools such as those provided by acpica.org. This is especially
+ relevant for AML type tables like DSDT and SSDT.
+
+NOTES:
+ 1. The AcpiTable parameter can match any installed table type.
+ Tables without specific handling will be displayed as a raw hex dump (or
+ dumped to a file if -d is used).
+ 2. -s option supports to display the specified AcpiTable type that is present
+ in the system. For normal type AcpiTable, it would display the data of the
+ AcpiTable and AcpiTable header. The following type may contain header type
+ other than AcpiTable header. The actual header can refer to the ACPI spec
+ 6.3
+ Extra A. Particular types:
+ APIC - Multiple APIC Description Table (MADT)
+ BGRT - Boot Graphics Resource Table
+ DBG2 - Debug Port Table 2
+ DSDT - Differentiated System Description Table
+ FACP - Fixed ACPI Description Table (FADT)
+ GTDT - Generic Timer Description Table
+ IORT - IO Remapping Table
+ MCFG - Memory Mapped Config Space Base Address Description Table
+ PPTT - Processor Properties Topology Table
+ RSDP - Root System Description Pointer
+ SLIT - System Locality Information Table
+ SPCR - Serial Port Console Redirection Table
+ SRAT - System Resource Affinity Table
+ SSDT - Secondary SystemDescription Table
+ XSDT - Extended System Description Table
+
+
+
+EXAMPLES:
+ * To display a list of the installed table types:
+ fs0:\> acpiviewapp.efi -l
+
+ * To parse and display a specific table type:
+ fs0:\> acpiviewapp.efi -s GTDT
+
+ * To save a binary dump of the contents of a table to a file
+ in the current working directory:
+ fs0:\> acpiviewapp.efi -s DSDT -d
+
+ * To display contents of all ACPI tables:
+ fs0:\> acpiviewapp.efi
+
+ * To check if all Server Base Boot Requirements (SBBR) v1.2 mandatory
+ ACPI tables are installed (Arm only):
+ fs0:\> acpiviewapp.efi -r 2
```
-EFI_HANDLE gImageHandle = NULL;
-EFI_SYSTEM_TABLE *gST = NULL;
-EFI_BOOT_SERVICES *gBS = NULL;
-EFI_STATUS
-EFIAPI
-UefiBootServicesTableLibConstructor (
- IN EFI_HANDLE ImageHandle,
- IN EFI_SYSTEM_TABLE *SystemTable
- )
-{
- gImageHandle = ImageHandle;
- gST = SystemTable;
- gBS = SystemTable->BootServices;
+With this program you can list ACPI tables in system:
+```
+FS0:\> AcpiViewApp.efi -l
+
+Installed Table(s):
+ 1. RSDP
+ 2. XSDT
+ 3. FACP
+ 4. FACS
+ 5. DSDT
+ 6. APIC
+ 7. HPET
+ 8. BGRT
+```
- return EFI_SUCCESS;
-}
+Show the content of any table:
```
-https://github.com/tianocore/edk2/blob/master/MdePkg/Include/Library/UefiBootServicesTableLib.h:
+FS0:\> AcpiViewApp.efi -s BGRT
+
+
+ --------------- BGRT Table ---------------
+
+Address : 0x7B77000
+Length : 56
+
+00000000 : 42 47 52 54 38 00 00 00 - 01 C5 49 4E 54 45 4C 20 BGRT8.....INTEL
+00000010 : 45 44 4B 32 20 20 20 20 - 02 00 00 00 20 20 20 20 EDK2 ....
+00000020 : 13 00 00 01 01 00 01 00 - 18 30 8B 06 00 00 00 00 .........0......
+00000030 : 2F 01 00 00 0F 01 00 00 /.......
+
+Table Checksum : OK
+
+BGRT :
+ Signature : BGRT
+ Length : 56
+ Revision : 1
+ Checksum : 0xC5
+ Oem ID : INTEL
+ Oem Table ID : EDK2
+ Oem Revision : 0x2
+ Creator ID :
+ Creator Revision : 0x1000013
+ Version : 0x1
+ Status : 0x1
+ Image Type : 0x0
+ Image Address : 0x68B3018
+ Image Offset X : 303
+ Image Offset Y : 271
+
+Table Statistics:
+ 0 Error(s)
+ 0 Warning(s)
```
-extern EFI_HANDLE gImageHandle;
-extern EFI_SYSTEM_TABLE *gST;
-extern EFI_BOOT_SERVICES *gBS;
+
+Or dump any ACPI table:
```
+FS0:\> acpiview -s APIC -d
+Dumping ACPI table to : .\APIC0000.bin ... DONE.
+```
+You can disassemble this image with `iasl -d <file>` like we did earlier.
+
-So as you can see this library just sets some global variables - shortcuts for the UEFI main parts. As the library constructors execute before the main app code, with this library you can access `gImageHandle`/`gST`/`gBS` anywhere in your app code from the very start.
+# Compile shell with 'acpiview' command in itself and run it under OVMF
+
+This case is a little bit crazy, we would be running a shell applicaion inside the shell application.
+
+I guess this is not the usual case, but it will help you to know how to compile the shell image that you can actually use in your projects.
+
+If you'll look at the https://github.com/tianocore/edk2/blob/master/ShellPkg/ShellPkg.dsc you'll see that if you build `ShellPkg`, you'll actually build two versions of the `Shell.inf`:
+- one would have general commands
+- another one would have all the commands
+```
+ShellPkg/Application/Shell/Shell.inf {
+ <PcdsFixedAtBuild>
+ gEfiShellPkgTokenSpaceGuid.PcdShellLibAutoInitialize|FALSE
+ <LibraryClasses>
+ NULL|ShellPkg/Library/UefiShellLevel2CommandsLib/UefiShellLevel2CommandsLib.inf
+ NULL|ShellPkg/Library/UefiShellLevel1CommandsLib/UefiShellLevel1CommandsLib.inf
+ NULL|ShellPkg/Library/UefiShellLevel3CommandsLib/UefiShellLevel3CommandsLib.inf
+fndef $(NO_SHELL_PROFILES)
+ NULL|ShellPkg/Library/UefiShellDriver1CommandsLib/UefiShellDriver1CommandsLib.inf
+ NULL|ShellPkg/Library/UefiShellInstall1CommandsLib/UefiShellInstall1CommandsLib.inf
+ NULL|ShellPkg/Library/UefiShellDebug1CommandsLib/UefiShellDebug1CommandsLib.inf
+ NULL|ShellPkg/Library/UefiShellNetwork1CommandsLib/UefiShellNetwork1CommandsLib.inf
+ NULL|ShellPkg/Library/UefiShellNetwork2CommandsLib/UefiShellNetwork2CommandsLib.inf
+ndif #$(NO_SHELL_PROFILES)
+}
-# DESTRUCTOR
+#
+# Build a second version of the shell with all commands integrated
+#
+ShellPkg/Application/Shell/Shell.inf {
+ <Defines>
+ FILE_GUID = EA4BB293-2D7F-4456-A681-1F22F42CD0BC
+ <PcdsFixedAtBuild>
+ gEfiShellPkgTokenSpaceGuid.PcdShellLibAutoInitialize|FALSE
+ <LibraryClasses>
+ NULL|ShellPkg/Library/UefiShellLevel2CommandsLib/UefiShellLevel2CommandsLib.inf
+ NULL|ShellPkg/Library/UefiShellLevel1CommandsLib/UefiShellLevel1CommandsLib.inf
+ NULL|ShellPkg/Library/UefiShellLevel3CommandsLib/UefiShellLevel3CommandsLib.inf
+ NULL|ShellPkg/Library/UefiShellDriver1CommandsLib/UefiShellDriver1CommandsLib.inf
+ NULL|ShellPkg/Library/UefiShellInstall1CommandsLib/UefiShellInstall1CommandsLib.inf
+ NULL|ShellPkg/Library/UefiShellDebug1CommandsLib/UefiShellDebug1CommandsLib.inf
+ NULL|ShellPkg/Library/UefiShellNetwork1CommandsLib/UefiShellNetwork1CommandsLib.inf
+ NULL|ShellPkg/Library/UefiShellNetwork2CommandsLib/UefiShellNetwork2CommandsLib.inf
+ NULL|ShellPkg/Library/UefiShellAcpiViewCommandLib/UefiShellAcpiViewCommandLib.inf <------- acpiview is present in this Shell version
+}
+```
-Similar we can create another version of a `SimpleLibrary` that would have both constructor and destructor.
+In case you wonder how `UefiShellAcpiViewCommandLib.inf` registers new command take a look at its sources:
-`UefiLessonsPkg/Library/SimpleLibraryWithConstructorAndDestructor/SimpleLibraryWithConstructorAndDestructor.inf`:
+https://github.com/tianocore/edk2/blob/master/ShellPkg/Library/UefiShellAcpiViewCommandLib/UefiShellAcpiViewCommandLib.inf
```
[Defines]
- INF_VERSION = 1.25
- BASE_NAME = SimpleLibraryWithConstructorAndDestructor
- FILE_GUID = 96952c1e-86a6-4700-96b0-e7303ac3f92d
+ INF_VERSION = 0x00010019
+ BASE_NAME = UefiShellAcpiViewCommandLib
+ FILE_GUID = FB5B305E-84F5-461F-940D-82D345757AFA
MODULE_TYPE = UEFI_APPLICATION
VERSION_STRING = 1.0
- LIBRARY_CLASS = SimpleLibrary | UEFI_APPLICATION
- CONSTRUCTOR = SimpleLibraryConstructor
- DESTRUCTOR = SimpleLibraryDestructor <-----------
+ LIBRARY_CLASS = AcpiViewCommandLib|UEFI_APPLICATION UEFI_DRIVER
+ CONSTRUCTOR = UefiShellAcpiViewCommandLibConstructor
+ DESTRUCTOR = UefiShellAcpiViewCommandLibDestructor
-[Sources]
- SimpleLibraryWithConstructorAndDestructor.c
-
-[Packages]
- MdePkg/MdePkg.dec
- UefiLessonsPkg/UefiLessonsPkg.dec
+ ...
```
-`UefiLessonsPkg/Library/SimpleLibraryWithConstructorAndDestructor/SimpleLibraryWithConstructorAndDestructor.c`:
+https://github.com/tianocore/edk2/blob/master/ShellPkg/Library/UefiShellAcpiViewCommandLib/UefiShellAcpiViewCommandLib.c
```
-#include <Library/UefiLib.h>
-#include <Library/SimpleLibrary.h>
-
-UINTN Plus2(UINTN number) {
- return number+2;
-}
-
EFI_STATUS
EFIAPI
-SimpleLibraryConstructor(
- IN EFI_HANDLE ImageHandle,
- IN EFI_SYSTEM_TABLE *SystemTable
+UefiShellAcpiViewCommandLibConstructor (
+ IN EFI_HANDLE ImageHandle,
+ IN EFI_SYSTEM_TABLE *SystemTable
)
{
- Print(L"Hello from library constructor!\n");
- return EFI_SUCCESS;
-}
+ ...
+ // Install our Shell command handler
+ ShellCommandRegisterCommandName (
+ L"acpiview",
+ ShellCommandRunAcpiView,
+ ShellCommandGetManFileNameAcpiView,
+ 0,
+ L"acpiview",
+ TRUE,
+ gShellAcpiViewHiiHandle,
+ STRING_TOKEN (STR_GET_HELP_ACPIVIEW)
+ );
-EFI_STATUS
-EFIAPI
-SimpleLibraryDestructor(
- IN EFI_HANDLE ImageHandle,
- IN EFI_SYSTEM_TABLE *SystemTable
- )
-{
- Print(L"Hello from library destructor!\n");
return EFI_SUCCESS;
}
```
+It doesn't look too scary, so you can even try to add your command to the shell. Maybe will try that in later lessons.
-Don't forget to change the library backend in the `UefiLessonsPkg/UefiLessonsPkg.dsc`:
+Now execute this command to build the Shell application:
```
-[LibraryClasses]
- ...
- #SimpleLibrary|UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf
- #SimpleLibrary|UefiLessonsPkg/Library/SimpleLibraryWithConstructor/SimpleLibraryWithConstructor.inf
- SimpleLibrary|UefiLessonsPkg/Library/SimpleLibraryWithConstructorAndDestructor/SimpleLibraryWithConstructorAndDestructor.inf
+build --platform=ShellPkg/ShellPkg.dsc --module=ShellPkg/Application/Shell/Shell.inf --arch=X64 --buildtarget=RELEASE --tagname=GCC5
```
-Now our app would have print strings both at the beginning and in the end:
+After the build there would be two files in the build folder:
```
-FS0:\> SimpleLibraryUser.efi
-Hello from library constructor!
-5
-Hello from library destructor!
+$ ls Build/Shell/RELEASE_GCC5/X64/Shell*.efi
+Build/Shell/RELEASE_GCC5/X64/Shell_7C04A583-9E3E-4f1c-AD65-E05268D0B4D1.efi
+Build/Shell/RELEASE_GCC5/X64/Shell_EA4BB293-2D7F-4456-A681-1F22F42CD0BC.efi
```
+If you look closely to the code from the `ShellPkg/ShellPkg.dsc` that I've pasted earlier, you can notice that the image that we need is an image with a `EA4BB293-2D7F-4456-A681-1F22F42CD0BC` guid.
-As an example of a library with both CONSTRUCTOR and DESTRUCTOR take a look at the https://github.com/tianocore/edk2/blob/master/MdePkg/Library/UefiDebugLibConOut/DebugLibConstructor.c, it uses `CreateEvent` in a constructor, and closes it in a desctrutor with a `CloseEvent`.
-
-
-# `NULL` library
+Copy it to the QEMU shared folder:
+```
+$ cp Build/Shell/RELEASE_GCC5/X64/Shell_EA4BB293-2D7F-4456-A681-1F22F42CD0BC.efi ~/UEFI_disk/
+```
+In your default shell there wouldn't be any `acpiview` command, but when as you'll move to the `Shell_EA4BB293-2D7F-4456-A681-1F22F42CD0BC.efi` this `acpiview` command would became present in the shell.
+```
+FS0:\> acpiview -l
+'acpiview' is not recognized as an internal or external command, operable program, or script file.
+FS0:\> Shell_EA4BB293-2D7F-4456-A681-1F22F42CD0BC.efi
+UEFI Interactive Shell v2.2
+EDK II
+UEFI v2.70 (EDK II, 0x00010000)
+Mapping table
+ FS0: Alias(s):HD0a1:;BLK1:
+ PciRoot(0x0)/Pci(0x1,0x1)/Ata(0x0)/HD(1,MBR,0xBE1AFDFA,0x3F,0xFBFC1)
+ BLK0: Alias(s):
+ PciRoot(0x0)/Pci(0x1,0x1)/Ata(0x0)
+ BLK2: Alias(s):
+ PciRoot(0x0)/Pci(0x1,0x1)/Ata(0x0)
+Press ESC in 4 seconds to skip startup.nsh or any other key to continue.
+FS0:\> acpiview -l
+
+Installed Table(s):
+ 1. RSDP
+ 2. XSDT
+ 3. FACP
+ 4. FACS
+ 5. DSDT
+ 6. APIC
+ 7. HPET
+ 8. BGRT
+```
+# Update OVMF image with a shell that actually includes 'acpiview' command in itself
-As you already know OVMF includes `Shell` app in itself. For its compilation OVMF package DSC file (https://github.com/tianocore/edk2/blob/master/OvmfPkg/OvmfPkgX64.dsc) contains these strings:
+Correct `OvmfPkg/OvmfPkgX64.dsc`. You'll need to add `UefiShellAcpiViewCommandLib.inf` to the `Shell.inf` library classes:
```
[Components]
...
@@ -184,44 +346,38 @@ As you already know OVMF includes `Shell` app in itself. For its compilation OVM
NULL|ShellPkg/Library/UefiShellDebug1CommandsLib/UefiShellDebug1CommandsLib.inf
NULL|ShellPkg/Library/UefiShellInstall1CommandsLib/UefiShellInstall1CommandsLib.inf
NULL|ShellPkg/Library/UefiShellNetwork1CommandsLib/UefiShellNetwork1CommandsLib.inf
- ...
+ NULL|ShellPkg/Library/UefiShellAcpiViewCommandLib/UefiShellAcpiViewCommandLib.inf <-----------
+!if $(NETWORK_IP6_ENABLE) == TRUE
+ NULL|ShellPkg/Library/UefiShellNetwork2CommandsLib/UefiShellNetwork2CommandsLib.inf
+!endif
HandleParsingLib|ShellPkg/Library/UefiHandleParsingLib/UefiHandleParsingLib.inf
PrintLib|MdePkg/Library/BasePrintLib/BasePrintLib.inf
BcfgCommandLib|ShellPkg/Library/UefiShellBcfgCommandLib/UefiShellBcfgCommandLib.inf
- ...
+ <PcdsFixedAtBuild>
+ gEfiMdePkgTokenSpaceGuid.PcdDebugPropertyMask|0xFF
+ gEfiShellPkgTokenSpaceGuid.PcdShellLibAutoInitialize|FALSE
+ gEfiMdePkgTokenSpaceGuid.PcdUefiLibMaxPrintBufferSize|8000
}
```
-Here you can notice that some of the library classes have `NULL` class.
-
-`NULL` library classes are conceptually an "anonymous library". It enables one to statically link code into a module even if the module doesn't directly call functions in that library.
-
-It can be useful if we don't need to call library API in our app, but just need library constructor/destructor functions.
-
-If you'll take a look at the file https://github.com/tianocore/edk2/blob/master/ShellPkg/Library/UefiShellLevel1CommandsLib/UefiShellLevel1CommandsLib.c you'll see that this module constructor is used to add additional commands to the Shell:
+Rebuild OVMF:
```
-EFI_STATUS
-EFIAPI
-ShellLevel1CommandsLibConstructor (
- IN EFI_HANDLE ImageHandle,
- IN EFI_SYSTEM_TABLE *SystemTable
- )
-{
- ...
- ShellCommandRegisterCommandName(L"stall", ShellCommandRunStall , ShellCommandGetManFileNameLevel1, 1, L"", FALSE, gShellLevel1HiiHandle, (EFI_STRING_ID)(PcdGet8(PcdShellSupportLevel) < 3 ? 0 : STRING_TOKEN(STR_GET_HELP_STALL) ));
- ShellCommandRegisterCommandName(L"for", ShellCommandRunFor , ShellCommandGetManFileNameLevel1, 1, L"", FALSE, gShellLevel1HiiHandle, (EFI_STRING_ID)(PcdGet8(PcdShellSupportLevel) < 3 ? 0 : STRING_TOKEN(STR_GET_HELP_FOR) ));
- ShellCommandRegisterCommandName(L"goto", ShellCommandRunGoto , ShellCommandGetManFileNameLevel1, 1, L"", FALSE, gShellLevel1HiiHandle, (EFI_STRING_ID)(PcdGet8(PcdShellSupportLevel) < 3 ? 0 : STRING_TOKEN(STR_GET_HELP_GOTO) ));
- ShellCommandRegisterCommandName(L"if", ShellCommandRunIf , ShellCommandGetManFileNameLevel1, 1, L"", FALSE, gShellLevel1HiiHandle, (EFI_STRING_ID)(PcdGet8(PcdShellSupportLevel) < 3 ? 0 : STRING_TOKEN(STR_GET_HELP_IF) ));
- ShellCommandRegisterCommandName(L"shift", ShellCommandRunShift , ShellCommandGetManFileNameLevel1, 1, L"", FALSE, gShellLevel1HiiHandle, (EFI_STRING_ID)(PcdGet8(PcdShellSupportLevel) < 3 ? 0 : STRING_TOKEN(STR_GET_HELP_SHIFT) ));
- ShellCommandRegisterCommandName(L"exit", ShellCommandRunExit , ShellCommandGetManFileNameLevel1, 1, L"", TRUE , gShellLevel1HiiHandle, (EFI_STRING_ID)(PcdGet8(PcdShellSupportLevel) < 3 ? 0 : STRING_TOKEN(STR_GET_HELP_EXIT) ));
- ShellCommandRegisterCommandName(L"else", ShellCommandRunElse , ShellCommandGetManFileNameLevel1, 1, L"", FALSE, gShellLevel1HiiHandle, (EFI_STRING_ID)(PcdGet8(PcdShellSupportLevel) < 3 ? 0 : STRING_TOKEN(STR_GET_HELP_ELSE) ));
- ShellCommandRegisterCommandName(L"endif", ShellCommandRunEndIf , ShellCommandGetManFileNameLevel1, 1, L"", FALSE, gShellLevel1HiiHandle, (EFI_STRING_ID)(PcdGet8(PcdShellSupportLevel) < 3 ? 0 : STRING_TOKEN(STR_GET_HELP_ENDIF) ));
- ShellCommandRegisterCommandName(L"endfor", ShellCommandRunEndFor , ShellCommandGetManFileNameLevel1, 1, L"", FALSE, gShellLevel1HiiHandle, (EFI_STRING_ID)(PcdGet8(PcdShellSupportLevel) < 3 ? 0 : STRING_TOKEN(STR_GET_HELP_ENDFOR)));
-
- return (EFI_SUCCESS);
+build --platform=OvmfPkg/OvmfPkgX64.dsc --arch=X64 --buildtarget=RELEASE --tagname=GCC5
```
-This is an elegant way to split shell command support to different modules.
-With this functionality you can easily compile your image of `Shell` with a necessary commands support.
+You can test that this OVMF image has a shell that includes `acpiview` command in itself:
+```
+FS0:\> acpiview -l
+
+Installed Table(s):
+ 1. RSDP
+ 2. XSDT
+ 3. FACP
+ 4. FACS
+ 5. DSDT
+ 6. APIC
+ 7. HPET
+ 8. BGRT
+```