Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions doc/howto/debug-initramfs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# How to debug initramfs issues

The EOS7 initramfs build process uses Dracut.

See the `eos/initramfs.bst` element for an overview of the main initramfs.

See the `eos/payg/uki.bst` element for details on the UKI used in PAYG devices.

## Inspecting the built initramfs

Linux initramfs files are packed using cpio, an ancient technology from decades past.
Dracut builds a small cpio archive containing microcode, then appends the main body
of the initramfs as a separate blob. In EOS7 this blob is compressed with Zstd
compression. Extracting the initramfs contents is a fun job. Here's how you
might do it.

1. Checkout the built artifact from the artifact cache.

bst artifact checkout --deps none eos/initramfs.bst --directory ./initramfs

You should now have `initramfs/usr/lib/modules/$(version)/initramfs` available,
change to that directory as well.

2. Use the `skipcpio` tool from Dracut which will write the body of the
initramfs to stdout. Make sure dracut and zstd installed on your build
machine, of course.

/usr/lib/dracut/skipcpio initramfs | zstd -d > initramfs.body.cpio

3. You can now unpack the initramfs into a new, empty directory with `cpio`:

mkdir extract
cd extract
cpio -idmv < ../initramfs.body.cpio

You can also compare it against a different initramfs using
[diffoscope](https://diffoscope.org/), which will unpack the cpio archive for you.

## Inspecting the PAYG UKI

The UKI is only used for PAYG devices.

Note that building the UKI is only possible within Endless. But you can find
the binary in all prebuilt EOS7 images at `/usr/lib/modules/$(version)/payg-image.efi`.

You can use `ukify inspect` to examine a UKI binary.

To extract contents of one of the sections, for example the initramfs, use `objdump`:

objcopy --dump-section .initrd="./initramfs" ./payg-image.efi
9 changes: 4 additions & 5 deletions elements/components/linux.bst
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,9 @@ config:
- |
python3 debian/scripts/misc/annotations --export --arch "%{debian_arch}" --flavour generic > .config

- |
scripts/config -e DEBUG_INFO_NONE

- |
make -j1 olddefconfig

Expand All @@ -61,11 +64,7 @@ config:
install -Dm644 "%{image-name}" '%{install-root}%{bootdir}/vmlinuz'
install -Dm644 System.map '%{install-root}%{bootdir}/System.map'
install -Dm644 .config '%{install-root}%{bootdir}/config'
make -j1 INSTALL_MOD_PATH='%{install-root}%{prefix}' modules_install

- |
release=$(make -s kernelrelease)
find "%{install-root}%{indep-libdir}/modules/${release}" -type f -name '*.ko' | xargs -P $MAXJOBS -n 2 -r xz;
make INSTALL_MOD_PATH='%{install-root}%{prefix}' modules_install

- |
release=$(make -s kernelrelease)
Expand Down
2 changes: 1 addition & 1 deletion elements/eos/payg/eos-payg-nonfree.bst
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ sources:
- kind: git_repo
url: github:endlessm/eos-payg-nonfree
track: master
ref: Release_6.0.7-6-ge1a4545cf194cae4cd047d6896995764e6b6cdca
ref: Release_6.0.7-8-g4dc4892a7fad5129324f279a9a1e702f178d7e9a

variables:
meson-local: >-
Expand Down
9 changes: 7 additions & 2 deletions elements/eos/payg/uki.bst
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ build-depends:
- freedesktop-sdk.bst:components/dracut.bst
- freedesktop-sdk.bst:components/ostree.bst
- freedesktop-sdk.bst:components/python3-pefile.bst
- freedesktop-sdk.bst:components/zstd.bst
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was this addition intentional?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, as the initramfs is zstd compressed, but i didnt put that in the commit message. will update

- gnome-build-meta.bst:core-deps/systemd.bst

variables:
Expand Down Expand Up @@ -52,13 +53,17 @@ config:
- |
version="$(ls -1 /lib/modules | head -n1)"
mkdir -p "%{install-root}%{install-path}"
dracut %{install-root}%{install-path}/payg-image.efi ${version} \
dracut %{install-root}%{install-path}/payg-image.efi \
--kver ${version} \
-k /usr/lib/modules/${version} --uefi \
--uefi-stub=%{install-root}/usr/lib/systemd/boot/efi/linuxx64.efi.stub \
--kernel-cmdline "eospayg efi_no_storage_paranoia rd.shell=0" \
--kernel-image /boot/vmlinuz \
--force-drivers "endlessdog" \
--add "eos-payg eos-payg-nonfree"
--add "eos-payg eos-payg-nonfree" \
--stdlog 6 \
--keep \
2> >(tee /var/tmp/dracut.log >&2)

# Dracut treats errors as warnings. In practice, errors often mean a
# broken initramfs, so we detect them here and raise an error.
Expand Down
Loading
Loading