EDK2之debug

DEBUG机制


简述

在UEFI开发中,非常重要的一个部分就是添加串口调试信息打印,这个通过DEBUG宏来完成。

在UEFI的代码中可以看到非常多的DEBUG代码,比如:

DEBUG ((EFI_D_INFO, "PlatformBootManagerBeforeConsole\n"));

需要注意的有几点:

  1. 括号是双重的,下面以第一个参数,第二个参数来分别称呼EFI_D_xx和字符串,但实际上稍微有点问题;

  2. 第二个参数是一个字符串,这个字符串里面也可以带格式化标志,下面是DEBUG常用的标志:

  • %a:表示ASCII字符串;
  • %c:表示ASCII字符;
  • %d:表示十进制,可以有%02d这样的用法;
  • %g:表示GUID;
  • %p:表示指针;
  • %r:表示函数的返回状态字符串,类型是EFI_STATUS;
  • %x:表示十六进制,可以有%016lx这样的用法,这样不足的前置位由0补充;
  • %lx:表示64位的十六进制;
  • %ld:表示64位的十进制;
  • %s/%S:表示宽字符串,就是类似L""的字符串,类型是CHAR16;
  1. 第一个参数表示打印级别,下面是说有的打印级别:

    //
    // Declare bits for PcdDebugPrintErrorLevel and the ErrorLevel parameter of DebugPrint()
    //
    #define DEBUG_INIT      0x00000001  // Initialization
    #define DEBUG_WARN      0x00000002  // Warnings
    #define DEBUG_LOAD      0x00000004  // Load events
    #define DEBUG_FS        0x00000008  // EFI File system
    #define DEBUG_POOL      0x00000010  // Alloc & Free (pool)
    #define DEBUG_PAGE      0x00000020  // Alloc & Free (page)
    #define DEBUG_INFO      0x00000040  // Informational debug messages
    #define DEBUG_DISPATCH  0x00000080  // PEI/DXE/SMM Dispatchers
    #define DEBUG_VARIABLE  0x00000100  // Variable
    #define DEBUG_BM        0x00000400  // Boot Manager
    #define DEBUG_BLKIO     0x00001000  // BlkIo Driver
    #define DEBUG_NET       0x00004000  // SNP Driver
    #define DEBUG_UNDI      0x00010000  // UNDI Driver
    #define DEBUG_LOADFILE  0x00020000  // LoadFile
    #define DEBUG_EVENT     0x00080000  // Event messages
    #define DEBUG_GCD       0x00100000  // Global Coherency Database changes
    #define DEBUG_CACHE     0x00200000  // Memory range cachability changes
    #define DEBUG_VERBOSE   0x00400000  // Detailed debug messages that may
                                        // significantly impact boot performance
    #define DEBUG_ERROR     0x80000000  // Error
     
    //
    // Aliases of debug message mask bits
    //
    #define EFI_D_INIT      DEBUG_INIT
    #define EFI_D_WARN      DEBUG_WARN
    #define EFI_D_LOAD      DEBUG_LOAD
    #define EFI_D_FS        DEBUG_FS
    #define EFI_D_POOL      DEBUG_POOL
    #define EFI_D_PAGE      DEBUG_PAGE
    #define EFI_D_INFO      DEBUG_INFO
    #define EFI_D_DISPATCH  DEBUG_DISPATCH
    #define EFI_D_VARIABLE  DEBUG_VARIABLE
    #define EFI_D_BM        DEBUG_BM
    #define EFI_D_BLKIO     DEBUG_BLKIO
    #define EFI_D_NET       DEBUG_NET
    #define EFI_D_UNDI      DEBUG_UNDI
    #define EFI_D_LOADFILE  DEBUG_LOADFILE
    #define EFI_D_EVENT     DEBUG_EVENT
    #define EFI_D_VERBOSE   DEBUG_VERBOSE
    #define EFI_D_ERROR     DEBUG_ERROR
    

    关于上面的宏定义:

    • 首先这里宏定义了两层,这是因为EDK和EDKII的兼容关系,一般还是用EFI开头的版本比较好;
    • 有一个比较特别的是EFI_D_ERROR,它是最高位为1,表示的错误;
    • 哪些级别会被打印出来取决于全局PCD变量的配置,这个在后面会讲到
    • DEBUG中打印字符的长度是有限制的,最多200个字符(可能不同的实现会不一样)。

