Home

Intel® UEFI Development Kit Debugger Tool Configuration and

1. cs scccccceeeseeserees 5 Figure 3 Current TARGET to outdated Tool connection advisory cc scccccceeeseessreees 5 Figure 4 Example macro using a null modem Cable ceceesessecesecesessesseaeeeeeessssssaees 10 Figure 5 Example macro using a USB 2 0 debug Cable ccccsccccccesssssssseeeeeeeseessaees 11 Figure 6 Remove the IsaSerialDxe module from the FDF c sccccccsssssssssseeeeeessesssaees 12 Figure 7 Don t produce IsaAcpi protocol for debug port c cccccccseessssssseeeeeeesesseaees 13 Figure 8 Ajays USB 2 0 debug Cable ccccccccccccsssessssecesececessesnsaeceseceseesessaeeeeeesseeseaees 15 Figure 9 Include more debug information in the compiler s OUtPUt ccccceeeesereees 16 Fig re LO PEIMMONI BINA eresse rense eerte se seas E ee EEES NEEE ESEE ENERE EERENS 17 Figure 11 Revised rule change for PEIM cccccccsssssssececececeesessaeceseesseessseeaeeeeeessssseaees 17 Figure 12 Updated CPU Driver exampl ss isses eie n ana ea ruia 19 Figure 13 Active components of a debug session on a Microsoft Windows XP platform22 Figure 14 Building a firmware image with the source level debug package 05 26 Figure 15 A WinDbg launch WINdOW c sccccccecssssssnseceeeeeceesesneaeeeeecsseesessaeeeeeesseeesnaaas 27 Figure 16 Target stopped at the late SEC phase ccccccccccecsssessssecesecesesssssseeeeeessessenaees 28 Figure 17 Target stopped due to late a
2. Microsoft Windows platforms e Windows XP IA32 Laz i321 e Windows 7 x64 Linux platforms Fedora 15 IA32 and x64 client e SUSE SLES 11 SP1 Enterprise Server and SP2 Beta beta 3 or later x64 e Ubuntu 32 Ubuntu 10 x or later IA32 client e Ubuntu 64 11 10 x64 client Ubuntu 10 x or later x64 client LTS server x64 The Intel UDK Debugger Tool may work on additional Linux platforms However the Intel UDK Debugger Tool has not yet been fully validated for additional Linux platforms Host and target configurations Requirements for the host machine debug configuration are OS specific The target machine debug configuration is the same for both Windows and Linux platforms The following figure shows the host and target machines Debug cable connects host and target machines Host machine Target machine Null modem cable or USB 2 0 cable Figure 1 Cable connection between the target and host machine The next two sections list the specific configuration requirements for Windows and Linux platforms Host configuration for Windows platforms This user manual assumes you have a working knowledge of the Intel UEFI Development Kit 2010 Intel UDK2010 and the Microsoft Windows Debug Tool WinDbg 13 22 1 3 3 Using the Intel UDK Debugger Tool on a Windows platform requires a host machine configured with e Microsoft Windows XP 32 bit platform with Service Pack 3 SP3 or the Microsof
3. A process that extends functionality to Microsoft WinDbg or other Microsoft applications Firmware device file First in first out GNU Project Debugger Host debugger IDT The debug functionality on the host system The host debugger is a combination of the Intel UDK Debugger Tool and the OS specific debug tool Interrupt description table Intel UDK2010 66 Intel s UEFI development kit Intel UDK Debugger Tool A debugger tool that adds functionality to an OS specific debug tool For example the Intel UDK Debugger Tool adds functionality to Microsoft Windows Debug Tool WinDbg as well as to the GNU Project debugger GDB for Linux platforms IP Instruction pointer MP Multiple processors OS Operating system PCD Platform configuration database PCI Peripheral component interconnect PDB Platform database the file extension of the file containing source level debug information from Microsoft compilers Linux compilers use a different extension PE PE COFF execution PE COFF Portable executable and object file format PEI Pre EFI initialization The PEI phase finishes initializing the CPU makes permanent RAM such as normal DRAM available It then determines the boot mode such as normal boot ACPI S3 resume from sleep or ACPI S4 resume from hibernation PEIM Pre EFI initialization module RAM Random access memory 67 A 2 A 2 1 SEC Security The security SEC phase
4. the source code and debug symbol files of the firmware may not be available If so only the driver or application compiled from the source code can be debugged When the source code and symbol files are not available debug BIOS firmware only at the assembly code level Restart the debug session Powering down the target machine while the Intel UDK Debugger Tool is running on the host machine is not supported and may produce unpredictable results Make sure to close the debugging session on the host machine before powering down the target system e Windows WinDbg 63 9 14 1 Use the reboot command to reset the target machine and restart the debug session e Linux GDB Use the resettarget GDB extension command to reboot the target machine and restart a debug session Shifting to a different architecture mode 32 bit vs 64 bit e Windows WinDbg Automatic relaunch with a change in architecture In some cases the reboot command is issued in 64 bit mode but the SEC PEI is in 32 bit mode If so WinDbg will automatically relaunch in order to continue debugging the 32 bit SEC PEI code e Linux GDB Already supports changes in architecture GDB supports changes in architecture and does not need to be relaunched when a mode changes between 32 bit and 64 bit NOTE Do not set unresolved breakpoints in code that runs in a different architecture mode e g setting an unresolved breakpoint in a DXE module
5. when the TARGET is stopped in PEI phase It may cause unpredicted results 64 Appendix A Additional Information A 1 TERMS This user manual uses the following acronyms and terms AP Additional processors BAR Base address register BSP Boot strap processor COM Communication cs Code segment CSM Compatibility support module CPU Central processing unit DSC The file extension for files containing information used during the FDF build process Debugger package A source level debug package provided by Intel and required during the BIOS build process When building the target firmware image the source level debugger package must be included in each build in order to use the Intel UDK Debugger Tool to debug the target system When included in the firmware build the target system has debug functionality target debugger 65 Debug solution DXE ECP EFI EHCI eXdi FDF FIFO GDB The combination of tools and packages that provide debug capability on both the host and target systems This includes the Intel UDK Debugger Tool the operating system OS specific debug tool on the host system and the source level debug package on the target system Driver execution The DXE phase initializes the rest of the system hardware Intel UEFI Development Kit 2010 Intel UDK2010 compatibility platforms Extensible Firmware Interface Extended extensible host controller interface
6. 14 1 Shifting to a different architecture mode 32 bit vs 64 bit Bases era a de ee ces alae pelea Sanches Sed ics Dante vee ety Seatac 64 Appendix A Additional INfOrmMatiO Nsce ccndess cde Mande ndeGetinedan 65 Bic ATERM Sienen aa a ele Gon cadet e AA S 65 A 2 Conventions used in this dOocCUMent s ssssssesesesesesesessesssesesesisrsnrnenee 68 A 2 1 Nomenclature of CPU architectures 000 0 cece 68 A 2 2 Pseudo code CONVENTIONS cscssssccsssssenescecsssssscecssesesesecses 69 A 2 3 Typographic conventions ceccssescsessssessssssesessesssassessessees 69 A 2 4 Other CONVENTIONS onasco A Ain easiest ees 70 AsO ROW More informatigN sorsien neea delet tla we tec edhe eta tansiahny 70 vi Tables Table 1 Library instances by module tyPe eeeeeessssececececessesneaeeeeecesesseaeaeeeeeeesseseaeas 8 Table 2 Library instances by module tyPe eceeeessssececececeesesneaeeeeececeeseaeaeeeeeeeseesenaees 9 Table 3 Library instances by module tyPe cece eeessssececeeeeessescaeeeeeceseeseaeaeeeeeeessesenaeas 9 Table 4 Library instances by cable CONNECTtION c cccccececsessssceceeeeesseseseaeeeeseesseseeaees 9 Table 5 Bit layout for an example PCD cccccesssssececeeecessssseaeceseessessesssaeeeeeesssesenaees 13 Figures Figure 1 Cable connection between the target and host machine c s cccccccessesereees 3 Figure 2 Current Tool to outdated TARGET connection advisory
7. That is it attempts to locate a file by prefixing each directory path specified by the Features SymbolPath setting to the original symbol file path read from the PE file Alternatively if it cannot locate the file it iteratively strips parts from the head of the original symbol file path until it locates the symbol file If it cannot locate the symbol file the symbol file won t be loaded For example The symbol file path stored in the PE file is J BuildRoot MdeModulePkg Application HelloWorld HelloWorld pdb and it is moved to C Users foo HelloWorld HelloWorld pdb With the following configuration setting 62 9 13 9 14 CAUTION Features SymbolPath C Users foo The following paths are tried until the symbol file is successfully located 1 2 3 4 5 6 Original symbol file path J BuildRoot MdeModulePkg Application HelloWorld HelloWorld pdb Combination of Features SymbolPath and the original symbol file path C Users fooJ BuildRoot MdeModulePkg Application HelloWorld HelloWorld pdb With J stripped C Users foo BuildRoot MdeModulePkg Application HelloWorld HelloWorld pdb With BuildRoot stripped C Users foo MdeModulePkg Application HelloWorld HelloWorld pdb With MdeModulePkg stripped C Users foo Application HelloWorld HelloWorld pdb With Application stripped C Users foo HelloWorld HelloWorld pdb Source code not available In some cases
8. The library may be included in the end user s Linux distribution or downloaded from http expat sourceforge net gdb source work Debugger Src NewHost GdbScript edk2_ gdb script HEHE HE FE FE EE aE FE FE FE HE HE E E FE FE FE FE AE aE FE FE FE E E a ERE FE FE FE FE FE FE FE HE FE FE FE FE HH FE FE FE RE RH HH HH This gdb configuration file contains settings and scripts for debugging UDK firmware Setting pending breakpoints is supported HEHE HE FE FE FE FE E HE FE FE FE FE HE E E FE FE FE FE FE E HE FE FE FE FE FE E HE FE FE FE FE FE E FE FE FE FE FE FE E HE FE FE FE FE HE FE FE FE FE FE FE HE HE HE HH HH Figure 19 Output when sourcing udk script if GDB includes Expat XML parsing library gdb source opt intel udkdebugger script udk gdb script HEHE HE FE FE FE FE HE E FE FE FE FE HE HE E HE FE FE FE FE E FE FE FE FE FE E E HE FE FE FE FE FE HE FE FE FE FE FE FE FE HE FE FE FE HE FE FE FE FE FE FE FE HE HE HH HH This gdb configuration file contains settings and scripts for debugging UDK firmware WARNING Setting pending breakpoints is NOT supported Load additional command HEHE HE FE FE FE FE HE E FE FE FE FE HE HE HE HE FE FE FE FE HE FE FE FE FE FE E FE HE FE FE FE FE FE HE FE FE FE FE FE FE FE HE FE FE FE FE HE FE FE FE FE FE RE HE HE HH HH Figure 20 Output when sourcing udk script if GDB doesn t include Expat XML parsing library 42 7 3 CAUTION gdb b PeiDispatcher Function PeiDispa
9. brings the system out of CPU reset and makes temporary RAM available for the stack and for data storage SecCore During the SEC security phase of execution the SecCore are the common functions across all platform implementations of the Intel UDK 2010 based firmware SMI System management interrupt SMM System management mode Target debugger The debugger functionality on the target system This functionality is part of a BIOS image that has been built with the Intel provided source level debugger package TE Terse execution This image format is a reduction in size of PE PE COFF execution Note that the PE image format has a large header portion that the TE image format trims significantly UDK UEFI Development Kit UEFI Unified Extensible Firmware Interface Conventions used in this document This document uses the following conventions for code samples and typographic differentiation Nomenclature of CPU architectures This user manual refers to the following architectures Intel IA32 refers to Intel s 32 bit processor architecture Intel x64 refers to Intel s 64 bit superset of IA32 Intel IA 64 refers to the Intel Itanium Platform Architecture Intel IPF 68 A 2 2 A 2 3 Pseudo code conventions Pseudo code is presented to describe algorithms in a more concise form None of the algorithms in this document are intended to be compiled directly The code is presented at a level correspondin
10. called firmware on Intel IA 32 and x64 Architecture platforms The debug solution is a combination of the Intel UDK Debugger Tool and an OS specific debugger on the host machine along with a source level debug package provided by Intel on the target machine The Intel UDK Debugger Tool adds functionality to the OS specific debugger for software debugging firmware For Microsoft Windows platforms the Intel UDK Debugger Tool adds functionality to the Microsoft Windows Debug Tool WinDbg On a Linux platform the tool adds functionality to the GNU Project Debugger GDB This overview section includes these main discussions e Configuration of host and target systems e OVMF platform used to demonstrate debug process Configuration The debug environment consists of Debug solution Intel UDK Debugger Tool OS specific debugger tool and a source level debugger package Host machine Configured with the Intel UDK Debugger Tool and the appropriate OS specific debugger WinDbg or GDB The Intel UDK Debugger Tool includes extension commands for OS specific debuggers Target machine Includes the UDK firmware to be debugged The firmware image must be built with the source level debug package SourceLevelDebugPkg provided by Intel Debug cable Null modem cable or USB host to host cable USB 2 0 debug device cable Supported platforms The Intel UDK Debugger Tool supports these platforms
11. change the platform boot manager library implementation The first method doesn t require rewriting code but the setting needs to be manually changed every time the firmware is burned The console device path begins with a vendor defined device path node followed by a UART device path node and a vendor defined messaging device path node An example follows e VenHw 865A5A9B B85D 474C 8455 65D1BE844BE2 Uart 115200 8 N 1 VenPcAnsi Refer to the global variable mSerialloDevicePath in the SourceLevelDebugPkg Library DebugAgent DxeDebugAgent Seriallo c file for console device path details If the platform has multiple serial ports and those ports other than the debug port are needed as console devices as well do not remove the IsaSerialDxe module from the FDF because the IsaSerialDxe module manages those other serial ports Instead modify the module that produces the IsaAcpi protocol to not produce the IsaAcpi protocol for the debug port For the OVMF platform modify the PCD in the DSC file instead of the IsaAcpiDxe module 12 2 2 4 2 2 4 1 CAUTION Table 5 lif SOURCE_DEBUG ENABLE TRUE gPcAtChipsetPkgTokenSpaceGuid PcdIsaAcpiComlEnable FALSE else gPcAtChipsetPkgTokenSpaceGuid PcdIsaAcpiComlEnable TRUE endif Figure 7 Don t produce IsaAcpi protocol for debug port Configure the USB debug port Configure PCDs The DebugCommunicationLibUsb library instance requires that several PCDs plat
12. control on the host machine should be turned off as well The flow control setting should be the same on both the host and target machines Configure the hardware buffer for FIFO In order for the debug solution to work properly the hardware buffer must be configured for first in first out FIFO However some platform specific Serial Port Library instances may not enable receive and transmit for the FIFO hardware buffer The specific process for configuring the hardware buffer is hardware dependent Refer to your hardware s data sheet for information about the hardware buffer The SerialPortLib instance provided by Intel in MdeModulePkg Library BaseSerialPortLib16550 library is also an example of implementing a FIFO hardware buffer Deactivate the terminal support Because the IsaSerialDxe driver tries to manage the serial port a conflict with the debug agent is created One way to prevent the conflict is to 11 remove the IsaSerialDxe module from the platform firmware device file FDF For example FV DXEFV ifndef SOURCE_DEBUG ENABLE INF IntelFrameworkModulePkg Bus Isa IsaSerialDxe IsaSerialDxe inf endif Figure 6 Remove the IsaSerialDxe module from the FDF The console device created by debug agent isn t added to the console input output device list by default There are two ways to add it to the list change the setting through the Intel UEFI Development Kit 2010 Intel UDK2010 front page UI or
13. file However compiler options for particular modules can be added in the Components section of the DSC file to force the compiler to include more debug information in the output file For example with Windows the default O2 level 2 optimization switch turns on some optimization reduces the size of the output file and omits some source level debugging information To disable level 2 optimization on a Windows system use the Od switch To disable optimization on a Linux system use the OO switch In the following example the Od and OO switches prevent each OS specific compiler from performing optimization functions 15 ZL De ZL 53 Components IA32 MdeModulePkg Core Dxe DxeMain inf lt BuildOptions gt MSFT CC FLAGS Od Gcc _ CC FLAGS 00 Figure 9 Include more debug information in the compiler s output WinDbg Turning off aggressive zeroing By default the GenFw tool turns on aggressive zeroing for some sections in the PE COFF Portable ExeCutable and Object File Format image However these sections in the PE COFF image may contain information needed for the debugger e g the stack frame information In order for the stack frame analysis to work effectively with the debugger add the following lines to the platform DSC Build Options section ifdef SOURCE_DEBUG ENABLE _ GENFW_FLAGS keepexceptiontable endif WinDbg Use the PE image format instead of TE If fre
14. interconnects for the debug cable e Null modem cable e USB host to host cable USB 2 0 debug device cable OVMF platform and the debug process The OVMF Open source Virtual Machine Firmware platform implementation is used to demonstrate the debug process in some of the examples The OVMF platform works on a virtual machine and can also be chosen as a configuration option in order to use virtual COM to COM connections The OVMF platform implementation is available from the EDK II project directory at www tianocore org http tianocore sourceforge net For general instructions on building and booting an OVMF image including setting up COM connections refer to the OVMF wiki page at http sourceforge net apps mediawiki tianocore index php title OVMF FAQ 2 1 2 1 1 2 1 2 2 2 Build the Firmware Image Introduction The firmware image including the source level debug package provided by Intel must be built before using the Intel UDK Debugger Tool To do this complete the appropriate build instructions for your Intel UDK2010 platform taking into consideration the modifications described in this section The firmware build process and most of the considerations for building the image are the same for both Windows and Linux platforms Differences are noted where appropriate Linux Platforms For Linux platforms x64 code can only be debugged when using GDB on x64 Linux platforms Make sure the firmware image i
15. mtrr Dump the MTRR setting of current processor Usage py mtrr 49 py DumpHobs py DumpHobs HobStartAddress Dump content of HOB list Usage py DumpHobs HobStartAddress Options HobStartAddress The start address of HOB list The first HOB in the HOB list must be the Phase Handoff Information Table PHIT HOB When HobStartAddress is not specified HOB list will be got from EFI Configuration Table and dumped py DumpVariable py DumpVariable VariableName Dump content of UEFI variable on flash Usage py DumpVariable VariableName Options VariableName The name of variable If a variable name is specified the contents of this variable will be dumped If a variable name is not specified the contents of all UEFI variables on flash will be dumped py DumpS3Script S3ScriptTableAddress py DumpS3Script S3ScriptTableAddress Dump content of S3 boot script Usage py DumpS3Script S3ScriptTableAddress Options S3ScriptTableAddress The base address of S3 boot script table 50 7 5 1 1 py Show fiDevicePath DevicePathAddress py Show fiDevicePath DevicePathAddress Convert UEFI device path to text Usage py ShowEfiDevicePath DevicePathAddress Options DevicePathAddress The start address of UEFI device path Data Breakpoint For Linux developers three extension commands iowatch info iowatchpoints and delete iowatchpoints are available to add show and delete IO breakpo
16. s Linux distribution If not it can be downloaded from http expat sourceforge net Install the Intel Debugger Tool on HOST The debug port can be configured during installation If the TARGET has more than 16 logical processors open the SoftDebugger ini through Start gt All Programs gt Intel R UEFI Development Kit Debugger Tool gt Change Configurations Change 38 6 4 Target System ProcessorCount to specify the number of logical processors in TARGET Connect HOST and TARGET HOST and TARGET must be connected through a debug cable The Intel UDK Debugger Tool supports these cables e Null modem cable e USB debug cable USB debug cable support is provided by Linux kernel starting from 2 6 20 If a USB debug cable is used the correct USB port on the target machine must be specified see the next discussion Always connect the USB debug cable to HOST before connecting to TARGET Once both HOST and TARGET have been configured and connected a debug session can be started 39 40 7 1 7 2 Use the Debug Solution on a Linux Platform Introduction This section explains how to perform basic debug operations It includes these key discussions e Supported features for Linux platforms as well as features not yet implemented e Using the Linux GDB debug solution to Start reset and stop a debug session e Basic debugging operations including GDB extension commands Supported features for Linux p
17. session using late attach 45 7 4 3 End the GDB debug SESSION ee ceceteeeeeteteeeeeeeeeteeeeateteeees 46 7 5 Basic GDB debugging Operations 0 ec eceeeeeeseteeeeeeeceeteeeeeteeeeeeeeseees 47 7 5 1 GDB extension commandS i303 node eee ee 47 8 Known Limitations amp Issues for LINUX platforms ee ceeeteeeeeeeeneees 53 8 1 Known NIMTNLARION Si ccs etc ale ate e eat te a a tele te et 53 9 Debug Tips FECnniques ncn ee tes ee ale ls ete 55 ad Introd ctiO m ss5ctsi A stare Pets E r a See acta Rtas Eek Ea chia 55 9 2 Terminal redirection cg seach i cccreephevocaet adsgih eater eee add eed ates 55 Do WURACC irl a tes a te hares aM deka a hat os niet azoies 57 9 4 CPU exception INfOrMation 230004 c i eM eee eee ee 57 3 5 Disabling OO CNMZAO Msc Atasee tt et Genta niee 58 9 6 Improving debugger productivity 22 d0sii cusadaaweuadnind Quince 58 9 7 Debugging SEC and PEI code soso votre ee casd vocanenlw potianiecveniamnimseesoutaans 58 9 8 Debugging DXE Code sancti ee eee 59 9 9 Debugging SIME COC Ce coins ccticce becuev sale e e E e 59 9 10 Debugging Boot Script code on S3 path wc eeeseeteeeeeeseeeeees 59 9 11 Debugging a standalone module loaded in a UEFI shell 60 9 12 Intelligent symbol path Searching ceeceeeeseteeeeseeeeeeeseeeeeeeeeeeeees 62 9 13 Source code not available cc eccessssssscessssseeseessssessseeseseseseeseesess 63 9 14 Restart the debug SESSION aden iteceni neni cerns ace 63 9
18. to connect HOST and TARGET machines for source level debugging From the device s appearance it s hard to distinguish which end to connect to the Host and which to the Target This is important however because the connection orientation determines which end provides the power to the debug cable and therefore impacts the debug cable s behavior The debug cable must be powered by the TARGET e To confirm proper orientation connect one end of the device to the HOST If oriented and connected properly the Windows Device Manager should NOT detect it If it is detected by the device manager connect the opposite end of the debug cable to the HOST 14 2 2 5 2S e Connect the open end to the Target When powered on the Windows Device Manager at the Host side should find the USB debug cable attached Note that if the connection is not made in this recommended fashion it may be not stable Figure 8 Ajays USB 2 0 debug cable Additional configuration requirements This discussion includes three special considerations e Windows and Linux Disabling compiler optimization in order to include more debug information in the compiler s output file e Windows Turning off aggressive zeroing e Windows Using the PE PE COFF execution image format instead of TE Include more debug information in the compiler s output Compiler optimization can reduce the amount of debug information included in the output
19. whose configuration space is to be dumped O by default if not specified 32 Ipy mtrr Ipy mtrr Dump the MTRR setting of current processor Ipy DumpHobs Ipy DumpHobs HobStartAddress Dump content of HOB list Options HobStartAddress The start address of HOB list The first HOB in the HOB list must be the Phase Handoff Information Table PHIT HOB When HobStartAddress is not specified HOB list will be got from EFI Configuration Table and dumped Ipy DumpVariable Ipy DumpVariable VariableName Dump content of UEFI variable on flash Options VariableName The name of variable If a variable name is specified the contents of this variable will be dumped If a variable name is not specified the contents of all UEFI variables on flash will be dumped Ipy DumpS3Script S3ScriptTableAddress Ipy DumpS3Script S3ScriptTableAddress Dump content of S3 boot script Options S3ScriptTableAddress The base address of S3 boot script table 33 Ipy ShowEfiDevicePath DevicePathAddress Ipy ShowEfiDevicePath DevicePathAddress Convert a UEFI device path to text Options DevicePathAddress The start address of a UEFI device path 34 Known Limitations amp Issues for Windows Platforms 5 1 Known limitations The debug solution has the following known limitations on a Windows platform Firmware output through the debug channel should not contain non ASCII characters Do not u
20. 3 first chance cai u 07fda0b1 cc int a a Za 0 kd gt sympath E WORK EDK2 BUILDNOVMF326 4 DEBUG_MYTOOLS IA32 MDEMODU work edk2 mdepkg library basedebuglibserialport det Symbol search path is E WORK EDK2 BUILD OVMF3264 DEBUG_MYTOOLS IA32 I Expanded Symbol search path is e amp workNedk2 buildNovmf 3264 debug_mytoc 2r 0 kd gt reload f PEICORE 0x0 7FD6000 7 7 Generate a Breakpoint DeadLoop c 0 kd gt sympath E WORK EDK2 BUILD OVMF3264 DEBUG_MYTOOLS IA32 MDEMODU YC Symbol search path is E WORK EDK2 BUILD OVMF3264 DEBUG_MYTOOLS IA32Nt if PedGet8 PcdDebugPropertyMask amp Expanded Symbol search path is amp work edk2 build ovmf 3264 debug_mytoc _ 0 kd gt reload f PEICORE 0x0 7FD6000 else if PodGet8 PcdDebugPropertyM_ CpuDeadLoop I AsmFuncs iii cpudeadloop c cpubreakpoint c 0 kd gt Ln 141 Col32 Sys0 eXDIKD Proc000 0 Thrd000 0 ASM OVR CAPS NUM Figure 17 Target stopped due to late attach End the WinDbg session To end a WinDbg debug session use the following steps 1 Halt the TARGET if the TARGET is running 2 Run q command in WinDbg Closing WinDbg without using the steps given above leaves the TARGET platform in an intermediate state and it cannot be reattached until rebooted 29 4 4 Basic WinDbg debugging operations When the target reaches a breakpoint or stops after a break command is issued the debugger loads the source of the cur
21. 422 4320 A7F3 41 EAEC2A367D WinDbg 6 12 0002 633 X86 E Offset Sscopeip Microsoft R Windows Debugger Version 6 12 0002 633 X86 07fdal8e pea ede rae ort set P Copyright c Microsoft Corporation All rights reserved 50 eax i Kernel Debugger connection established EFE FETCORE Debugger data list address is NULL 340424 eae T Connected to eXDI Device 0 x86 compatible target at Thu May 17 17 02 e8fd120000 PEIC RET Symbol search path is Invalid HHH HHH HH HHH JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE EKER EEEEEA 07fda0a9 8d0c24 ecx esp e87a1e0000 PEICORE Symbol loading may be unreliable without a symbol search path Use symfix to have the debugger choose a symbol path 07fda0b2 Bb 5 a b After setting your symbol path use reload to refresh symbol locatic 07 da0b4 Sa nov sha eDp HHH HHH HH HHH JE JE HHH JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE JE ME JE JE E EE EE 07 da0bS o3 pet eoP Executable search path is PEICORE PeCof f LoaderGetMachineType eXDI Device Kernel Version 0 UP Free x86 compatible Machine Name D raanbe eee ly ssi esi Primary image base 0x00000000 Loaded module list 0x00000000 System Uptime not available 07fda0ba 6804cbfd07 push offset P Break instruction exception code 8000000
22. DK2010 based firmware image with the debug feature enabled If the WinDbg is closed by pressing X before the HOST and TARGET are connected windbg exe may still be running in the background Open the Task Manager to terminate the process or the Intel UDK Debugger Tool may fail to launch 3 If OVMF is used refer to the README file under OvmfPkg for details on how to launch an OVFM platform Be sure to specify the appropriate serial or USB port used to connect with the host 4 Wait until WinDbg is connected and is ready to accept commands This will take a few seconds If source debugging enabled from SEC WinDbg should then stop the target in the late SEC phase and load the symbols for SecCore It will then display the source code The output should look similar to the following figure although the layout may vary depending on OS preferences etc 27 4 3 2 eXDI exdi clsid 66C102B6 D4F 6 4F 8E 84CC B09802D364EA WinDbg 6 11 0001 404 X86 File Edit View Debug Window Help a OP Po N AsniriteDr 0 20000480 AsnYriteCr4 Cr4 BIT3 Microsoft R Windows Debugger Version 6 1 ir Copyright c Microsoft Corporation All r Do an IN from IO_PORT_BREAKPOINT_ADDRESS to generate lt returns a read value other than DEBUG_AGENT_WAIT Kernel Debugger connection established ride Debugger data list address is NULL do Connected to eXDI Device 0 x86 compatible Debug gentStatus IoRead8 I0_PORT_BREAKPOIN
23. ES tos cent cdc ort Ao a i EA EEEE E 25 43 gt gt VGENEFal debug TOW siege ciceaet cucarnieconentominn eaa ea ae eens 25 4 3 1 Start a WinDbg debug SESSION cece eteteeeteteteteeeeteee 26 4 3 2 Start a WinDbg session using late attach 0 ee 28 4 3 3 End the WinDbg SESSION a ccs cnadacwGaen ee auiaees 29 4 4 Basic WinDbg debugging Operations cceceeeeeseeeeeeteeeeteteeeeeees 30 4 4 1 WinDbg extension COMMANGS cece eeteteeeteteteteeeeteee 31 Known Limitations amp Issues for Windows Platforms cece 35 5 1 Known limitations c c5 wecciet ances at bcd coeeeneea ene pete meen nes 35 Setup the Linux Debug ENVIrOnMeNn tos sxc ccsentea ret aucente eens 37 Gly sENEFOCUCUION EG Antone a una a aa cue aetna ae 37 6 2 gt Rebuild GDB on HOS Torreira riot A E E a a ea 38 6 3 Install the Intel Debugger Tool on HOST sessssssssssriesisseserressee 38 6 4 Connect HOST and TARGET acs cciatanotiiotian ieee esata eanie ears 39 Use the Debug Solution on a Linux Platform 0 ee cceeeeeeteeeeeeeeeees 41 Pod o Introd ction e e a a eae E ei a E 41 7 2 Supported features for Linux PlatfOrMS cc eeseeeteeeeeeeeteeeeees 41 7 2 1 Unresolved breakpoint setting in LINUX eee 42 7 3 General debug Tow sinc nt eee tee et le ees Ce enti 2 43 7 4 Using the Linux GDB debug solution 0 eee ce eeteteeeeetteeeteeeeeeees 44 7 4 1 Start a GDB debug SESSION oe eceteeeeeeeteeeeeeeeeeteeetateeeeees 44 7 4 2 Start a GDB debug
24. Intel UEFI Development Kit Debugger Tool Configuration and Setup Guide Version 1 8 December 17 2012 INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL PRODUCTS NO LICENSE EXPRESS OR IMPLIED BY ESTOPPEL OR OTHERWISE TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT EXCEPT AS PROVIDED IN INTEL S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS INTEL ASSUMES NO LIABILITY WHATSOEVER AND INTEL DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY RELATING TO SALE AND OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE MERCHANTABILITY OR INFRINGEMENT OF ANY PATENT COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT Intel products are not intended for use in medical life saving or life sustaining applications Intel may make changes to specifications and product descriptions at any time without notice Designers must not rely on the absence or characteristics of any features or instructions marked reserved or undefined Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them The Intel UEFI Development Kit Debugger Tool may contain design defects or errors known as errata which may cause the product to deviate from published specifications Current characterized errata are available on request Contact your local Intel sales office or your distribut
25. Setup the Linux Debug Environment Introduction Setting up the Linux debug environment consists of four general steps iL 2 3 A Build the firmware image and burn it to TARGET described earlier in Section 3 Rebuild GDB on HOST Install the Intel UDK Debugger Tool on HOST Connect the HOST and TARGET The following figure shows how the debug components interact on a Linux host during a debug session 37 6 2 6 3 Active components of a typical debug session on a Linux based machine Host machine Target machine Linux OS Debugger Linux based GNU Debugger GDB GL Source UEFI Intel UDK etia Coe Deb souaga package debugged Debug cable Figure 18 Active components of a debug session on a Linux platform Rebuild GDB on HOST For Linux platforms x64 code can only be debugged when using GDB on x64 Linux platforms When debugging x64 platforms make sure to build the firmware image on an x64 Linux machine so that the debug symbols are accessible to the GDB GDB supports the unresolved breakpoint setting by design but it needs to be rebuilt to support this feature because the GDB pre installed doesn t include the Expat XML parsing library Using the GDB pre installed doesn t block the other features Use target x86_64 w64 mingw32 with expat as the parameter to configure the GDB before make so GDB can use the Expat XML parsing library This library may be included in the end user
26. T_ADDRESS Symbol search path is SRV c symbols http while DebugAgentStatus DEBUG_AGENT_IMAGE WAIT Executable search path is eXDI Device Kernel Version 0 UP Free x86 c else if LoadImageMethod DEBUG_LOAD_IMAGE_METHOD_SOFT_ ef 0x00000000 Loaded mod Generate a software break point ime not available a Break instruction SeEPREeR code 8000000 CpuBreakpoint ffifeeab6 cc 0 kd gt sympath BUILD OVMETA32SDEBUG_ MY Symbol search path is V BUILD OVMFIA32 D Beaters Debug Register State only when Host didn t chance 0 reload f SECHAIN 0x0 FFFEE064 g User halts the target and sets the HW breakpoint w in the above exception handler ji SECMAIN PeCof fLoaderRelocateInageExtra cti fffeeab 0f21f8 eax dr NewDr AsmReadDr 0 kd gt sympath V BUILD OVMFIA32SDEBUG MY if IsDrxEnabled 0 NewDr7 Symbol search path is BUILD OYMFIA32N ND AsnWriteDrO Dr0 Expanded Symbol search path is v build o 0 kd gt reload f SECMAIN 0x0 FFFEE064 if IsDrxEnabled 1 NewDr7 AsnWriteDr1 Dr1 if IsDrxEnabled 2 NewDr 7 AsnWriteDr2 Dr2 if IsDrxEnabled 3 NewDr7 AsnWriteDr3 Dr3 if AsmReadCr4 Cr4 BIT3 AsniriteCr4 Cr4 vis Ln 105 Col 38 Sys O eXDIKD Proc 000 0 Thrd 000 0 Figure 16 Target stopped at the late SEC phase Run third party terminal software to connect the terminal redirection port to get the debug output and terminal outp
27. ad DebugAgentDxe efi from the USB memory stick Shell gt map r Shell gt fsO fs0 gt Load nc DebugAgentDxe efi b If debug port is USB Debug Port copy DebugAgentDxe efi and the debugged driver s efi file into the hard disk Shell gt map r OXUATEFDO5 0X3 61 9 12 Shell gt copy fs1 DebugAgentDxe efi fs1 example efi fs0 Shell gt fs0 fs0 gt Load DebugAgentDxe efi 8 On the host machine launch the Intel UDK Debugger Tool to connect the TARGET 9 On the host set an unresolved breakpoint at the entry point for the driver or application and let the TARGET go e WinDbg Issue the go command e Linux GDB Enter the c command 10 On the target machine load and execute the driver s efi file from the USB memory stick or the hard disk On the host the debugger tool will stop at the unresolved breakpoint set in Step 6 above After that performing basic debug operations can begin with the debug session for the application or driver loaded on the target machine Intelligent symbol path searching Sometimes the location of the symbol files is moved Change Features SymbolPath setting to identify multiple directory paths semicolon as the separator where the symbol files can be searched Intel UDK Debugger Tool gets the symbol file path stored in the PE file When it cannot locate the symbol file an intelligent symbol path searching method is used to find the correct symbol file path
28. alidated on a variety of Intel platforms operating systems and application software It is available for download at www tianocore org http tianocore sourceforge net 70
29. bug Agent library Different Debug Agent library instances provide the functions needed by the Intel UDK Debugger Tool for modules executed in different booting phases Be sure to specify the correct library instance in the DSC file The following table lists the correct library instances to replace the NULL instances for each module type Intele UDK Debugger Tool supports three scenarios debugging from SEC PEI or DXE Debugging from SEC including PEI DXE and SMM Library instances by module type Module type Library instance SEC or PEI modules SourceLevelDebugPkg Library DebugAgent SecPeiDebugAgentLib inf DxeCore and DXE SourceLevelDebugPkg Library DebugAgent DxeDebugAgentLib inf modules SMM modules SourceLevelDebugPkg Library DebugAgent SmmDebugAgentLib inf For definitions of acronyms refer to Appendix A at the end of this user manual Debugging from PEI including DXE and SMM First the PEIM SourceLevelDebugPkg DebugAgentPei DebugAgentPei inf should be added into DSC FDF files to enable source level debugging feature in PEI phase Only the PEIM dispatched after DebugAgentPei could be debugged Table 2 Library instances by module type Module type Library instance SEC MdeModulePkg Library DebugAgentLibNull DebugAgentLibNull inf PEI modules SourceLevelDebugPkg Library DebugAgent SecPeiDebugAgentLib inf DxeCore and DXE SourceLevelDebugPkg Library DebugAgent DxeDebugAgentLib inf modules SMM modules SourceLevelDebugP
30. bugged This includes early SEC code early SMM code and other code During the SEC PEI phases only one processor the BSP or boot strap processor can be debugged This also applies to the DXE phase before the Multiple Processor MP Services Protocol is installed While in the DXE phase after the MP Services Protocol has been installed switching to other active processors AP or Additional Processors is possible Debugging is not supported if the CPU is executing in 16 bit real mode If the CPU is executing with interrupts disabled breaks from the host to the target are not supported When using the USB debug cable as the debug communication channel USB devices cannot be detected on any other USB ports associated with the same EHCI controller USB ports associated with other EHCI controllers are not impacted Only AP code invoked by the Platform Initialization Multiprocessor Services Protocol can be debugged For example on EdkCompatibilityPkg based platforms AP code invoked through the Framework Multiprocessor Services Protocol cannot be debugged 53 54 9 1 9 2 Debug Tips amp Techniques Introduction The debugging tips and techniques described in this section generally apply to both Windows and Linux systems Any platform specific differences are explained in the topic Terminal redirection Terminal I O can be redirected to a local TCP port default port is 20715 which can be connected to using a
31. bugger Tool automatically shows the vector number and the error code whenever a CPU exception occurs in firmware If a CPU exception happens in firmware before the Intel UDK Debugger Tool attaches the Intel UDK Debugger Tool automatically shows the exception information as soon as it attaches to the firmware For the Linux version the 57 9 5 9 6 9 7 exception information is shown after sourcing the GDB script gdb c Continuing Program received signal SIGTRAP Trace breakpoint trap 0x0000000037f36fal in gt 0x0000000037f36fal 48 8b 04 25 00 00 ff ff mov rax QWORD PTR ds 0xffffffrffffffooo0o Target encounters an exception Vector 14 Error Code 00000000 Figure 31 Output in GDB when a CPU exception happens in firmware Disabling optimization Compiler optimization switches are often used to reduce the size of the output file including the reduction of the debug information included in the output file To include more debug information in the output file add compiler tags in the Components section of the DSC file For more information and an example of adding compiler tags refer to section 2 2 5 Additional configuration requirements Improving debugger productivity The debug tool can be more effective if these features are used e Set unresolved breakpoint e Adjust the PcdDebugPropertyMask to enable CpuBreakpoint on ASSERT conditions Debugging SEC and PEI code Most code for th
32. ds or segments can also be embedded in a normal text paragraph Italic Monospace In code or in text words in Italic Monospace indicate placeholder names for variable information i e arguments that must be supplied 69 A 2 4 A 3 Other conventions This user manual also uses the following convention for Linux examples foo foo A user defined command prompt for Linux based command lines used in the examples in this manual For more information UEFI Specification Information about UEFI device types and status codes can be found in the Unified Extensible Firmware Interface version 2 3 1 or later and at the UEFI Forum www uefi org A Summary of UEFI services and GUIDs can be found in the Doxygen generated help documents for the MdePkg in the Intel UDK 2010 releases tianocore org The Intel UDK 2010 source filesand specifications are available at www tianocore org http tianocore sourceforge net UEFI Driver Writers Guide Refer to the UEFI Driver Writer s Guide for key descriptions of how to implement UEFI requirements as well as recommendations for writing drivers This guide is now available at www tianocore org http tianocore sourceforge net UEFI Development Kit 2010 UDK2010 This open source kit provides the modern feature rich cross platform firmware development environment for the UEFI and PI specifications The Intel UDK2010 is a stable release of this open source kit and has been v
33. e SEC and PEI pre EFI initialization phases executes from read only memory The Intel UDK Debugger Tool automatically uses a hardware breakpoint if it detects the address is within the read only memory flash range Currently the Intel UDK Debugger Tool assumes the range from 4GB 1MB to 4GB to be read only 58 9 8 9 9 9 10 Debugging DXE code Some platform initialization firmware implementations execute SEC PEI in 32 bit mode and execute DXE SMM in 64 bit mode When the Intel UDK Debugger Tool detects a mode switch from 32 bit mode to 64 bit mode or vice versa WinDbg is automatically re launched Debugging SMM code The Intel UDK Debugger Tool does not enable a timer interrupt in SMM to look for a break in the request from the host Instead an smmentrybreak command must be used to set a flag so that the next entry into SMM will force the target to break into the debugger Breakpoints can be set after the target enters SMM mode and debugging can continue Refer to the discussion on WinDbg extension commands later in this section for a brief description of the smmentrybreak command When the target system stops at the SMM entry the source code for SMM handlers and set software breakpoints may be opened Basic debug operations may also be performed when the target system is stopped at the SMM SMM context is not visible after exiting SMM Debugging Boot Script code on S3 path The Intel UDK Debugger Tool do
34. elDebug package is not included the Intel UDK Debugger Tool cannot debug the target firmware 2 Program Program the firmware image into flash memory on the target system 3 Launch and debug On the host system launch a debugger that includes the functionality added by the Intel UDK Debugger Tool Target system UDK based firmware Firmware image Source level debug package SourceLevelDebugPkg Each firmware build must include the source level debug package which provides the debugger capabilities on the target system Figure 14 Building a firmware image with the source level debug package The source level debug package in the firmware build must be included each time the firmware image is built Start a WinDbg debug session Follow these steps to start a WinDbg session 1 Launch Start WinDbg using UDK Debugger Tool from Windows Start gt All Programs gt Intel UDK Debugger Tool 26 wi _ n coma WinDbg 6 12 0002 633 X86 e SS File Edit View Debug Window Help ox 0 Gd kd Gl O tf Gel oael Aal e Command WinDbg 6 12 0002 633 X86 Microsoft R Windows Debugger Version 6 12 0002 633 X86 Copyright c Microsoft Corporation All rights reserved Debuggee not connected Ln0 Col0 Sys0 lt None gt Proc000 0 Thrd000 0 ASM OVR CAPS NUM Figure 15 A WinDbg launch window 2 Start up the target system using the Intel UEFI Development Kit 2010 Intel U
35. er This driver must be updated during the build process so that the target platform s debugging feature can be enabled This step is not needed for native platforms using a CPU driver compliant with the Intel UDK Debugger Tool solution The main task performed by the update is to reserve the original configuration of the interrupt description table IDT entries and prevent those entries from being modified The update performs these steps 1 Loads the original IDT table 17 2 Calculates the IDT table s entries count 3 Copies the original IDT table entries to the new IDT table 4 Updates the code segment CS field for the IDT table entries as the DXE driver execution phase is using a different segment descriptor 5 Fills the rest of IDT entries needed by CPU driver If the CPU module is not linked with BaseLib refer to MdePkg Library BaseLib for the implementation of AsmReadIdtr AsmWriteldtr and AsmReadCs The updated code should look similar to the following 18 2 2 7 STATIC VOID InitInterruptDescriptorTable VOID Get original IDT address and size AsmReadIdtr IA32_DESCRIPTOR amp Idtr ti Copy original IDT entry CopyMem amp gIdtTable 0 VOID Idtr Base Idtr Limit 1 Update all IDT entries to use current CS value 1 for Index 0 Index lt INTERRUPT VECTOR NUMBER Index CurrentHandler 0x08 gIidtTab
36. ere see itreueeaRaecoetees 7 Dade TOC TION erore i tected AE EE 7 2 1 1 Linux PlatformS 5 asecsscessccstencaccesecesctanspsstaiecetectelsnencdtiszeectemsenaeate 7 2 1 2 Windows PlatformS 5 scs cc 5 sacceiasstessdapsnseeraisidectessnntectentiestaxseacsianvadeces 7 2 2 Modify the configuration files for the firmware used by the target MaCHIN E seee ea eaae EEEE ERE e emerson ae 7 2 2 1 Select the appropriate libraries sesssseeeessesseeeess 8 2 2 2 Turn debugging on or Off ss s ssssessssessesissssrisrrsresesrerrsrsnserresrss 10 2 2 3 Configure a serial port for debug usage n 11 2 2 4 Configure the USB debug poft ss ssessssrissisrssssieresessrserresess 13 2 2 5 Additional configuration requirements eee 15 2 2 6 Update the CPU driver on ECP based platforme 17 2 2 7 Build the image and update flash memory before debugging SOUTEE 1EV CL CO GG cearn are netir e E e ee 19 Setup the Windows Debug Environment uu ccseeseescsseseteeesseesseeessseeaseess 21 Sul Introduction eanusne tan n n eae ee Ue eee 21 3 2 Install the Windows Debugger on HOST cc cceeeeeeeeeteteteeeteeeeeees 22 3 3 Install the Intel Debugger Tool ON HOST cecceeeeeeeseeeteeeeeeeeeees 22 3 4 Connect HOST and TARGET poca ctissreccecaneiscuinesssttnosssacessnccvetnrainteonisvetnvdens 22 Use the Debug Solution on a Windows Platform s s sssssnsssssesesisisernenee 25 4T Tntrod cti n cisrenan 25 4 2 S pported TEALUR
37. es not enable a timer interrupt during executing Boot Script code on S3 path to look for a break in the request from the host Instead a bootccriptentrybreak command must be used to set a flag so that target will break into debugger tools before executing Boot script code Breakpoints can be set when target breaks before executing Boot Script code and debugging can continue Refer to the discussion on WinDbg extension commands later in this section for a brief description of the bootccriptentrybreak command When the target system stops before executing boot script code the source code of MdeModulePkg Library PiDxeS3BootScriptLib BootScriptExecute c could be opened and set software breakpoints for specific OpCode in S3BootScriptExecute Basic debug operations may also be performed from then on 59 9 11 Debugging a standalone module loaded in a UEFI shell The Intel UDK Debugging Tool allows debugging of UEFI applications or UEFI drivers that are loaded and executed in the UEFI shell environment on the target even if the target firmware does not include the source level debug feature The source code and debug symbol files of the firmware are not needed in order to use the Intel UDK Debugging Tool For information about building a UEFI driver or UEFI application refer to Compiling a UEFI Driver using the Intel UEFI Development Kit 2010 available at http www intel com content www us en architecture and technology un
38. esreees 58 viii 1 1 1 1 1 hlg 1 1 3 1 1 4 Configuration Overview Document Purpose and Organization This guide explains how to set up a host and target system and perform basic debugging operations from Windows platform and Linux platform host systems using the Intel UEFI Development Kit Debugger Tool Intel UDK Debugger Tool It also includes debugging tips and techniques as well as known issues and it is intended for developers with a solid understanding of the Intel UEFI Development Kit 2010 Intel UDK2010 and its predecessors and related subjects Configuration and Build Chapters 1 and 2 provide an overview of the configuration and building of the firmware image Windows Windows users should continue with Chapters 3 5 These chapters detail setting up the environment usage and known limitations of the Intel UDK Debugger Tool for Windows platforms Linux After Chapter 2 Linux users should skip to chapters 6 8 These chapters detail setting up the environment usage and known limitations of the Intel UDK Debugger Tool for Linux platforms Debugging Tips and Appendix Chapter 9 provides general debugging tips and the Appendix provides additional information such as a glossary and document conventions 1 2 1 3 1 3 1 Tool Introduction The Intel UEFI Development Kit Debugger Tool Intel UDK Debugger Tool helps debug UDK compliant applications drivers and firmware hereafter
39. form configuration database be configured correctly The default value provided by the SourceLevelDebugPkg works for most cases but the values may need to be adjusted For example two PCDs for a WinDbg based debug solution follow e gEfiSourceLevelDebugPkg TokenSpaceGuid PcdUsbDebugPortMemoryS paceBase e gEfiSourceLevelDebugPkg TokenSpaceGuid PcdUsbEhciMemorySpaceB ase The example PCDs specify the base address for the memory mapped IO base address register for the extensible host controller interface EHCI controller and the USB debug port since the debug agent may run early in SEC Make sure these memory ranges do not conflict with memory ranges including physical memory assigned to other devices Memory conflicts can cause the debugger to fail The following example PCD specifies the PCI Peripheral Component Interconnect address of the EHCI controller e gEfiSourceLevelDebugPkgTokenSpaceGuid PcdUsbEhciPciAddress The EHCI includes the debug port to be used for debug The PCI address is specified by bus device and function number The bit layout for the PCD is shown in Table 5 Bit layout for an example PCD Bits 28 31 Bits 20 27 Bits 15 19 Bits 12 14 Bits 00 11 0 Bus number Device number Function number 0 For example for a PCI address at bus 0x0 device 0x1D function 0x07 the PCD value is OxOOOEFOOO 13 2 2 4 2 2 2 4 3 Identify the correct USB port for the debug cable There is only one USB port in one EHCI c
40. g a firmware image with the source level debug package The source level debug package provided by Intel must be included in the firmware build each time you compile the image Using the Linux GDB debug solution This discussion explains how to start restart and end a debug session Start a GDB debug session Follow these steps to start a GDB debug session 1 At the shell prompt start the GDB server by entering the appropriate command similar to the following foo foo usr bin udk gdb server The command line is a symbolic link to opt intel udkdebugger bin udk gdb server A message similar to the following should appear UDK GDB Server Version 1 2 Waiting for the connection from the Target Debugging through serial port dev ttyS0 115200 Hardware Redirect TARGET output to TCP port 20715 2 Power up the target system The system must include the Intel UEFI Development Kit 2010 Intel UDK2010 based firmware image built with the source level debug package and it must have the debug feature enabled 3 Wait 1 or 2 seconds until the GDB server successfully connects to the target debugger A message similar to the following should appear The 44 7 4 2 message indicates that the GDB server has successfully connected and in this example is listening on TCP port 1234 GdbServer on lt HOST gt is waiting for connection on port 1234 Connect with target remote lt HOST gt 1234 4 GDB communica
41. g operations The Intele UDK Debugger Tool supports GDB operations for Linux platforms including these critical operations e Embed a breakpoint in the source code Adding the CpuBreakpoint statement to the source code allows the GDB to enter interactive mode when the target executes the line e Add a function breakpoint in a debug session As long as a module s symbol file is loaded use of the break command to set a breakpoint for a function within the module is permissible Command syntax for the break command is break lt function_name gt In the following example a breakpoint is added to the IoBitFieldRead16 function foo foo break IoBitFieldRead16 GDB extension commands The following extension commands add additional functionality to GDB to assist debugging the target firmware They are provided by the udk gdb script set smmentrybreak set smmentrybreak onloff Specify whether or not the debugger stops the target machine when entering SMM set bootscriptentrybreak set bootscriptentrybreak onloff Specify whether the debugger stops the target machine before executing boot script set resetdelay set resetdelay lt 1 20 gt Specify the delay the host system will wait to begin running again after the target system resets 47 cpuid cpuid Index SubIndex Retrieves CPUID information Options Index Value of EAX priori to executing CPUID instruction defau
42. g to the surrounding text In describing variables a list is an unordered collection of homogeneous objects A queue is an ordered list of homogeneous objects Unless otherwise noted the ordering is assumed to be first in first out FIFO Pseudo code is presented in a C like format using C conventions where appropriate The coding style particularly the indentation style is used for readability and does not necessarily comply with an implementation of the UEFI specification Typographic conventions This document uses the typographic and illustrative conventions described below Plain text The normal text typeface is used for the vast majority of the descriptive text in a specification Plain text blue In the electronic version of this specification any plain text under lined and in blue indicates an active link to the cross reference Bold In text a Bold typeface identifies a processor register name In other instances a Bold typeface is used as a running head within a paragraph or to emphasize a critical term Italic In text an Italic typeface can be used as emphasis to introduce a new term or to indicate the title of documentation such as a user s manual or name of a specification Monospace Computer code example code segments pseudo code and all prototype code segments use a BOLD Monospace typeface with a dark red color These code listings normally appear in one or more separate paragraphs though wor
43. ified extensible firmware interface uefi driver and application tool resources html This procedure also assumes that the source code of the UEFI driver or application resides on the host machine To debug in the shell environment follow these general steps 1 Make sure the target machine has available debug port Serial Port or USB Debug Port 2 Build DebugAgentDxe driver in SourceLevelDebugPkg by configure the correct DebugCommunicationLib instance per debug port copy DebugAgentDxe efi into a USB memory stick 3 On the host system build the UEFI application or UEFI driver to be debugged and copy the executable output file such as example efi to the USB memory stick 4 Remove the USB memory stick from the host and plug it into the target system 5 Power up the target machine and wait for the target to boot to the UEFI shell 6 Connect the debug cable between the target and host machines 7 Start Debugging feature on target machine by following steps a If debug port is Serial Port 1 Get handle number of IsaSerialDxe Shell gt Drivers AS 60 2 Find the handle number of serial port managed by IsaSerialDxe by IsaSerialDxe s handle number Shell gt dh d AC 9FB3 11D4 9434 6996273FC14D DriverBinding 273FC14D t OxO Pc1 OxLF axe Child PciRoot x Pc Ox1F o 3 Disconnect the controller managed by IsaSerialDxe by serial port s handle number Shell gt disconnect EF 4 Lo
44. ints Note that they are not available in Windows because by design GDB doesn t use the IO concept gdb help iowatch Set a watchpoint for an IO address Usage iowatch SIZE PORT A watchpoint stops execution of your program whenever the IO address is either read or written PORT is an expression for the IO address to Access SIZE letters are b byte h halfword w word VALUE is an expression to write to the PORT gdb iowatch b 0x80 IO Watchpoint 1 80 1 Figure 24 Add IO watch point in GDB gdb help info iowatchpoints Status of specified IO watchpoint all watchpoints if no argument gdb info iowatchpoints Num Port Size 1 0x80 1 Figure 25 List IO watch point in GDB 51 gdb help delete iowatchpoints Delete some IO watchpoints Argument is IO watchpoints number To delete all IO watchpoints give no argument gdb delete iowatchpoints 1 Succeeded to delete IO watchpoint 1 Figure 26 Delete IO watch point in GDB 52 8 1 Known Limitations amp Issues for Linux platforms Known limitations The debug solution has these known limitations on a Linux platform Firmware output through the debug channel should not contain non ASCII characters Do not use more than three user specified breakpoints in the SEC PEI phase since hardware breakpoints are used for code executing from read only memory Code occurring before the source level debug package is initialized cannot be de
45. kg Library DebugAgent SmmDebugAgentLib inf 2 2 1 1 3 Debugging from DXE including SMM Table 3 Library instances by module type Module type Library instance SEC or PEI modules MdeModulePkg Library DebugAgentLibNull DebugAgentLibNull inf DxeCore and DXE SourceLevelDebugPkg Library DebugAgent DxeDebugAgentLib inf modules SMM modules SourceLevelDebugPkg Library DebugAgent SmmDebugAgentLib inf Cee Specify the appropriate Debug Communication library The non null Debug Agent library instances consume the Debug Communication library Because of this the appropriate library instance for the type of communication cable null modem or USB used to connect the target and host systems must be specified see the following table Table 4 Library instances by cable connection Connection type Library instance Serial connection SourceLevelDebugPkg Library DebugCommunicationLibSerialPort Debug CommunicationLibSerialPort inf This library instance depends on the Serial Port Library so an appropriate Serial Port Library instance for all modules dependent on it must also be specified USB 2 0 debug cable SourceLevelDebugPkg Library DebugCommunicationLibUsb DebugComm connection unicationLibUsb inf 22 13 Specify the appropriate Timer library The Debug Communication library consumes the Timer library Because of this a proper Timer library instance for modules in the DSC file including the SEC security module must be selected There is n
46. l modem cable LibraryClasses ifdef SOURCE_DEBUG_ENABLE PeCoffExtraActionLib SourceLevelDebugPkg Library PeCoffExtraAct ionLibDebug PeCoffExtraActionLibDebug inf DebugCommunicationLib SourceLevelDebugPkg Library DebugCommunic ationLibUsb DebugCommunicationLibUsb inf DebugAgentLib SourceLevelDebugPkg Library DebugAgent SecPeiDebu gAgentLib inf else PeCoffExtraActionLib MdePkg Library BasePeCoffExtraActionLibNul 1 BasePeCoffExtraActionLibNull inf 10 2 2 3 2 2 3 1 CL 3 2 255 2 2 3 4 DebugAgentLib MdeModulePkg Library DebugAgentLibNull DebugAgent LibNull inf endif Figure 5 Example macro using a USB 2 0 debug cable Configure a serial port for debug usage The DebugCommunicationLibSerialPort library instance consumes the Serial Port Library In addition to choosing an appropriate Serial Port Library for the target platform the serial port parameters on the target machine must be configured to match the settings on the host Baud rate In most cases it is preferable to set the baud rate to 115200 The baud rate should be the same on both the host and target machines If flow control is disabled and the serial connection is not stable specify a lower baud rate Hardware flow control On both Windows and Linux platforms flow control is on by default In most cases make sure to not disable flow control If the platform specific Serial Port Library does not support hardware flow control flow
47. latforms The Intel UDK Debugger Tool for Linux platforms helps in the use of GDB to debug Intel UEFI Development Kit 2010 Intel UDK2010 based firmware running on an IA 32 processor The Intel UDK Debugger Tool provides the host side software in binary form to support GDB remote debugging across a null modem cable With the Intel UDK Debugger Tool it is possible to e Debug source level code using GDB with a host running a Linux OS e Debug could begin as early as late SEC after temporary RAM set up for the normal boot path Start debugging SMM system management mode code by stopping the target at the next SMI system management interrupt Use a null modem cable as a debug cable Set unresolved breakpoints also known as pending breakpoints Debug code running on AP additional processors Late attach The following features are not yet supported for Linux platforms e Use of a USB 2 0 debug cable also known as a USB host to host cable or USB 2 0 debug device 41 7 2 1 Unresolved breakpoint setting in Linux By design GDB supports the unresolved breakpoint setting However the end user needs to recompile the GDB to include the Expat XML parsing library since a pre installed GDB does not include it Using the GDB as pre installed doesn t block the other features Use target x86_64 w64 mingw32 with expat as the parameter to configure the GDB before Make so it can use the Expat XML parsing library
48. le Index Bits Selector AsmReadCs AsmWriteIdtr IdtPtr Figure 12 Updated CPU Driver example Build the image and update flash memory before debugging source level code The image must be built and the flash memory updated before source level debugging is started If the macro SOURCE_DEBUG_ENABLE is used to turn on the debug feature conditionally use the following command to 19 build the image The following assumes the Conf target txt file is configured to identify the build target build D SOURCE_DEBUG_ ENABLE 22734 For Linux platforms For Linux platforms debug x64 code only when using GDB on x64 Linux platforms When debugging x64 Linux platforms make sure the firmware image is built on an x64 Linux machine so that the debug symbols are accessible to the GDB 20 3 1 Setup the Windows Debug Environment Introduction Setting up the Windows debug environment consists of four general steps 1 Build the firmware image and burn it to TARGET described earlier in Chapter 2 2 Install the Windows Debugger WinDbg on HOST 3 Install the Intel UDK Debugger Tool on HOST 4 Connect HOST and TARGET The following figure shows how the debug components interact on a Windows host during a debug session 21 Active components of a typical debug session on a Microsoft Windows XP platform Host machine Target machine Microsoft Windows XP Debugger Microsoft Windows Debug Tool WinDbg S
49. lts to 1 32 bit max base 16 SubIndex Value of ECX priori to executing CPUID instruction defaults to 0 32 bit max base 16 resettarget resettarget Resets the target system refresharch refresharch Queries the target processor for the processor mode i386 IA32 or i386x86 64 x64 The following four commands are only provided when GDB doesn t support setting an unresolved breakpoint info modules info modules ModuleName ModuleName Lists information about the loaded modules or the specified module s loadthis loadthis Loads the symbol file for the current IP Internet protocol address 48 loadimageat loadimageat lt hex address gt Loads the symbol file for the specified address loadall loadall Loads symbols for all loaded modules The commands below are executed with py prefix for example py pci py pci py pci Bus Dev Func Display PCI device list or PCI function configuration space Usage py pci Bus Dev Func Options Bus When only Bus is specified it is the starting bus number for enumeration 0 by default if not specified Otherwise the bus number of the PCI device whose configuration space is to be dumped Dev Device number of the PCI device whose configuration space is to be dumped Func Function number of the PCI device whose configuration space is to be dumped O by default if not specified py mtrr py
50. o single specific timer library appropriate for a platform or for the modules in the DSC file The appropriate library instance must be chosen based on knowledge of the platform 2 2 1 4 2 2 2 Specify the appropriate PeCoffExtraAction library The PeCoffExtraAction library instance is invoked each time a module is loaded or unloaded This library instance is responsible for informing the host that the target has loaded or unloaded a module In the DSC file the following PeCoffExtraAction library instance must be specified for any module that depends on the PeCoffExtraAction library class e SourceLevelDebugPkg Library PeCoffExtraActionLibDebug PeCoffExtra ActionLibDebug inf Turn debugging on or off Use a macro to turn the debug feature on or off The next two code samples show fragments in the LibraryClasses section that use a macro to do so LibraryClasses ifdef SOURCE_DEBUG ENABLE PeCoffExtraActionLib SourceLevelDebugPkg Library PeCoffExtraAct ionLibDebug PeCoffExtraActionLibDebug inf DebugCommunicationLib SourceLevelDebugPkg Library DebugCommunic ationLibSerialPort DebugCommunicationLibSerialPort inf DebugAgentLib SourceLevelDebugPkg Library DebugAgent SecPeiDebu gAgentLib inf else PeCoffExtraActionLib MdePkg Library BasePeCoffExtraActionLibNul 1 BasePeCoffExtraActionLibNull inf DebugAgentLib MdeModulePkg Library DebugAgentLibNull DebugAgent LibNull inf endif Figure 4 Example macro using a nul
51. ontroller that supports debugging and some motherboards may not wire this port to a physical USB port It can be difficult to discover the correct USB port for the USB debug cable If a valid USB debug port can t be located a USB debug cable cannot be used to establish a debug communication channel A few ways to identify the correct port follow e Read the EHCI controller datasheet and identify the port number supporting USB de bug The port number should be listed at bits 20 23 of the EHCI HCSPARAMS register e Plug the USB debug cable into one of the USB ports on the target system and boot to the UEFI shell Identify the device path of the USB debug cable and make sure the cable is plugged into the USB port supporting debug If not seen plug the USB debug cable into another USB port and view the device path again e Plug the USB debug cable into one of the USB ports on the target system Boot to Windows and launch the Microsoft UsbView tool usbview exe included with the Microsoft Windows Debugging Tools e Look at the USB device tree structure then identify the port number for the parent node of the USB debug cable device Count the ports from top to bottom in the list If the port number listed is not the one that supports USB debugging plug the USB debug cable into another USB port until a match is found Identify the correct USB connection orientation The Ajays USB 2 0 debug cable is a device used
52. or displayed when the terminal redirection port cannot be opened Features TerminalRedirectionPort 30000 Figure 29 Sample configuration for using 30000 as the terminal redirection port The following figure illustrates the data flow between TARGET and HOST from the end user s perspective The TCP Port is actually created by the Intel UDK Debugger Tool 56 9 3 9 4 TARGET HOST Debug Output AA a pany terminal TCP Port lt gt Le software e g PuTTY Text Output Setup Shell etc DebugAgent Communication OAT Packet Figure 30 Data flow between TARGET and HOST Trace With Trace the Intel UDK Debugger Tool logs the debug output during execution When a tool issue occurs the log can be sent back to the developer for root causing Tracing is turned off by default Enable it in your configuration file with the following code snippet Debug Trace 0x1f The log file is located in the root of the current user s home directory For example with Windows XP the log file is in C Document and Settings lt userid gt udk debugger trace log e For Windows 7 the log file is in C Users lt userid gt udk debugger trace log e For Linux the log file is in home lt userid gt udk debugger trace log Note that the log file is truncated to empty every time the Intel UDK Debugger Tool starts up and tracing is turned on CPU exception information The Intel UDK De
53. or to obtain the latest specifications and before placing your product order Intel Intel UEFI Development Kit Debugger Tool Intel UDK Debugger Tool and the Intel logo are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries Other names and brands may be claimed as the property of others Copyright 2012 Intel Corporation All rights reserved Contents Configuration OvervieW 0 cscdi te ess Sevan doaesenea i aoendesesan Gere eatnana A Gydereeeelsetoys 1 1 1 Document Purpose and Organization ipacosecsssessrusieczessssrwsnsnescseests 1 1 1 1 Configuration and Build sssssssssessessssssresrstsssstnesrsnesssrnnrsrssssrees 1 E12 WNAOWS es ionssrke ensena nae aiia AEE REE nR RR 1 LS LINUX snesena a a E a 1 1 1 4 Debugging Tips and Appendix s sssssssssssessssesresrsssssrsrrsrssesren 1 1 2 Tool Introd ctioN soiin eine ai at 2 1 3 Configuratii 2 2cccrisratussenecteancomanentueteuenemenesunceteer 2 1 3 1 Supported PlAO MMS s cs5 cssccanesceionsscnaraesatderereipeeccanecearauctes 2 1 3 2 Host and target configurations cee ceeeeeeeeteeeeeeeeteteeeeeees 3 1 3 3 Target COMMUNIC wis cecncsreranecaraasciettelacesaaninetemeseaudoeteiacs 4 1 3 4 Connection between host and target machines 6 1 4 OVMF platform and the debug ProceSs ec ceseecsseeeeesssseeeeeeeseees 6 Build the Firmware IMage ep ccexsssistmtecevsesuedansaseaeriousa ess
54. ource UEFI Intel UDK ee noel Deb eae ci package debugged Platform database file and source code Debug cable Figure 13 Active components of a debug session on a Microsoft Windows XP platform 3 2 Install the Windows Debugger on HOST Make sure the host machine is configured with Windows XP 32 bit SP3 or Windows 7 64 bit and the Windows Debugger WinDbg to be installed is an X86 version 3 3 Install the Intel Debugger Tool on HOST The debug port can be configured during installation If the TARGET has more than 16 logical processors open the SoftDebugger ini through Start gt All Programs gt Intel R UEFI Development Kit Debugger Tool gt Change Configurations Change Target System ProcessorCount to specify the number of logical processors in TARGET 3 4 Connect HOST and TARGET HOST and TARGET must be connected through a debug cable The Intel UDK Debugger Tool supports these cables e Null modem cable 22 e USB debug cable If a USB debug cable is used the correct USB port on the target machine must be specified see the next discussion Always connect the USB debug cable to HOST before connecting to TARGET Once both HOST and TARGET have been configured and connected a debug session can be started 23 24 Use the Debug Solution on a Windows Platform 4 1 Introduction This section introduces the Intel UDK Debugger Tool for the Windows platform and includes these main disc
55. quent debug function calls between modules are needed when using WinDbg use the PE image format instead of the terse execution TE image format When specifying the PE image format during build note that the rule section of the code should also be changed as needed On Linux systems GDB can handle both PE and TE image formats When using WinDbg the rule section for PEIM pre EFI initialization module must change as shown in the following examples Change from Rule Common PEIM FILE PEIM NAMED GUID PEI_DEPEX PEI_DEPEX Optional 16 2 2 6 INF_OUTPUT MODULE_NAME depex TE TE INF_OUTPUT MODULE_NAME efi UI STRING MODULE_NAME Optional VERSION STRING INF_VERSION Optional BUILD _NUM BUILD NUMBER Figure 10 PEIM original To Rule Common PEIM FILE PEIM NAMED GUID PEI _DEPEX PEI_DEPEX Optional depex PE32 PE32 Align 32 ef2 UI STRING MODULE_NAME Optional VERSION STRING INF_VERSION Optional BUILD _NUM BUILD NUMBER Figure 11 Revised rule change for PEIM Apply similar changes to the rule sections for SEC and PEI_CORE The corresponding rule section names may vary on different platforms but could look like Rule Common SEC or Rule Common PEI_CORE Update the CPU driver on ECP based platforms Most Intel UEFI Development Kit 2010 Intel UDK2010 compatibility platforms ECP use their own central processing unit CPU driv
56. rent module as well as all other modules that have executed if possible or applicable This list briefly describes basic debugging operations available through WinDbg e Open source code and set clear breakpoints e Open a disassembly window to see instructions around the current instruction pointer IP e Open a memory window to read or write memory In order to prevent a system hang on some platforms accessing 0 128M memory before physical memory is ready will not cause a similar memory access on the target system Instead dummy data is displayed The filtering capability is disabled during the transition from pre memory to post memory PEI For example the memory in OVMF is functional from reset and displays actual memory contents 1 Open a local variable window to read or to write local variables and function parameters The Od compiler option disables some optimization and makes sure all local variables are displayed in the output code At optimization levels above Od local variables optimized into registers are not visible Local variables stored on the stack may still been seen The same conditions apply to parameters passed into a function 2 Open a register window to read write general purpose registers 3 Open a call stack window to see the call stack and or parameter names and or values 4 Issue step into step over or go commands to tell the target to execute When using WinDbg on systems with m
57. s built on an x64 Linux machine so that the debug symbols are accessible to the GDB Windows Platforms For Windows platforms there are two special considerations to keep in mind aggressive zeroing and using the PE image format instead of TE These considerations are discussed later in this section Modify the configuration files for the firmware used by the target machine For best results appropriately configure the firmware in the TARGET machine to support debugging e The firmware in the target machine must include the Intel provided source level debug package because it supports debugging with the Intel UDK Debugger Tool e Update the platform s DSC FDF firmware device file files to ensure the appropriate library instances are selected DSC files contain information used during the FDF build process e The serial port or USB debug port may need to be configured for debugging 2 2 1 2gs 2 2 1 1 1 Table 1 2 2 1 1 2 e When making changes to DSC FDF files define a macro that allows for conditional turn on of the debug feature An example is shown later in this section Select the appropriate libraries When building the firmware the DSC file must include the appropriate libraries in order to use the Intel UDK Debugger Tool Be sure to specify instances of each of the following e Debug Agent library e Debug Communication library e Timer library e PeCoffExtraAction library Specify the appropriate De
58. sage is displayed advising that the TARGET code must be upgraded e The debug session is terminated e You should update TARGET firmware to use the latest SourceLevelDebugPkg Intel R UEFI Development Kit Debugger Tool le Se The debug target firmware does not meet the minimum requirements The current supported version of the SourceLevelDebugPkg is v0 8 or greater Figure 2 Current Tool to outdated TARGET connection advisory Similarly when an older version of the Intel UDK Debugger Tool connects to firmware with a current version of TARGET an upgrade advisory is issued tf van aR p y O L CAProgram Files inte Bugge oe we mgm Please launch the target system Debugging through Serial Port COMS5 115266 none gt See SecCoreStartupWithStack xFFFEC 66 6x86008 gt Send INIT break packet to HOST The SourceLevelDebugPkg you are using requires a newer version of the Intel lt R U DK Debugger Tool Figure 3 Current TARGET to outdated Tool connection advisory The Intel UDK Debugger Tool for Windows version 1 2 hides the debug console window given above This result is that in the upgrade advisory given above cannot be seen when that version of tool connects to a newer TARGET To show the debug console modify the configuration file with the following code snippet 1 3 4 1 4 Debug Debug 1 Connection between host and target machines The Intel UDK Debugger Tool supports the following
59. script resetdelay resetdelay lt time in second gt Specifies the time to delay between the debugger s reset on the target system and the start of the WinDbg session s setup on the host For example use this command to set the delay value to a non O value when a platform is setting up a timer and not clearing it in early SEC 31 Without a delay the hardware reset could interfere with the debug session Setting the delay to a value larger than the timer timeout value may resolve this problem Typically a delay of 10 seconds is enough This can help avoid the need to delay each reboot by clearing the timer early in the SEC phase cpuid cpuid Index SubIndex Retrieves CPUID information Options Index Value of EAX priori to executing CPUID instruction defaults to 1 32 bit max base 16 SubIndex Value of ECX priori to executing CPUID instruction defaults to 0 32 bit max base 16 NOTE The following commands are executed with py prefix for example py pci Ipy pci Ipy pci Bus Dev Func Display PCI device list or PCI function configuration space Options Bus When only Bus is specified it is the starting bus number for enumeration 0 by default if not specified Otherwise the bus number of the PCI device whose configuration space is to be dumped Dev Device number of the PCI device whose configuration space is to be dumped Func Function number of the PCI device
60. se more than three user specified breakpoints in the SEC PEI phase since hardware breakpoints are used for code executing from read only memory Code occurring before the source level debug package is initialized cannot be debugged This includes early SEC code early SMM code and other code The TE image header is emulated as a PE header for WinDbg As a result the contents of the TE header are not visible to WinDbg During the SEC PEI phases only one processor the BSP or boot strap processor can be debugged This also applies to the DXE phase before the Multiple Processor MP Services Protocol is installed While in the DXE phase after the MP Services Protocol has been installed switching to other active processors AP or Additional Processors is possible Debugging is not supported if the CPU is executing in 16 bit real mode If the CPU is executing with interrupts disabled breaks from the host to the target are not supported When using the USB debug cable as the debug communication channel USB devices cannot be detected on any other USB ports associated with the same EHCI controller USB ports associated with other EHCI controllers are not impacted Only AP code invoked by the Platform Initialization Multiprocessor Services Protocol can be debugged 35 36 For example on EdkCompatibilityPkg based platforms AP code invoked through the Framework Multiprocessor Services Protocol cannot be debugged 6 1
61. t Win7 64 bit platform e Microsoft Windows Debug Tool WinDbg 6 11 0001 404 X86 WinDbg is available for download at http msdl microsoft com download symbols debuggers dbg x86 _ 6 11 1 404 msi e Intel UDK Debugger Tool which adds functionality to WinDbg is available for download at www intel com udk Host configuration for Linux platforms This user manual assumes you have a working knowledge of the Intel UEFI Development Kit 2010 Intel UDK2010 and the GNU Project Debugger GDB for Linux platforms Using the Intel UDK Debugger Tool on a Linux platform requires a host machine configured with e A supported Linux operating system Fedora 15 IA32 and x64 client SUSE SLES 11 SP1 Enterprise Server and SP2 Beta beta 3 or later x64 Ubuntu 32 Ubuntu 10 x or later IA32 client Ubuntu 64 11 10 x64 client Ubuntu 10 x or later x64 client LTS server x64 e GNU Project Debugger GDB e Intele UDK Debugger Tool which adds functionality to GDB It is available at www intel com udk Target configuration The target machine must have a firmware build that includes the source level debug package SourceLevelDebugPkg a part of the Intel UEFI Development Kit 2010 Intel UDK2010 located at www tianocore org http tianocore souorceforge net When the Intel UDK Debugger Tool connects to the TARGET firmware with an older version of SourceLevelDebugPkg code e An error mes
62. tcher not defined Make breakpoint pending on future shared library load y or n y Breakpoint 1 PeiDispatcher pending gdb c Continuing Breakpoint 1 PeiDispatcher SecCoreData 0x7ffac Private 0x7f548 at home ray work AllPackagesDev MdeModulePkg Core Pei Dispatch er Dispatcher c 623 623 Figure 21 Add the unresolved breakpoint in GDB General debug flow There are three general steps in the typical debug process 1 Build the firmware image including the source level debug package provided by Intel See Figure 22 Each time the firmware image is rebuilt the source level debug package must be included If the debug package is not included the Intel UDK Debugger Tool cannot be used to debug the target firmware The files to edit for the source level debug package are included in the build image Those files ensure that the firmware build has debug capability until debug related changes are explicitly removed from the files 2 Program the firmware image into flash memory on the target system 3 Launch and debug on the host system with a debugger that includes the functionality added by the Intel UDK Debugger Tool 43 7 4 7 4 1 Target system UDK based firmware Firmware image Source level debug package SourceLevelDebugPkg Each firmware build must include the source level debug package which provides the debugger capabilities on the target system Figure 22 Compilin
63. tes with the target system via the GDB server When prompted by the GDB server connect the GDB to the GDB server by entering the following command in GDB Inthe command line replace lt HOST gt with the name of the target machine target remote lt HOST gt 1234 5 Run third party terminal software to connect the terminal redirection port to get the debug output and terminal output from the firmware 6 Enter the following command in GDB to load the GDB extension for the Intel UDK Debugger Tool source opt intel udkdebugger bin udk gdb script The GDB extension commands can now be used to begin debugging the target firmware at the source level Extension commands are described at the end of this section Start a GDB debug session using late attach 1 Power up the target system The system must include the Intel UEFI Development Kit 2010 Intel UDK2010 based firmware image built with the source level debug package and it must have the debug feature enabled Atthe shell prompt start the GDB server by entering the appropriate command similar to the following foo foo usr bin udk gdb server This command line is a symbolic link to opt intel udkdebugger bin udk gdb server A message similar to the following should appear 45 7 4 3 UDK GDB Server Version 1 2 Waiting for the connection from the Target Debugging through serial port dev ttyS0 115200 Hardware Redirect TARGET output
64. third party terminal software such as PuTTY as shown below The output from the TARGET firmware can be redirected to the terminal software and the end user input from the terminal software can be redirected to the TARGET firmware ff amoo E ____ Basic options for your PuTTY session Specify the destination you want to connect to Host Name or IP address Port localhost 20715 Connection type Raw Telnet Rogn SSH Serial Load save or delete a stored session Saved Sessions Default Settings Load Figure 27 Using PuTTY to connect to the terminal redirection port 55 When source level debug is enabled the debugger uses the serial port for command packet communication and PuTTY cannot connect to the serial port because it s already in use by the debugger To enable the ability to type in shell commands from PuTTY the debugger redirects the firmware output to the TCP port and redirects the input from the TCP port to firmware This enables a user to connect PuTTY to the TCP port for typing in shell commands and viewing firmware output If the tool is unable to use the selected TCP Port it displays an error message as shown in Figure 28 To correct this issue modify the configuration file to use a different TCP port as shown in the following example Intel R UEFI Development Kit Debugger Tool lt x Terminal port redirection failed on port 20715 Figure 28 Err
65. to TCP port 20715 GdbServer on lt HOST gt is waiting for connection on port 1234 Connect with target remote lt HOST gt 1234 2 GDB communicates with the target system via the GDB server When prompted by the GDB server connect the GDB to the GDB server by entering the following command in GDB Inthe command line replace lt HOST gt with the name of the target machine target remote lt HOST gt 1234 3 Run third party terminal software to connect the terminal redirection port and get the debug and terminal output from the firmware 4 Enter the following command in GDB to load the GDB extension for the Intel UDK Debugger Tool source opt intel udkdebugger bin udk gdb script The GDB extension commands can now be used to begin debugging the target firmware at the source level Extension commands are described at the end of this section End the GDB debug session To end a GDB debug session follow these steps 1 Halt the TARGET if the TARGET is running 2 In GDB enter the quit command to end the debugging session gdb quit A debugging session is active Inferior 1 Remote target will be detached Quit anyway y or n y qTStatus Remote connection closed user user Ubuntul1 64 S Figure 23 Detach in GDB NOTE Closing GDB without running the quit command leaves the TARGET firmware in an intermediate state and it cannot be reattached until restarted 46 75 7 5 1 Basic GDB debuggin
66. ttach cccccsssccccecessesssececeeesessesneaeeeeeeeseessaaeas 29 Figure 18 Active components of a debug session on a Linux platform ceceeeseeeees 38 Figure 19 Output when sourcing udk script if GDB includes Expat XML parsing library 42 Figure 20 Output when sourcing udk script if GDB doesn t include Expat XML parsing library PEE EA A duty egal eae adh ve Sues eve teed ona Code tone danse va suas awa NEE Geet sue aeons eeeaen te 42 Figure 21 Add the unresolved breakpoint in GDB cccceccssessssececeeeseesesnsaeeeeeeeseesseaeas 43 Figure 22 Compiling a firmware image with the source level debug package 44 Figure 23 Detach GDB aa aie ie E n aE E Enana a ar AR aa i eh aa a hes 46 Figure 24 Add IO watch pointin GDB sssssssssssssssssensrssssrserrrsrsssserreresssssserernessssesrrernesse 51 Figure 25 List IO watch pointin GDB aeaaee aaae aa aeaa 51 Figure 26 Delete IO watch point in GDB ceeccccsssseceeececeesesseaeeeceesseessssaeeeeeesseesenaeas 52 Figure 27 Using PuTTY to connect to the terminal redirection port ccccccccccesessseeees 55 Figure 28 Error displayed when the terminal redirection port cannot be opened 56 Figure 29 Sample configuration for using 30000 as the terminal redirection port 56 Figure 30 Data flow between TARGET and HOST cccccccccccsssssssssseceeesessssssaeeeeeesseeseeaees 57 Figure 31 Output in GDB when a CPU exception happens in firmware ccccccee
67. ultiple processors step into and step over will cause only one processor to execute and leave other processors at the stopped state The go command causes all processors to start execution Only one processor at a time can be debugged when using DBG 5 Issue the break command while the target is running to break in On multiple processor systems WinDbg only all active processors will be stopped 6 Open a Processes and Threads window to view and specify the current processor to emulate 30 4 4 1 On multiple processor systems WinDbg only each logical processoris emulated as a separate thread 7 Use the Watch window to look at global variables i e gBS gST gRT gDS WinDbg extension commands The following extension commands add additional functionalities to WinDbg to assist debugging target firmware They are provided by the UdkExtension dll smmentrybreak smmentrybreak onloff Controls whether the target should stop the next time SMM mode is entered e Set the command to on to make the target stop on the next SMM entry e Set the command to off to prevent the target from stopping on the next SMM entry bootscriptentrybreak bootscriptentrybreak on off Controls whether the target should stop before executing boot script e Set the command to on to make the target stop before executing boot script e Set the command to off to prevent the target from stopping before executing boot
68. ussions e General debug flow e Using the WinDbg debug solution Start and stop a debug session e Basic debugging operations including WinDbg extension commands 4 2 Supported features The Intel UDK Debugger Tool for Windows platforms helps in the use of WinDbg to debug Intel UEFI Development Kit 2010 Intel UDK2010 based firmware running on an IA 32 processor The Intel UDK Debugger Tool provides the host side software in binary form to support WinDbg remote debugging across a null modem cable or USB debug cable With the Intel UDK Debugger Tool it is possible to e Debug source level code using WinDbg with a host running a Windows OS e Debug could begin as early as late SEC after temporary RAM set up for the normal boot path e Start debugging SMM system management mode code by stopping the target at the next SMI system management interrupt Setting unresolved breakpoints also known as pending breakpoints Debugging code running on AP additional processors Late attach Using a null modem cable or a USB 2 0 debug cable also known as a USB host to host cable or USB 2 0 debug device 4 3 General debug flow There are three general steps in a typical debug process 25 1 Build Build the firmware image including the source level debug package provided by Intel See Figure 14 CAUTION Each time the firmware image is rebuilt the SourceLevelDebug package must be included If 4 3 1 the SourceLev
69. ut from the firmware WinDbg settings can now be configured to set breakpoints To resume execution on the target click go in the WinDbg tool bar When the target execution encounters a breakpoint WinDbg automatically enters interactive mode In this mode it is ready to accept commands In addition the corresponding source code is loaded to the source window To break the execution click break on the WinDbg tool bar The target image can still run without a host side debugger In this situation the target image will pause for a few seconds at a time to continue trying to detect the existence of a debug host and will perform a normal boot if a timeout occurs Start a WinDbg session using late attach Follow these steps to start a WinDbg session 1 Start up the target system using the Intel UEFI Development Kit 2010 Intel UDK2010 based firmware image with the debug feature enabled 28 4 3 3 2 Launch Start WinDbg using UDK Debugger Tool from Windows Start gt All Programs gt Intel UDK Debugger Tool 3 Wait a few seconds until WinDbg is connected and ready to accept commands WinDbg should stop the target and load the symbols for the current module It will then display source code looking similar to the following figure allowing for different machines and user preferences File Edit View Debug Window Help ore S O ROO 8 amp OOS fit Aa Disassembly Command eXDI exdizclsid F56FC1A6 3

Intel® UEFI Development Kit Debugger Tool Configuration and

Contents

Download Pdf Manuals

Related Search

Related Contents

Intel&reg; UEFI Development Kit Debugger Tool Configuration and

Contents

Download Pdf Manuals

Related Search

Related Contents

Intel® UEFI Development Kit Debugger Tool Configuration and