はじめに

この記事は自作OS Advent Calendar 2021の11日目の記事として書かれました。

元ネタは、こちらです。

UEFIアプリケーションをデバッグする

『ゼロからのOS自作入門』(通称:みかん本)を進める上で、多くの壁に直面します。Linux/UNIXコマンドに不慣れであったり、MikanOSをビルドする環境の構築が上手くいかなったりなど、最初の方でつまずくことが多くあります。これらの壁については、『ゼロからのOS自作入門』のWikiなどで補足されています。

これらの最初の壁を乗り越えた後に、直面するのがUEFIアプリケーションとして実装するMikanOSブートローダのデバッグです。

MikanOSブートローダの開発では、フレームバッファの情報収集や、MikanOSカーネルのロードなど、メモリ操作を伴う機能を実装します。これらの機能が正常に動作しない場合、問題の原因追求と解決のために、GDBを利用したデバッグが有効です。

以下、この記事では、QEMUを使用した開発環境にてGDBを用いたデバッグができるようになるまでの手順を説明します。

デバッグ環境の構築

おおまかな流れ

1. debug.log出力対応のOVMFイメージの作成
2. QEMUを起動しdebug.logを取得
3. gdbscriptの作成
4. GDB+QEMUでのデバッグ

debug.log出力対応のOVMFイメージのビルド

まず、UEFIモードで起動したQEMUが、debug.logを出力するようにします。これを実現するためには、debug.log出力に対応したOVMFイメージが必要であるため、EDK2をビルドし直します。

ここでは~の直下にedk2ディレクトリが作成されているものします。edk2ディレクトリは、GitHub上のtianocore/edk2 をcloneしたディレクトリです。 (記事を書くにあたり、edk2は2021/12/6時点で最新のstableリリースedk2-stable202111を利用しています)

$ cd ~/edk2
$ git checkout edk2-stable202111
$ make -C BaseTools/Source/C

この2行の作業は、mikanos-buildでansibleを利用して開発環境を構築する際に実行済みです。実行していない場合、次のOVMFのビルドに失敗するので明記しておきます。

$ cd ~/edk2
$ source ./edksetup.sh
$ build -p OvmfPkg/OvmfPkgX64.dsc -b DEBUG -a X64 -t CLANG38

最後のbuildで-b DEBUGを指定することで、debug.logの出力に対応したOVMFイメージが生成されます。

$ ls ~/edk2/Build/OvmfX64/DEBUG_CLANG38/FV/ |grep OVMF_
OVMF_CODE.fd
OVMF_VARS.fd

作成したOVMFイメージを、別のディレクトリに移動しておきましょう。

$ mkdir -p ~/debug-efiapp/ovmf
$ cp ~/edk2/Build/OvmfX64/DEBUG_CLANG38/FV/OVMF_* ~/debug-efiapp/ovmf/
$ ls debug-efiapp/ovmf/
OVMF_CODE.fd  OVMF_VARS.fd

デバッグしたいEFIアプリケーションを用意

~/debug-efiappディレクトリ以下にEFIアプリケーションのソースファイルを用意します。

$ cd ~/debug-efiapp
$ mkdir LoaderPkg
...
$ ls LoaderPkg
Loader.inf LoaderPkg.dec LoaderPkg.dsc Main.c frame_buffer_config.hpp

ビルドします。この時デッバグシンボルファイルが生成されるように、-b DEBUGオプションを指定します。

$ ln -s  ~/debug-efiapp/LoaderPkg ~/edk2/LoaderPkg
$ cd edk2/
$ source edksetup.sh --reconfigure
$ build -p LoaderPkg/LoaderPkg.dsc -b DEBUG -a X64 -t CLANG38
$ ls ~/edk2/LoaderPkg/Build/X64/DEBUG_CLANG38/X64
Loader.debug  Loader.efi  LoaderPkg  MdePkg  TOOLS_DEF.X64

ビルド生成物のLoader.efiがEFIアプリケーションで、Loader.debugがシンボルファイルです。

QEMU実行時のdebug.log取得

QEMUで利用する Virtual FAT disk image 用のディレクトリを作成し、Loader.efiを配置します。

$ mkdir ~/debug-efiapp/efi
$ cp ~/edk2/LoaderPkg/Build/X64/DEBUG_CLANG38/X64/Loader.efi ~/debug-efiapp/efi/