DEBUG宏实现

  1. DEBUG宏的位置是在MdePkg\Include\Library\DebugLib.h文件中:

    /**  
      Macro that calls DebugPrint().
      If MDEPKG_NDEBUG is not defined and the DEBUG_PROPERTY_DEBUG_PRINT_ENABLED 
      bit of PcdDebugProperyMask is set, then this macro passes Expression to 
      DebugPrint().
      @param  Expression  Expression containing an error level, a format string, 
                          and a variable argument list based on the format string.
      
    **/
    #if !defined(MDEPKG_NDEBUG)      
      #define DEBUG(Expression)        \
        do {                           \
          if (DebugPrintEnabled ()) {  \
            _DEBUG (Expression);       \
          }                            \
        } while (FALSE)
    #else
      #define DEBUG(Expression)
    #endif
    

    需要注意这里的MDEPKG_NDEBUG宏,如果开启了这个宏,表示所有的DEBUG信息都不会有打印了,因为走了#else分支。

    而MDEPKG_NDEBUG这个宏一般定义在dsc文件中,这里以OvmfPkgX64.dsc为例:

    [BuildOptions]
      GCC:*_UNIXGCC_*_CC_FLAGS             = -DMDEPKG_NDEBUG
      GCC:RELEASE_*_*_CC_FLAGS             = -DMDEPKG_NDEBUG
      INTEL:RELEASE_*_*_CC_FLAGS           = /D MDEPKG_NDEBUG
      MSFT:RELEASE_*_*_CC_FLAGS            = /D MDEPKG_NDEBUG
    

    可以看到在Release版本中通常会定义它来确定调试的打印。

  2. 除了MDEPKG_NDEBUG这个宏,这里还有一个判断条件:DebugPrintEnabled ()

    这个函数定义在DebugLib中,不同的Pkg可能会有不同的实现,还是以OvmfPkgX64.dsc为例:

    !ifdef $(DEBUG_ON_SERIAL_PORT)
      DebugLib|MdePkg/Library/BaseDebugLibSerialPort/BaseDebugLibSerialPort.inf
    !else
      DebugLib|OvmfPkg/Library/PlatformDebugLibIoPort/PlatformDebugLibIoPort.inf
    !endif
    

    这里我们看下BaseDebugLibSerialPort.inf中的实现:

    BOOLEAN
    EFIAPI
    DebugPrintEnabled (
      VOID
      )
    {
      return (BOOLEAN) ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_DEBUG_PRINT_ENABLED) != 0);
    }
    

    从中可以看到它是去判断PcdDebugPropertyMask这个PCD变量的值,而它定义在OvmfPkgX64.dsc中:

    !ifdef $(SOURCE_DEBUG_ENABLE)
      gEfiMdePkgTokenSpaceGuid.PcdDebugPropertyMask|0x17
    !else
      gEfiMdePkgTokenSpaceGuid.PcdDebugPropertyMask|0x2F
    !endif
    

    另外一个宏DEBUG_PROPERTY_DEBUG_PRINT_ENABLED定义如下:

    //
    // Declare bits for PcdDebugPropertyMask
    //
    #define DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED       0x01
    #define DEBUG_PROPERTY_DEBUG_PRINT_ENABLED        0x02
    #define DEBUG_PROPERTY_DEBUG_CODE_ENABLED         0x04
    #define DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED       0x08
    #define DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED  0x10
    #define DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED    0x20
    

    所以可以确定对于OvmfPkgX64.dsc,函数DebugPrintEnabled ()返回的是TRUE。

  3. 之后需要关注的是_DEBUG宏:

    /**
      Internal worker macro that calls DebugPrint().
      This macro calls DebugPrint() passing in the debug error level, a format
      string, and a variable argument list.
      __VA_ARGS__ is not supported by EBC compiler, Microsoft Visual Studio .NET 2003
      and Microsoft Windows Server 2003 Driver Development Kit (Microsoft WINDDK) version 3790.1830.
      @param  Expression  Expression containing an error level, a format string,
                          and a variable argument list based on the format string.
    **/
     
    #if !defined(MDE_CPU_EBC) && (!defined (_MSC_VER) || _MSC_VER > 1400)
      #define _DEBUG_PRINT(PrintLevel, ...)              \
        do {                                             \
          if (DebugPrintLevelEnabled (PrintLevel)) {     \
            DebugPrint (PrintLevel, ##__VA_ARGS__);      \
          }                                              \
        } while (FALSE)
      #define _DEBUG(Expression)   _DEBUG_PRINT Expression
    #else
    #define _DEBUG(Expression)   DebugPrint Expression
    #endif
    

    这里又涉及到几个判断条件。

    • 首先是编译器的支持情况,这个在注释中已经说明。

    • 另外一个是DebugPrintLevelEnabled()函数,它有一个参数PrintLevel,它就是DEBUG函数的第一个参数。

      这个函数也定义在DebugLib库中,我们同样使用BaseDebugLibSerialPort.inf中的实现:

      /**
        Returns TRUE if any one of the bit is set both in ErrorLevel and PcdFixedDebugPrintErrorLevel.
        This function compares the bit mask of ErrorLevel and PcdFixedDebugPrintErrorLevel.
        @retval  TRUE    Current ErrorLevel is supported.
        @retval  FALSE   Current ErrorLevel is not supported.
      **/
      BOOLEAN
      EFIAPI
      DebugPrintLevelEnabled (
        IN  CONST UINTN        ErrorLevel
        )
      {
        return (BOOLEAN) ((ErrorLevel & PcdGet32(PcdFixedDebugPrintErrorLevel)) != 0);
      }
      

      这里也涉及到一个PCD变量,它同样定义在MdePkg.dec文件中:

        ## This flag is used to control build time optimization based on debug print level.
        #  Its default value is 0xFFFFFFFF to expose all debug print level.
        #  BIT0  - Initialization message.<BR>
        #  BIT1  - Warning message.<BR>
        #  BIT2  - Load Event message.<BR>
        #  BIT3  - File System message.<BR>
        #  BIT4  - Allocate or Free Pool message.<BR>
        #  BIT5  - Allocate or Free Page message.<BR>
        #  BIT6  - Information message.<BR>
        #  BIT7  - Dispatcher message.<BR>
        #  BIT8  - Variable message.<BR>
        #  BIT10 - Boot Manager message.<BR>
        #  BIT12 - BlockIo Driver message.<BR>
        #  BIT14 - Network Driver message.<BR>
        #  BIT16 - UNDI Driver message.<BR>
        #  BIT17 - LoadFile message.<BR>
        #  BIT19 - Event message.<BR>
        #  BIT20 - Global Coherency Database changes message.<BR>
        #  BIT21 - Memory range cachability changes message.<BR>
        #  BIT22 - Detailed debug message.<BR>
        #  BIT31 - Error message.<BR>
        # @Prompt Fixed Debug Message Print Level.
        gEfiMdePkgTokenSpaceGuid.PcdFixedDebugPrintErrorLevel|0xFFFFFFFF|UINT32|0x30001016
      

      它的值是全FF,所以这个函数必定返回TRUE,也因为这个DEBUG宏的第一个参数在这里并没有派上用处。

DebugPrint()的实现

之后就涉及到了真正的函数DebugPrint(),它也定义在DebugLib中,还是以BaseDebugLibSerialPort.inf为例:

VOID
 EFIAPI
 DebugPrint (
   IN  UINTN        ErrorLevel,
   IN  CONST CHAR8  *Format,
   ...
   )
 {
   CHAR8    Buffer[MAX_DEBUG_MESSAGE_LENGTH];
   VA_LIST  Marker;
  
   //
   // If Format is NULL, then ASSERT().
   //
   ASSERT (Format != NULL);
  
   //
   // Check driver debug mask value and global mask
   //
   if ((ErrorLevel & GetDebugPrintErrorLevel ()) == 0) {
     return;
   }
  
   //
   // Convert the DEBUG() message to an ASCII String
   //
   VA_START (Marker, Format);
   AsciiVSPrint (Buffer, sizeof (Buffer), Format, Marker);
   VA_END (Marker);
  
   //
   // Send the print string to a Serial Port 
   //
   SerialPortWrite ((UINT8 *)Buffer, AsciiStrLen (Buffer));
 }

函数也比较简单,有几点说明:

  • Buffer是一个有大小的数组,这说明DEBUG能够打印的信息是有大小限制的;
  • GetDebugPrintErrorLevel()函数获取PCD变量,并与DEBUG的第一个参数进行比较,来确定是否需要输出打印;

这里使用的PCD变量是PcdDebugPrintErrorLevel,它的值在dsc文件中定义:

  # DEBUG_INIT      0x00000001  // Initialization
  # DEBUG_WARN      0x00000002  // Warnings
  # DEBUG_LOAD      0x00000004  // Load events
  # DEBUG_FS        0x00000008  // EFI File system
  # DEBUG_POOL      0x00000010  // Alloc & Free (pool)
  # DEBUG_PAGE      0x00000020  // Alloc & Free (page)
  # DEBUG_INFO      0x00000040  // Informational debug messages
  # DEBUG_DISPATCH  0x00000080  // PEI/DXE/SMM Dispatchers
  # DEBUG_VARIABLE  0x00000100  // Variable
  # DEBUG_BM        0x00000400  // Boot Manager
  # DEBUG_BLKIO     0x00001000  // BlkIo Driver
  # DEBUG_NET       0x00004000  // SNP Driver
  # DEBUG_UNDI      0x00010000  // UNDI Driver
  # DEBUG_LOADFILE  0x00020000  // LoadFile
  # DEBUG_EVENT     0x00080000  // Event messages
  # DEBUG_GCD       0x00100000  // Global Coherency Database changes
  # DEBUG_CACHE     0x00200000  // Memory range cachability changes
  # DEBUG_VERBOSE   0x00400000  // Detailed debug messages that may
  #                             // significantly impact boot performance
  # DEBUG_ERROR     0x80000000  // Error
  # jw_debug, change 0x8000004F to 0x80000040
  gEfiMdePkgTokenSpaceGuid.PcdDebugPrintErrorLevel|0x80000040

之后是SerialPortWrite()函数,它是具体输出到某个介质的实现了。

ReportStatusCodeEx

除了BaseDebugLibSerialPort.inf这一种实现方式外(OVMF使用了这种方式),还有一个更加普遍的实现:PeiDxeDebugLibReportStatusCode.inf,它的实现方式是:

  //
  // Send the DebugInfo record
  //
  REPORT_STATUS_CODE_EX (
    EFI_DEBUG_CODE,
    (EFI_SOFTWARE_DXE_BS_DRIVER | EFI_DC_UNSPECIFIED),
    0,
    NULL,
    &gEfiStatusCodeDataTypeDebugGuid,
    DebugInfo,
    TotalSize
    );

这里又使用了一个宏REPORT_STATUS_CODE_EX,它的实现如下:

#define REPORT_STATUS_CODE_EX(Type,Value,Instance,CallerId,ExtendedDataGuid,ExtendedData,ExtendedDataSize)  \
  (ReportProgressCodeEnabled() && ((Type) & EFI_STATUS_CODE_TYPE_MASK) == EFI_PROGRESS_CODE)             ?  \
  ReportStatusCodeEx(Type,Value,Instance,CallerId,ExtendedDataGuid,ExtendedData,ExtendedDataSize)        :  \
  (ReportErrorCodeEnabled() && ((Type) & EFI_STATUS_CODE_TYPE_MASK) == EFI_ERROR_CODE)                   ?  \
  ReportStatusCodeEx(Type,Value,Instance,CallerId,ExtendedDataGuid,ExtendedData,ExtendedDataSize)        :  \
  (ReportDebugCodeEnabled() && ((Type) & EFI_STATUS_CODE_TYPE_MASK) == EFI_DEBUG_CODE)                   ?  \
  ReportStatusCodeEx(Type,Value,Instance,CallerId,ExtendedDataGuid,ExtendedData,ExtendedDataSize)        :  \
  EFI_UNSUPPORTED

这里会根据xxxEnabled()和一个type参数来确定是否执行函数ReportStatusCodeEx()。

其中Enabled是根据dsc文件中的PCD变量来的,以ReportDebugCodeEnabled()为例:

/**
  Returns TRUE if status codes of type EFI_DEBUG_CODE are enabled
  This function returns TRUE if the REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED
  bit of PcdReportStatusCodeProperyMask is set.  Otherwise FALSE is returned.
  @retval  TRUE   The REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED bit of
                  PcdReportStatusCodeProperyMask is set.
  @retval  FALSE  The REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED bit of
                  PcdReportStatusCodeProperyMask is clear.
**/
BOOLEAN
EFIAPI
ReportDebugCodeEnabled (
  VOID
  )
{
  return (BOOLEAN) ((PcdGet8 (PcdReportStatusCodePropertyMask) & REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED) != 0);
}

PCD变量指的是PcdReportStatusCodePropertyMask,它的值可以是

//
// Declare bits for PcdReportStatusCodePropertyMask
//
#define REPORT_STATUS_CODE_PROPERTY_PROGRESS_CODE_ENABLED          0x00000001
#define REPORT_STATUS_CODE_PROPERTY_ERROR_CODE_ENABLED             0x00000002
#define REPORT_STATUS_CODE_PROPERTY_DEBUG_CODE_ENABLED             0x00000004

这里的3个值刚好和REPORT_STATUS_CODE_EX宏里面的一一对应。

关于REPORT_STATUS_CODE_EX的第一个参数type也对应的有3种:

///
/// Definition of code types. All other values masked by
/// EFI_STATUS_CODE_TYPE_MASK are reserved for use by
/// this specification.
///
///@{
#define EFI_PROGRESS_CODE             0x00000001
#define EFI_ERROR_CODE                0x00000002
#define EFI_DEBUG_CODE                0x00000003
///@}

对于我们的DEBUG宏来说,使用的是EFI_DEBUG_CODE这种类型。

事实上REPORT_STATUS_CODE_EX宏可以单独的拿出来用,并使用不同的type类型,比如说BdsEntry.c中就有:

      REPORT_STATUS_CODE_EX (
        EFI_ERROR_CODE,
        PcdGet32 (PcdErrorCodeSetVariable),
        0,
        NULL,
        &gEdkiiStatusCodeDataTypeVariableGuid,
        SetVariableStatus,
        sizeof (EDKII_SET_VARIABLE_STATUS) + NameSize + DataSize
        );

ReportStatusCodeEx()函数具体实现

之后就涉及到函数ReportStatusCodeEx()了。它的实现非常多,PEI阶段、DXE阶段、SMM模块,RUNTIME模块等等都有不同的实现。

下面以DXE阶段为例,它的实现位于MdeModulePkg/Library/DxeReportStatusCodeLib/DxeReportStatusCodeLib.inf(对于Coreboot来说)。它的实现并不复杂,不过要注意其中有优先级的变化,这在实际应用中可能导致一些问题。

  1. ReportStatusCodeEx()函数又调用了InternalReportStatusCode()函数,而后者是通gEfiStatusCodeRuntimeProtocolGuid对应的Protocol来进行输出的。

  2. 对于gEfiStatusCodeRuntimeProtocolGuid,它是在IntelFrameworkModulePkg/Universal/StatusCode/RuntimeDxe/StatusCodeRuntimeDxe.inf中安装的(对于Coreboot来说),该Protocol只包含一个函数:ReportDispatcher,在InternalReportStatusCode()函数中就是调用了该函数实现。

    ReportDispatcher()函数需要关注的主要代码如下:

  if (FeaturePcdGet (PcdStatusCodeUseSerial)) {
    SerialStatusCodeReportWorker (
      CodeType,
      Value,
      Instance,
      CallerId,
      Data
      );
  }
  if (FeaturePcdGet (PcdStatusCodeUseMemory)) {
    RtMemoryStatusCodeReportWorker (
      CodeType,
      Value,
      Instance
      );
  }
  if (FeaturePcdGet (PcdStatusCodeUseDataHub)) {
    DataHubStatusCodeReportWorker (
      CodeType,
      Value,
      Instance,
      CallerId,
      Data
      );
  }
  if (FeaturePcdGet (PcdStatusCodeUseOEM)) {
    //
    // Call OEM hook status code library API to report status code to OEM device
    //
    OemHookStatusCodeReport (
      CodeType,
      Value,
      Instance,
      CallerId,
      Data
      );
  }

根据不同的PCD变量,可以选在不同的打印输出,甚至还有自定义的方式。

SerialStatusCodeReportWorker()为例,它到最后也是调用了SerialPortWrite(),这跟OVMF中的实现就对应上了。跟OVMF版本不同的是这里可以有更多的扩展。

ASSERT 宏实现

以上就是DEBUG的实现。另外再补充一个与DEBUG同一级别的调试代码ASSERT,它最终对应的代码是:

VOID
EFIAPI
DebugAssert (
  IN CONST CHAR8  *FileName,
  IN UINTN        LineNumber,
  IN CONST CHAR8  *Description
  )

使用ASSERT的时候要特别注意,当ASSERT之后代码可以进入CPU Dead Loop,这个时候代码就无法继续执行下去。

通常在发行版的UEFI中不会让这种情况出现,这个使用就需要设置DSC(或者DEC)中的一个PCD:PcdDebugPropertyMask,它可以设置不同的值,每个BIT代表的意义如下:

//
// Declare bits for PcdDebugPropertyMask
//
#define DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED       0x01
#define DEBUG_PROPERTY_DEBUG_PRINT_ENABLED        0x02
#define DEBUG_PROPERTY_DEBUG_CODE_ENABLED         0x04
#define DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED       0x08
#define DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED  0x10
#define DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED    0x20

当设置了DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED就会进入Dead Loop:

  //
  // Generate a Breakpoint, DeadLoop, or NOP based on PCD settings
  //
  if ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED) != 0) {
    CpuBreakpoint ();
  } else if ((PcdGet8(PcdDebugPropertyMask) & DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED) != 0) {
    CpuDeadLoop ();
  }

还没有说ASSERT的使用,这里举个例子:

ASSERT (FileHandle != NULL);

需要特别注意,*这里()中的条件是我们希望的*,所以ASSERT(FALSE)才是真正错误的情况。

其实还有一种类型的ASSERT:ASSERT_EFI_ERROR (Status);

就是说当Status是错误的返回值时就ASSERT。

  • 1
    点赞
  • 6
    收藏
    觉得还不错? 一键收藏
  • 打赏
    打赏
  • 2
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论 2
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

老衲不依

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值