---?image=assets/images/gitpitch-audience.jpg @title[EDK II UDK Debugger]

UEFI & EDK II Training

EDK II UDK Debugger

Please be aware that this tool has been EOL
The replacement is the Intel System Studio Debugger

tianocore.org Note: PITCHME.md for UEFI / EDK II Training EDK II UDK Debugger Pres

Redistribution and use in source (original document form) and 'compiled' forms (converted to PDF, epub, HTML and other formats) with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code (original document form) must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified.
Redistributions in compiled form (transformed to other DTDs, converted to PDF, epub, HTML and other formats) must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS DOCUMENTATION IS PROVIDED BY TIANOCORE PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL TIANOCORE PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

@title[Lesson Objective]

<p align="center"Lesson Objective

@fa[certificate gp-bullet-green] Identify the Intel® UEFI Development Kit Debugger
host and target basic configuration and components
@fa[certificate gp-bullet-cyan] Access the debugger tools
@fa[certificate gp-bullet-gold] Make changes to the target firmware
@fa[certificate gp-bullet-ltgreen] Launch the debug application
@fa[certificate gp-bullet-yellow] Use debug commands
@fa[certificate gp-bullet-magenta] Debugging PI’s phases

---?image=assets/images/binary-strings-black2.jpg @title[UDK Debugger Overview Section]

UDK Debugger Overview

Intel® UEFI Development Kit Debugger Tool

Note:

@title[UDK Debugger Overview]

Intel® UEFI Development Kit Debugger Tool

@ul[no-bullet] - @fa[star gp-bullet-magenta]  Source level debug of UEFI firmware, drivers &
        OpROM - @fa[star gp-bullet-gold]  Low-cost alternative to ITP/JTAG debug - @fa[star gp-bullet-green]  Host-to-target connect via COM port or USB debug
         port - @fa[star gp-bullet-cyan]  Open source based on existing software debuggers
         for Windows & Linux - @fa[star gp-bullet-ltgreen]  User Manual PDF @ulend

Note:

---?image=/assets/images/slides2/Slide5.JPG @title[UDK Debugger tool block diagram]

Intel® UEFI Development Kit Debugger Tool

@snap[south span-95 fragment] @box[bg-purple-pp text-white rounded my-box-pad2 ](

Source Level Debugger for UEFI

) @snapend

Note:

This slide represents a block diagram of the Host machine connected to the Target using the Host Debugger tools
- Linux GDB
- Windows WinDBG
The build of the target machine needs to be on the host including all the debug and symbol file information
the UDK Debugger works like a layer inbetween the host machines debugger to intercept the information coming to /from the target debug output
The target machine needs to also be built with the SourceDebugPkg libraries.

Source Level Debugger for UEFI - EDK II

---?image=/assets/images/slides2/Slide6.JPG @title[Host & Target Debug Setup]

Host & Target Debug Setup

@snap[north span-35 ]

Null Modem Cable or
USB 2.0 Debug or USB 3.0 Cable

@snapend

Note:

@title[Distribution ]

Distribution

Tool EOL replaced by Replaced by Intel System Studio

Target source: `SourceLevelDebugPkg` at @fa[github gp-bullet-gold] Tianocore.org

Note:

Binary application for host on Windows or Linux from http://firmware.intel.com
Source code for Target from tianocore.org via github

---?image=/assets/images/slides2/Slide8.JPG @title[Host Configuration Requirements - Windows ]

Host Configuration Requirements

@fa[windows gp-bullet-cyan] Microsoft Windows

XP with Service Pack 3 and Windows 7 and Windows 10
Debug Tool (WINDBG) x86, version 6.11.0001.404
Intel UDK Debugger Tool
WinDBG Extensions in edk2.dll http://msdl.microsoft.com/ ... /dbg_x86_6.11.1.404.msi

Details on WinDBG - Debugging using WinDBG

Note:

May need to search for the version of WinDBG

---?image=/assets/images/slides2/Slide9.JPG @title[Host Configuration Requirements - Linux ]

Host Configuration Requirements

@fa[linux gp-bullet-white] Linux

Ubuntu 16.04 LTS client (x64 build)- validated and examples shown

GNU Debugger (GDB) - with Expat library

Intel UDK Debugger Tool 1.5.1

Note:

---?image=/assets/images/slides/Slide12.JPG @title[Host Configuration Requirements - Linux GDB ]

