What is a "NULL" library class?

What is a "NULL" library class?

[wonderfly]

[-- Attachment #1: Type: text/plain, Size: 546 bytes --]

Hi,

I am super new to EDK2 development so excuse my ignorance.  While browsing the code base I find a lot places where the keyword "NULL" is used in place of a LibraryClass, specifically in DSC files.  For example,

in edk2/UefiPayloadPkg/UefiPayloadPkgIa32.dsc:
MdeModulePkg/Core/Dxe/DxeMain.inf {
<LibraryClasses>
NULL|MdeModulePkg/Library/LzmaCustomDecompressLib/LzmaCustomDecompressLib.inf
}

What does this mean?  Does it mean that the LzmaCustomDecompressLib.inf library instance is unconditionally linked for this package?

[-- Attachment #2: Type: text/html, Size: 949 bytes --]

Re: [edk2-devel] What is a "NULL" library class?

[Nate DeSimone]

Hi There,

First of all, welcome!

So, “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. All libraries, both regular libraries with a declared LibraryClass as well as these anonymous libraries, can publish both a constructor and a destructor. The EDK II build system will automatically generate a small amount of C code that invokes all library constructors before the entry point for the module is invoked, and all destructors after the entry point returns. This is useful for building statically linked plug-ins.

I think my favorite example of this in-action is the UEFI Shell, here is what a typical DSC declaration for the UEFI Shell looks like:

ShellPkg/Application/Shell/Shell.inf {
  <PcdsFixedAtBuild>
    gEfiShellPkgTokenSpaceGuid.PcdShellLibAutoInitialize|FALSE
  <LibraryClasses>
    NULL|ShellPkg/Library/UefiShellLevel1CommandsLib/UefiShellLevel1CommandsLib.inf
    NULL|ShellPkg/Library/UefiShellLevel2CommandsLib/UefiShellLevel2CommandsLib.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
    ShellCommandLib|ShellPkg/Library/UefiShellCommandLib/UefiShellCommandLib.inf
    HandleParsingLib|ShellPkg/Library/UefiHandleParsingLib/UefiHandleParsingLib.inf
    BcfgCommandLib|ShellPkg/Library/UefiShellBcfgCommandLib/UefiShellBcfgCommandLib.inf
    ShellCEntryLib|ShellPkg/Library/UefiShellCEntryLib/UefiShellCEntryLib.inf
    ShellLib|ShellPkg/Library/UefiShellLib/UefiShellLib.inf
}

If you take a look at ShellPkg/Library/UefiShellLevel1CommandsLib/UefiShellLevel1CommandsLib.inf, you will see that the constructor for that anonymous library is named ShellLevel1CommandsLibConstructor(). Now, let's go and look at the definition for ShellLevel1CommandsLibConstructor() in ShellPkg/Library/UefiShellLevel1CommandsLib/UefiShellLevel1CommandsLib.c and note the following code snippet:

ShellCommandRegisterCommandName(L"stall",  ShellCommandRunStall   ...
ShellCommandRegisterCommandName(L"for",    ShellCommandRunFor     ...
ShellCommandRegisterCommandName(L"goto",   ShellCommandRunGoto    ...
ShellCommandRegisterCommandName(L"if",     ShellCommandRunIf      ...
ShellCommandRegisterCommandName(L"shift",  ShellCommandRunShift   ...
ShellCommandRegisterCommandName(L"exit",   ShellCommandRunExit    ...
ShellCommandRegisterCommandName(L"else",   ShellCommandRunElse    ...
ShellCommandRegisterCommandName(L"endif",  ShellCommandRunEndIf   ...
ShellCommandRegisterCommandName(L"endfor", ShellCommandRunEndFor  ...

This library is installing new commands into the UEFI shell during its initialization procedure. This allows one to add custom commands to the shell as statically linked built-ins. A typical use case would be implementing platform specific diagnostic/recovery utilities.

Hope that helps!
Nate

> From: devel@edk2.groups.io <devel@edk2.groups.io> On Behalf Of wonderfly@waymo.com
> Sent: Thursday, January 28, 2021 10:22 AM
> To: devel@edk2.groups.io
> Subject: [edk2-devel] What is a "NULL" library class?
> 
> Hi,
> 
> I am super new to EDK2 development so excuse my ignorance.  While browsing the code base I find a lot places where the keyword "NULL" is used in place of a LibraryClass, specifically in DSC files.  For example,
> in edk2/UefiPayloadPkg/UefiPayloadPkgIa32.dsc:                                                                       
>   MdeModulePkg/Core/Dxe/DxeMain.inf {
>     <LibraryClasses>
>       NULL|MdeModulePkg/Library/LzmaCustomDecompressLib/LzmaCustomDecompressLib.inf
>   }
> 
> What does this mean?  Does it mean that the LzmaCustomDecompressLib.inf library instance is unconditionally linked for this package?
> 

Re: [edk2-devel] What is a "NULL" library class?

[Daniel Wang]

[-- Attachment #1: Type: text/plain, Size: 4533 bytes --]

Thanks for the detailed explanation.  Makes sense now.

On Thu, Jan 28, 2021 at 5:43 PM Nate DeSimone <
nathaniel.l.desimone@intel.com> wrote:

> Hi There,
>
> First of all, welcome!
>
> So, “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. All libraries, both
> regular libraries with a declared LibraryClass as well as these anonymous
> libraries, can publish both a constructor and a destructor. The EDK II
> build system will automatically generate a small amount of C code that
> invokes all library constructors before the entry point for the module is
> invoked, and all destructors after the entry point returns. This is useful
> for building statically linked plug-ins.
>
> I think my favorite example of this in-action is the UEFI Shell, here is
> what a typical DSC declaration for the UEFI Shell looks like:
>
> ShellPkg/Application/Shell/Shell.inf {
>   <PcdsFixedAtBuild>
>     gEfiShellPkgTokenSpaceGuid.PcdShellLibAutoInitialize|FALSE
>   <LibraryClasses>
>
> NULL|ShellPkg/Library/UefiShellLevel1CommandsLib/UefiShellLevel1CommandsLib.inf
>
> NULL|ShellPkg/Library/UefiShellLevel2CommandsLib/UefiShellLevel2CommandsLib.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
>
> ShellCommandLib|ShellPkg/Library/UefiShellCommandLib/UefiShellCommandLib.inf
>
> HandleParsingLib|ShellPkg/Library/UefiHandleParsingLib/UefiHandleParsingLib.inf
>
> BcfgCommandLib|ShellPkg/Library/UefiShellBcfgCommandLib/UefiShellBcfgCommandLib.inf
>
> ShellCEntryLib|ShellPkg/Library/UefiShellCEntryLib/UefiShellCEntryLib.inf
>     ShellLib|ShellPkg/Library/UefiShellLib/UefiShellLib.inf
> }
>
> If you take a look at
> ShellPkg/Library/UefiShellLevel1CommandsLib/UefiShellLevel1CommandsLib.inf,
> you will see that the constructor for that anonymous library is named
> ShellLevel1CommandsLibConstructor(). Now, let's go and look at the
> definition for ShellLevel1CommandsLibConstructor() in
> ShellPkg/Library/UefiShellLevel1CommandsLib/UefiShellLevel1CommandsLib.c
> and note the following code snippet:
>
> ShellCommandRegisterCommandName(L"stall",  ShellCommandRunStall   ...
> ShellCommandRegisterCommandName(L"for",    ShellCommandRunFor     ...
> ShellCommandRegisterCommandName(L"goto",   ShellCommandRunGoto    ...
> ShellCommandRegisterCommandName(L"if",     ShellCommandRunIf      ...
> ShellCommandRegisterCommandName(L"shift",  ShellCommandRunShift   ...
> ShellCommandRegisterCommandName(L"exit",   ShellCommandRunExit    ...
> ShellCommandRegisterCommandName(L"else",   ShellCommandRunElse    ...
> ShellCommandRegisterCommandName(L"endif",  ShellCommandRunEndIf   ...
> ShellCommandRegisterCommandName(L"endfor", ShellCommandRunEndFor  ...
>
> This library is installing new commands into the UEFI shell during its
> initialization procedure. This allows one to add custom commands to the
> shell as statically linked built-ins. A typical use case would be
> implementing platform specific diagnostic/recovery utilities.
>
> Hope that helps!
> Nate
>
> > From: devel@edk2.groups.io <devel@edk2.groups.io> On Behalf Of
> wonderfly@waymo.com
> > Sent: Thursday, January 28, 2021 10:22 AM
> > To: devel@edk2.groups.io
> > Subject: [edk2-devel] What is a "NULL" library class?
> >
> > Hi,
> >
> > I am super new to EDK2 development so excuse my ignorance.  While
> browsing the code base I find a lot places where the keyword "NULL" is used
> in place of a LibraryClass, specifically in DSC files.  For example,
> > in edk2/UefiPayloadPkg/UefiPayloadPkgIa32.dsc:
>
> >   MdeModulePkg/Core/Dxe/DxeMain.inf {
> >     <LibraryClasses>
> >
>  NULL|MdeModulePkg/Library/LzmaCustomDecompressLib/LzmaCustomDecompressLib.inf
> >   }
> >
> > What does this mean?  Does it mean that the LzmaCustomDecompressLib.inf
> library instance is unconditionally linked for this package?
> >
>
>
> 
>
>
>

-- 
Best,
Daniel

[-- Attachment #2: Type: text/html, Size: 5694 bytes --]