tree 7a7aa247d0e4497ecaca3b509105257557201345
parent 1ee5007139cd897eb8850455f63bd2ddf2ee1f9d
author Andrew Jeffery <andrew@aj.id.au> 1658364294 +0930
committer Andrew Jeffery <andrew@aj.id.au> 1664524435 +0930

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