Search notes:

Linux kernel source tree

Source root

Directories

arch Architecture specific code.
block Code for block devices.
certs Certificates, signature checking
crypto Cryptographic algorithms. Also: a framework to offload such algorithms in hardware
Documentation
drivers
fs The virtual filesystem switch
include Header files
init Architecture independent initialization code to start the kernel.
io_uring
ipc
kernel
lib Supporting functions
LICENSES
mm Memory management
net Networking
rust
samples Driver samples
scripts Supporting scripts, especially for the build system.
security Linux security module framework which allows to extend the default security model (SELinux etc.)
sound ALSA (and the older OSS)
tools User space tools (used for testing etc.)
usr initrd. Default directory when calling make header_… (overridable with INSTALL_HDR_PATH environment variable).
virt KVM

Files

built-in.a Created when the kernel is made
COPYING
CREDITS
Kbuild
Kconfig
MAINTAINERS
Makefile
modules.builtin Created when the kernel is made
modules.builtin.modinfo Created when the kernel is made
modules.order Created when the kernel is made
Module.symvers Created when the kernel is made
README
.config Values of config symboles used when compiling the Kernel.
System.map Created when the kernel is made
vmlinux Created when the kernel is made
vmlinux.a Created when the kernel is made
vmlinux.o Created when the kernel is made
.mailmap
tags Created with one of the make targets to create a tags file.
.vmlinux.export.c
.tmp_vmlinux.kallsyms1
.tmp_vmlinux.kallsyms2
.tmp_vmlinux.kallsyms1.syms
.tmp_vmlinux.kallsyms2.syms
.tmp_vmlinux.kallsyms1.S
.tmp_vmlinux.kallsyms2.S
.version

Determining the latest version (in a script etc.)

In the command line (or by extension a script), the latest version numbers can be determined with 
$ curl -s https://www.kernel.org/finger_banner
The latest stable version of the Linux kernel is:             6.9.8
The latest mainline version of the Linux kernel is:           6.10-rc7
The latest stable 6.9 version of the Linux kernel is:         6.9.8
The latest longterm 6.6 version of the Linux kernel is:       6.6.38
The latest longterm 6.1 version of the Linux kernel is:       6.1.97
The latest longterm 5.15 version of the Linux kernel is:      5.15.162
The latest longterm 5.10 version of the Linux kernel is:      5.10.221
The latest longterm 5.4 version of the Linux kernel is:       5.4.279
The latest longterm 4.19 version of the Linux kernel is:      4.19.317
The latest linux-next version of the Linux kernel is:         next-20240709

$ curl -s https://www.kernel.org/releases.json | jq -r .latest_stable.version
6.9.8

Getting the sources

From an archive

