From ee0fb99105a191c16926b8d6cd58ce2151eb7894 Mon Sep 17 00:00:00 2001 From: MikeBeaton Date: Mon, 14 Jun 2021 23:55:51 +0100 Subject: [PATCH] Debug: Add VSCode source-level debug example config; update QEMU FAT drive commands; other minor additional debug doc info --- .gitignore | 1 + Changelog.md | 5 +++- Debug/README.md | 80 +++++++++++++++++++++++++++++++++++++++++-------- 3 files changed, 73 insertions(+), 13 deletions(-) diff --git a/.gitignore b/.gitignore index 0af5c962..0948e683 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ xcuserdata project.xcworkspace *.dSYM *.linux +.vscode Utilities/AppleEfiSignTool/AppleEfiSignTool Utilities/ACPIe/ACPIe Utilities/acdtinfo/acdtinfo diff --git a/Changelog.md b/Changelog.md index a2876eee..03436382 100644 --- a/Changelog.md +++ b/Changelog.md @@ -8,7 +8,10 @@ OpenCore Changelog - Fixed transparency click detection on OpenCanopy boot entries - Added PCI device info dumping to `SysReport` - Fixed `SetApfsTrimTimeout` on macOS 12 -- Documented and added safe fallback for existing requirement for SetDefault width to match Selector width +- Documented requirement for SetDefault.icns width to match Selector.icns width +- Added explicit warn and safe fallback to builtin picker on failure to match the above +- Added VSCode source level IDE debug config example to debug docs +- Added other minor debug docs updates #### v0.7.0 - Fixed NVRAM reset on firmware with write-protected `BootOptionSupport` diff --git a/Debug/README.md b/Debug/README.md index 2618c7e0..4354839a 100644 --- a/Debug/README.md +++ b/Debug/README.md @@ -1,5 +1,5 @@ -UEFI Debugging with GDB -======================= +UEFI Debugging with GDB/LLDB +============================ These scripts provide support for easier UEFI code debugging on virtual machines like VMware Fusion or QEMU. The code is based on [Andrei Warkentin](https://github.com/andreiw)'s @@ -30,7 +30,7 @@ build -a X64 -t CLANGPDB -b NOOPT -p OpenCorePkg/OpenCorePkg.dsc # for other sys To wait for debugger connection on startup `WaitForKeyPress` functions from `OcMiscLib.h` can be utilised. Do be aware that this function additionally calls `DebugBreak` function, which may -be broken at during GDB init. +be broken at during GDB/LLDB init. #### VMware Configuration @@ -83,6 +83,8 @@ when no macOS guest booting is required. To build OVMF with SMM support add `-D SMM_REQUIRE=1`. To build OVMF with serial debugging add `-D DEBUG_ON_SERIAL_PORT=1`. + _Note_: Optionally, you may build OvmfPkg with its own build script, which is located within the OvmfPkg directory. Use e.g. `./build.sh -a X64` or `./build.sh -a X64 -b NOOPT`; additional build arguments such as for serial debugging or SMM support may be appended to this. + 2. Prepare launch directory with OpenCore as usual. For example, make a directory named `QemuRun` and `cd` to it. You should have a similar directory structure: @@ -97,33 +99,49 @@ when no macOS guest booting is required. └── config.plist ``` -3. Run QEMU (`OVMF_BUILD` should point to OVMF build directory, e.g. - `$HOME/UefiWorkspace/Build/OvmfX64/NOOPT_XCODE5/FV`): +3. Run QEMU + + The OvmfPkg build script can also start the virtual machine which it has just built, e.g. `./build.sh -a X64 qemu -drive format=raw,file=fat:rw:ESP` should be sufficient to start OpenCore; all options after `qemu` are passed directly to QEMU. Starting QEMU this way uses file `OVMF.fd` from the OVMF build directory, which is `OVMF_CODE.fd` and `OVMF_VARS.fd` combined; you may prefer to follow the second example below which specifies these files separately. + + In the remaining examples `OVMF_BUILD` should point to the OVMF build directory, e.g. + `$HOME/UefiWorkspace/Build/OvmfX64/NOOPT_XCODE5/FV`. + + To start QEMU directly, and with a more realistic machine architecture: ``` - qemu-system-x86_64 -L . -bios "$OVMF_BUILD/OVMF.fd" -hda fat:rw:ESP \ + qemu-system-x86_64 -L . -bios "$OVMF_BUILD/OVMF.fd" -drive format=raw,file=fat:rw:ESP \ -machine q35 -m 2048 -cpu Penryn -smp 4,cores=2 -usb -device usb-mouse -gdb tcp::8864 ``` - To run QEMU with SMM support use the following command: + To run QEMU with SMM support; also specifying CODE and VARS separately; also specifying the port required to connect a debugger (next section): + ``` qemu-system-x86_64 -L . -global driver=cfi.pflash01,property=secure,value=on \ -drive if=pflash,format=raw,unit=0,file="$OVMF_BUILD"/OVMF_CODE.fd,readonly=on \ - -drive if=pflash,format=raw,unit=1,file="$OVMF_BUILD"/OVMF_VARS.fd -hda fat:rw:ESP \ + -drive if=pflash,format=raw,unit=1,file="$OVMF_BUILD"/OVMF_VARS.fd \ + -drive format=raw,file=fat:rw:ESP \ -global ICH9-LPC.disable_s3=1 -machine q35,smm=on,accel=tcg -m 2048 -cpu Penryn \ -smp 4,cores=2 -usb -device usb-mouse -gdb tcp::8864 ``` You may additionally pass `-S` flag to QEMU to stop at first instruction - and wait for GDB connection. To use serial debugging add `-serial stdio`. + and wait for GDB connection. To use serial debugging add `-serial stdio` + (this causes OpenCore console log output to go to the shell which started QEMU). + +4. Key and mouse support when running OpenCore in QEMU: + + Enabling keyboard and mouse support is effectively the same as on a normal machine, however some typical options are: + + For keyboard support either, a) use `KeySupport=true`, or b) use `KeySupport=false`, in which case pass `-usb -device usb-kbd` to QEMU, and use `OpenUsbKbDxe.efi` driver. + + For mouse support either, a) use `Ps2MouseDxe.efi` driver, or b) pass `-usb -device usb-mouse` to QEMU and use `UsbMouseDxe.efi` driver. #### Debugger Configuration For simplicitly `efidebug.tool` performs all the necessary GDB or LLDB scripting. -Note, that you need to run `reload-uefi` after any new binary loads. +Note, this adds the `reload-uefi` command within the debugger, which you need to run after any new binary loads. -Check `efidebug.tool` header for environment variables to configure your setup. -For example, you can use `EFI_DEBUGGER` variable to force LLDB (`LLDB`) or GDB (`GDB`). +The script will run and attempt to connect with reasonable defaults without additional configuration, but check `efidebug.tool` header for environment variables to configure your setup. For example, you can use `EFI_DEBUGGER` variable to force LLDB (`LLDB`) or GDB (`GDB`). #### GDB Configuration @@ -170,6 +188,44 @@ The reason for this requirement is fragile `--add-gnudebug-link` option It strips path from the debug file preserving only filename and also does not update DataDirectory debug entry. +#### IDE Source Level Debugging + +Once you have got command line GDB or LLDB source level debugging working, setting up IDE source level debugging (if you prefer to use it) is a matter of choosing an IDE which already knows about whichever of GDB or LLDB you will be using, and then extracting the relevant config setup which `efidebug.tool` would have applied for you. + +For example, this is a working setup for LLDB debugging in VS Code on macOS: + +``` +{ + "name": "OC lldb", + "type": "cppdbg", + "request": "launch", + "targetArchitecture": "x64", + "program": "${workspaceFolder}/Debug/GdbSyms/Bin/X64_XCODE5/GdbSyms.dll", + "cwd": "${workspaceFolder}/Debug", + "MIMode": "lldb", + "setupCommands": [ + {"text": "settings set plugin.process.gdb-remote.target-definition-file Scripts/x86_64_target_definition.py"}, + ], + "customLaunchSetupCommands": [ + {"text": "gdb-remote localhost:8864"}, + {"text": "target create GdbSyms/Bin/X64_XCODE5/GdbSyms.dll", "ignoreFailures": true}, + {"text": "command script import Scripts/lldb_uefi.py"}, + {"text": "command script add -c lldb_uefi.ReloadUefi reload-uefi"}, + {"text": "reload-uefi"}, + ], + "launchCompleteCommand": "exec-continue", + "logging": { + "engineLogging": false, + "trace": true, + "traceResponse": true + } +} +``` + +_Note 1_: Debug type `cppdbg` is part of the standard VSCode cpp tools - you do not need to install any other marketplace LLDB tools. + +_Note 2_: Step `b DebugBreak` from `efidebug.tool` is ommitted from `customLaunchSetupCommands`, you need to add the breakpoint by hand in VSCode before launching your first debug session, otherwise VSCode will complain about hitting a breakpoint which it did not set. + #### References 1. https://communities.vmware.com/thread/390128 -- GitLab