Commit 43d8ce9d authored by Joel Fernandes (Google)'s avatar Joel Fernandes (Google) Committed by Greg Kroah-Hartman
Browse files

Provide in-kernel headers to make extending kernel easier

Introduce in-kernel headers which are made available as an archive
through proc (/proc/kheaders.tar.xz file). This archive makes it
possible to run eBPF and other tracing programs that need to extend the
kernel for tracing purposes without any dependency on the file system
having headers.

A github PR is sent for the corresponding BCC patch at:

On Android and embedded systems, it is common to switch kernels but not
have kernel headers available on the file system. Further once a
different kernel is booted, any headers stored on the file system will
no longer be useful. This is an issue even well known to distros.
By storing the headers as a compressed archive within the kernel, we can
avoid these issues that have been a hindrance for a long time.

The best way to use this feature is by building it in. Several users
have a need for this, when they switch debug kernels, they do not want to
update the filesystem or worry about it where to store the headers on
it. However, the feature is also buildable as a module in case the user
desires it not being part of the kernel image. This makes it possible to
load and unload the headers from memory on demand. A tracing program can
load the module, do its operations, and then unload the module to save
kernel memory. The total memory needed is 3.3MB.

By having the archive available at a fixed location independent of
filesystem dependencies and conventions, all debugging tools can
directly refer to the fixed location for the archive, without concerning
with where the headers on a typical filesystem which significantly
simplifies tooling that needs kernel headers.

The code to read the headers is based on /proc/config.gz code and uses
the same technique to embed the headers.