Get the link for the latest «stable» sources and downoad it: 
$ latest_stable_dir=~/latest-stable-kernel
$ mkdir -p $latest_stable_dir
$ latest_stable_url=$( curl -s https://www.kernel.org/releases.json | jq -r '.releases[] | select(.moniker == "stable") | .source' )
$ curl $latest_stable_url | tar xJ -C $latest_stable_dir
$ dir $latest_stable_dir
linux-6.9.8
Alternatively, using the --strip-components option of tar, the kernel sources can be extracted to a destination without having a directory with the version number: 
$ curl $latest_stable_url | tar xJ -C $latest_stable_dir --strip-components=1
$ ls $latest_stable_dir/
arch   certs    CREDITS  Documentation  fs   init    ipc     Kconfig  lib       MAINTAINERS  mm   README  samples  security  tools  virt
block  COPYING  crypto   drivers  include  io_uring  Kbuild  kernel   LICENSES  Makefile     net  rust    scripts  sound     usr
Same idea, but as an (almost) one-liner: 
mkdir -p linux-src
curl $( curl -s https://www.kernel.org/releases.json | jq -r '.releases[] | select(.moniker == "stable") | .source' ) | tar xJ -C linux-src --strip-components=1

With git

Shallow copy of most recent sources in git repository: 
$ git clone --depth 1 -b master https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git ~/linux-src

Browsing the sources

Elixir Cross Referencer
There are specific make targets to create tag files.

Find definition of a given struct

Find the definition of a given struct (here: struct task_struct): 
grep -rl -P '^struct task_struct {(?!})' --include='*.h'

TODO

KCONFIG variables

The KCONFIG variables found in the source tree can be found with 
$ grep -r -h -o -P '\bKCONFIG_\w+' | sort | uniq
KCONFIG_ALLCONFIG Specifies the location of a file that contains preset config symbols. If set to "" or 1, make *config tries to find such config symbols in a file named all{yes/mod/no/def/random}.config
KCONFIG_CONFIG Specifies the path to the kernel config file (Default is .config)
KCONFIG_DEFCONFIG_LIST A (white space separated) list of base config files, the first existing of which is used in case a .config is not present.
KCONFIG_OVERWRITECONFIG If set, Kconfig will not break symlinks when .config is symlinked to another file.
KCONFIG_PATH Only used as script variable in tools/testing/kunit/kunit_kernel.py
KCONFIG_REL_PATHS Only used as script variable in tools/testing/selftests/bpf/vmtest.sh
KCONFIG_WARN_UNKNOWN_SYMBOLS If set, Kconfig will warn about all unrecognized symbols in the config input
KCONFIG_WERROR If set, Kconfig will treat warnings as errors.
Variables used in conjunction with randconfig:
KCONFIG_SEED Sets the seed for the random number generator (default: current time)
KCONFIG_PROBABILITY Used to skew probabilities.
Variables used in conjunction with syncconfig:
KCONFIG_AUTOCONFIG Specifies the path of the auto.conf file (default: include/config/auto.conf)
KCONFIG_AUTOHEADER Specifies the path of the autoconf.h header file (default: include/generated/autoconf.h)
KCONFIG_NOSILENTUPDATE If value is non-blank, silent kernel config updates are prevented (i. e. explicit updates are required)
Others
KCONFIG_ARG Only used as shell script variable in tools/testing/selftests/rcutorture/bin/kvm.sh
KCONFIG_ARGS Only used as shell script variable in scripts/tags.sh
KCONFIG_RUSTCCFG Found only in scripts/kconfig/confdata.c
KCONFIG_SEC Found only in tools/lib/bpf/libbpf.c where it is #defined to .kconfig

Memory

Page tables

A page table page can be thought of an array like 
pXd_t levelY_kernel_pgt[PTRS_PER_PxD]
pXd_t levelY_ident_pgt [PTRS_PER_PxD]
X is one of 4, u, m, t; Y is 4, 3, 2, 1
There is also a top level tree: init_top_pgt.
These variables are externally declared in arch/x86/include/asm/pgtable_64.h.
pXx_index() returns the index of the entry in the page table page which would control the given virtual address.
On x86, CONFIG_PGTABLE_LEVELS is an integer that is set to
  • 5 if X86_5LEVEL is enabled,
  • 4 if x86_64 is enabled,
  • 3 if X86_PAE is enable,
  • 2 otherwise
include/linux/pgtable.h
__PAGETABLE_P4D_FOLDED, __PAGETABLE_PUD_FOLDED, __PAGETABLE_PMD_FOLDED
See also page tables (memory).

5-level page tables

5-level page tables allow to access up to 128 PiB of virtual and 4 PiB of physical address space.
On x86_X64, the config option X86_5LEVEL must be enabled to use 5-level page tables.
An x86 CPU supports 5-level pages tables if the la57 flag is present which can be queried from the flags lines in /proc/cpuinfo: 
$ grep '^flags.*la57' /proc/cpuinfo && echo 'la57 is enabled'
See also Documentation/arch/x86/x86_64/5level-paging.rst.

__KERNEL__ and __MODULE__

The macro __KERNEL__ is defined (gcc … -D__KERNEL__ …`) when compiling a source file for the kernel.
This allows for example to include the same header file for both the kernel and a user space program.
See for example include/linux/raid/pq.h.
__MODULE__ is defined if a driver is selected to be compiled as a module (rather than be built-in the kernel).

EFI

CONFIG_EFI_MIXED

The .compat section in header.S is only present if CONFIG_EFI_MIXED is enabled.

Handover Protocol

LKML: efi: x86: Make the deprecated EFI handover protocol optional
CONFIG_EFI_HANDOVER_PROTOCOL

Sections

objdump -h vmlinux prints all sections found in the kernel.

Data sections

.data
.data.rel

Init data sections

.init.setup
.init.rodata
.meminit.rodata
.init.data
.meminit.data

Exit data sections

.exit.data
.memexit.data

Text sections

.text
.text.*
.sched.text
.kprobes.text
.cpuidle.text
.noinstr.text

Init text sections

.init.text
.meminit.text

Ext text sections

.exit.text
.memexit.text

Other text sections

.ref.text
.head.text This section is placed at the head of vmlinux, before the normal .text section, and is typically used for entry point functions. The macro __HEAD is defined to be __section(".head.text","ax"). See also this comment in scripts/head-object-list.txt.
.spinlock.text
.fixup
.entry.text
.exception.text
.coldtext
.softirqentry.text
.bstext The bootsector? Found in arch/x86/boot/header.S

PCI init sections

.pci_fixup_early
.pci_fixup_header
.pci_fixup_final
.pci_fixup_enable
.pci_fixup_resume
.pci_fixup_resume_early
.pci_fixup_suspend

White list

scripts/mod/modpost.c says: sections that we do not want to do full section mismatch check on
.comment* echo $(objcopy --dump-section .comment=/dev/tty vmlinux) prints something like GCC: (Debian 10.2.1-6) 10.2.1 20210110
.debug*
.zdebug* Compressed debug sections.
.GCC.command.line record-gcc-switches
.mdebug* alpha, score, mips etc.
.pdr alpha, score, mips etc.
.stab*
.note*
.got*
.toc*
.xt.prop xtensa
.xt.lit xtensa
.arcextmap* arc
.gnu.linkonce.arcext* arc : modules
.cmem* EZchip
.fmt_slot* EZchip
.gnu.lto*
.discard.*
.llvm.call-graph-profile call graph

kallsyms

With CONFIG_KALLSYMS enabled, the kernel is built with the symbols of functions (text and inittext sections) in order to print out stack backtraces and crash information with these symbols
CONFIG_KALLSYMS_ALL includes all symbols (i. e. names of variables from the data section)
These features comes with the cost of an increased kernel size because it contains the symbols.
kallsyms_lookup_name is used by the in-kernel kprobe address resolution code.
Wih enabled kallsyms, the s and S format specifies in printk print the symbol names rather than their address.
See also

Kprobes

Kprobes allows to dynamically break into (non-blacklisted) kernel function and collect debugging and performance information non-disruptively.
See also Documentation/trace/kprobes.rst

Determine the GCC options with which a source file is compiled

Using make -V can be used to determine the GCC options with which a C-file is compiled: 
$ touch kernel/sys.c
$ make V=1 2>/dev/null | grep 'gcc.*sys.c' > /tmp/compile-command
Of course, the created /tmp/compile-command file allows to produced the pre processed source file with a given configuration: the -E option must be added and the -c -o ….o options must be removed.

Minimal requirements to compile the Kernel

Documentation/process/changes.rst provides a list of the minimal requirements (software and version) to compile the Kernel.

BTF

With CONFIG_DEBUG_INFO_BTF enabled, building the Kernel also generates BTF (BPF type format) from DWARF in vmlinux and from kernel modules.
This feature requires pahole or llvm.
pahole acts as a dwarf2btf converter.
See also
  • include/uapi/linux/btf.h
  • Documentation/bpf/btf.rst
  • The function gen_btf() in scripts/link-vmlinux.sh.
  • The resolve_btfids tool (tools/bpf/resolve_btfids) scanes ELF objects for .BTF_ids sections and resolves its symbols with BTF ID values.

Most frequent first line

Count the number each different first line occurrs: 
$ find . -type f \( -name '*.c' -o -name '*.h' -o -name '*.rst' \) -exec head -1 {} \+ | sort | uniq -c | sort -nr | head -20
  60399 
  10189 // SPDX-License-Identifier: GPL-2.0
   8898 // SPDX-License-Identifier: GPL-2.0-only
   8526 /* SPDX-License-Identifier: GPL-2.0 */
   6600 /*
   5411 // SPDX-License-Identifier: GPL-2.0-or-later
   3970 /* SPDX-License-Identifier: GPL-2.0-only */
   2376 /* SPDX-License-Identifier: GPL-2.0-or-later */
   2022 // SPDX-License-Identifier: GPL-2.0+
   1203 .. SPDX-License-Identifier: GPL-2.0
   1093 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
    736 /* SPDX-License-Identifier: MIT */
    643 /* SPDX-License-Identifier: GPL-2.0+ */
    546 /* SPDX-License-Identifier: GPL-2.0
    363 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
    337 // SPDX-License-Identifier: MIT
    261 // SPDX-License-Identifier: BSD-3-Clause OR GPL-2.0
    258 // SPDX-License-Identifier: ISC
    207 // SPDX-License-Identifier: GPL-2.0 OR Linux-OpenIB
    207 // SPDX-License-Identifier: GPL-2.0 OR BSD-3-Clause
See also the scripts spdxcheck.py, spdxcheck-test.sh and spdxexclude.

Commiter != Author

git log --pretty='%aN#%cN'  | grep -v -P '^(.*)#\1$'

See also

Historically, Linux sources were owned by the user sys (which is obsolete now).

Index