This article describes how the EDK2 build reporting system works.  I think it's a little known topic; most people just run a build and see some status output at the end.  However, the reporting can be customized in powerful ways, mainly as described in §13 of the EDK2 Build Specification.  Let's dive in.

First, we need to define terminology.  EDK2 distinguishes between a build log and build report:

  • Build Log (-j LOGFILE, --log=LOGFILE):  this is exactly what you see on the console during the build, mainly the compiler and linker output.  There is a brief build summary at the end.
  • Build Report (-y REPORTFILE, --report-file=REPORTFILE):  the build report contains higher-level data regarding the content of what you've built, not the status of compiling/linking.

The build log is straightforward, so this article will focus on the build report.  By default, unless the quiet or silent options are used (--quiet/--silent), the build system will automatically generate the following output at the end of the build:

  • Each region, offset and size defined in the FD
  • The location of the GUID cross reference file
  • The size of the data in each FV region
  • The date and time the build completed

For example, if I get the latest EDK2 source (edk2-stable202408 at time of writing), and build the default target, EmulatorPkg, I get reporting on the console that looks like:

Fd File Name:FV_RECOVERY (<path>\edk2\Build\EmulatorX64\DEBUG_VS2015x86\FV\FV_RECOVERY.fd)

Generate Region at Offset 0x0
   Region Size = 0x580000
   Region Name = FV

Generating FVRECOVERY FV
#####
Generate Region at Offset 0x580000
   Region Size = 0xC000
   Region Name = DATA

Generate Region at Offset 0x58C000
   Region Size = 0x2000
   Region Name = None

Generate Region at Offset 0x58E000
   Region Size = 0x2000
   Region Name = DATA

Generate Region at Offset 0x590000
   Region Size = 0x10000
   Region Name = None

GUID cross reference file can be found at <path>\edk2\Build\EmulatorX64\DEBUG_VS2015x86\FV\Guid.xref

FV Space Information
FVRECOVERY [49%Full] 5767168 (0x580000) total, 2847968 (0x2b74e0) used, 2919200 (0x2c8b20) free

- Done -
Build end time: 16:56:24, Oct.01 2024

Build total time: 00:02:05

Extending the Default Build Reporting

This default build reporting can be extended in two ways, with the -y switch and -Y switch:

  • -y REPORTFILE, --report-file=REPORTFILE — Asks for creation of a specific build report file with the default set of build report flags:  PCD, LIBRARY, FLASH, DEPEX, HASH, BUILD_FLAGS and FIXED_ADDRESS

  • -Y REPORTTYPE, --report-type=REPORTTYPE — Used to customize the set of default build report flags (above).  This can be used to create a smaller build report focusing on just one or more of the default flags, and/or add the special EXECUTION_ORDER flag.

The build report flags are fairly self-explanatory:  PCD, LIBRARY, FLASH, DEPEX, HASH, BUILD_FLAGS and FIXED_ADDRESS.  Each flag adds to the build report data regarding PCDs, libraries, flash map outline, dependency expressions, etc., respectively.  §13 of the EDK2 Build Specification does a good job providing more information, so please look there for help, or even better, generate some reports of your own and take a look at them.

Problems with EXECUTION_ORDER

A special note on the EXECUTION_ORDER build report flag that isn't part of the default build report.  First, it fails to build on the edk2-stable202408 tag:

<path>\edk2\BaseTools\Source\Python\Eot\EotGlobalData.py:14: SyntaxWarning: invalid escape sequence '\S'                                                                                                                           
  gSHELL_INF = 'Application\Shell'                                                                                          
<path>\edk2\BaseTools\Source\Python\Eot\c.py:57: SyntaxWarning: invalid escape sequence '\w'            
  p = re.compile('[_\w\s]*\([\w\s]*\*+\s*[_\w]+\s*\)\s*\(.*\)', re.DOTALL)                                                  
(Python 3.12.6 on win32                                                                                                     
Traceback (most recent call last):                                                                                          
  File <path>\edk2\BaseTools\Source\Python\build\BuildReport.py", line 1690, in _InvokeEotTool         
    from Eot.EotMain import Eot                                                                                             
  File "<path>\edk2\BaseTools\Source\Python\Eot\EotMain.py", line 23, in <module>                       
    from Eot import c                                                                                                       
  File "<path>\edk2\BaseTools\Source\Python\Eot\c.py", line 17, in <module>                             
    from . import CodeFragmentCollector                                                                                     
  File "<path>\edk2\BaseTools\Source\Python\Eot\CodeFragmentCollector.py", line 19, in <module>         
    import antlr4 as antlr                                                                                                  
ModuleNotFoundError: No module named 'antlr4'                                                                               
)                                                                                    

...                                                                                                                 
BuildReport.py: : warning: Failed to generate execution order prediction report, for some error occurred in executing EOT. 
    import antlr4 as antlr                                                                                                  
ModuleNotFoundError: No module named 'antlr4'

So, it appears maybe there is a dependency on antlr?  I didn't find that documented, and I did rebuild all the EDK2 tools, so it looks like this is a bug, either in code or in documentation.

Also, the EDK2 Build Specification says you can use the -Y EXECUTION_ORDER switch by itself and the build system will generate an HTML report in the working directory.  That doesn't work at all.

Conclusion

Corner-case issues with the EXECUTION_ORDER flag aside, the EDK2 system of build logs and build reports is helpful.  I encourage you to experiment with it, and refer to §13 of the specification for more information!


Post a Comment

Be sure to select an account profile (e.g. Google, OpenID, etc.) before typing your comment!