Other approaches were discussed such as having an in-memory mountable
filesystem, but that has drawbacks such as requiring an in-kernel xz
decompressor which we don't have today, and requiring usage of 42 MB of
kernel memory to host the decompressed headers at anytime. Also this
approach is simpler than such approaches.
Reviewed-by: default avatarMasahiro Yamada <>
Signed-off-by: default avatarJoel Fernandes (Google) <>
Signed-off-by: default avatarGreg Kroah-Hartman <>
parent 1fd7c3b4
......@@ -580,6 +580,16 @@ config IKCONFIG_PROC
This option enables access to the kernel configuration file
through /proc/config.gz.
tristate "Enable kernel header artifacts through /proc/kheaders.tar.xz"
depends on PROC_FS
This option enables access to the kernel header and other artifacts that
are generated during the build process. These can be used to build eBPF
tracing programs, or similar programs. If you build the headers as a
module, a module called kheaders.ko is built which can be loaded on-demand
to get access to the headers.
int "Kernel log buffer size (16 => 64KB, 17 => 128KB)"
range 12 25
# Generated files
......@@ -70,6 +70,7 @@ obj-$(CONFIG_UTS_NS) += utsname.o
obj-$(CONFIG_USER_NS) += user_namespace.o
obj-$(CONFIG_PID_NS) += pid_namespace.o
obj-$(CONFIG_IKCONFIG) += configs.o
obj-$(CONFIG_IKHEADERS_PROC) += kheaders.o
obj-$(CONFIG_SMP) += stop_machine.o
obj-$(CONFIG_KPROBES_SANITY_TEST) += test_kprobes.o
obj-$(CONFIG_AUDIT) += audit.o auditfilter.o
......@@ -121,3 +122,12 @@ $(obj)/configs.o: $(obj)/config_data.gz
targets += config_data.gz
$(obj)/config_data.gz: $(KCONFIG_CONFIG) FORCE
$(call if_changed,gzip)
$(obj)/kheaders.o: $(obj)/kheaders_data.tar.xz
quiet_cmd_genikh = CHK $(obj)/kheaders_data.tar.xz
cmd_genikh = $(srctree)/kernel/ $@
$(obj)/kheaders_data.tar.xz: FORCE
$(call cmd,genikh)
clean-files := kheaders_data.tar.xz kheaders.md5
# SPDX-License-Identifier: GPL-2.0
# This script generates an archive consisting of kernel headers
set -e
spath="$(dirname "$(readlink -f "$0")")"
# Script filename relative to the kernel source root
# We add it to the archive because it is small and any changes
# to this script will also cause a rebuild of the archive.
sfile="$(realpath --relative-to $kroot "$(readlink -f "$0")")"
# Support incremental builds by skipping archive generation
# if timestamps of files being archived are not changed.
# This block is useful for debugging the incremental builds.
# Uncomment it for debugging.
# iter=1
# if [ ! -f /tmp/iter ]; then echo 1 > /tmp/iter;
# else; iter=$(($(cat /tmp/iter) + 1)); fi
# find $src_file_list -type f | xargs ls -lR > /tmp/src-ls-$iter
# find $obj_file_list -type f | xargs ls -lR > /tmp/obj-ls-$iter
# include/generated/compile.h is ignored because it is touched even when none
# of the source files changed. This causes pointless regeneration, so let us
# ignore them for md5 calculation.
pushd $kroot > /dev/null
src_files_md5="$(find $src_file_list -type f |
grep -v "include/generated/compile.h" |
xargs ls -lR | md5sum | cut -d ' ' -f1)"
popd > /dev/null
obj_files_md5="$(find $obj_file_list -type f |
grep -v "include/generated/compile.h" |
xargs ls -lR | md5sum | cut -d ' ' -f1)"
if [ -f $tarfile ]; then tarfile_md5="$(md5sum $tarfile | cut -d ' ' -f1)"; fi
if [ -f kernel/kheaders.md5 ] &&
[ "$(cat kernel/kheaders.md5|head -1)" == "$src_files_md5" ] &&
[ "$(cat kernel/kheaders.md5|head -2|tail -1)" == "$obj_files_md5" ] &&
[ "$(cat kernel/kheaders.md5|tail -1)" == "$tarfile_md5" ]; then
if [ "${quiet}" != "silent_" ]; then
echo " GEN $tarfile"
rm -rf $cpio_dir
mkdir $cpio_dir
pushd $kroot > /dev/null
for f in $src_file_list;
do find "$f" ! -name "*.cmd" ! -name ".*";
done | cpio --quiet -pd $cpio_dir
popd > /dev/null
# The second CPIO can complain if files already exist which can
# happen with out of tree builds. Just silence CPIO for now.
for f in $obj_file_list;
do find "$f" ! -name "*.cmd" ! -name ".*";
done | cpio --quiet -pd $cpio_dir >/dev/null 2>&1
# Remove comments except SDPX lines
find $cpio_dir -type f -print0 |
xargs -0 -P8 -n1 perl -pi -e 'BEGIN {undef $/;}; s/\/\*((?!SPDX).)*?\*\///smg;'
tar -Jcf $tarfile -C $cpio_dir/ . > /dev/null
echo "$src_files_md5" > kernel/kheaders.md5
echo "$obj_files_md5" >> kernel/kheaders.md5
echo "$(md5sum $tarfile | cut -d ' ' -f1)" >> kernel/kheaders.md5
rm -rf $cpio_dir
// SPDX-License-Identifier: GPL-2.0
* Provide kernel headers useful to build tracing programs
* such as for running eBPF tracing tools.
* (Borrowed code from kernel/configs.c)
#include <linux/kernel.h>
#include <linux/module.h>
#include <linux/proc_fs.h>
#include <linux/init.h>
#include <linux/uaccess.h>
* Define kernel_headers_data and kernel_headers_data_end, within which the
* compressed kernel headers are stored. The file is first compressed with xz.
asm (
" .pushsection .rodata, \"a\" \n"
" .global kernel_headers_data \n"
"kernel_headers_data: \n"
" .incbin \"kernel/kheaders_data.tar.xz\" \n"
" .global kernel_headers_data_end \n"
"kernel_headers_data_end: \n"
" .popsection \n"
extern char kernel_headers_data;
extern char kernel_headers_data_end;
static ssize_t
ikheaders_read_current(struct file *file, char __user *buf,
size_t len, loff_t *offset)
return simple_read_from_buffer(buf, len, offset,
&kernel_headers_data_end -
static const struct file_operations ikheaders_file_ops = {
.read = ikheaders_read_current,
.llseek = default_llseek,
static int __init ikheaders_init(void)
struct proc_dir_entry *entry;
/* create the current headers file */
entry = proc_create("kheaders.tar.xz", S_IRUGO, NULL,
if (!entry)
return -ENOMEM;
&kernel_headers_data_end -
return 0;
static void __exit ikheaders_cleanup(void)
remove_proc_entry("kheaders.tar.xz", NULL);
MODULE_AUTHOR("Joel Fernandes");
MODULE_DESCRIPTION("Echo the kernel header artifacts used to build the kernel");
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment