tools: ipkdbg: Generate gdb environments from opkg package archives
ipkdbg serves interactive debugging and coredump analysis of split-debug
binaries by exploiting bitbake's runtime package management support
outside the context of the BMC.
To enable ipkdbg in your environment you will need to be familiar with
bitbake's support of [package feeds][package-feeds].
[package-feeds]: https://docs.yoctoproject.org/dev-manual/common-tasks.html?highlight=package+feed#using-runtime-package-management
ipkdbg MUST have access to an appopriate opkg.conf that identifies the
location of the ipk package archive from which the binary under
inspection was installed. ipkdbg supports fetching opkg.conf from a
well-known, remote location if required.
ipkdbg MUST have access to a gdb binary that supports multi-arch for
cross-architecture debugging.
It is RECOMMENDED that ipkdbg also has access to the opkg database used
for populating the rootfs of the BMC firmware image. This is used for
reverse-mapping of absolute binary paths to the package that installed
the binary. With this capability, it is no-longer necessary to list the
set of packages to include in the debug rootfs on the ipkdbg
command-line when processing a core dump, they are automatically
discovered through extracting the path of the failed binary from the
core file.
To make bitbake retain the opkg database for a given build, set
[`INC_IPK_IMAGE_GEN = "1"`][incremental-builds] in your bitbake
configuration, and capture
`./tmp/work/*/obmc-phosphor-image/1.0-r0/temp/saved` as a build artefact
using the following incantation:
$ tar -cJf opkg-database.tar.xz \
-C ./tmp/work/*/obmc-phosphor-image/1.0-r0/temp/saved/target/ \
info lists status
[incremental-builds]: https://git.openembedded.org/openembedded-core/commit/?id=adf587e55c0f9bc74f0bef415273c937401baebb
Finally, opkg binaries are not provided directly due to licensing and
distribution concerns. The binaries should be built and copied into a
bin/ directory alongside `ipkdbg.in` using the
${arch}/${release_id}/${release_version_id}/opkg scheme outlined in the
code:
```
ipkdbg_opkg_path() {
...
local arch=$(uname -m)
local release_id=$(. /etc/os-release; echo $ID)
local release_version_id=$(. /etc/os-release; echo $VERSION_ID)
local p=${root}/bin/${arch}/${release_id}/${release_version_id}/opkg
...
```
Once placed in bin/ the Makefile handles stripping and archiving them
for packaging into the final `ipkdbg` script.
A helper script for building opkg, `build-opkg`, is provided in place of
the binaries themselves.
Help output:
$ ./ipkdbg -h
NAME
ipkdbg - debug OpenBMC applications from an (internally) released firmware
SYNOPSIS
ipkdbg [-q] RELEASE FILE CORE [PACKAGE...]
DESCRIPTION
RELEASE is the firmware release whose packages to install
FILE is the absolute path to the binary of interest in the target environment
CORE is an optional core file generated by FILE. Pass '-' for no core file
PACKAGES will be used to populate a temporary rootfs for debugging FILE
OPTIONS
-h
Print this help.
-q
Quit gdb once done. Intended for use in a scripting environment in combination
with a core file, as the backtrace will be printed as an implicit first command.
ENVIRONMENT
There are several important environment variables controlling the behaviour of
the script:
IPKDBG_OPKG_CACHE
A package cache directory for opkg. Defaults to empty, disabling the cache.
IPKDBG_CONF_HOST
Hostname for access to opkg.conf over the web interface
Defaults to 'host.local'
IPKDBG_CONF_MNT
Mount-point for access to opkg.conf
Defaults to 'mountpoint'
IPKDBG_CONF_LOC
Geo-location for access to opkg.conf
Defaults to 'themoon'
IPKDBG_CONF_ROOT
Path to the directory containing build artifacts, for access to opkg.conf
Defaults to 'path'
IPKDBG_CONF_USER
Username for access to opkg.conf over the web interface
Defaults to $USER (andrew)
IPKDBG_GDB
The gdb(1) binary to invoke. Automatically detected if unset.
IPKDBG_WGET_OPTS
User options to pass to wget(1) when fetching opkg.conf. Defaults to
'--quiet'
IPKDBG_ZSTD
The zstd(1) binary to extract the compressed core dump. Automatically
detected if unset.
EXAMPLE
ipkdbg 1020.2206.20220208a \
/usr/bin/nvmesensor - \
dbus-sensors dbus-sensors-dbg
Signed-off-by: Andrew Jeffery <andrew@aj.id.au>
Change-Id: Ib5a7619d0c657754bc0fa2e04cd97e64e4b6da47
diff --git a/ipkdbg/Makefile b/ipkdbg/Makefile
new file mode 100644
index 0000000..9262f1f
--- /dev/null
+++ b/ipkdbg/Makefile
@@ -0,0 +1,44 @@
+all: ipkdbg
+
+ARCH_PPC64LE_BINS=
+ARCH_X86_64_BINS=
+
+SOURCE_DATE_EPOCH=$(shell git log --format='%at' -n1 -- `git ls-files bin`)
+
+STRIPPED_ARCH_PPC64LE_BINS=$(patsubst %,stripped/%,$(ARCH_PPC64LE_BINS))
+STRIPPED_ARCH_X86_64_BINS=$(patsubst %,stripped/%,$(ARCH_X86_64_BINS))
+
+STRIPPED_BINS=$(STRIPPED_ARCH_PPC64LE_BINS) \
+ $(STRIPPED_ARCH_X86_64_BINS)
+
+$(STRIPPED_ARCH_PPC64LE_BINS): stripped/%: %
+ mkdir -p $(dir $@) && \
+ powerpc64le-linux-gnu-strip --strip-all -o $@ $<
+
+$(STRIPPED_ARCH_X86_64_BINS): stripped/%: %
+ mkdir -p $(dir $@) && \
+ x86_64-linux-gnu-strip --strip-all -o $@ $<
+
+# https://reproducible-builds.org/docs/archives/
+# https://www.gnu.org/software/tar/manual/html_section/create-options.html
+bin.tar.gz: $(STRIPPED_BINS)
+ tar \
+ --sort=name \
+ --clamp-mtime \
+ --mtime="@${SOURCE_DATE_EPOCH}" \
+ --owner=0 --group=0 --numeric-owner \
+ --pax-option=exthdr.name=%d/PaxHeaders/%f,delete=atime,delete=ctime \
+ -czf $@ \
+ -C stripped $(patsubst stripped/%,%,$^)
+
+bin.tar.gz.b64: bin.tar.gz
+ base64 $^ > $@
+
+ipkdbg: ipkdbg.in bin.tar.gz.b64
+ cat $^ > $@
+ chmod +x $@
+
+.PHONY: clean
+clean:
+ $(RM) -r stripped
+ $(RM) bin.tar.gz bin.tar.gz.b64 ipkdbg