Host Configuration Requirements -GDB

Check for the configuration of GDB that is installed ```bash bash$ gdb --configuration ```

Install `gdb` if not installed

```
bash$ sudo apt-get update
bash$ sudo apt-get install gdb
```

Download `gdb` source and compile with Expat library if there is no "`--with-expat`" as on the screen shot here

```
bash$ ./configure --target=x86_64-w64-mingw32 --with-expat
bash$ make
```

Note:

If need to compile with expat

 // 1. Download and extract
 bash$ wget "http://ftp.gnu.org/gnu/gdb/gdb-7.11.tar.gz" 
 bash$ tar -xvzf gdb-7.11.tar.gz 
 // 2. Configure and compile
 bash$ apt-get install libexpat1-dev
 bash$ apt-get install expat
 bash$ cd gdb-7.11
 bash$ ./configure --target=x86_64-w64-mingw32 --with-expat
 bash$ make 
 // 3. install
 bash$ make install

---?image=/assets/images/slides/Slide13.JPG @title[Install UDK Debugger - Linux ]

Install UDK Debugger - Linux

Please be aware that this tool has been EOL
The replacement is the Intel System Studio Debugger

Extract the .zip file to a temp directory

```
bash$ cd 
bash$ sudo chmod +x UDK_Debugger_Tool_v1_5_1.bin
  // run the installer
bash$ sudo ./UDK_Debugger_Tool_v1_5_1.bin
```

The tool will be installed to `/opt/intel/udkdebugger` by default

Configuration file: `/etc/udkdebugger.conf`

Note:

+++?image=/assets/images/slides/Slide14.JPG @title[Install UDK Debugger - Linux 02]

Install UDK Debugger - Linux

Menu to configure the tool for the port

Configure Debug Port Menu

```
 // Debug Port Channel
   Serial or USB
 // Port:  using FTDI USB Serial use `bash$ dmesg` to check 
   /dev/ttyUSB0
 // Baudrate:
   115200
 // Flow control  
   none
```

Configuration file: `/etc/udkdebugger.conf`

Note:

---?image=/assets/images/slides2/Slide13.JPG @title[Debug Cable Options]

Debug Cable Options

@snap[north-west span-30 ]

@size[1.2em](Serial Null Modem)

•  @size[.85em](Target must support standard RS-232 COM port)
•  @size[.85em](Host can support standard RS-232 or USB COM port)
•  @size[.85em](Supported by Windows & Linux)

@snapend

@snap[north span-30 fragment]

@size[1.2em](  USB 2.0 Debug)

•  @size[.85em](EHCI debug descriptor (using NET20DC adapter or AMI Debug Rx device))
•  @size[.85em](Target must support USB 2.0 EHCI debug port)

@snapend

@snap[north-east span-30 fragment]

@size[1.2em]( USB 3.0)

• @size[.85em](Added Release 1.5)

@snapend

Note:

Serial Null Modem
USB 2.0 Debug
USB 3.0

---?image=assets/images/binary-strings-black2.jpg @title[Changes to target Section]

Changes to target

Required changes needed to be built with the target
platform

Note:

---?image=/assets/images/slides/Slide20.JPG @title[Changes to Target Firmware]

Changes to Target Firmware

Goal: Minimize changes to target firmware

Add call to the library class (`DebugAgentLib`) In `SEC`, `DXE` Main, and `SMM CPU` Modules

Or if you don’t want to add one A `NULL` implementation of `DebugAgentLib` is checked into open source

Note:

Goal: Minimize changes to target firmware
Add call to new library class (DebugAgentLib) One in SEC, one in DXE Main, one in SMM CPU Module
Or if you don’t want to add one A NULL implementation of DebugAgentLib will be checked into open source so all modules can build with debug feature disabled

@title[Updates to DSC]

Updates to DSC

@snap[north-west span-100 ]

@box[bg-grey-15 text-white rounded my-box-pad2 ](

) @snapend

@snap[north-west span-50 ]

Libraries

  [LibraryClasess] General
     PeCoffExtraActionLib
     DebugCommunicationLib

  [LibraryClasses.IA32] SEC / PEI
     DebugAgentLib

  [LibraryClasses.X64] DXE
     DebugAgentLib

  [LibraryClasses.X64.DXE_SMM_DRIVER] SMM
     DebugAgentLib

@snapend

@snap[north-east span-55 ]

