2019-01-02 22:16:34 +00:00
|
|
|
---
|
|
|
|
title: Hacking on systemd
|
2019-12-11 09:49:28 +00:00
|
|
|
category: Contributing
|
2019-12-11 16:01:46 +00:00
|
|
|
layout: default
|
2021-09-14 14:05:21 +00:00
|
|
|
SPDX-License-Identifier: LGPL-2.1-or-later
|
2019-01-02 22:16:34 +00:00
|
|
|
---
|
|
|
|
|
2018-10-30 10:28:58 +00:00
|
|
|
# Hacking on systemd
|
|
|
|
|
|
|
|
We welcome all contributions to systemd. If you notice a bug or a missing
|
2021-10-27 09:50:19 +00:00
|
|
|
feature, please feel invited to fix it, and submit your work as a
|
|
|
|
[GitHub Pull Request (PR)](https://github.com/systemd/systemd/pull/new).
|
2018-10-30 10:28:58 +00:00
|
|
|
|
2024-02-23 08:56:00 +00:00
|
|
|
Please make sure to follow our [Coding Style](CODING_STYLE) when submitting
|
|
|
|
patches. Also have a look at our [Contribution Guidelines](CONTRIBUTING).
|
2018-10-30 10:28:58 +00:00
|
|
|
|
2024-03-14 09:18:27 +00:00
|
|
|
To start, run the following commands in the systemd git repository to set up
|
2024-03-14 09:29:55 +00:00
|
|
|
git correctly (running `meson` will run these commands for you automatically):
|
2024-03-14 09:18:27 +00:00
|
|
|
|
|
|
|
```shell
|
|
|
|
$ git config submodule.recurse true
|
|
|
|
$ git config fetch.recurseSubmodules on-demand
|
2024-03-21 15:07:58 +00:00
|
|
|
$ git config push.recurseSubmodules no
|
2024-04-10 12:35:20 +00:00
|
|
|
$ cp .git/hooks/pre-commit.sample .git/hooks/pre-commit
|
|
|
|
$ cp tools/git-post-rewrite-hook.sh .git/hooks/post-rewrite
|
2024-03-14 09:18:27 +00:00
|
|
|
```
|
|
|
|
|
2018-10-30 10:28:58 +00:00
|
|
|
When adding new functionality, tests should be added. For shared functionality
|
|
|
|
(in `src/basic/` and `src/shared/`) unit tests should be sufficient. The general
|
|
|
|
policy is to keep tests in matching files underneath `src/test/`,
|
|
|
|
e.g. `src/test/test-path-util.c` contains tests for any functions in
|
|
|
|
`src/basic/path-util.c`. If adding a new source file, consider adding a matching
|
|
|
|
test executable. For features at a higher level, tests in `src/test/` are very
|
2018-11-23 18:01:50 +00:00
|
|
|
strongly recommended. If that is not possible, integration tests in `test/` are
|
2018-10-30 10:28:58 +00:00
|
|
|
encouraged.
|
|
|
|
|
2024-02-23 08:56:00 +00:00
|
|
|
Please also have a look at our list of [code quality tools](CODE_QUALITY) we
|
2021-05-10 06:35:21 +00:00
|
|
|
have setup for systemd, to ensure our codebase stays in good shape.
|
2018-10-30 10:28:58 +00:00
|
|
|
|
|
|
|
Please always test your work before submitting a PR. For many of the components
|
2022-03-15 16:04:36 +00:00
|
|
|
of systemd testing is straightforward as you can simply compile systemd and
|
2018-10-30 10:28:58 +00:00
|
|
|
run the relevant tool from the build directory.
|
|
|
|
|
2022-05-11 13:31:07 +00:00
|
|
|
For some components (most importantly, systemd/PID 1 itself) this is not
|
2018-10-30 10:28:58 +00:00
|
|
|
possible, however. In order to simplify testing for cases like this we provide
|
2024-01-25 21:48:55 +00:00
|
|
|
a set of `mkosi` config files directly in the source tree.
|
2021-10-27 09:50:19 +00:00
|
|
|
[mkosi](https://github.com/systemd/mkosi) is a tool for building clean OS images
|
|
|
|
from an upstream distribution in combination with a fresh build of the project
|
2024-01-25 21:48:55 +00:00
|
|
|
in the local working directory. To make use of this, please install the latest
|
|
|
|
version of mkosi from the [GitHub repository](https://github.com/systemd/mkosi).
|
|
|
|
`mkosi` will build an image for the host distro by default. First, run
|
|
|
|
`mkosi genkey` to generate a key and certificate to be used for secure boot and
|
|
|
|
verity signing. After that is done, it is sufficient to type `mkosi` in the
|
|
|
|
systemd project directory to generate a disk image you can boot either in
|
|
|
|
`systemd-nspawn` or in a UEFI-capable VM:
|
2018-10-30 10:28:58 +00:00
|
|
|
|
2021-10-27 11:21:57 +00:00
|
|
|
```sh
|
2023-02-16 19:05:55 +00:00
|
|
|
$ sudo mkosi boot # nspawn still needs sudo for now
|
2018-10-30 10:28:58 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
or:
|
|
|
|
|
2021-10-27 11:21:57 +00:00
|
|
|
```sh
|
|
|
|
$ mkosi qemu
|
2018-10-30 10:28:58 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
Every time you rerun the `mkosi` command a fresh image is built, incorporating
|
2023-06-29 11:35:03 +00:00
|
|
|
all current changes you made to the project tree.
|
2021-01-23 12:16:18 +00:00
|
|
|
|
2023-12-07 18:52:41 +00:00
|
|
|
By default a directory image is built. This requires `virtiofsd` to be installed
|
|
|
|
on the host. To build a disk image instead which does not require `virtiofsd`,
|
|
|
|
add the following to `mkosi.local.conf`:
|
|
|
|
|
|
|
|
```conf
|
|
|
|
[Output]
|
|
|
|
Format=disk
|
|
|
|
```
|
|
|
|
|
|
|
|
To boot in UEFI mode instead of using QEMU's direct kernel boot, add the following
|
|
|
|
to `mkosi.local.conf`:
|
|
|
|
|
|
|
|
```conf
|
|
|
|
[Host]
|
|
|
|
QemuFirmware=uefi
|
|
|
|
```
|
|
|
|
|
2024-04-08 10:14:47 +00:00
|
|
|
To avoid having to build a new image all the time when iterating on a patch, add
|
|
|
|
the following to `mkosi.local.conf`:
|
|
|
|
|
|
|
|
```conf
|
|
|
|
[Host]
|
|
|
|
RuntimeBuildSources=yes
|
|
|
|
```
|
|
|
|
|
|
|
|
After enabling this setting, the source and build directories will be mounted to
|
|
|
|
`/work/src` and `/work/build` respectively when booting the image as a container
|
|
|
|
or virtual machine. To build the latest changes and re-install, run
|
|
|
|
`meson install -C /work/build --only-changed` in the container or virtual machine
|
|
|
|
and optionally restart the daemon(s) you're working on using
|
2024-04-08 21:17:33 +00:00
|
|
|
`systemctl restart <units>` or `systemctl daemon-reexec` if you're working on pid1
|
|
|
|
or `systemctl soft-reboot` to restart everything.
|
2024-04-08 10:14:47 +00:00
|
|
|
|
2023-10-05 15:04:53 +00:00
|
|
|
Putting this all together, here's a series of commands for preparing a patch
|
|
|
|
for systemd:
|
|
|
|
|
|
|
|
```sh
|
2023-11-28 17:38:22 +00:00
|
|
|
$ git clone https://github.com/systemd/mkosi.git # If mkosi v19 or newer is not packaged by your distribution
|
|
|
|
$ ln -s $PWD/mkosi/bin/mkosi /usr/local/bin/mkosi # If mkosi v19 or newer is not packaged by your distribution
|
2023-10-05 15:04:53 +00:00
|
|
|
$ git clone https://github.com/systemd/systemd.git
|
|
|
|
$ cd systemd
|
|
|
|
$ git checkout -b <BRANCH> # where BRANCH is the name of the branch
|
|
|
|
$ vim src/core/main.c # or wherever you'd like to make your changes
|
|
|
|
$ mkosi -f qemu # (re-)build and boot up the test image in qemu
|
|
|
|
$ git add -p # interactively put together your patch
|
|
|
|
$ git commit # commit it
|
|
|
|
$ git push -u <REMOTE> # where REMOTE is your "fork" on GitHub
|
|
|
|
```
|
|
|
|
|
|
|
|
And after that, head over to your repo on GitHub and click "Compare & pull request"
|
|
|
|
|
2021-01-23 12:16:18 +00:00
|
|
|
If you want to do a local build without mkosi, most distributions also provide
|
2023-10-05 15:04:53 +00:00
|
|
|
very simple and convenient ways to install most development packages necessary
|
2021-10-27 10:30:47 +00:00
|
|
|
to build systemd:
|
2018-10-30 10:28:58 +00:00
|
|
|
|
2021-10-27 10:30:47 +00:00
|
|
|
```sh
|
|
|
|
# Fedora
|
|
|
|
$ sudo dnf builddep systemd
|
|
|
|
# Debian/Ubuntu
|
2021-10-27 15:40:35 +00:00
|
|
|
$ sudo apt-get build-dep systemd
|
2021-10-27 10:30:47 +00:00
|
|
|
# Arch
|
2023-10-05 15:21:01 +00:00
|
|
|
$ sudo pacman -S devtools
|
|
|
|
$ pkgctl repo clone --protocol=https systemd
|
|
|
|
$ cd systemd
|
2021-10-27 10:30:47 +00:00
|
|
|
$ makepkg -seoc
|
2018-10-30 10:28:58 +00:00
|
|
|
```
|
|
|
|
|
2023-10-05 15:04:53 +00:00
|
|
|
After installing the development packages, systemd can be built from source as follows:
|
2018-10-30 10:28:58 +00:00
|
|
|
|
|
|
|
```sh
|
2023-10-05 15:04:53 +00:00
|
|
|
$ meson setup build <options>
|
|
|
|
$ ninja -C build
|
|
|
|
$ meson test -C build
|
2018-10-30 10:28:58 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
Happy hacking!
|
|
|
|
|
2021-05-17 19:32:49 +00:00
|
|
|
## Templating engines in .in files
|
|
|
|
|
|
|
|
Some source files are generated during build. We use two templating engines:
|
|
|
|
* meson's `configure_file()` directive uses syntax with `@VARIABLE@`.
|
|
|
|
|
2021-05-19 11:53:41 +00:00
|
|
|
See the
|
|
|
|
[Meson docs for `configure_file()`](https://mesonbuild.com/Reference-manual.html#configure_file)
|
|
|
|
for details.
|
2021-05-17 19:32:49 +00:00
|
|
|
|
2021-05-19 11:22:25 +00:00
|
|
|
{% raw %}
|
2021-05-17 19:32:49 +00:00
|
|
|
* most files are rendered using jinja2, with `{{VARIABLE}}` and `{% if … %}`,
|
|
|
|
`{% elif … %}`, `{% else … %}`, `{% endif … %}` blocks. `{# … #}` is a
|
|
|
|
jinja2 comment, i.e. that block will not be visible in the rendered
|
2021-05-19 11:22:25 +00:00
|
|
|
output. `{% raw %} … `{% endraw %}`{{ '{' }}{{ '% endraw %' }}}` creates a block
|
|
|
|
where jinja2 syntax is not interpreted.
|
2021-05-17 19:32:49 +00:00
|
|
|
|
2021-05-19 11:53:41 +00:00
|
|
|
See the
|
|
|
|
[Jinja Template Designer Documentation](https://jinja2docs.readthedocs.io/en/stable/templates.html#synopsis)
|
2021-05-17 19:32:49 +00:00
|
|
|
for details.
|
|
|
|
|
|
|
|
Please note that files for both template engines use the `.in` extension.
|
2018-10-30 10:28:58 +00:00
|
|
|
|
2020-09-17 07:02:16 +00:00
|
|
|
## Developer and release modes
|
|
|
|
|
|
|
|
In the default meson configuration (`-Dmode=developer`), certain checks are
|
|
|
|
enabled that are suitable when hacking on systemd (such as internal
|
2021-05-17 19:32:49 +00:00
|
|
|
documentation consistency checks). Those are not useful when compiling for
|
|
|
|
distribution and can be disabled by setting `-Dmode=release`.
|
2020-09-17 07:02:16 +00:00
|
|
|
|
2022-07-15 00:26:52 +00:00
|
|
|
## Sanitizers in mkosi
|
|
|
|
|
2024-02-23 08:56:00 +00:00
|
|
|
See [Testing systemd using sanitizers](TESTING_WITH_SANITIZERS) for more information
|
2022-07-15 00:26:52 +00:00
|
|
|
on how to build with sanitizers enabled in mkosi.
|
|
|
|
|
2018-10-30 10:28:58 +00:00
|
|
|
## Fuzzers
|
|
|
|
|
|
|
|
systemd includes fuzzers in `src/fuzz/` that use libFuzzer and are automatically
|
2020-06-11 16:34:42 +00:00
|
|
|
run by [OSS-Fuzz](https://github.com/google/oss-fuzz) with sanitizers.
|
2019-06-11 06:25:45 +00:00
|
|
|
To add a fuzz target, create a new `src/fuzz/fuzz-foo.c` file with a `LLVMFuzzerTestOneInput`
|
2018-10-30 10:28:58 +00:00
|
|
|
function and add it to the list in `src/fuzz/meson.build`.
|
|
|
|
|
|
|
|
Whenever possible, a seed corpus and a dictionary should also be added with new
|
|
|
|
fuzz targets. The dictionary should be named `src/fuzz/fuzz-foo.dict` and the seed
|
|
|
|
corpus should be built and exported as `$OUT/fuzz-foo_seed_corpus.zip` in
|
|
|
|
`tools/oss-fuzz.sh`.
|
|
|
|
|
|
|
|
The fuzzers can be built locally if you have libFuzzer installed by running
|
2023-10-14 15:47:10 +00:00
|
|
|
`tools/oss-fuzz.sh`, or by running:
|
|
|
|
|
|
|
|
```
|
|
|
|
CC=clang CXX=clang++ \
|
|
|
|
meson setup build-libfuzz -Dllvm-fuzz=true -Db_sanitize=address,undefined -Db_lundef=false \
|
|
|
|
-Dc_args='-fno-omit-frame-pointer -DFUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION'
|
|
|
|
ninja -C build-libfuzz fuzzers
|
|
|
|
```
|
|
|
|
|
|
|
|
Each fuzzer then can be then run manually together with a directory containing
|
|
|
|
the initial corpus:
|
|
|
|
|
|
|
|
```
|
|
|
|
export UBSAN_OPTIONS=print_stacktrace=1:print_summary=1:halt_on_error=1
|
|
|
|
build-libfuzz/fuzz-varlink-idl test/fuzz/fuzz-varlink-idl/
|
|
|
|
```
|
|
|
|
|
|
|
|
Note: the `halt_on_error=1` UBSan option is especially important, otherwise
|
|
|
|
the fuzzer won't crash when undefined behavior is triggered.
|
|
|
|
|
|
|
|
You should also confirm that the fuzzers can be built and run using
|
2022-05-26 15:22:50 +00:00
|
|
|
[the OSS-Fuzz toolchain](https://google.github.io/oss-fuzz/advanced-topics/reproducing/#building-using-docker):
|
2018-10-30 10:28:58 +00:00
|
|
|
|
|
|
|
```
|
2022-05-26 15:22:50 +00:00
|
|
|
path_to_systemd=...
|
|
|
|
|
|
|
|
git clone --depth=1 https://github.com/google/oss-fuzz
|
|
|
|
cd oss-fuzz
|
|
|
|
|
|
|
|
for sanitizer in address undefined memory; do
|
|
|
|
for engine in libfuzzer afl honggfuzz; do
|
|
|
|
./infra/helper.py build_fuzzers --sanitizer "$sanitizer" --engine "$engine" \
|
|
|
|
--clean systemd "$path_to_systemd"
|
|
|
|
|
|
|
|
./infra/helper.py check_build --sanitizer "$sanitizer" --engine "$engine" \
|
|
|
|
-e ALLOWED_BROKEN_TARGETS_PERCENTAGE=0 systemd
|
|
|
|
done
|
|
|
|
done
|
|
|
|
|
2022-05-29 07:36:33 +00:00
|
|
|
./infra/helper.py build_fuzzers --clean --architecture i386 systemd "$path_to_systemd"
|
|
|
|
./infra/helper.py check_build --architecture i386 -e ALLOWED_BROKEN_TARGETS_PERCENTAGE=0 systemd
|
|
|
|
|
2022-05-26 15:22:50 +00:00
|
|
|
./infra/helper.py build_fuzzers --clean --sanitizer coverage systemd "$path_to_systemd"
|
|
|
|
./infra/helper.py coverage --no-corpus-download systemd
|
2018-10-30 10:28:58 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
If you find a bug that impacts the security of systemd, please follow the
|
2024-02-23 08:56:00 +00:00
|
|
|
guidance in [CONTRIBUTING.md](CONTRIBUTING) on how to report a security vulnerability.
|
2018-10-30 10:28:58 +00:00
|
|
|
|
|
|
|
For more details on building fuzzers and integrating with OSS-Fuzz, visit:
|
|
|
|
|
2020-02-17 22:23:34 +00:00
|
|
|
- [Setting up a new project - OSS-Fuzz](https://google.github.io/oss-fuzz/getting-started/new-project-guide/)
|
|
|
|
- [Tutorials - OSS-Fuzz](https://google.github.io/oss-fuzz/reference/useful-links/#tutorials)
|
2021-01-23 12:17:36 +00:00
|
|
|
|
2022-08-18 12:38:19 +00:00
|
|
|
## Debugging binaries that need to run as root in vscode
|
|
|
|
|
|
|
|
When trying to debug binaries that need to run as root, we need to do some custom configuration in vscode to
|
|
|
|
have it try to run the applications as root and to ask the user for the root password when trying to start
|
|
|
|
the binary. To achieve this, we'll use a custom debugger path which points to a script that starts `gdb` as
|
|
|
|
root using `pkexec`. pkexec will prompt the user for their root password via a graphical interface. This
|
|
|
|
guide assumes the C/C++ extension is used for debugging.
|
|
|
|
|
|
|
|
First, create a file `sgdb` in the root of the systemd repository with the following contents and make it
|
|
|
|
executable:
|
|
|
|
|
|
|
|
```
|
|
|
|
#!/bin/sh
|
|
|
|
exec pkexec gdb "$@"
|
|
|
|
```
|
|
|
|
|
|
|
|
Then, open launch.json in vscode, and set `miDebuggerPath` to `${workspaceFolder}/sgdb` for the corresponding
|
|
|
|
debug configuration. Now, whenever you try to debug the application, vscode will try to start gdb as root via
|
|
|
|
pkexec which will prompt you for your password via a graphical interface. After entering your password,
|
|
|
|
vscode should be able to start debugging the application.
|
|
|
|
|
|
|
|
For more information on how to set up a debug configuration for C binaries, please refer to the official
|
|
|
|
vscode documentation [here](https://code.visualstudio.com/docs/cpp/launch-json-reference)
|
|
|
|
|
2021-08-20 18:09:37 +00:00
|
|
|
## Debugging systemd with mkosi + vscode
|
|
|
|
|
|
|
|
To simplify debugging systemd when testing changes using mkosi, we're going to show how to attach
|
2023-03-21 15:06:15 +00:00
|
|
|
[VSCode](https://code.visualstudio.com/)'s debugger to an instance of systemd running in a mkosi image using
|
|
|
|
QEMU.
|
2021-08-20 18:09:37 +00:00
|
|
|
|
|
|
|
To allow VSCode's debugger to attach to systemd running in a mkosi image, we have to make sure it can access
|
2023-03-21 15:06:15 +00:00
|
|
|
the virtual machine spawned by mkosi where systemd is running. mkosi makes this possible via a handy SSH
|
|
|
|
option that makes the generated image accessible via SSH when booted. Thus you must build the image with
|
2023-11-28 17:38:22 +00:00
|
|
|
`mkosi --ssh`. The easiest way to set the option is to create a file `mkosi.local.conf` in the root of the
|
2023-10-17 14:03:42 +00:00
|
|
|
repository and add the following contents:
|
2021-08-20 18:09:37 +00:00
|
|
|
|
|
|
|
```
|
|
|
|
[Host]
|
|
|
|
Ssh=yes
|
2023-10-17 14:03:42 +00:00
|
|
|
RuntimeTrees=.
|
2021-08-20 18:09:37 +00:00
|
|
|
```
|
|
|
|
|
2023-03-21 15:06:15 +00:00
|
|
|
Also make sure that the SSH agent is running on your system and that you've added your SSH key to it with
|
2023-10-17 14:03:42 +00:00
|
|
|
`ssh-add`. Also make sure that `virtiofsd` is installed.
|
2023-03-21 15:06:15 +00:00
|
|
|
|
|
|
|
After rebuilding the image and booting it with `mkosi qemu`, you should now be able to connect to it by
|
|
|
|
running `mkosi ssh` from the same directory in another terminal window.
|
2021-08-20 18:09:37 +00:00
|
|
|
|
|
|
|
Now we need to configure VSCode. First, make sure the C/C++ extension is installed. If you're already using
|
|
|
|
a different extension for code completion and other IDE features for C in VSCode, make sure to disable the
|
|
|
|
corresponding parts of the C/C++ extension in your VSCode user settings by adding the following entries:
|
|
|
|
|
|
|
|
```json
|
|
|
|
"C_Cpp.formatting": "Disabled",
|
|
|
|
"C_Cpp.intelliSenseEngine": "Disabled",
|
|
|
|
"C_Cpp.enhancedColorization": "Disabled",
|
|
|
|
"C_Cpp.suggestSnippets": false,
|
|
|
|
```
|
|
|
|
|
|
|
|
With the extension set up, we can create the launch.json file in the .vscode/ directory to tell the VSCode
|
2022-10-25 14:09:29 +00:00
|
|
|
debugger how to attach to the systemd instance running in our mkosi container/VM. Create the file, and possibly
|
|
|
|
the directory, and add the following contents:
|
2021-08-20 18:09:37 +00:00
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"version": "0.2.0",
|
|
|
|
"configurations": [
|
|
|
|
{
|
|
|
|
"type": "cppdbg",
|
|
|
|
"program": "/usr/lib/systemd/systemd",
|
2021-10-18 12:29:15 +00:00
|
|
|
"processId": "${command:pickRemoteProcess}",
|
2021-08-20 18:09:37 +00:00
|
|
|
"request": "attach",
|
|
|
|
"name": "systemd",
|
|
|
|
"pipeTransport": {
|
|
|
|
"pipeProgram": "mkosi",
|
|
|
|
"pipeArgs": [
|
|
|
|
"-C",
|
|
|
|
"/path/to/systemd/repo/directory/on/host/system/",
|
|
|
|
"ssh"
|
|
|
|
],
|
|
|
|
"debuggerPath": "/usr/bin/gdb"
|
|
|
|
},
|
|
|
|
"MIMode": "gdb",
|
|
|
|
"sourceFileMap": {
|
2023-10-17 14:03:42 +00:00
|
|
|
"/root/src/systemd": {
|
2021-08-20 18:09:37 +00:00
|
|
|
"editorPath": "${workspaceFolder}",
|
|
|
|
"useForBreakpoints": false
|
|
|
|
},
|
|
|
|
}
|
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
Now that the debugger knows how to connect to our process in the container/VM and we've set up the necessary
|
|
|
|
source mappings, go to the "Run and Debug" window and run the "systemd" debug configuration. If everything
|
|
|
|
goes well, the debugger should now be attached to the systemd instance running in the container/VM. You can
|
|
|
|
attach breakpoints from the editor and enjoy all the other features of VSCode's debugger.
|
|
|
|
|
|
|
|
To debug systemd components other than PID 1, set "program" to the full path of the component you want to
|
|
|
|
debug and set "processId" to "${command:pickProcess}". Now, when starting the debugger, VSCode will ask you
|
|
|
|
the PID of the process you want to debug. Run `systemctl show --property MainPID --value <component>` in the
|
|
|
|
container to figure out the PID and enter it when asked and VSCode will attach to that process instead.
|
2021-12-19 17:05:44 +00:00
|
|
|
|
2022-05-17 13:54:46 +00:00
|
|
|
## Debugging systemd-boot
|
2021-12-19 17:05:44 +00:00
|
|
|
|
2023-05-19 15:18:41 +00:00
|
|
|
During boot, systemd-boot and the stub loader will output messages like
|
|
|
|
`systemd-boot@0x0A` and `systemd-stub@0x0B`, providing the base of the loaded
|
|
|
|
code. This location can then be used to attach to a QEMU session (provided it
|
|
|
|
was run with `-s`). See `debug-sd-boot.sh` script in the tools folder which
|
|
|
|
automates this processes.
|
|
|
|
|
|
|
|
If the debugger is too slow to attach to examine an early boot code passage,
|
|
|
|
the call to `DEFINE_EFI_MAIN_FUNCTION()` can be modified to enable waiting. As
|
|
|
|
soon as the debugger has control, we can then run `set variable wait = 0` or
|
|
|
|
`return` to continue. Once the debugger has attached, setting breakpoints will
|
|
|
|
work like usual.
|
2021-12-19 17:05:44 +00:00
|
|
|
|
|
|
|
To debug systemd-boot in an IDE such as VSCode we can use a launch configuration like this:
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"name": "systemd-boot",
|
|
|
|
"type": "cppdbg",
|
|
|
|
"request": "launch",
|
|
|
|
"program": "${workspaceFolder}/build/src/boot/efi/systemd-bootx64.efi",
|
|
|
|
"cwd": "${workspaceFolder}",
|
|
|
|
"MIMode": "gdb",
|
|
|
|
"miDebuggerServerAddress": ":1234",
|
|
|
|
"setupCommands": [
|
|
|
|
{ "text": "shell mkfifo /tmp/sdboot.{in,out}" },
|
|
|
|
{ "text": "shell qemu-system-x86_64 [...] -s -serial pipe:/tmp/sdboot" },
|
|
|
|
{ "text": "shell ${workspaceFolder}/tools/debug-sd-boot.sh ${workspaceFolder}/build/src/boot/efi/systemd-bootx64.efi /tmp/sdboot.out systemd-boot.gdb" },
|
|
|
|
{ "text": "source /tmp/systemd-boot.gdb" },
|
|
|
|
]
|
|
|
|
}
|
|
|
|
```
|