Document how to debug an application built with uefi-rs

[nicholasbishop]

Splitting this out from #285:

@timrobertsdev wrote:

I've been attempting to investigate why, but I've been having a little trouble getting rust-gdb and rust-lldb to recognize the symbols in the uefi-test-runner.efi binary. Oddly enough, objdump -freports that it is flagged as HAS_DEBUG, but objdump -t wasn't able to find any symbols. Attemping image dump symtab in rust-lldb results in num-symbols = 0. I've probably got something setup incorrectly on my end, any advice would be greatly appreciated.

I don't know the answer to this, but it would be nice to have a straightforward way to debug an application built with uefi-rs running under qemu. I'm not sure if there is something that currently works and it just needs some documentation, or if there's work needed in the toolchain.

[timrobertsdev]

I found this article, but their approach doesn't seem to work. It finds the base address and address of each section, but still doesn't provide any symbols to gdb. Then I found a uefi_test_runner_xxxx.pdb file alongside a uefi_test_runner_xxxx.efi file in target/{arch}/debug/deps/, but lldb doesn't seem to want to load it, maybe the location of the .pdb isn't in the executable? I'm starting to lean towards it being a toolchain issue. I'll try building EDK2 and OVMF using their LLVM/Clang toolchain and see if it outputs usable debug info first.

[no92]

Previous versions of rustc and/or cargo worked flawlessly as described in the article above, but this doesn't work with recent version. I don't remember whether the .pdb files were always there, but in any case they don't include any symbols now.

IIRC, the spec requires that UEFI apps tick a few boxes, e.g. the subsystem type, but it also states that they ought to be stripped, hence this behavior.

[timrobertsdev]

The executable should be stripped, but applications built in C with EDK2 in DEBUG mode do output .map and .pdb files for debugging. Source: https://edk2-docs.gitbook.io/edk-ii-build-specification/12_build_changes_and_customizations/121_building_for_debug

With that in mind, it sounds like this might be worth filing a bug for the x86_64-unknown-uefi target?

[no92]

I'm in the process of bisecting compiler versions to determine where the old behavior of having symbol tables was lost.

[no92]

The last build that provides symbol tables is nightly-2020-11-14-x86_64-unknown-linux-gnu, while nightly-2020-11-15-x86_64-unknown-linux-gnu doesn't.

I'll try to do some digging as to why that happens, but I don't know the first thing about rustc or cargo code so I don't expect to find the solution TBH.

Methodology

I took uefi-test-runner @ v0.6.0 as a testbed. Rust nightlies tried ranged from 2020-10-20 to 2021-10-04. For getting versions of Rust, I used these commands, substituting the dates accordingly:

rustup toolchain add nightly-2020-11-14 --profile minimal
rustup default nightly-2020-11-14
rustup component add rust-src

For building, ./build.py build was used. In order to detect whether symbol tables are present, the following commands were run in gdb via a .gdbinit file:

add-symbol-file ../target/x86_64-unknown-uefi/debug/uefi-test-runner.efi
info functions

[no92]

Bisecting leads to rust-lang/rust#78959, which is also linked to by rust-lang/rust#87157 where the author of the blog post above reports the same issue.

The solution seems to be to do rustc +nightly -Z unstable-options --print target-spec-json --target x86_64-unknown-uefi | sed -e 's/"is-like-msvc": true/"is-like-msvc": false/g' > x86_64-unknown-uefi-debug.json.

[timrobertsdev]

Can confirm the above solution works, with the additional step of removing "is-builtin" from the target file. build.py would need to be updated to use the custom target as well.

I'll dive into debugging something in QEMU tonight, but this looks like it solves the issue completely as gdb can see all symbols and map them back to the source files.

[nicholasbishop]

I'm not seeing quite the same thing as you with the builtin x86_64-unknown-uefi target. I do get what seems to be a valid pdb file generated under the deps directory. I dumped the symbols in it with the pdb_symbols utility in the pdb crate, and it looks correct. (rustc 1.57.0-nightly (9dbb26efe 2021-10-03.)

So if I'm understanding correctly, rustc used to include DWARF-style debug sections in the executable, and now it outputs a pdb. Which does seem like reasonable behavior.

lldb seems like it supports loading pdb files (either with a Windows-specific loader, or the "native pdb" plugin on other platforms), but in testing on Linux I haven't had any luck getting it to successfully load symbols.

[timrobertsdev]

Yeah, that's the same issue that I was having with the pdb files. I tested on both linux and windows(mingw) and was unable to correctly load any symbols. I'll give MSVC a try.

With @no92's solution, gdb and lldb in linux are able to recognize the symbols enough to say they have successfully set a breakpoint, but they won't actually break with br or hbr. Maybe the addresses aren't correct and need to be fixed up before debugging?

EDIT: Tried to fixup the addresses using the above article, but it segfaulted while running on my machine.

[no92]

@nicholasbishop wrote:

I do get what seems to be a valid pdb file generated under the deps directory. I dumped the symbols in it with the pdb_symbols utility in the pdb crate, and it looks correct.

I had checked it with some pdb tool I frankly can't remember right now, and I didn't find anything resembling symbols. It was, however, a valid pdb file. As it was some random tool pulled from GitHub, it could just be wrong and the Rust crate right. Oops.

@timrobertsdev wrote:

With @no92's solution, gdb and lldb in linux are able to recognize the symbols enough to say they have successfully set a breakpoint, but they won't actually break with br or hbr. Maybe the addresses aren't correct and need to be fixed up before debugging?

As EFI apps are relocatable, the base address changes. This could be read out via the LoadedImage Protocol, but transferring that info from the remote to the debugger host would have to take place somehow. Alternatively, the instructions in the article work for me, I'm not sure why it's segfaulting for you. I use the python script via a .gdbinit in gdb itself as well as some VSCode interface that ultimately uses gdb, too.

[timrobertsdev]

@no92 Nevermind, I got it working. The mistake I was making was attempting to run the dbg gdbscript while QEMU itself was halted and waiting for debugger, instead of the wait_for_debugger() fn outlined in that article.