`SourceLevelDebugPkg`
Lib Instance

@size[1.5em](➣)  PeCoffExtraActionLibDebug.inf
@size[1.5em](➣)  DebugCommunicationLibSerialPort.inf
       or
@size[1.5em](➣)  DebugCommunicationLibUsb.inf

@size[1.5em](➣)  SecPeiDebugAgentLib.inf

@size[1.5em](➣)  DxeDebugAgentLib.inf

@size[1.5em](➣)  SmmDebugAgentLib.inf

@snapend

@snap[north-east span-60 fragment]

@size[4.5em]({) @size[4.5em](})

@snapend

@snap[north-east span-65 fragment]

    COM1
    OR
    USB

@snapend

Note:

Library class sections

 [LibraryClasess]  General
  PeCoffExtraActionLib PeCoffExtraActionLibDebug.inf

 DebugCommunicationLib
   DebugCommunicationLibSerialPort.inf
     or
   DebugCommunicationLibUsb.inf

 [LibraryClasses.IA32] SEC/PEI
  DebugAgentLib SecPeiDebugAgentLib.inf

 [LibraryClasses.X64] DXE
  DebugAgentLib DxeDebugAgentLib.inf

 [LibraryClasses.X64.DXE_SMM_DRIVER] SMM
  DebugAgentLib SmmDebugAgentLib.inf

@title[Updates to DSC USB 3.0]

Updates to DSC for USB 3.0

@snap[north-west span-100 ]

@box[bg-grey-15 text-white rounded my-box-pad2 ](

) @snapend

@snap[north-west span-50 ]

Libraries

  [LibraryClasess] General
     PeCoffExtraActionLib

  [LibraryClasses.IA32] SEC / PEI
     DebugCommunicationLib
     DebugAgentLib

  [LibraryClasses.X64] DXE
     DebugCommunicationLib
     DebugAgentLib

  [LibraryClasses.X64.DXE_SMM_DRIVER] SMM
     DebugCommunicationLib
     DebugAgentLib

@snapend

@snap[north-east span-55 ]

`SourceLevelDebugPkg`
Lib Instance

@size[1.5em](➣)  PeCoffExtraActionLibDebug.inf

@size[1.5em](➣)  DebugCommunicationLibUsb3Pei.inf
@size[1.5em](➣)  SecPeiDebugAgentLib.inf

@size[1.5em](➣)  DebugCommunicationLibUsb3Dxe.inf
@size[1.5em](➣)  DxeDebugAgentLib.inf

@size[1.5em](➣)  DebugCommunicationLibUsb3Dxe.inf
@size[1.5em](➣)  SmmDebugAgentLib.inf

@snapend

Note:

Library class sections for USB 3.0

 [LibraryClasess]  General
  PeCoffExtraActionLib PeCoffExtraActionLibDebug.inf

 [LibraryClasses.IA32] SEC/PEI
  DebugAgentLib SecPeiDebugAgentLib.inf
  DebugCommunicationLib DebugCommunicationLibUsb3Pei.inf

 [LibraryClasses.X64] DXE
  DebugAgentLib DxeDebugAgentLib.inf
  DebugCommunicationLib DebugCommunicationLibUsb3Dxe.inf

 [LibraryClasses.X64.DXE_SMM_DRIVER] SMM
  DebugAgentLib SmmDebugAgentLib.inf
  DebugCommunicationLib DebugCommunicationLibUsb3Dxe.inf

@title[Updates to FDF]

Updates to FDF

Update for the Firmware Volume `FVMAIN`
- this is so there is no conflict with the terminal console driver

```php [FV.FVMAIN] . . . # DXE Phase modules . . . # Comment out module for Terminal driver # INF IntelFrameworkModulePkg/Bus/Isa/IsaSerialDxe/IsaSerialDxe.inf ``` Updates to INF - Default with "Debug" builds ```php //. . . [BuildOptions] MSFT:*_*_*_CC_FLAGS = /Od /Oy- ```

Note:

@title[Configure COM Port (PCD) (Target)]

Configure COM Port (PCD) (Target)

@fa[bullseye gp-bullet-green] Configure target to use COM port via PCD
@fa[bullseye gp-bullet-yellow] Ensure COM port not used by other project
modules/features
@fa[bullseye gp-bullet-magenta] COM 1 is the default on target
@fa[bullseye gp-bullet-cyan] Simple “ASCII Print” though COM port is allowed
@fa[bullseye gp-bullet-ltgreen] Non-NULL DebugAgent library instance must be used

