Debug: Add VSCode source-level debug example config; update QEMU FAT …

…drive commands; other minor additional debug doc info

.gitignore

@@ -8,6 +8,7 @@ xcuserdata
 project.xcworkspace
 *.dSYM
 *.linux
+.vscode
 Utilities/AppleEfiSignTool/AppleEfiSignTool
 Utilities/ACPIe/ACPIe
 Utilities/acdtinfo/acdtinfo

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`

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