From 2b35e76599443600dae2d01261bf2650eda62488 Mon Sep 17 00:00:00 2001 From: Konstantin Aladyshev Date: Thu, 4 Aug 2022 16:43:03 +0300 Subject: Update feature PCD lesson Signed-off-by: Konstantin Aladyshev --- Lessons/Lesson_22/README.md | 127 +++++++++++++++++++++----------------------- 1 file changed, 62 insertions(+), 65 deletions(-) (limited to 'Lessons/Lesson_22') diff --git a/Lessons/Lesson_22/README.md b/Lessons/Lesson_22/README.md index 5280e72..2d23674 100644 --- a/Lessons/Lesson_22/README.md +++ b/Lessons/Lesson_22/README.md @@ -1,117 +1,114 @@ -Let's explore another PCD type - feature flag PCD. +Let's explore another PCD type - feature flag PCD. This is basically a boolean value. -Add PCD to DEC file UefiLessonsPkg/UefiLessonsPkg.dec: +Add this PCD to DEC file `UefiLessonsPkg/UefiLessonsPkg.dec`: ``` [PcdsFeatureFlag] - gUefiLessonsPkgTokenSpaceGuid.PcdMyFeatureFlagVar|FALSE|BOOLEAN|0x20000001 + gUefiLessonsPkgTokenSpaceGuid.PcdFeatureFlag|TRUE|BOOLEAN|0x16DD586E ``` -Populate it to INF UefiLessonsPkg/PCDLesson/PCDLesson.inf: +And populate it to the INF file `UefiLessonsPkg/PCDLesson/PCDLesson.inf`. In the INF file PCDs of this type goes to `[FeaturePcd]` section: ``` [FeaturePcd] - gUefiLessonsPkgTokenSpaceGuid.PcdMyFeatureFlagVar + gUefiLessonsPkgTokenSpaceGuid.PcdFeatureFlag ``` -To get PCD value in a *.c file either `FeaturePcdGet` or `PcdGetBool` can be used which are practically the same https://github.com/tianocore/edk2/blob/master/MdePkg/Include/Library/PcdLib.h: +To get the PCD value in a `*.c` file either `FeaturePcdGet` or `PcdGetBool` can be used which are practically the same [https://github.com/tianocore/edk2/blob/master/MdePkg/Include/Library/PcdLib.h](https://github.com/tianocore/edk2/blob/master/MdePkg/Include/Library/PcdLib.h): ``` #define FeaturePcdGet(TokenName) _PCD_GET_MODE_BOOL_##TokenName +... #define PcdGetBool(TokenName) _PCD_GET_MODE_BOOL_##TokenName ``` -Let's add both to our UefiLessonsPkg/PCDLesson/PCDLesson.c +Let's use both methonds in our `UefiLessonsPkg/PCDLesson/PCDLesson.c` to print the flag value: ``` -Print(L"PcdMyFeatureFlagVar=%d\n", FeaturePcdGet(PcdMyFeatureFlagVar)); -Print(L"PcdMyFeatureFlagVar=%d\n", PcdGetBool(PcdMyFeatureFlagVar)); +Print(L"PcdFeatureFlag=%d\n", FeaturePcdGet(PcdFeatureFlag)); +Print(L"PcdFeatureFlag=%d\n", PcdGetBool(PcdFeatureFlag)); ``` -Ok, we are ready to build. Build your module and check out AutoGen files. - -Build/UefiLessonsPkg/RELEASE_GCC5/X64/UefiLessonsPkg/PCDLesson/PCDLesson/DEBUG/AutoGen.h -``` -#define _PCD_TOKEN_PcdMyFeatureFlagVar 0U -#define _PCD_SIZE_PcdMyFeatureFlagVar 1 -#define _PCD_GET_MODE_SIZE_PcdMyFeatureFlagVar _PCD_SIZE_PcdMyFeatureFlagVar -#define _PCD_VALUE_PcdMyFeatureFlagVar ((BOOLEAN)0U) -extern const BOOLEAN _gPcd_FixedAtBuild_PcdMyFeatureFlagVar; -#define _PCD_GET_MODE_BOOL_PcdMyFeatureFlagVar _gPcd_FixedAtBuild_PcdMyFeatureFlagVar -//#define _PCD_SET_MODE_BOOL_PcdMyFeatureFlagVar ASSERT(FALSE) // It is not allowed to set value for a FIXED_AT_BUILD PCD -``` - -Build/UefiLessonsPkg/RELEASE_GCC5/X64/UefiLessonsPkg/PCDLesson/PCDLesson/DEBUG/AutoGen.c +Ok, we are ready to build. Build your module and check out `AutoGen.h` file `Build/UefiLessonsPkg/RELEASE_GCC5/X64/UefiLessonsPkg/PCDLesson/PCDLesson/DEBUG/AutoGen.h`: ``` -GLOBAL_REMOVE_IF_UNREFERENCED const BOOLEAN _gPcd_FixedAtBuild_PcdMyFeatureFlagVar = _PCD_VALUE_PcdMyFeatureFlagVar; +#define _PCD_TOKEN_PcdFeatureFlag 0U +#define _PCD_SIZE_PcdFeatureFlag 1 +#define _PCD_GET_MODE_SIZE_PcdFeatureFlag _PCD_SIZE_PcdFeatureFlag +#define _PCD_VALUE_PcdFeatureFlag ((BOOLEAN)1U) +extern const BOOLEAN _gPcd_FixedAtBuild_PcdFeatureFlag; +#define _PCD_GET_MODE_BOOL_PcdFeatureFlag _gPcd_FixedAtBuild_PcdFeatureFlag +//#define _PCD_SET_MODE_BOOL_PcdFeatureFlag ASSERT(FALSE) // It is not allowed to set value for a FIXED_AT_BUILD PCD ``` So both calls for our PCD would translate to: ``` -FeaturePcdGet/PcdGetBool(PcdMyFeatureFlagVar) --> _PCD_GET_MODE_BOOL_PcdMyFeatureFlagVar --> _gPcd_FixedAtBuild_PcdMyFeatureFlagVar +FeaturePcdGet/PcdGetBool(PcdFeatureFlag) --> _PCD_GET_MODE_BOOL_PcdFeatureFlag --> _gPcd_FixedAtBuild_PcdFeatureFlag ``` -And this variable is declared in AutoGen.c file: + +And this `_gPcd_FixedAtBuild_PcdFeatureFlag` variable is a constant from the `AutoGen.c` file `Build/UefiLessonsPkg/RELEASE_GCC5/X64/UefiLessonsPkg/PCDLesson/PCDLesson/DEBUG/AutoGen.c`: ``` -GLOBAL_REMOVE_IF_UNREFERENCED const BOOLEAN _gPcd_FixedAtBuild_PcdMyFeatureFlagVar = ((BOOLEAN)0U); +GLOBAL_REMOVE_IF_UNREFERENCED const BOOLEAN _gPcd_FixedAtBuild_PcdFeatureFlag; // = ((BOOLEAN)1U); ``` -If you execute it under OVMF these print statements would get you: +If you execute the application under OVMF the print statements would get you: ``` -PcdMyFeatureFlagVar=0 -PcdMyFeatureFlagVar=0 +FS0:\> PCDLesson.efi +... +PcdFeatureFlag=1 +PcdFeatureFlag=1 ``` -________________________ - -So as you can see a feature PCD is similar to a BOOLEAN PCD defined under `PcdsFixedAtBuild` section +# Comparision to `[PcdsFixedAtBuild]` BOOLEAN datum type PCD -Let's create a fixed bool PCD and compare results: +As you can see a feature PCD is similar to a BOOLEAN PCD defined under `PcdsFixedAtBuild` section. -UefiLessonsPkg/UefiLessonsPkg.dec: +Compare how they are declared in the DEC file `UefiLessonsPkg/UefiLessonsPkg.dec`: ``` [PcdsFixedAtBuild] ... - gUefiLessonsPkgTokenSpaceGuid.PcdMyVarBool|FALSE|BOOLEAN|0x00000004 + gUefiLessonsPkgTokenSpaceGuid.PcdBool|TRUE|BOOLEAN|0x69E88A63 [PcdsFeatureFlag] - gUefiLessonsPkgTokenSpaceGuid.PcdMyFeatureFlagVar|FALSE|BOOLEAN|0x20000001 + gUefiLessonsPkgTokenSpaceGuid.PcdFeatureFlag|TRUE|BOOLEAN|0x16DD586E ``` -UefiLessonsPkg/PCDLesson/PCDLesson.inf: + +And in the INF file `UefiLessonsPkg/PCDLesson/PCDLesson.inf`: ``` [FixedPcd] ... - gUefiLessonsPkgTokenSpaceGuid.PcdMyVarBool + gUefiLessonsPkgTokenSpaceGuid.PcdBool [FeaturePcd] - gUefiLessonsPkgTokenSpaceGuid.PcdMyFeatureFlagVar + gUefiLessonsPkgTokenSpaceGuid.PcdFeatureFlag ``` -UefiLessonsPkg/PCDLesson/PCDLesson.c: + +As for the `UefiLessonsPkg/PCDLesson/PCDLesson.c` in case of a FeatureFlag PCD you should use `FeaturePcdGet` instead of `FixedPcdGetBool`. But at the same time in both cases you can use `PcdGetBool` function: ``` -Print(L"PcdMyFeatureFlagVar=%d\n", FeaturePcdGet(PcdMyFeatureFlagVar)); -Print(L"PcdMyFeatureFlagVar=%d\n", PcdGetBool(PcdMyFeatureFlagVar)); -Print(L"PcdMyVarBool=%d\n", FixedPcdGetBool(PcdMyVarBool)); -Print(L"PcdMyVarBool=%d\n", PcdGetBool(PcdMyVarBool)); +Print(L"PcdFeatureFlag=%d\n", FeaturePcdGet(PcdFeatureFlag)); +Print(L"PcdFeatureFlag=%d\n", PcdGetBool(PcdFeatureFlag)); +Print(L"PcdBool=%d\n", FixedPcdGetBool(PcdBool)); +Print(L"PcdBool=%d\n", PcdGetBool(PcdBool)); ``` -Ok, now let's build and look at AutoGen files: +Ok, now let's compare the code for the PCDs in the AutoGen files: -AutoGen.c +`AutoGen.c`: ``` -GLOBAL_REMOVE_IF_UNREFERENCED const BOOLEAN _gPcd_FixedAtBuild_PcdMyVarBool = _PCD_VALUE_PcdMyVarBool; -GLOBAL_REMOVE_IF_UNREFERENCED const BOOLEAN _gPcd_FixedAtBuild_PcdMyFeatureFlagVar = _PCD_VALUE_PcdMyFeatureFlagVar; +GLOBAL_REMOVE_IF_UNREFERENCED const BOOLEAN _gPcd_FixedAtBuild_PcdBool = _PCD_VALUE_PcdBool; +GLOBAL_REMOVE_IF_UNREFERENCED const BOOLEAN _gPcd_FixedAtBuild_PcdFeatureFlag = _PCD_VALUE_PcdFeatureFlag; ``` -AutoGen.h +`AutoGen.h`: ``` -#define _PCD_TOKEN_PcdMyVarBool 0U -#define _PCD_SIZE_PcdMyVarBool 1 -#define _PCD_GET_MODE_SIZE_PcdMyVarBool _PCD_SIZE_PcdMyVarBool -#define _PCD_VALUE_PcdMyVarBool 0U -extern const BOOLEAN _gPcd_FixedAtBuild_PcdMyVarBool; -#define _PCD_GET_MODE_BOOL_PcdMyVarBool _gPcd_FixedAtBuild_PcdMyVarBool -//#define _PCD_SET_MODE_BOOL_PcdMyVarBool ASSERT(FALSE) // It is not allowed to set value for a FIXED_AT_BUILD PCD +#define _PCD_TOKEN_PcdBool 0U +#define _PCD_SIZE_PcdBool 1 +#define _PCD_GET_MODE_SIZE_PcdBool _PCD_SIZE_PcdBool +#define _PCD_VALUE_PcdBool 1U +extern const BOOLEAN _gPcd_FixedAtBuild_PcdBool; +#define _PCD_GET_MODE_BOOL_PcdBool _gPcd_FixedAtBuild_PcdBool +//#define _PCD_SET_MODE_BOOL_PcdBool ASSERT(FALSE) // It is not allowed to set value for a FIXED_AT_BUILD PCD -#define _PCD_TOKEN_PcdMyFeatureFlagVar 0U -#define _PCD_SIZE_PcdMyFeatureFlagVar 1 -#define _PCD_GET_MODE_SIZE_PcdMyFeatureFlagVar _PCD_SIZE_PcdMyFeatureFlagVar -#define _PCD_VALUE_PcdMyFeatureFlagVar ((BOOLEAN)0U) -extern const BOOLEAN _gPcd_FixedAtBuild_PcdMyFeatureFlagVar; -#define _PCD_GET_MODE_BOOL_PcdMyFeatureFlagVar _gPcd_FixedAtBuild_PcdMyFeatureFlagVar -//#define _PCD_SET_MODE_BOOL_PcdMyFeatureFlagVar ASSERT(FALSE) // It is not allowed to set value for a FIXED_AT_BUILD PCD +#define _PCD_TOKEN_PcdFeatureFlag 0U +#define _PCD_SIZE_PcdFeatureFlag 1 +#define _PCD_GET_MODE_SIZE_PcdFeatureFlag _PCD_SIZE_PcdFeatureFlag +#define _PCD_VALUE_PcdFeatureFlag ((BOOLEAN)1U) +extern const BOOLEAN _gPcd_FixedAtBuild_PcdFeatureFlag; +#define _PCD_GET_MODE_BOOL_PcdFeatureFlag _gPcd_FixedAtBuild_PcdFeatureFlag +//#define _PCD_SET_MODE_BOOL_PcdFeatureFlag ASSERT(FALSE) // It is not allowed to set value for a FIXED_AT_BUILD PCD ``` -As you see the differences are subtle. `FeaturePcd` is simply a syntactic sugar for BOOLEAN `FixedAtBuild` PCD. +So as you see the differences are subtle. Therefore the `FeaturePcd` is simply a syntactic sugar for BOOLEAN `FixedAtBuild` PCD. -- cgit v1.2.3-18-g5258