このままではQEMU起動後にLoader.efiが実行されないので、EFI Shell用のstartup.nshを用意します。以下のスクリプトでは、startup.nsh実行直後に一時停止します。何かキー入力すれば、Loader.efiが実行されます。

[~debug-efiapp/efi/startup.nsh]
pause
fs0:Loader.efi

QEMUを起動します。-debugcon file:debug.log -global isa-debugcon.iobase=0x402を追加することで、debug.logが取得できます。-sはQEMUのgdbserverをtcp::1234で起動するオプションです。

OVMF_DIR=`realpath ~/debug-efiapp/ovmf`
EFI_DIR=`realpath ~/debug-efiapp/efi`

sudo qemu-system-x86_64 -m 1G -boot menu=on,splash-time=8000\
        -drive if=pflash,format=raw,readonly,file=$OVMF_DIR/OVMF_CODE.fd \
        -drive if=pflash,format=raw,file=$OVMF_DIR/OVMF_VARS.fd \
        -drive if=ide,index=0,media=disk,format=raw,file=fat:rw:$EFI_DIR \
        -device nec-usb-xhci,id=xhci -device usb-mouse -device usb-kbd \
        -debugcon file:debug.log -global isa-debugcon.iobase=0x402 \
        -monitor stdio \
        -s

Loader.efi実行後に、debug.logを確認すると、以下の記述が見つかります。

[debug.log]
Loading driver at 0x0003E45E000 EntryPoint=0x0003E45F8CB Loader.efi

上の記述では，Loader.efiが 0x0003E45E000 にロードされていることがわかります。

gdbscriptの作成

gdbで利用するシンボルファイルLoader.debugを読み込むためのgdbscriptを用意します。Loader.debugと同じディレクトリに以下の内容のファイルを作成します。

[gdbscript]
add-symbol-file ./Loader.debug 0x0003E45E240 -s .data 0x0003E460680

上記のファイルに記述されている、0x0003E45E240と0x0003E460680は、.textセクションと.dataセクションの物理アドレスになります。算出方法は以下のとおりです。

gdbのinfo fileを利用して、各セクションのオフセットアドレスを取得します。

$ gdb efi/Loader.efi
GNU gdb (Debian 10.1-1.7) 10.1.90.20210103-git
...
(gdb) info file
Symbols from "efi/Loader.efi".
Local exec file:
        `efi/Loader.efi', file type pei-x86-64.
        Entry point: 0x18cb
        0x0000000000000240 - 0x0000000000002680 is .text
        0x0000000000002680 - 0x0000000000002840 is .data
        0x0000000000002840 - 0x0000000000002880 is .reloc

debug.logから取得したベースアドレスをもとに.text,.dataの物理アドレスを計算します。

.text: 0x0003E45E000 + 0x00240 = 0x0003E45E240
.data: 0x0003E45E000 + 0x02680 = 0x0003E460680

いざGDBでデバッグ

GDB操作用とQEMU操作用にターミナルは2つ立ち上げましょう。

• (gdb) target remote :1234 は，startup.nshのpauseを解除する前に実行する．

以下の図は、206行目をブレークポイントに設定して、GDBのContinueを実行した様子を示しています。

ローカル変数のtimeには、200行目でEFI_TIME型のデータが格納されているので、GDBのp timeでデータの内部を見ることができます。更に、nで一度ステップ実行しているので処理はMemoryMapを取得する箇所まで進んでおり、QEMUの画面から206行目のPrint文を実行していることがわかります。

おわりに

この記事では、QEMUを利用したEFIアプリケーションのデバッグ方法について、環境構築から実際にデバッグできるようなるまでの一連の流れを説明しました。

記事を作成するにあたり、環境構築を1から行ったことで、理解がまた深まりました。

今回実行した内容は、以下のリポジトリにまとめています。ぜひ参考にしてみてください。

• https://github.com/rkarsnk/debug-efiapp

なにかあれば、上記リポジトリのissueか下記コメント欄まで。

参考文献

• How-to-run-OVMF (tianocore)
• How to debug OVMF with QEMU using GDB (tianocore)
• OVMFのデバッグ
• Debugging_UEFI_applications_with_GDB (wiki.osdev.org)
• UEFI OVMF symbol load script for GDB (artem-nefedov/uefi-gdb)
• QEMUで実行されているGRUB2 EFIイメージをデバッグする