---?image=/assets/images/slides/Slide14.JPG @title[Configure Host - Linux ]

Configure the Host - Linux

Menu to configure the tool for the port on installation

Configure Debug Port Menu

```
 // Debug Port Channel
   Serial or USB
 // Port:  using FTDI USB Serial use `bash$ dmesg` to check 
   /dev/ttyUSB0
 // Baudrate:
   115200
 // Flow control  
   none
```

OR update the Configuration file: `/etc/udkdebugger.conf`

Note:

---?image=assets/images/binary-strings-black2.jpg @title[Debugging using GDB Section]

Debugging using GDB

Note:

@title[Source Level Debug Features]

Source Level Debug Features

@ul[no-bullet] - View call stack Go

-    Insert `CpuBreakpoint()`

-    View and edit local/global variables

-    Set breakpoint    Step into/over routines

- Go till View disassembled code

- View/edit general purpose register values
@ulend

Note:

use gdb help to see how to

---?image=/assets/images/slides/Slide35.JPG @title[Launching UDK Debugger- Linux udk ]

Launching UDK Debugger- Linux

Example showing Ubuntu 16.04 LTS with GDB

Need to open 3 Terminal prompt windows
First Terminal(1) is the UDK debugger server

```
 bash$ cd opt/intel/udkdebugger
 bash$ ./bin/udk-gdb-server
```

Power on the Target and wait 2-3 seconds

Note:

---?image=/assets/images/slides/Slide36.JPG @title[Launching UDK Debugger- Linux gdb]

Launching UDK Debugger- Linux

Example showing Ubuntu 16.04 LTS with GDB

Open a second Terminal(2) for GDB

```
 bash$ cd opt/intel/udkdebugger
 bash$ gdb
```

Attach to the UDK debugger

```
 (gdb) target remote :1234
```

Terminal(1) will show "Connection from localhost" message

Note:

---?image=/assets/images/slides/Slide37.JPG @title[Launching UDK Debugger- Linux -scripts]

Launching UDK Debugger- Linux

Example showing Ubuntu 16.04 LTS with GDB

Open the udk scripts in GDB - Terminal(2)

```
 (gdb) source ./script/udk_gdb_script
```

Symbols will show for PeiCore, also notice the prompt changes from "(gdb)" to "(udb)"

Note:

---?image=/assets/images/slides/Slide38.JPG @title[Launching UDK Debugger- terminal]

Launching UDK Debugger- Linux

Optional - open a 3rd Terminal(3) with a terminal program
- Example showing "screen" terminal program

Note:

most debugging will be from Teriminal(2)
terminal (3) is just to see where it is.

---?image=/assets/images/slides/Slide42.JPG @title[UDK Debugger - setting break points]

UDK Debugger - Setting break points

Terminal(2) Breakpoint at PeiDispatcher

```
 (udb) b PeiDispatcher
```

Break at Port 0x80

```
 (udb)iowatch/b 0x80
```

Break at absolute address

```
 (udb)b *0xfff94a68
```

Note:

---?image=assets/images/binary-strings-black2.jpg @title[Debugging through Boot phases Section]

Debugging Thru boot flow

Note:

---?image=/assets/images/slides/Slide43.JPG

@title[Debugging the Boot Phases]

Debugging the Boot Phases

Note:

+++?image=/assets/images/slides/Slide44.JPG

@title[Debugging the Boot Phases 02]

Debugging the Boot Phases

Note:

+++?image=/assets/images/slides/Slide45.JPG

@title[Debugging the Boot Phases 03]

Debugging the Boot Phases

Note:

+++?image=/assets/images/slides/Slide46.JPG

@title[Debugging the Boot Phases 04]

Debugging the Boot Phases

Note:

---?image=/assets/images/slides/Slide48.JPG @title[Debugging the Boot Phases SEC]

Debugging the Boot Phases - SEC

Debugging Sec phase

@snap[south-west span-100 fragment ]

@size[8em](@color[red](X)) @color[yellow](SORRY) - Requires a hardware debugger

@snapend

Note:

SEC Must use hardware debugger, not Intel® UEFI Development Kit Debugger

---?image=/assets/images/slides/Slide50.JPG @title[Debugging the Boot Phases PEI]

