From 6064c1e48b622f53538f4df9bdd402c607a87d51 Mon Sep 17 00:00:00 2001 From: Konstantin Aladyshev Date: Sat, 10 Jul 2021 00:04:40 +0300 Subject: Move lessons to separate folder Signed-off-by: Konstantin Aladyshev --- Lessons/Lesson_01/README.md | 138 ++++++++++++++++++++++++++ Lessons/Lesson_01/SimplestApp/SimplestApp.c | 10 ++ Lessons/Lesson_01/SimplestApp/SimplestApp.inf | 16 +++ 3 files changed, 164 insertions(+) create mode 100644 Lessons/Lesson_01/README.md create mode 100644 Lessons/Lesson_01/SimplestApp/SimplestApp.c create mode 100644 Lessons/Lesson_01/SimplestApp/SimplestApp.inf (limited to 'Lessons/Lesson_01') diff --git a/Lessons/Lesson_01/README.md b/Lessons/Lesson_01/README.md new file mode 100644 index 0000000..2f7d3ce --- /dev/null +++ b/Lessons/Lesson_01/README.md @@ -0,0 +1,138 @@ +In last lesson we've built an app that was already included in the TianoCore sources. + +Let's work our way through to our own app. +We will be working on UEFI app that can be run in UEFI shell. + +Create directory for our app: +``` +mkdir SimplestApp +``` + +Then create *.c source file for our app with the folowing content: +``` +$ cat SimplestApp/SimplestApp.c + +EFI_STATUS +EFIAPI +UefiMain ( + IN EFI_HANDLE ImageHandle, + IN EFI_SYSTEM_TABLE *SystemTable + ) +{ + return EFI_SUCCESS; +} +``` + +Then we need to create edk2 app configuration file. This configuration in edk2 is represented in the *.inf format. +INF file can have several sections: +- Defines +- Sources +- Packages +- LibraryClasses +- Guids +- Ppis +- Protocols +- FeaturePcd +- Pcd +- ... + +But right now for our minimal example we're interested in the 3 of those: +- Defines - this section contatins some basic module description. In this section: + +BASE_NAME - our app name + +FILE_GUID - as was said earlier UEFI uses GUID numbers for identification of the components. You could use free online GUID generator to get random GUID https://www.guidgenerator.com/ or simply use `uuidgen` command line utility: +``` +$ uuidgen +e7218aab-998e-4d88-af9b-9573a5bf90ea +``` +MODULE_TYPE - we want to build an application that can be run from the UEFI shell, so we use `UEFI_APPLICATION` here. UEFI application is like a simple program that you can run from shell. It is getting loaded to some memory address, executes and returns something, after that app memory would be freed again. For example other possible value here is UEFI_DRIVER - the difference is when you load a driver it keeps staying in memory even after its execution. +Other values are listed here: https://edk2-docs.gitbook.io/edk-ii-inf-specification/appendix_f_module_types + +ENTRY_POINT - name of the main function in our *.c source file. As it was `UefiMain` this is the value that we write here. + +- Sources - source files for our edk2 module +- LibraryClasses - we need to include `UefiApplicationEntryPoint` library class for our minimal example +- Packages - `MdePkg/MdePkg.dec` is edk2 package with basic UEFI services. It includes `UefiApplicationEntryPoint` that we need to compile our package. + +vi SimplestApp/SimplestApp.inf +``` +[Defines] + INF_VERSION = 1.25 + BASE_NAME = SimplestApp + FILE_GUID = 4a298956-fbe0-47fb-ae3a-2d5a0a959a26 + MODULE_TYPE = UEFI_APPLICATION + VERSION_STRING = 1.0 + ENTRY_POINT = UefiMain + +[Sources] + SimplestApp.c + +[Packages] + MdePkg/MdePkg.dec + +[LibraryClasses] + UefiApplicationEntryPoint +``` +Full specification for the "Module Information (INF) File" can be found under https://edk2-docs.gitbook.io/edk-ii-inf-specification/ + +After the creation of the INF file we need to include our app to some package so we could build it. + +We don't have our own package, so let's include it to `OvmfPkg/OvmfPkgX64.dsc` that we've compiled earlier. +Add a path to our app *.inf file in the components section. +``` + ################################################################################ + [Components] ++ SimplestApp/SimplestApp.inf + OvmfPkg/ResetVector/ResetVector.inf + +``` + +Then build OVMF: +``` +build --platform=OvmfPkg/OvmfPkgX64.dsc --arch=X64 --buildtarget=RELEASE --tagname=GCC5 +``` + +Our compiled app would be in a directory `Build/OvmfX64/RELEASE_GCC5/X64`: +``` +$ ls -lh Build/OvmfX64/RELEASE_GCC5/X64/SimplestApp.efi +-rw-r--r-- 1 kostr kostr 832 Jun 13 10:14 Build/OvmfX64/RELEASE_GCC5/X64/SimplestApp.efi +``` + +Create a folder that we would populate to UEFI shell and copy our app into it: +``` +mkdir ~/UEFI_disk +cp Build/OvmfX64/RELEASE_GCC5/X64/SimplestApp.efi ~/UEFI_disk +``` + +Now lets run OVMF with this folder included: +``` +$ qemu-system-x86_64 -drive if=pflash,format=raw,file=Build/OvmfX64/RELEASE_GCC5/FV/OVMF.fd \ + -drive format=raw,file=fat:rw:~/UEFI_disk \ + -nographic \ + -net none +``` + +Hopefully you'll see something like this: +``` +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 3 seconds to skip startup.nsh or any other key to continue. +``` + +As you can see we have new rows in our mapping table. Our app would be under `FS0`. Lets `mount` this filesystem and execute our app. +``` +Shell> fs0: +FS0:\> SimplestApp.efi +FS0:\> +``` + + diff --git a/Lessons/Lesson_01/SimplestApp/SimplestApp.c b/Lessons/Lesson_01/SimplestApp/SimplestApp.c new file mode 100644 index 0000000..8bdf500 --- /dev/null +++ b/Lessons/Lesson_01/SimplestApp/SimplestApp.c @@ -0,0 +1,10 @@ +EFI_STATUS +EFIAPI +UefiMain ( + IN EFI_HANDLE ImageHandle, + IN EFI_SYSTEM_TABLE *SystemTable + ) +{ + return EFI_SUCCESS; +} + diff --git a/Lessons/Lesson_01/SimplestApp/SimplestApp.inf b/Lessons/Lesson_01/SimplestApp/SimplestApp.inf new file mode 100644 index 0000000..7d4bae2 --- /dev/null +++ b/Lessons/Lesson_01/SimplestApp/SimplestApp.inf @@ -0,0 +1,16 @@ +[Defines] + INF_VERSION = 1.25 + BASE_NAME = SimplestApp + FILE_GUID = 4a298956-fbe0-47fb-ae3a-2d5a0a959a26 + MODULE_TYPE = UEFI_APPLICATION + VERSION_STRING = 1.0 + ENTRY_POINT = UefiMain + +[Sources] + SimplestApp.c + +[Packages] + MdePkg/MdePkg.dec + +[LibraryClasses] + UefiApplicationEntryPoint -- cgit v1.2.3-18-g5258