diff options
9 files changed, 309 insertions, 0 deletions
diff --git a/Lessons/Lesson_36/README.md b/Lessons/Lesson_36/README.md new file mode 100644 index 0000000..f6d64ad --- /dev/null +++ b/Lessons/Lesson_36/README.md @@ -0,0 +1,157 @@ +In this lesson we will try to create the most simple library. + +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`: +``` +[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 + +[Sources] + SimpleLibrary.c + +[Packages] + MdePkg/MdePkg.dec +``` + +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>] +``` + +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 +``` + +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. +``` +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 +``` + +And include this `UefiLessonsPkg/UefiLessonsPkg.dec` file to the library module INF file section `[Packages]`: +``` +[Packages] + MdePkg/MdePkg.dec + UefiLessonsPkg/UefiLessonsPkg.dec +``` + +Now we are good, build would succeed. + +# SimpleLibraryUser + +Now let's create an application that would use our library. + +UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.c: +``` +#include <Library/UefiBootServicesTableLib.h> +#include <Library/UefiLib.h> + +#include <Library/SimpleLibrary.h> + +EFI_STATUS +EFIAPI +UefiMain ( + IN EFI_HANDLE ImageHandle, + IN EFI_SYSTEM_TABLE *SystemTable + ) +{ + Print(L"%d\n", Plus2(3)); + + return EFI_SUCCESS; +} +``` + +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 + +[Sources] + SimpleLibraryUser.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) + +[LibraryClasses] + UefiApplicationEntryPoint + UefiLib + SimpleLibrary <--- library is included as usual +``` + +Now add modifications to the `UefiLessonsPkg/UefiLessonsPkg.dsc`: +``` +[LibraryClasses] + ... + SimpleLibrary|UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf + +[Components] + ... + UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.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: +``` +FS0:\> SimpleLibraryUser.efi +5 +``` + +`3+2` is indeed `5`, so our library works correctly! + diff --git a/Lessons/Lesson_36/UefiLessonsPkg/Include/Library/SimpleLibrary.h b/Lessons/Lesson_36/UefiLessonsPkg/Include/Library/SimpleLibrary.h new file mode 100644 index 0000000..105bc87 --- /dev/null +++ b/Lessons/Lesson_36/UefiLessonsPkg/Include/Library/SimpleLibrary.h @@ -0,0 +1,2 @@ +UINTN Plus2(UINTN number); + diff --git a/Lessons/Lesson_36/UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.c b/Lessons/Lesson_36/UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.c new file mode 100644 index 0000000..acffba4 --- /dev/null +++ b/Lessons/Lesson_36/UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.c @@ -0,0 +1,5 @@ +#include <Library/SimpleLibrary.h> + +UINTN Plus2(UINTN number) { + return number+2; +} diff --git a/Lessons/Lesson_36/UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf b/Lessons/Lesson_36/UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf new file mode 100644 index 0000000..92027a4 --- /dev/null +++ b/Lessons/Lesson_36/UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf @@ -0,0 +1,15 @@ +[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 + +[Sources] + SimpleLibrary.c + +[Packages] + MdePkg/MdePkg.dec + UefiLessonsPkg/UefiLessonsPkg.dec + diff --git a/Lessons/Lesson_36/UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.c b/Lessons/Lesson_36/UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.c new file mode 100644 index 0000000..9747b97 --- /dev/null +++ b/Lessons/Lesson_36/UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.c @@ -0,0 +1,16 @@ +#include <Library/UefiBootServicesTableLib.h> +#include <Library/UefiLib.h> + +#include <Library/SimpleLibrary.h> + +EFI_STATUS +EFIAPI +UefiMain ( + IN EFI_HANDLE ImageHandle, + IN EFI_SYSTEM_TABLE *SystemTable + ) +{ + Print(L"%d\n", Plus2(3)); + + return EFI_SUCCESS; +} diff --git a/Lessons/Lesson_36/UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.inf b/Lessons/Lesson_36/UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.inf new file mode 100644 index 0000000..d7e5be8 --- /dev/null +++ b/Lessons/Lesson_36/UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.inf @@ -0,0 +1,20 @@ +[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 + +[Sources] + SimpleLibraryUser.c + +[Packages] + MdePkg/MdePkg.dec + UefiLessonsPkg/UefiLessonsPkg.dec + +[LibraryClasses] + UefiApplicationEntryPoint + UefiLib + SimpleLibrary + diff --git a/Lessons/Lesson_36/UefiLessonsPkg/UefiLessonsPkg.dec b/Lessons/Lesson_36/UefiLessonsPkg/UefiLessonsPkg.dec new file mode 100644 index 0000000..cc355aa --- /dev/null +++ b/Lessons/Lesson_36/UefiLessonsPkg/UefiLessonsPkg.dec @@ -0,0 +1,34 @@ +[Defines]
+ DEC_SPECIFICATION = 0x00010005
+ PACKAGE_NAME = UefiLessonsPkg
+ PACKAGE_GUID = 7e7edbba-ca2c-4177-a3f0-d3371358773a
+ PACKAGE_VERSION = 1.01
+
+[Includes]
+ Include
+
+[Guids]
+ # FILE_GUID as defined in UefiLessonsPkg/HelloWorld/HelloWorld.inf
+ gHelloWorldFileGuid = {0x2e55fa38, 0xf148, 0x42d3, {0xaf, 0x90, 0x1b, 0xe2, 0x47, 0x32, 0x3e, 0x30}}
+ gUefiLessonsPkgTokenSpaceGuid = {0x150cab53, 0xad47, 0x4385, {0xb5, 0xdd, 0xbc, 0xfc, 0x76, 0xba, 0xca, 0xf0}}
+
+[Protocols]
+
+[PcdsFixedAtBuild]
+ gUefiLessonsPkgTokenSpaceGuid.PcdMyVar32|42|UINT32|0x00000001
+ gUefiLessonsPkgTokenSpaceGuid.PcdMyVar32_1|42|UINT32|0x00000002
+ gUefiLessonsPkgTokenSpaceGuid.PcdMyVar32_2|42|UINT32|0x00000003
+ gUefiLessonsPkgTokenSpaceGuid.PcdMyVarBool|FALSE|BOOLEAN|0x00000004
+
+[PcdsPatchableInModule]
+ gUefiLessonsPkgTokenSpaceGuid.PcdMyPatchableVar32|0x31313131|UINT32|0x10000001
+
+[PcdsFeatureFlag]
+ gUefiLessonsPkgTokenSpaceGuid.PcdMyFeatureFlagVar|FALSE|BOOLEAN|0x20000001
+
+[PcdsDynamic]
+ gUefiLessonsPkgTokenSpaceGuid.PcdMyDynamicVar32|0x38323232|UINT32|0x30000001
+ gUefiLessonsPkgTokenSpaceGuid.PcdMyDynamicVar32_1|42|UINT32|0x30000002
+
+[PcdsDynamicEx]
+ gUefiLessonsPkgTokenSpaceGuid.PcdMyDynamicExVar32|0x38333333|UINT32|0x40000001
diff --git a/Lessons/Lesson_36/UefiLessonsPkg/UefiLessonsPkg.dsc b/Lessons/Lesson_36/UefiLessonsPkg/UefiLessonsPkg.dsc new file mode 100644 index 0000000..c42b57d --- /dev/null +++ b/Lessons/Lesson_36/UefiLessonsPkg/UefiLessonsPkg.dsc @@ -0,0 +1,59 @@ +[Defines] + DSC_SPECIFICATION = 0x0001001C + PLATFORM_GUID = 3db7270f-ffac-4139-90a4-0ae68f3f8167 + PLATFORM_VERSION = 0.01 + PLATFORM_NAME = UefiLessonsPkg + SKUID_IDENTIFIER = DEFAULT + SUPPORTED_ARCHITECTURES = X64 + BUILD_TARGETS = RELEASE + + +[LibraryClasses] + UefiApplicationEntryPoint|MdePkg/Library/UefiApplicationEntryPoint/UefiApplicationEntryPoint.inf + UefiBootServicesTableLib|MdePkg/Library/UefiBootServicesTableLib/UefiBootServicesTableLib.inf + DebugLib|MdePkg/Library/UefiDebugLibConOut/UefiDebugLibConOut.inf + BaseLib|MdePkg/Library/BaseLib/BaseLib.inf + #PcdLib|MdePkg/Library/BasePcdLibNull/BasePcdLibNull.inf + PcdLib|MdePkg/Library/DxePcdLib/DxePcdLib.inf + BaseMemoryLib|MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf + RegisterFilterLib|MdePkg/Library/RegisterFilterLibNull/RegisterFilterLibNull.inf + PrintLib|MdePkg/Library/BasePrintLib/BasePrintLib.inf + DebugPrintErrorLevelLib|MdePkg/Library/BaseDebugPrintErrorLevelLib/BaseDebugPrintErrorLevelLib.inf + UefiLib|MdePkg/Library/UefiLib/UefiLib.inf + MemoryAllocationLib|MdePkg/Library/UefiMemoryAllocationLib/UefiMemoryAllocationLib.inf + DevicePathLib|MdePkg/Library/UefiDevicePathLib/UefiDevicePathLib.inf + UefiRuntimeServicesTableLib|MdePkg/Library/UefiRuntimeServicesTableLib/UefiRuntimeServicesTableLib.inf + ShellCEntryLib|ShellPkg/Library/UefiShellCEntryLib/UefiShellCEntryLib.inf + ShellLib|ShellPkg/Library/UefiShellLib/UefiShellLib.inf + FileHandleLib|MdePkg/Library/UefiFileHandleLib/UefiFileHandleLib.inf + HiiLib|MdeModulePkg/Library/UefiHiiLib/UefiHiiLib.inf + SortLib|MdeModulePkg/Library/UefiSortLib/UefiSortLib.inf + UefiHiiServicesLib|MdeModulePkg/Library/UefiHiiServicesLib/UefiHiiServicesLib.inf + SimpleLibrary|UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf + +[Components] + UefiLessonsPkg/SimplestApp/SimplestApp.inf + UefiLessonsPkg/HelloWorld/HelloWorld.inf + UefiLessonsPkg/ImageHandle/ImageHandle.inf + UefiLessonsPkg/ImageInfo/ImageInfo.inf + UefiLessonsPkg/MemoryInfo/MemoryInfo.inf + UefiLessonsPkg/SimpleShellApp/SimpleShellApp.inf + UefiLessonsPkg/ListVariables/ListVariables.inf + UefiLessonsPkg/ShowBootVariables/ShowBootVariables.inf + UefiLessonsPkg/InteractiveApp/InteractiveApp.inf + #UefiLessonsPkg/GOPInfo/GOPInfo.inf + #UefiLessonsPkg/HiiMenu/HiiMenu.inf + #UefiLessonsPkg/TestGlyphs/TestGlyphs.inf + #UefiLessonsPkg/ShowHii/ShowHii.inf + UefiLessonsPkg/PCDLesson/PCDLesson.inf + UefiLessonsPkg/ShowTables/ShowTables.inf + UefiLessonsPkg/AcpiInfo/AcpiInfo.inf + UefiLessonsPkg/SaveBGRT/SaveBGRT.inf + UefiLessonsPkg/ListPCI/ListPCI.inf + UefiLessonsPkg/PCIRomInfo/PCIRomInfo.inf + UefiLessonsPkg/Library/SimpleLibrary/SimpleLibrary.inf + UefiLessonsPkg/SimpleLibraryUser/SimpleLibraryUser.inf + +[PcdsFixedAtBuild] + gUefiLessonsPkgTokenSpaceGuid.PcdMyVar32_2|44 + @@ -39,6 +39,7 @@ Lessons description: - Lesson 33: Use `EfiRom` utility for parsing and creation of PCI Option ROM images - Lesson 34: Create a simple UEFI driver. Use `load`/`unload` UEFI shell commands to work with a driver image - Lesson 35: Investigate ways how to add `acpiview` command functionality to your shell +- Lesson 36: Create a simple library and use it in an app ______ |