Debugging the Boot Phases - PEI

Use debugger prior to PEI Main
Check proper execution of PEI drivers
Execute basic chipset & Memory init.
Check memory availability
Complete flash accessibility
Execute recovery driver
Detect DXE IPL

Note:

SEC Must use hardware debugger, not Intel® UEFI Development Kit Debugger
Begin using debugger prior to PEI Main
Check proper execution of all PEI drivers
Execute basic chipset initialization
Execute memory initialization instructions
Check availability of memory
Complete flash accessibility
Execute recovery driver if the recovery jumper is selected, and execution of recovery path if recovery is detected
Detection of DXE IPL PEIM which in turn detects and launches the DXE core

@title[PEI Phase: Trace Each PEIM]

PEI Phase: Trace Each PEIM

There is a loop function in :
@fa[github gp-bullet-gold] MdeModulePkg/Core/Pei/Dispatcher/Dispatcher.c
Add `CpuBreakpoint();` before launching each PEIM

VOID
PeiDispatcher (
  IN CONST EFI_SEC_PEI_HAND_OFF  *SecCoreData,
  IN PEI_CORE_INSTANCE           *Private
  )
{// ...
        // Call the PEIM entry point
        //
        PeimEntryPoint = (EFI_PEIM_ENTRY_POINT2)(UINTN)EntryPoint;
        PERF_START (PeimFileHandle, "PEIM", NULL, 0);
// Add a call to CpuBreakpoint();  approx. line 1004
        CpuBreakpoint();
        PeimEntryPoint(PeimFileHandle, (const EFI_PEI_SERVICES **) &Private->Ps);

Note:

For Loop in Function: PeiDispatcher()
- MdeModulePkg/Core/Pei/Dispatcher/Dispatcher.c
Trace all PEIMs dispatched in PEIMAIN module
PeiDispatcher() function - set a break point at the main dispatch loop before each PEIM Entry
- // Call the PEIM entry point
CpuBreakpoint() ;
- PeimEntryPoint(PeimFileHandle, (const EFI_PEI_SERVICES **) &Private->Ps);
On breakpoint, step into function to trace PEIMs

@title[Check for transition from PEI to DXE]

Check for transition from PEI to DXE

Critical point before calling DXE in:
@fa[github gp-bullet-gold] MdeModulePkg/Core/Pei/PeiMain.c
Add `CpuBreakpoint();` before entering DxeIpl

VOID
EFIAPI
PeiCore (
  IN CONST EFI_SEC_PEI_HAND_OFF        *SecCoreDataPtr,
  IN CONST EFI_PEI_PPI_DESCRIPTOR      *PpiList,
  IN VOID                              *Data
  )
{ // ...
  // Enter DxeIpl to load Dxe core.
  //
  DEBUG ((EFI_D_INFO, "DXE IPL Entry\n"));
// Add a call to CpuBreakpoint();  approx. line 468
  CpuBreakpoint();
  Status = TempPtr.DxeIpl->Entry (
                             TempPtr.DxeIpl,
                             &PrivateData.Ps,
                             PrivateData.HobList

Note:

There may also be issues with transition from 32 to 64 bit so this makes a good place to add a breakpoint

@title[Check for transition from DxeIpl to DXE]

Check for transition from DxeIpl to DXE

Critical point before calling DXE Core in:
@fa[github gp-bullet-gold] MdeModulePkg/Core/DxeIplPeim/DxeLoad.c
Before entering Dxe Core ( Notice also this is a standalone module - DxeIpl.efi)

EFI_STATUS
EFIAPI
DxeLoadCore (
  IN CONST EFI_DXE_IPL_PPI *This,
  IN EFI_PEI_SERVICES      **PeiServices,
  IN EFI_PEI_HOB_POINTERS  HobList
  )
{ // ...
  // Transfer control to the DXE Core
  // The hand off state is simply a pointer to the HOB list
  //
// Add a call to CpuBreakpoint();  approx. line 790
  CpuBreakpoint();
  HandOffToDxeCore (DxeCoreEntryPoint, HobList);
  //
  // If we get here, then the DXE Core returned.  This is an error

Note:

Check for transition from IPL to DXE
MdeModulePkg/Core/DxeIplPeim/DxeLoad.c
Verify address of DXE Core Entry point after IPL from PEI – DxeLoadCore function in DxeIpl->Entry()
HandOffToDxeCore call (DxeCoreEntryPoint)

 // Transfer control to the DXE Core
 // The hand off state is simply a pointer to the HOB list
 //
   CpuBreakpoint() ;
    HandOffToDxeCore (DxeCoreEntryPoint, HobList);
 //
 // If we get here, then the DXE Core returned.  This is an error

---?image=/assets/images/slides/Slide55.JPG @title[Debugging the Boot Phases DXE]

Debugging the Boot Phases - DXE

Search for cyclic dependency check
Trace ASSERTs caused during DXE execution
Debug individual DXE drivers
Check for architectural protocol failure
Ensure BDS entry call

Note:

@title[DXE: Trace Each Driver Load]

DXE: Trace Each Driver Load

DXE Dispatcher calls to each driver's entry point in:
@fa[github gp-bullet-gold] MdeModulePkg/Core/Dxe/Image/Image.c
Break every time a DXE driver is loaded.

EFI_STATUS
EFIAPI
CoreStartImage (
  IN EFI_HANDLE  ImageHandle,
  OUT UINTN      *ExitDataSize,
  OUT CHAR16     **ExitData  OPTIONAL
  )
{ // ...
    //
    // Call the image's entry point
    //
    Image->Started = TRUE;
// Add a call to CpuBreakpoint();  approx. line 1673
    CpuBreakpoint();
    Image->Status = Image->EntryPoint (ImageHandle, Image->Info.SystemTable);

Note:

MdeModulePkg/Core/Dxe/Image/Image.c
Image->EntryPoint() call in CoreStartImage
remember to step "INTO" when it gets to desired module to debug
Check if control transfers to image entry points
System breaks here every time a new DXE driver is loaded. Step into this function to trace the driver.
Image->Started = TRUE;
CpuBreakpoint() ;
Image->Status=Image->EntryPoint (ImageHandle, Image->Info.SystemTable);

---?image=/assets/images/slides/Slide58.JPG @title[Debugging the Boot Phases BDS]

Debugging the Boot Phases - BDS

Detect console devices (input and output)
Check enumeration of all devices’ preset
Detect boot policy
Ensure BIOS BDS “front page” is loaded

Note:

@title[BDS Phase – Entry Point]

BDS Phase – Entry Point

DXE call to BDS entry point in:
@fa[github gp-bullet-gold] MdeModulePkg/Core/Dxe/DxeMain/DxeMain.c
Add `CpuBreakpoint();` to break before BDS.

VOID
EFIAPI
DxeMain (
  IN  VOID *HobStart
  )
{ // ...
  // Transfer control to the BDS Architectural Protocol
  //
// Add a call to CpuBreakpoint();  approx. line 554
  CpuBreakpoint();
  gBds->Entry (gBds);

  //
  // BDS should never return
  //
  ASSERT (FALSE);
  CpuDeadLoop ();

Note:

MdeModulePkg/Core/Dxe/DxeMain/DxeMain.c
gBds->Entry (gBds); call in DxeMain
Verify BDS Phase Entry

	CpuBreakpoint();
	gBds->Entry (gBds);
	// BDS should never return
	ASSERT (FALSE);
	CpuDeadLoop ();

---?image=/assets/images/slides/Slide61.JPG @title[Debugging the Boot Phases Pre-Boot]

Debugging the Boot Phases - Pre-Boot

“C” source debugging
UEFI Drivers

Init - entry point
Supported
Start

UEFI Shell Applications

Entry point
Local variables

`CpuBreakpoint();`

Note:

---?image=/assets/images/slides/Slide63.JPG @title[Debug in Pre-Boot – UEFI Shell]

Debug in Pre-Boot – UEFI Shell Application

Add `CpuBreakpoint()` to SampleApp.c near the entry point

Add SampleApp.inf to the platform .dsc file

```
bash$ cd 
bash$ . edksetup.sh
bash$ build -m SampleApp/SampleApp.inf
```

Copy the binary SampleApp.efi to USB drive

Note:

---?image=/assets/images/slides/Slide64.JPG @title[Debug in Pre-Boot – UEFI Shell GDB]

Debug in Pre-Boot – UEFI Shell Application

Use UDK Debugger and GDB to debug SampleApp

At the shell prompt on the target invoke SampleApp

```
Shell> Fs0:
FS0:/> SampleApp
```

GDB will break at the CpuBreakpoint
Begin debugging SampleApp

```
(udb) layout src
(udb) info locals
(udb) next
```

Note:

@title[Summary]

Summary

@fa[certificate gp-bullet-green] Identify the Intel® UEFI Development Kit Debugger
host and target basic configuration and components
@fa[certificate gp-bullet-cyan] Access the debugger tools
@fa[certificate gp-bullet-gold] Make changes to the target firmware
@fa[certificate gp-bullet-ltgreen] Launch the debug application
@fa[certificate gp-bullet-yellow] Use debug commands
@fa[certificate gp-bullet-magenta] Debugging PI’s phases

---?image=assets/images/gitpitch-audience.jpg @title[Questions]

---?image=assets/images/gitpitch-audience.jpg @title[Logo Slide]

![Logo Slide](/assets/images/TianocoreLogo.png =10x)

@title[Acknowledgements]

Acknowledgements

/**
Redistribution and use in source (original document form) and 'compiled' forms (converted
to PDF, epub, HTML and other formats) with or without modification, are permitted provided
that the following conditions are met:

Redistributions of source code (original document form) must retain the above copyright 
notice, this list of conditions and the following disclaimer as the first lines of this 
file unmodified.

Redistributions in compiled form (transformed to other DTDs, converted to PDF, epub, HTML
and other formats) must reproduce the above copyright notice, this list of conditions and 
the following disclaimer in the documentation and/or other materials provided with the 
distribution.

THIS DOCUMENTATION IS PROVIDED BY TIANOCORE PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED 
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL TIANOCORE PROJECT BE 
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY 
OF SUCH DAMAGE.

Copyright (c) 2018, Intel Corporation. All rights reserved.
**/

---?image=assets/images/binary-strings-black2.jpg @title[Using WinDBG Section]

Debugging using WinDBG

Note:

---?image=/assets/images/slides/Slide70.JPG @title[Configure SoftDebugger.ini (Host)]

Configure SoftDebugger.ini (Host)

```php [Debug Port] ; Channel = Usb Channel = Serial

;The following settings only apply when Channel=Serial Port = COM1 FlowControl = 1 BaudRate = 115200

[Target System]

[Debugger]

[Features] LoadModuleSymbol = 1 TerminalRedirectionPort = 20715

[Maintenance] Debug=1


Note:


---?image=/assets/images/slides/Slide72.JPG
@title[Launch the UDK Debugger Tool]
<br>
<p align="center"><span class="gold" ><b>Launch the UDK Debugger Tool Application</b></span></p>
<br>


Note:
- Start WinDbg with Intel UDK Debugger Tool
- Start up the target system using the UDK based firmware image with the debug feature enabled (within 30 seconds after starting WinDbg)

- Wait two or three seconds, until WinDbg is connected and is ready to accept commands




---?image=/assets/images/slides/Slide74.JPG
@title[Initial Breakpoint for Debugger]
<br>
<p align="center"><span class="gold" ><b>Initial Breakpoint for Debugger</b></span></p>
<br>


Note:

- WinDBG will stop the TARGET in late SEC phase, and load the symbols for SecCore.



---?image=/assets/images/slides/Slide76.JPG
@title[Initial Breakpoint for Debugger]
<br>
<p align="center"><span class="gold" ><b>Initial Breakpoint for Debugger</b></span></p>
<span style="font-size:0.9em"> Code can be viewed after a “Control Break”</span>


Note:



---?image=/assets/images/slides/Slide78.JPG
<!-- .slide: data-transition="none" -->
@title[View Source from Call Stack]
<p align="center"><span class="gold" ><b>View Source from Call Stack</b></span></p>
<br>

<div class="left">
<ul>
 <li><span style="font-size:0.7em" ><u>Alt</u> +6 - to View Call Stack</span> </li>
 <li><span style="font-size:0.7em" >Double click on desired source code</span></li>
 
</ul>
</div>
<div class="right">
<span style="font-size:0.8em" >&nbsp;  </span>
</div>

Note:

+++?image=/assets/images/slides/Slide79.JPG
<!-- .slide: data-background-transition="none" -->
<!-- .slide: data-transition="none" -->
@title[View Source from Call Stack]
<p align="center"><span class="gold" ><b>View Source from Call Stack</b></span></p>
<br>

<div class="left">
<ul>
 <li><span style="font-size:0.7em" ><u>Alt</u> +6 - to View Call Stack</span> </li>
 <li><span style="font-size:0.7em" >Double click on desired source code</span></li><br>
 <li><span style="font-size:0.7em" >Double click to open source code for PeiDispatcher</span></li>
</ul>
</div>
<div class="right">
<span style="font-size:0.8em" >&nbsp;  </span>
</div>

Note:


+++?image=/assets/images/slides/Slide81.JPG
<!-- .slide: data-background-transition="none" -->
<!-- .slide: data-transition="none" -->
@title[PeiDispatcher.c Opened from Call Stack]
<br>
<p align="center"><span class="gold" ><b>PeiDispatcher.c Opened from Call Stack</b></span></p>
<br>

Note:

- can only set a breakpoint if current IP is within that module check by stepping...


---?image=/assets/images/slides2/Slide57.JPG
<!-- .slide: data-transition="none" -->
@title[Set a Break Point from the Call Stack]
<br>
<p align="center"><span class="gold" ><b>Set a Break Point from the Call Stack</b></span></p>

@snap[north-west span-35]
<br>
<br>
<br>
<br>

<p style="line-height:60%" align="left"><span style="font-size:0.60em; " >
&bull;&nbsp;Click on desired location in the <br>&nbsp;&nbsp;Call Stack<br>
&bull;&nbsp;Select w/ Cntl-C (copy)<br>
&bull;&nbsp;Alt+F9 - Breakpoints menu<br>
&bull;&nbsp;Add "bp" command <br>
&bull;&nbsp;And Cntl-v to (paste) from Call <br>&nbsp;&nbsp;Stack reference <br>
&bull;&nbsp;Click "OK"<br>
</span></p>
@snapend

@snap[north-west span-30 fragment]
<br>
<br>
<br>
<br>
<p style="line-height:60%" align="left"><span style="font-size:0.60em; " >
&nbsp;<br>
&nbsp;<br>
&nbsp;<br>
&nbsp;<br>
&nbsp;<br>
&nbsp;<br><br><br>
&bull;&nbsp;Press "F5" to GO
</span></p>
@snapend

@snap[north-east span-55 fragment]
<br>
<br>
<br>
<br>
<br>
<p style="line-height:30%" align="left"><span style="font-size:0.60em; " >
&nbsp;<br>
&nbsp;<br>
&nbsp;<br>
&nbsp;<br><br><br><br><br><br>
<font color="black">@size[.55em](<b>`0 e fffd2459 [l:\lr\mdemodulekg\core\pei\dispatcher\dispatch `</b>)</font><br>
<br>
</span></p>
@snapend

Note:

1. Click on desired location in the Call Stack
2. Select w/ Cntl-C (copy)
3. Alt+F9 – Breakpoints menu
4. Add “bp” command  and Cntl-v to (paste) from Call Stack reference 
6. Click “OK” 	
7. Press “F5” to Go




---?image=/assets/images/slides/Slide86.JPG
@title[Next “Go” will break in Pei Dispatcher.c]
<br>
<p align="center"><span class="gold" ><b>Next “Go” will break in Pei Dispatcher.c</b></span></p>
<br>


---?image=assets/images/binary-strings-black2.jpg
@title[End Using WinDBG Section]
<br><br><br><br><br><br><br>
### <span class="gold"  >&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;End of WinDBG</span>
<span style="font-size:0.9em" >&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span>

Note:


---?image=assets/images/gitpitch-audience.jpg
@title[Logo Slide]
<br><br><br>
![Logo Slide](/assets/images/TianocoreLogo.png =10x)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

PITCHME.md

PITCHME.md

UEFI & EDK II Training

EDK II UDK Debugger

<p align="center"Lesson Objective

UDK Debugger Overview

Source Level Debugger for UEFI - EDK II

Changes to target

Library class sections

Library class sections for USB 3.0

Debugging using GDB

Debugging Thru boot flow

Summary

Acknowledgements

Debugging using WinDBG

Files

PITCHME.md

Latest commit

History

PITCHME.md

File metadata and controls

UEFI & EDK II Training

EDK II UDK Debugger

<p align="center"Lesson Objective

UDK Debugger Overview

Source Level Debugger for UEFI - EDK II

Changes to target

Library class sections

Library class sections for USB 3.0

Debugging using GDB

Debugging Thru boot flow

Summary

Acknowledgements

Debugging using WinDBG