diff options
Diffstat (limited to 'Documentation/dev-tools')
23 files changed, 828 insertions, 1186 deletions
diff --git a/Documentation/dev-tools/autofdo.rst b/Documentation/dev-tools/autofdo.rst new file mode 100644 index 000000000000..1f0a451e9ccd --- /dev/null +++ b/Documentation/dev-tools/autofdo.rst @@ -0,0 +1,168 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================== +Using AutoFDO with the Linux kernel +=================================== + +This enables AutoFDO build support for the kernel when using +the Clang compiler. AutoFDO (Auto-Feedback-Directed Optimization) +is a type of profile-guided optimization (PGO) used to enhance the +performance of binary executables. It gathers information about the +frequency of execution of various code paths within a binary using +hardware sampling. This data is then used to guide the compiler's +optimization decisions, resulting in a more efficient binary. AutoFDO +is a powerful optimization technique, and data indicates that it can +significantly improve kernel performance. It's especially beneficial +for workloads affected by front-end stalls. + +For AutoFDO builds, unlike non-FDO builds, the user must supply a +profile. Acquiring an AutoFDO profile can be done in several ways. +AutoFDO profiles are created by converting hardware sampling using +the "perf" tool. It is crucial that the workload used to create these +perf files is representative; they must exhibit runtime +characteristics similar to the workloads that are intended to be +optimized. Failure to do so will result in the compiler optimizing +for the wrong objective. + +The AutoFDO profile often encapsulates the program's behavior. If the +performance-critical codes are architecture-independent, the profile +can be applied across platforms to achieve performance gains. For +instance, using the profile generated on Intel architecture to build +a kernel for AMD architecture can also yield performance improvements. + +There are two methods for acquiring a representative profile: +(1) Sample real workloads using a production environment. +(2) Generate the profile using a representative load test. +When enabling the AutoFDO build configuration without providing an +AutoFDO profile, the compiler only modifies the dwarf information in +the kernel without impacting runtime performance. It's advisable to +use a kernel binary built with the same AutoFDO configuration to +collect the perf profile. While it's possible to use a kernel built +with different options, it may result in inferior performance. + +One can collect profiles using AutoFDO build for the previous kernel. +AutoFDO employs relative line numbers to match the profiles, offering +some tolerance for source changes. This mode is commonly used in a +production environment for profile collection. + +In a profile collection based on a load test, the AutoFDO collection +process consists of the following steps: + +#. Initial build: The kernel is built with AutoFDO options + without a profile. + +#. Profiling: The above kernel is then run with a representative + workload to gather execution frequency data. This data is + collected using hardware sampling, via perf. AutoFDO is most + effective on platforms supporting advanced PMU features like + LBR on Intel machines. + +#. AutoFDO profile generation: Perf output file is converted to + the AutoFDO profile via offline tools. + +The support requires a Clang compiler LLVM 17 or later. + +Preparation +=========== + +Configure the kernel with:: + + CONFIG_AUTOFDO_CLANG=y + +Customization +============= + +The default CONFIG_AUTOFDO_CLANG setting covers kernel space objects for +AutoFDO builds. One can, however, enable or disable AutoFDO build for +individual files and directories by adding a line similar to the following +to the respective kernel Makefile: + +- For enabling a single file (e.g. foo.o) :: + + AUTOFDO_PROFILE_foo.o := y + +- For enabling all files in one directory :: + + AUTOFDO_PROFILE := y + +- For disabling one file :: + + AUTOFDO_PROFILE_foo.o := n + +- For disabling all files in one directory :: + + AUTOFDO_PROFILE := n + +Workflow +======== + +Here is an example workflow for AutoFDO kernel: + +1) Build the kernel on the host machine with LLVM enabled, + for example, :: + + $ make menuconfig LLVM=1 + + Turn on AutoFDO build config:: + + CONFIG_AUTOFDO_CLANG=y + + With a configuration that with LLVM enabled, use the following command:: + + $ scripts/config -e AUTOFDO_CLANG + + After getting the config, build with :: + + $ make LLVM=1 + +2) Install the kernel on the test machine. + +3) Run the load tests. The '-c' option in perf specifies the sample + event period. We suggest using a suitable prime number, like 500009, + for this purpose. + + - For Intel platforms:: + + $ perf record -e BR_INST_RETIRED.NEAR_TAKEN:k -a -N -b -c <count> -o <perf_file> -- <loadtest> + + - For AMD platforms: + + The supported systems are: Zen3 with BRS, or Zen4 with amd_lbr_v2. To check, + + For Zen3:: + + $ cat proc/cpuinfo | grep " brs" + + For Zen4:: + + $ cat proc/cpuinfo | grep amd_lbr_v2 + + The following command generated the perf data file:: + + $ perf record --pfm-events RETIRED_TAKEN_BRANCH_INSTRUCTIONS:k -a -N -b -c <count> -o <perf_file> -- <loadtest> + +4) (Optional) Download the raw perf file to the host machine. + +5) To generate an AutoFDO profile, two offline tools are available: + create_llvm_prof and llvm_profgen. The create_llvm_prof tool is part + of the AutoFDO project and can be found on GitHub + (https://github.com/google/autofdo), version v0.30.1 or later. + The llvm_profgen tool is included in the LLVM compiler itself. It's + important to note that the version of llvm_profgen doesn't need to match + the version of Clang. It needs to be the LLVM 19 release of Clang + or later, or just from the LLVM trunk. :: + + $ llvm-profgen --kernel --binary=<vmlinux> --perfdata=<perf_file> -o <profile_file> + + or :: + + $ create_llvm_prof --binary=<vmlinux> --profile=<perf_file> --format=extbinary --out=<profile_file> + + Note that multiple AutoFDO profile files can be merged into one via:: + + $ llvm-profdata merge -o <profile_file> <profile_1> <profile_2> ... <profile_n> + +6) Rebuild the kernel using the AutoFDO profile file with the same config as step 1, + (Note CONFIG_AUTOFDO_CLANG needs to be enabled):: + + $ make LLVM=1 CLANG_AUTOFDO_PROFILE=<profile_file> diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst index 127968995847..76bd0ddb0041 100644 --- a/Documentation/dev-tools/checkpatch.rst +++ b/Documentation/dev-tools/checkpatch.rst @@ -342,24 +342,6 @@ API usage See: https://www.kernel.org/doc/html/latest/RCU/whatisRCU.html#full-list-of-rcu-apis - **DEPRECATED_VARIABLE** - EXTRA_{A,C,CPP,LD}FLAGS are deprecated and should be replaced by the new - flags added via commit f77bf01425b1 ("kbuild: introduce ccflags-y, - asflags-y and ldflags-y"). - - The following conversion scheme maybe used:: - - EXTRA_AFLAGS -> asflags-y - EXTRA_CFLAGS -> ccflags-y - EXTRA_CPPFLAGS -> cppflags-y - EXTRA_LDFLAGS -> ldflags-y - - See: - - 1. https://lore.kernel.org/lkml/20070930191054.GA15876@uranus.ravnborg.org/ - 2. https://lore.kernel.org/lkml/1313384834-24433-12-git-send-email-lacombar@gmail.com/ - 3. https://www.kernel.org/doc/html/latest/kbuild/makefiles.html#compilation-flags - **DEVICE_ATTR_FUNCTIONS** The function names used in DEVICE_ATTR is unusual. Typically, the store and show functions are used with <attr>_store and @@ -470,8 +452,6 @@ API usage usleep_range() should be preferred over udelay(). The proper way of using usleep_range() is mentioned in the kernel docs. - See: https://www.kernel.org/doc/html/latest/timers/timers-howto.html#delays-information-on-the-various-kernel-delay-sleep-mechanisms - Comments -------- @@ -906,6 +886,20 @@ Macros, Attributes and Symbols See: https://lore.kernel.org/lkml/1399671106.2912.21.camel@joe-AO725/ + **MACRO_ARG_UNUSED** + If function-like macros do not utilize a parameter, it might result + in a build warning. We advocate for utilizing static inline functions + to replace such macros. + For example, for a macro such as the one below:: + + #define test(a) do { } while (0) + + there would be a warning like below:: + + WARNING: Argument 'a' is not used in function-like macro. + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#macros-enums-and-rtl + **SINGLE_STATEMENT_DO_WHILE_MACRO** For the multi-statement macros, it is necessary to use the do-while loop to avoid unpredictable code paths. The do-while loop helps to diff --git a/Documentation/dev-tools/clang-format.rst b/Documentation/dev-tools/clang-format.rst new file mode 100644 index 000000000000..1d089a847c1b --- /dev/null +++ b/Documentation/dev-tools/clang-format.rst @@ -0,0 +1,184 @@ +.. _clangformat: + +clang-format +============ + +``clang-format`` is a tool to format C/C++/... code according to +a set of rules and heuristics. Like most tools, it is not perfect +nor covers every single case, but it is good enough to be helpful. + +``clang-format`` can be used for several purposes: + + - Quickly reformat a block of code to the kernel style. Specially useful + when moving code around and aligning/sorting. See clangformatreformat_. + + - Spot style mistakes, typos and possible improvements in files + you maintain, patches you review, diffs, etc. See clangformatreview_. + + - Help you follow the coding style rules, specially useful for those + new to kernel development or working at the same time in several + projects with different coding styles. + +Its configuration file is ``.clang-format`` in the root of the kernel tree. +The rules contained there try to approximate the most common kernel +coding style. They also try to follow :ref:`Documentation/process/coding-style.rst <codingstyle>` +as much as possible. Since not all the kernel follows the same style, +it is possible that you may want to tweak the defaults for a particular +subsystem or folder. To do so, you can override the defaults by writing +another ``.clang-format`` file in a subfolder. + +The tool itself has already been included in the repositories of popular +Linux distributions for a long time. Search for ``clang-format`` in +your repositories. Otherwise, you can either download pre-built +LLVM/clang binaries or build the source code from: + + https://releases.llvm.org/download.html + +See more information about the tool at: + + https://clang.llvm.org/docs/ClangFormat.html + + https://clang.llvm.org/docs/ClangFormatStyleOptions.html + + +.. _clangformatreview: + +Review files and patches for coding style +----------------------------------------- + +By running the tool in its inline mode, you can review full subsystems, +folders or individual files for code style mistakes, typos or improvements. + +To do so, you can run something like:: + + # Make sure your working directory is clean! + clang-format -i kernel/*.[ch] + +And then take a look at the git diff. + +Counting the lines of such a diff is also useful for improving/tweaking +the style options in the configuration file; as well as testing new +``clang-format`` features/versions. + +``clang-format`` also supports reading unified diffs, so you can review +patches and git diffs easily. See the documentation at: + + https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting + +To avoid ``clang-format`` formatting some portion of a file, you can do:: + + int formatted_code; + // clang-format off + void unformatted_code ; + // clang-format on + void formatted_code_again; + +While it might be tempting to use this to keep a file always in sync with +``clang-format``, specially if you are writing new files or if you are +a maintainer, please note that people might be running different +``clang-format`` versions or not have it available at all. Therefore, +you should probably refrain yourself from using this in kernel sources; +at least until we see if ``clang-format`` becomes commonplace. + + +.. _clangformatreformat: + +Reformatting blocks of code +--------------------------- + +By using an integration with your text editor, you can reformat arbitrary +blocks (selections) of code with a single keystroke. This is specially +useful when moving code around, for complex code that is deeply intended, +for multi-line macros (and aligning their backslashes), etc. + +Remember that you can always tweak the changes afterwards in those cases +where the tool did not do an optimal job. But as a first approximation, +it can be very useful. + +There are integrations for many popular text editors. For some of them, +like vim, emacs, BBEdit and Visual Studio you can find support built-in. +For instructions, read the appropriate section at: + + https://clang.llvm.org/docs/ClangFormat.html + +For Atom, Eclipse, Sublime Text, Visual Studio Code, XCode and other +editors and IDEs you should be able to find ready-to-use plugins. + +For this use case, consider using a secondary ``.clang-format`` +so that you can tweak a few options. See clangformatextra_. + + +.. _clangformatmissing: + +Missing support +--------------- + +``clang-format`` is missing support for some things that are common +in kernel code. They are easy to remember, so if you use the tool +regularly, you will quickly learn to avoid/ignore those. + +In particular, some very common ones you will notice are: + + - Aligned blocks of one-line ``#defines``, e.g.:: + + #define TRACING_MAP_BITS_DEFAULT 11 + #define TRACING_MAP_BITS_MAX 17 + #define TRACING_MAP_BITS_MIN 7 + + vs.:: + + #define TRACING_MAP_BITS_DEFAULT 11 + #define TRACING_MAP_BITS_MAX 17 + #define TRACING_MAP_BITS_MIN 7 + + - Aligned designated initializers, e.g.:: + + static const struct file_operations uprobe_events_ops = { + .owner = THIS_MODULE, + .open = probes_open, + .read = seq_read, + .llseek = seq_lseek, + .release = seq_release, + .write = probes_write, + }; + + vs.:: + + static const struct file_operations uprobe_events_ops = { + .owner = THIS_MODULE, + .open = probes_open, + .read = seq_read, + .llseek = seq_lseek, + .release = seq_release, + .write = probes_write, + }; + + +.. _clangformatextra: + +Extra features/options +---------------------- + +Some features/style options are not enabled by default in the configuration +file in order to minimize the differences between the output and the current +code. In other words, to make the difference as small as possible, +which makes reviewing full-file style, as well diffs and patches as easy +as possible. + +In other cases (e.g. particular subsystems/folders/files), the kernel style +might be different and enabling some of these options may approximate +better the style there. + +For instance: + + - Aligning assignments (``AlignConsecutiveAssignments``). + + - Aligning declarations (``AlignConsecutiveDeclarations``). + + - Reflowing text in comments (``ReflowComments``). + + - Sorting ``#includes`` (``SortIncludes``). + +They are typically useful for block re-formatting, rather than full-file. +You might want to create another ``.clang-format`` file and use that one +from your editor/IDE instead. diff --git a/Documentation/dev-tools/coccinelle.rst b/Documentation/dev-tools/coccinelle.rst index 535ce126fb4f..6e70a1e9a3c0 100644 --- a/Documentation/dev-tools/coccinelle.rst +++ b/Documentation/dev-tools/coccinelle.rst @@ -250,25 +250,17 @@ variables for .cocciconfig is as follows: - Your directory from which spatch is called is processed next - The directory provided with the ``--dir`` option is processed last, if used -Since coccicheck runs through make, it naturally runs from the kernel -proper dir; as such the second rule above would be implied for picking up a -.cocciconfig when using ``make coccicheck``. - ``make coccicheck`` also supports using M= targets. If you do not supply any M= target, it is assumed you want to target the entire kernel. The kernel coccicheck script has:: - if [ "$KBUILD_EXTMOD" = "" ] ; then - OPTIONS="--dir $srctree $COCCIINCLUDE" - else - OPTIONS="--dir $KBUILD_EXTMOD $COCCIINCLUDE" - fi - -KBUILD_EXTMOD is set when an explicit target with M= is used. For both cases -the spatch ``--dir`` argument is used, as such third rule applies when whether -M= is used or not, and when M= is used the target directory can have its own -.cocciconfig file. When M= is not passed as an argument to coccicheck the -target directory is the same as the directory from where spatch was called. + OPTIONS="--dir $srcroot $COCCIINCLUDE" + +Here, $srcroot refers to the source directory of the target: it points to the +external module's source directory when M= used, and otherwise, to the kernel +source directory. The third rule ensures the spatch reads the .cocciconfig from +the target directory, allowing external modules to have their own .cocciconfig +file. If not using the kernel's coccicheck target, keep the above precedence order logic of .cocciconfig reading. If using the kernel's coccicheck target, diff --git a/Documentation/dev-tools/gcov.rst b/Documentation/dev-tools/gcov.rst index 5fce2b06f229..075df6a4598d 100644 --- a/Documentation/dev-tools/gcov.rst +++ b/Documentation/dev-tools/gcov.rst @@ -23,7 +23,7 @@ Possible uses: associated code is never run?) .. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html -.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php +.. _lcov: https://github.com/linux-test-project/lcov Preparation @@ -75,6 +75,17 @@ Only files which are linked to the main kernel image or are compiled as kernel modules are supported by this mechanism. +Module specific configs +----------------------- + +Gcov kernel configs for specific modules are described below: + +CONFIG_GCOV_PROFILE_RDS: + Enables GCOV profiling on RDS for checking which functions or + lines are executed. This config is used by the rds selftest to + generate coverage reports. If left unset the report is omitted. + + Files ----- diff --git a/Documentation/dev-tools/gdb-kernel-debugging.rst b/Documentation/dev-tools/gdb-kernel-debugging.rst deleted file mode 100644 index 895285c037c7..000000000000 --- a/Documentation/dev-tools/gdb-kernel-debugging.rst +++ /dev/null @@ -1,179 +0,0 @@ -.. highlight:: none - -Debugging kernel and modules via gdb -==================================== - -The kernel debugger kgdb, hypervisors like QEMU or JTAG-based hardware -interfaces allow to debug the Linux kernel and its modules during runtime -using gdb. Gdb comes with a powerful scripting interface for python. The -kernel provides a collection of helper scripts that can simplify typical -kernel debugging steps. This is a short tutorial about how to enable and use -them. It focuses on QEMU/KVM virtual machines as target, but the examples can -be transferred to the other gdb stubs as well. - - -Requirements ------------- - -- gdb 7.2+ (recommended: 7.4+) with python support enabled (typically true - for distributions) - - -Setup ------ - -- Create a virtual Linux machine for QEMU/KVM (see www.linux-kvm.org and - www.qemu.org for more details). For cross-development, - https://landley.net/aboriginal/bin keeps a pool of machine images and - toolchains that can be helpful to start from. - -- Build the kernel with CONFIG_GDB_SCRIPTS enabled, but leave - CONFIG_DEBUG_INFO_REDUCED off. If your architecture supports - CONFIG_FRAME_POINTER, keep it enabled. - -- Install that kernel on the guest, turn off KASLR if necessary by adding - "nokaslr" to the kernel command line. - Alternatively, QEMU allows to boot the kernel directly using -kernel, - -append, -initrd command line switches. This is generally only useful if - you do not depend on modules. See QEMU documentation for more details on - this mode. In this case, you should build the kernel with - CONFIG_RANDOMIZE_BASE disabled if the architecture supports KASLR. - -- Build the gdb scripts (required on kernels v5.1 and above):: - - make scripts_gdb - -- Enable the gdb stub of QEMU/KVM, either - - - at VM startup time by appending "-s" to the QEMU command line - - or - - - during runtime by issuing "gdbserver" from the QEMU monitor - console - -- cd /path/to/linux-build - -- Start gdb: gdb vmlinux - - Note: Some distros may restrict auto-loading of gdb scripts to known safe - directories. In case gdb reports to refuse loading vmlinux-gdb.py, add:: - - add-auto-load-safe-path /path/to/linux-build - - to ~/.gdbinit. See gdb help for more details. - -- Attach to the booted guest:: - - (gdb) target remote :1234 - - -Examples of using the Linux-provided gdb helpers ------------------------------------------------- - -- Load module (and main kernel) symbols:: - - (gdb) lx-symbols - loading vmlinux - scanning for modules in /home/user/linux/build - loading @0xffffffffa0020000: /home/user/linux/build/net/netfilter/xt_tcpudp.ko - loading @0xffffffffa0016000: /home/user/linux/build/net/netfilter/xt_pkttype.ko - loading @0xffffffffa0002000: /home/user/linux/build/net/netfilter/xt_limit.ko - loading @0xffffffffa00ca000: /home/user/linux/build/net/packet/af_packet.ko - loading @0xffffffffa003c000: /home/user/linux/build/fs/fuse/fuse.ko - ... - loading @0xffffffffa0000000: /home/user/linux/build/drivers/ata/ata_generic.ko - -- Set a breakpoint on some not yet loaded module function, e.g.:: - - (gdb) b btrfs_init_sysfs - Function "btrfs_init_sysfs" not defined. - Make breakpoint pending on future shared library load? (y or [n]) y - Breakpoint 1 (btrfs_init_sysfs) pending. - -- Continue the target:: - - (gdb) c - -- Load the module on the target and watch the symbols being loaded as well as - the breakpoint hit:: - - loading @0xffffffffa0034000: /home/user/linux/build/lib/libcrc32c.ko - loading @0xffffffffa0050000: /home/user/linux/build/lib/lzo/lzo_compress.ko - loading @0xffffffffa006e000: /home/user/linux/build/lib/zlib_deflate/zlib_deflate.ko - loading @0xffffffffa01b1000: /home/user/linux/build/fs/btrfs/btrfs.ko - - Breakpoint 1, btrfs_init_sysfs () at /home/user/linux/fs/btrfs/sysfs.c:36 - 36 btrfs_kset = kset_create_and_add("btrfs", NULL, fs_kobj); - -- Dump the log buffer of the target kernel:: - - (gdb) lx-dmesg - [ 0.000000] Initializing cgroup subsys cpuset - [ 0.000000] Initializing cgroup subsys cpu - [ 0.000000] Linux version 3.8.0-rc4-dbg+ (... - [ 0.000000] Command line: root=/dev/sda2 resume=/dev/sda1 vga=0x314 - [ 0.000000] e820: BIOS-provided physical RAM map: - [ 0.000000] BIOS-e820: [mem 0x0000000000000000-0x000000000009fbff] usable - [ 0.000000] BIOS-e820: [mem 0x000000000009fc00-0x000000000009ffff] reserved - .... - -- Examine fields of the current task struct(supported by x86 and arm64 only):: - - (gdb) p $lx_current().pid - $1 = 4998 - (gdb) p $lx_current().comm - $2 = "modprobe\000\000\000\000\000\000\000" - -- Make use of the per-cpu function for the current or a specified CPU:: - - (gdb) p $lx_per_cpu("runqueues").nr_running - $3 = 1 - (gdb) p $lx_per_cpu("runqueues", 2).nr_running - $4 = 0 - -- Dig into hrtimers using the container_of helper:: - - (gdb) set $next = $lx_per_cpu("hrtimer_bases").clock_base[0].active.next - (gdb) p *$container_of($next, "struct hrtimer", "node") - $5 = { - node = { - node = { - __rb_parent_color = 18446612133355256072, - rb_right = 0x0 <irq_stack_union>, - rb_left = 0x0 <irq_stack_union> - }, - expires = { - tv64 = 1835268000000 - } - }, - _softexpires = { - tv64 = 1835268000000 - }, - function = 0xffffffff81078232 <tick_sched_timer>, - base = 0xffff88003fd0d6f0, - state = 1, - start_pid = 0, - start_site = 0xffffffff81055c1f <hrtimer_start_range_ns+20>, - start_comm = "swapper/2\000\000\000\000\000\000" - } - - -List of commands and functions ------------------------------- - -The number of commands and convenience functions may evolve over the time, -this is just a snapshot of the initial version:: - - (gdb) apropos lx - function lx_current -- Return current task - function lx_module -- Find module by name and return the module variable - function lx_per_cpu -- Return per-cpu variable - function lx_task_by_pid -- Find Linux task by PID and return the task_struct variable - function lx_thread_info -- Calculate Linux thread_info from task variable - lx-dmesg -- Print Linux kernel log buffer - lx-lsmod -- List currently loaded modules - lx-symbols -- (Re-)load symbols of Linux kernel and currently loaded modules - -Detailed help can be obtained via "help <command-name>" for commands and "help -function <function-name>" for convenience functions. diff --git a/Documentation/dev-tools/gpio-sloppy-logic-analyzer.rst b/Documentation/dev-tools/gpio-sloppy-logic-analyzer.rst new file mode 100644 index 000000000000..d69f24c0d9e1 --- /dev/null +++ b/Documentation/dev-tools/gpio-sloppy-logic-analyzer.rst @@ -0,0 +1,93 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================= +Linux Kernel GPIO based sloppy logic analyzer +============================================= + +:Author: Wolfram Sang + +Introduction +============ + +This document briefly describes how to run the GPIO based in-kernel sloppy +logic analyzer running on an isolated CPU. + +The sloppy logic analyzer will utilize a few GPIO lines in input mode on a +system to rapidly sample these digital lines, which will, if the Nyquist +criteria is met, result in a time series log with approximate waveforms as they +appeared on these lines. One way to use it is to analyze external traffic +connected to these GPIO lines with wires (i.e. digital probes), acting as a +common logic analyzer. + +Another feature is to snoop on on-chip peripherals if the I/O cells of these +peripherals can be used in GPIO input mode at the same time as they are being +used as inputs or outputs for the peripheral. That means you could e.g. snoop +I2C traffic without any wiring (if your hardware supports it). In the pin +control subsystem such pin controllers are called "non-strict": a certain pin +can be used with a certain peripheral and as a GPIO input line at the same +time. + +Note that this is a last resort analyzer which can be affected by latencies, +non-deterministic code paths and non-maskable interrupts. It is called 'sloppy' +for a reason. However, for e.g. remote development, it may be useful to get a +first view and aid further debugging. + +Setup +===== + +Your kernel must have CONFIG_DEBUG_FS and CONFIG_CPUSETS enabled. Ideally, your +runtime environment does not utilize cpusets otherwise, then isolation of a CPU +core is easiest. If you do need cpusets, check that helper script for the +sloppy logic analyzer does not interfere with your other settings. + +Tell the kernel which GPIOs are used as probes. For a Device Tree based system, +you need to use the following bindings. Because these bindings are only for +debugging, there is no official schema:: + + i2c-analyzer { + compatible = "gpio-sloppy-logic-analyzer"; + probe-gpios = <&gpio6 21 GPIO_OPEN_DRAIN>, <&gpio6 4 GPIO_OPEN_DRAIN>; + probe-names = "SCL", "SDA"; + }; + +Note that you must provide a name for every GPIO specified. Currently a +maximum of 8 probes are supported. 32 are likely possible but are not +implemented yet. + +Usage +===== + +The logic analyzer is configurable via files in debugfs. However, it is +strongly recommended to not use them directly, but to use the script +``tools/gpio/gpio-sloppy-logic-analyzer``. Besides checking parameters more +extensively, it will isolate the CPU core so you will have the least +disturbance while measuring. + +The script has a help option explaining the parameters. For the above DT +snippet which analyzes an I2C bus at 400kHz on a Renesas Salvator-XS board, the +following settings are used: The isolated CPU shall be CPU1 because it is a big +core in a big.LITTLE setup. Because CPU1 is the default, we don't need a +parameter. The bus speed is 400kHz. So, the sampling theorem says we need to +sample at least at 800kHz. However, falling edges of both signals in an I2C +start condition happen faster, so we need a higher sampling frequency, e.g. +``-s 1500000`` for 1.5MHz. Also, we don't want to sample right away but wait +for a start condition on an idle bus. So, we need to set a trigger to a falling +edge on SDA while SCL stays high, i.e. ``-t 1H+2F``. Last is the duration, let +us assume 15ms here which results in the parameter ``-d 15000``. So, +altogether:: + + gpio-sloppy-logic-analyzer -s 1500000 -t 1H+2F -d 15000 + +Note that the process will return you back to the prompt but a sub-process is +still sampling in the background. Unless this has finished, you will not find a +result file in the current or specified directory. For the above example, we +will then need to trigger I2C communication:: + + i2cdetect -y -r <your bus number> + +Result is a .sr file to be consumed with PulseView or sigrok-cli from the free +`sigrok`_ project. It is a zip file which also contains the binary sample data +which may be consumed by other software. The filename is the logic analyzer +instance name plus a since-epoch timestamp. + +.. _sigrok: https://sigrok.org/ diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst index efa49cdc8e2e..65c54b27a60b 100644 --- a/Documentation/dev-tools/index.rst +++ b/Documentation/dev-tools/index.rst @@ -10,12 +10,16 @@ whole; patches welcome! A brief overview of testing-specific tools can be found in Documentation/dev-tools/testing-overview.rst +Tools that are specific to debugging can be found in +Documentation/process/debugging/index.rst + .. toctree:: :caption: Table of contents :maxdepth: 2 testing-overview checkpatch + clang-format coccinelle sparse kcov @@ -26,12 +30,13 @@ Documentation/dev-tools/testing-overview.rst kmemleak kcsan kfence - gdb-kernel-debugging - kgdb kselftest kunit/index ktap checkuapi + gpio-sloppy-logic-analyzer + autofdo + propeller .. only:: subproject and html diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst index d7de44f5339d..0a1418ab72fd 100644 --- a/Documentation/dev-tools/kasan.rst +++ b/Documentation/dev-tools/kasan.rst @@ -511,19 +511,14 @@ Tests ~~~~~ There are KASAN tests that allow verifying that KASAN works and can detect -certain types of memory corruptions. The tests consist of two parts: +certain types of memory corruptions. -1. Tests that are integrated with the KUnit Test Framework. Enabled with -``CONFIG_KASAN_KUNIT_TEST``. These tests can be run and partially verified +All KASAN tests are integrated with the KUnit Test Framework and can be enabled +via ``CONFIG_KASAN_KUNIT_TEST``. The tests can be run and partially verified automatically in a few different ways; see the instructions below. -2. Tests that are currently incompatible with KUnit. Enabled with -``CONFIG_KASAN_MODULE_TEST`` and can only be run as a module. These tests can -only be verified manually by loading the kernel module and inspecting the -kernel log for KASAN reports. - -Each KUnit-compatible KASAN test prints one of multiple KASAN reports if an -error is detected. Then the test prints its number and status. +Each KASAN test prints one of multiple KASAN reports if an error is detected. +Then the test prints its number and status. When a test passes:: @@ -550,16 +545,16 @@ Or, if one of the tests failed:: not ok 1 - kasan -There are a few ways to run KUnit-compatible KASAN tests. +There are a few ways to run the KASAN tests. 1. Loadable module - With ``CONFIG_KUNIT`` enabled, KASAN-KUnit tests can be built as a loadable - module and run by loading ``kasan_test.ko`` with ``insmod`` or ``modprobe``. + With ``CONFIG_KUNIT`` enabled, the tests can be built as a loadable module + and run by loading ``kasan_test.ko`` with ``insmod`` or ``modprobe``. 2. Built-In - With ``CONFIG_KUNIT`` built-in, KASAN-KUnit tests can be built-in as well. + With ``CONFIG_KUNIT`` built-in, the tests can be built-in as well. In this case, the tests will run at boot as a late-init call. 3. Using kunit_tool diff --git a/Documentation/dev-tools/kcsan.rst b/Documentation/dev-tools/kcsan.rst index 94b6802ab0ab..8575178aa87f 100644 --- a/Documentation/dev-tools/kcsan.rst +++ b/Documentation/dev-tools/kcsan.rst @@ -91,6 +91,16 @@ the below options are available: behaviour when encountering a data race is deemed safe. Please see `"Marking Shared-Memory Accesses" in the LKMM`_ for more information. +* Similar to ``data_race(...)``, the type qualifier ``__data_racy`` can be used + to document that all data races due to accesses to a variable are intended + and should be ignored by KCSAN:: + + struct foo { + ... + int __data_racy stats_counter; + ... + }; + * Disabling data race detection for entire functions can be accomplished by using the function attribute ``__no_kcsan``:: @@ -193,7 +203,7 @@ they happen concurrently in different threads, and at least one of them is a least one is a write. For a more thorough discussion and definition, see `"Plain Accesses and Data Races" in the LKMM`_. -.. _"Plain Accesses and Data Races" in the LKMM: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/memory-model/Documentation/explanation.txt#n1922 +.. _"Plain Accesses and Data Races" in the LKMM: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/memory-model/Documentation/explanation.txt?id=8f6629c004b193d23612641c3607e785819e97ab#n2164 Relationship with the Linux-Kernel Memory Consistency Model (LKMM) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -351,7 +361,8 @@ Alternatives Considered ----------------------- An alternative data race detection approach for the kernel can be found in the -`Kernel Thread Sanitizer (KTSAN) <https://github.com/google/ktsan/wiki>`_. +`Kernel Thread Sanitizer (KTSAN) +<https://github.com/google/kernel-sanitizers/blob/master/KTSAN.md>`_. KTSAN is a happens-before data race detector, which explicitly establishes the happens-before order between memory operations, which can then be used to determine data races as defined in `Data Races`_. diff --git a/Documentation/dev-tools/kfence.rst b/Documentation/dev-tools/kfence.rst index 936f6aaa75c8..541899353865 100644 --- a/Documentation/dev-tools/kfence.rst +++ b/Documentation/dev-tools/kfence.rst @@ -53,6 +53,13 @@ configurable via the Kconfig option ``CONFIG_KFENCE_DEFERRABLE``. The KUnit test suite is very likely to fail when using a deferrable timer since it currently causes very unpredictable sample intervals. +By default KFENCE will only sample 1 heap allocation within each sample +interval. *Burst mode* allows to sample successive heap allocations, where the +kernel boot parameter ``kfence.burst`` can be set to a non-zero value which +denotes the *additional* successive allocations within a sample interval; +setting ``kfence.burst=N`` means that ``1 + N`` successive allocations are +attempted through KFENCE for each sample interval. + The KFENCE memory pool is of fixed size, and if the pool is exhausted, no further KFENCE allocations occur. With ``CONFIG_KFENCE_NUM_OBJECTS`` (default 255), the number of available guarded objects can be controlled. Each object diff --git a/Documentation/dev-tools/kgdb.rst b/Documentation/dev-tools/kgdb.rst deleted file mode 100644 index f83ba2601e55..000000000000 --- a/Documentation/dev-tools/kgdb.rst +++ /dev/null @@ -1,939 +0,0 @@ -================================================= -Using kgdb, kdb and the kernel debugger internals -================================================= - -:Author: Jason Wessel - -Introduction -============ - -The kernel has two different debugger front ends (kdb and kgdb) which -interface to the debug core. It is possible to use either of the -debugger front ends and dynamically transition between them if you -configure the kernel properly at compile and runtime. - -Kdb is simplistic shell-style interface which you can use on a system -console with a keyboard or serial console. You can use it to inspect -memory, registers, process lists, dmesg, and even set breakpoints to -stop in a certain location. Kdb is not a source level debugger, although -you can set breakpoints and execute some basic kernel run control. Kdb -is mainly aimed at doing some analysis to aid in development or -diagnosing kernel problems. You can access some symbols by name in -kernel built-ins or in kernel modules if the code was built with -``CONFIG_KALLSYMS``. - -Kgdb is intended to be used as a source level debugger for the Linux -kernel. It is used along with gdb to debug a Linux kernel. The -expectation is that gdb can be used to "break in" to the kernel to -inspect memory, variables and look through call stack information -similar to the way an application developer would use gdb to debug an -application. It is possible to place breakpoints in kernel code and -perform some limited execution stepping. - -Two machines are required for using kgdb. One of these machines is a -development machine and the other is the target machine. The kernel to -be debugged runs on the target machine. The development machine runs an -instance of gdb against the vmlinux file which contains the symbols (not -a boot image such as bzImage, zImage, uImage...). In gdb the developer -specifies the connection parameters and connects to kgdb. The type of -connection a developer makes with gdb depends on the availability of -kgdb I/O modules compiled as built-ins or loadable kernel modules in the -test machine's kernel. - -Compiling a kernel -================== - -- In order to enable compilation of kdb, you must first enable kgdb. - -- The kgdb test compile options are described in the kgdb test suite - chapter. - -Kernel config options for kgdb ------------------------------- - -To enable ``CONFIG_KGDB`` you should look under -:menuselection:`Kernel hacking --> Kernel debugging` and select -:menuselection:`KGDB: kernel debugger`. - -While it is not a hard requirement that you have symbols in your vmlinux -file, gdb tends not to be very useful without the symbolic data, so you -will want to turn on ``CONFIG_DEBUG_INFO`` which is called -:menuselection:`Compile the kernel with debug info` in the config menu. - -It is advised, but not required, that you turn on the -``CONFIG_FRAME_POINTER`` kernel option which is called :menuselection:`Compile -the kernel with frame pointers` in the config menu. This option inserts code -into the compiled executable which saves the frame information in registers -or on the stack at different points which allows a debugger such as gdb to -more accurately construct stack back traces while debugging the kernel. - -If the architecture that you are using supports the kernel option -``CONFIG_STRICT_KERNEL_RWX``, you should consider turning it off. This -option will prevent the use of software breakpoints because it marks -certain regions of the kernel's memory space as read-only. If kgdb -supports it for the architecture you are using, you can use hardware -breakpoints if you desire to run with the ``CONFIG_STRICT_KERNEL_RWX`` -option turned on, else you need to turn off this option. - -Next you should choose one of more I/O drivers to interconnect debugging -host and debugged target. Early boot debugging requires a KGDB I/O -driver that supports early debugging and the driver must be built into -the kernel directly. Kgdb I/O driver configuration takes place via -kernel or module parameters which you can learn more about in the in the -section that describes the parameter kgdboc. - -Here is an example set of ``.config`` symbols to enable or disable for kgdb:: - - # CONFIG_STRICT_KERNEL_RWX is not set - CONFIG_FRAME_POINTER=y - CONFIG_KGDB=y - CONFIG_KGDB_SERIAL_CONSOLE=y - -Kernel config options for kdb ------------------------------ - -Kdb is quite a bit more complex than the simple gdbstub sitting on top -of the kernel's debug core. Kdb must implement a shell, and also adds -some helper functions in other parts of the kernel, responsible for -printing out interesting data such as what you would see if you ran -``lsmod``, or ``ps``. In order to build kdb into the kernel you follow the -same steps as you would for kgdb. - -The main config option for kdb is ``CONFIG_KGDB_KDB`` which is called -:menuselection:`KGDB_KDB: include kdb frontend for kgdb` in the config menu. -In theory you would have already also selected an I/O driver such as the -``CONFIG_KGDB_SERIAL_CONSOLE`` interface if you plan on using kdb on a -serial port, when you were configuring kgdb. - -If you want to use a PS/2-style keyboard with kdb, you would select -``CONFIG_KDB_KEYBOARD`` which is called :menuselection:`KGDB_KDB: keyboard as -input device` in the config menu. The ``CONFIG_KDB_KEYBOARD`` option is not -used for anything in the gdb interface to kgdb. The ``CONFIG_KDB_KEYBOARD`` -option only works with kdb. - -Here is an example set of ``.config`` symbols to enable/disable kdb:: - - # CONFIG_STRICT_KERNEL_RWX is not set - CONFIG_FRAME_POINTER=y - CONFIG_KGDB=y - CONFIG_KGDB_SERIAL_CONSOLE=y - CONFIG_KGDB_KDB=y - CONFIG_KDB_KEYBOARD=y - -Kernel Debugger Boot Arguments -============================== - -This section describes the various runtime kernel parameters that affect -the configuration of the kernel debugger. The following chapter covers -using kdb and kgdb as well as providing some examples of the -configuration parameters. - -Kernel parameter: kgdboc ------------------------- - -The kgdboc driver was originally an abbreviation meant to stand for -"kgdb over console". Today it is the primary mechanism to configure how -to communicate from gdb to kgdb as well as the devices you want to use -to interact with the kdb shell. - -For kgdb/gdb, kgdboc is designed to work with a single serial port. It -is intended to cover the circumstance where you want to use a serial -console as your primary console as well as using it to perform kernel -debugging. It is also possible to use kgdb on a serial port which is not -designated as a system console. Kgdboc may be configured as a kernel -built-in or a kernel loadable module. You can only make use of -``kgdbwait`` and early debugging if you build kgdboc into the kernel as -a built-in. - -Optionally you can elect to activate kms (Kernel Mode Setting) -integration. When you use kms with kgdboc and you have a video driver -that has atomic mode setting hooks, it is possible to enter the debugger -on the graphics console. When the kernel execution is resumed, the -previous graphics mode will be restored. This integration can serve as a -useful tool to aid in diagnosing crashes or doing analysis of memory -with kdb while allowing the full graphics console applications to run. - -kgdboc arguments -~~~~~~~~~~~~~~~~ - -Usage:: - - kgdboc=[kms][[,]kbd][[,]serial_device][,baud] - -The order listed above must be observed if you use any of the optional -configurations together. - -Abbreviations: - -- kms = Kernel Mode Setting - -- kbd = Keyboard - -You can configure kgdboc to use the keyboard, and/or a serial device -depending on if you are using kdb and/or kgdb, in one of the following -scenarios. The order listed above must be observed if you use any of the -optional configurations together. Using kms + only gdb is generally not -a useful combination. - -Using loadable module or built-in -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -1. As a kernel built-in: - - Use the kernel boot argument:: - - kgdboc=<tty-device>,[baud] - -2. As a kernel loadable module: - - Use the command:: - - modprobe kgdboc kgdboc=<tty-device>,[baud] - - Here are two examples of how you might format the kgdboc string. The - first is for an x86 target using the first serial port. The second - example is for the ARM Versatile AB using the second serial port. - - 1. ``kgdboc=ttyS0,115200`` - - 2. ``kgdboc=ttyAMA1,115200`` - -Configure kgdboc at runtime with sysfs -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -At run time you can enable or disable kgdboc by echoing a parameters -into the sysfs. Here are two examples: - -1. Enable kgdboc on ttyS0:: - - echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc - -2. Disable kgdboc:: - - echo "" > /sys/module/kgdboc/parameters/kgdboc - -.. note:: - - You do not need to specify the baud if you are configuring the - console on tty which is already configured or open. - -More examples -^^^^^^^^^^^^^ - -You can configure kgdboc to use the keyboard, and/or a serial device -depending on if you are using kdb and/or kgdb, in one of the following -scenarios. - -1. kdb and kgdb over only a serial port:: - - kgdboc=<serial_device>[,baud] - - Example:: - - kgdboc=ttyS0,115200 - -2. kdb and kgdb with keyboard and a serial port:: - - kgdboc=kbd,<serial_device>[,baud] - - Example:: - - kgdboc=kbd,ttyS0,115200 - -3. kdb with a keyboard:: - - kgdboc=kbd - -4. kdb with kernel mode setting:: - - kgdboc=kms,kbd - -5. kdb with kernel mode setting and kgdb over a serial port:: - - kgdboc=kms,kbd,ttyS0,115200 - -.. note:: - - Kgdboc does not support interrupting the target via the gdb remote - protocol. You must manually send a :kbd:`SysRq-G` unless you have a proxy - that splits console output to a terminal program. A console proxy has a - separate TCP port for the debugger and a separate TCP port for the - "human" console. The proxy can take care of sending the :kbd:`SysRq-G` - for you. - -When using kgdboc with no debugger proxy, you can end up connecting the -debugger at one of two entry points. If an exception occurs after you -have loaded kgdboc, a message should print on the console stating it is -waiting for the debugger. In this case you disconnect your terminal -program and then connect the debugger in its place. If you want to -interrupt the target system and forcibly enter a debug session you have -to issue a :kbd:`Sysrq` sequence and then type the letter :kbd:`g`. Then you -disconnect the terminal session and connect gdb. Your options if you -don't like this are to hack gdb to send the :kbd:`SysRq-G` for you as well as -on the initial connect, or to use a debugger proxy that allows an -unmodified gdb to do the debugging. - -Kernel parameter: ``kgdboc_earlycon`` -------------------------------------- - -If you specify the kernel parameter ``kgdboc_earlycon`` and your serial -driver registers a boot console that supports polling (doesn't need -interrupts and implements a nonblocking read() function) kgdb will attempt -to work using the boot console until it can transition to the regular -tty driver specified by the ``kgdboc`` parameter. - -Normally there is only one boot console (especially that implements the -read() function) so just adding ``kgdboc_earlycon`` on its own is -sufficient to make this work. If you have more than one boot console you -can add the boot console's name to differentiate. Note that names that -are registered through the boot console layer and the tty layer are not -the same for the same port. - -For instance, on one board to be explicit you might do:: - - kgdboc_earlycon=qcom_geni kgdboc=ttyMSM0 - -If the only boot console on the device was "qcom_geni", you could simplify:: - - kgdboc_earlycon kgdboc=ttyMSM0 - -Kernel parameter: ``kgdbwait`` ------------------------------- - -The Kernel command line option ``kgdbwait`` makes kgdb wait for a -debugger connection during booting of a kernel. You can only use this -option if you compiled a kgdb I/O driver into the kernel and you -specified the I/O driver configuration as a kernel command line option. -The kgdbwait parameter should always follow the configuration parameter -for the kgdb I/O driver in the kernel command line else the I/O driver -will not be configured prior to asking the kernel to use it to wait. - -The kernel will stop and wait as early as the I/O driver and -architecture allows when you use this option. If you build the kgdb I/O -driver as a loadable kernel module kgdbwait will not do anything. - -Kernel parameter: ``kgdbcon`` ------------------------------ - -The ``kgdbcon`` feature allows you to see printk() messages inside gdb -while gdb is connected to the kernel. Kdb does not make use of the kgdbcon -feature. - -Kgdb supports using the gdb serial protocol to send console messages to -the debugger when the debugger is connected and running. There are two -ways to activate this feature. - -1. Activate with the kernel command line option:: - - kgdbcon - -2. Use sysfs before configuring an I/O driver:: - - echo 1 > /sys/module/kgdb/parameters/kgdb_use_con - -.. note:: - - If you do this after you configure the kgdb I/O driver, the - setting will not take effect until the next point the I/O is - reconfigured. - -.. important:: - - You cannot use kgdboc + kgdbcon on a tty that is an - active system console. An example of incorrect usage is:: - - console=ttyS0,115200 kgdboc=ttyS0 kgdbcon - -It is possible to use this option with kgdboc on a tty that is not a -system console. - -Run time parameter: ``kgdbreboot`` ----------------------------------- - -The kgdbreboot feature allows you to change how the debugger deals with -the reboot notification. You have 3 choices for the behavior. The -default behavior is always set to 0. - -.. tabularcolumns:: |p{0.4cm}|p{11.5cm}|p{5.6cm}| - -.. flat-table:: - :widths: 1 10 8 - - * - 1 - - ``echo -1 > /sys/module/debug_core/parameters/kgdbreboot`` - - Ignore the reboot notification entirely. - - * - 2 - - ``echo 0 > /sys/module/debug_core/parameters/kgdbreboot`` - - Send the detach message to any attached debugger client. - - * - 3 - - ``echo 1 > /sys/module/debug_core/parameters/kgdbreboot`` - - Enter the debugger on reboot notify. - -Kernel parameter: ``nokaslr`` ------------------------------ - -If the architecture that you are using enable KASLR by default, -you should consider turning it off. KASLR randomizes the -virtual address where the kernel image is mapped and confuse -gdb which resolve kernel symbol address from symbol table -of vmlinux. - -Using kdb -========= - -Quick start for kdb on a serial port ------------------------------------- - -This is a quick example of how to use kdb. - -1. Configure kgdboc at boot using kernel parameters:: - - console=ttyS0,115200 kgdboc=ttyS0,115200 nokaslr - - OR - - Configure kgdboc after the kernel has booted; assuming you are using - a serial port console:: - - echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc - -2. Enter the kernel debugger manually or by waiting for an oops or - fault. There are several ways you can enter the kernel debugger - manually; all involve using the :kbd:`SysRq-G`, which means you must have - enabled ``CONFIG_MAGIC_SYSRQ=y`` in your kernel config. - - - When logged in as root or with a super user session you can run:: - - echo g > /proc/sysrq-trigger - - - Example using minicom 2.2 - - Press: :kbd:`CTRL-A` :kbd:`f` :kbd:`g` - - - When you have telneted to a terminal server that supports sending - a remote break - - Press: :kbd:`CTRL-]` - - Type in: ``send break`` - - Press: :kbd:`Enter` :kbd:`g` - -3. From the kdb prompt you can run the ``help`` command to see a complete - list of the commands that are available. - - Some useful commands in kdb include: - - =========== ================================================================= - ``lsmod`` Shows where kernel modules are loaded - ``ps`` Displays only the active processes - ``ps A`` Shows all the processes - ``summary`` Shows kernel version info and memory usage - ``bt`` Get a backtrace of the current process using dump_stack() - ``dmesg`` View the kernel syslog buffer - ``go`` Continue the system - =========== ================================================================= - -4. When you are done using kdb you need to consider rebooting the system - or using the ``go`` command to resuming normal kernel execution. If you - have paused the kernel for a lengthy period of time, applications - that rely on timely networking or anything to do with real wall clock - time could be adversely affected, so you should take this into - consideration when using the kernel debugger. - -Quick start for kdb using a keyboard connected console ------------------------------------------------------- - -This is a quick example of how to use kdb with a keyboard. - -1. Configure kgdboc at boot using kernel parameters:: - - kgdboc=kbd - - OR - - Configure kgdboc after the kernel has booted:: - - echo kbd > /sys/module/kgdboc/parameters/kgdboc - -2. Enter the kernel debugger manually or by waiting for an oops or - fault. There are several ways you can enter the kernel debugger - manually; all involve using the :kbd:`SysRq-G`, which means you must have - enabled ``CONFIG_MAGIC_SYSRQ=y`` in your kernel config. - - - When logged in as root or with a super user session you can run:: - - echo g > /proc/sysrq-trigger - - - Example using a laptop keyboard: - - Press and hold down: :kbd:`Alt` - - Press and hold down: :kbd:`Fn` - - Press and release the key with the label: :kbd:`SysRq` - - Release: :kbd:`Fn` - - Press and release: :kbd:`g` - - Release: :kbd:`Alt` - - - Example using a PS/2 101-key keyboard - - Press and hold down: :kbd:`Alt` - - Press and release the key with the label: :kbd:`SysRq` - - Press and release: :kbd:`g` - - Release: :kbd:`Alt` - -3. Now type in a kdb command such as ``help``, ``dmesg``, ``bt`` or ``go`` to - continue kernel execution. - -Using kgdb / gdb -================ - -In order to use kgdb you must activate it by passing configuration -information to one of the kgdb I/O drivers. If you do not pass any -configuration information kgdb will not do anything at all. Kgdb will -only actively hook up to the kernel trap hooks if a kgdb I/O driver is -loaded and configured. If you unconfigure a kgdb I/O driver, kgdb will -unregister all the kernel hook points. - -All kgdb I/O drivers can be reconfigured at run time, if -``CONFIG_SYSFS`` and ``CONFIG_MODULES`` are enabled, by echo'ing a new -config string to ``/sys/module/<driver>/parameter/<option>``. The driver -can be unconfigured by passing an empty string. You cannot change the -configuration while the debugger is attached. Make sure to detach the -debugger with the ``detach`` command prior to trying to unconfigure a -kgdb I/O driver. - -Connecting with gdb to a serial port ------------------------------------- - -1. Configure kgdboc - - Configure kgdboc at boot using kernel parameters:: - - kgdboc=ttyS0,115200 - - OR - - Configure kgdboc after the kernel has booted:: - - echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc - -2. Stop kernel execution (break into the debugger) - - In order to connect to gdb via kgdboc, the kernel must first be - stopped. There are several ways to stop the kernel which include - using kgdbwait as a boot argument, via a :kbd:`SysRq-G`, or running the - kernel until it takes an exception where it waits for the debugger to - attach. - - - When logged in as root or with a super user session you can run:: - - echo g > /proc/sysrq-trigger - - - Example using minicom 2.2 - - Press: :kbd:`CTRL-A` :kbd:`f` :kbd:`g` - - - When you have telneted to a terminal server that supports sending - a remote break - - Press: :kbd:`CTRL-]` - - Type in: ``send break`` - - Press: :kbd:`Enter` :kbd:`g` - -3. Connect from gdb - - Example (using a directly connected port):: - - % gdb ./vmlinux - (gdb) set serial baud 115200 - (gdb) target remote /dev/ttyS0 - - - Example (kgdb to a terminal server on TCP port 2012):: - - % gdb ./vmlinux - (gdb) target remote 192.168.2.2:2012 - - - Once connected, you can debug a kernel the way you would debug an - application program. - - If you are having problems connecting or something is going seriously - wrong while debugging, it will most often be the case that you want - to enable gdb to be verbose about its target communications. You do - this prior to issuing the ``target remote`` command by typing in:: - - set debug remote 1 - -Remember if you continue in gdb, and need to "break in" again, you need -to issue an other :kbd:`SysRq-G`. It is easy to create a simple entry point by -putting a breakpoint at ``sys_sync`` and then you can run ``sync`` from a -shell or script to break into the debugger. - -kgdb and kdb interoperability -============================= - -It is possible to transition between kdb and kgdb dynamically. The debug -core will remember which you used the last time and automatically start -in the same mode. - -Switching between kdb and kgdb ------------------------------- - -Switching from kgdb to kdb -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -There are two ways to switch from kgdb to kdb: you can use gdb to issue -a maintenance packet, or you can blindly type the command ``$3#33``. -Whenever the kernel debugger stops in kgdb mode it will print the -message ``KGDB or $3#33 for KDB``. It is important to note that you have -to type the sequence correctly in one pass. You cannot type a backspace -or delete because kgdb will interpret that as part of the debug stream. - -1. Change from kgdb to kdb by blindly typing:: - - $3#33 - -2. Change from kgdb to kdb with gdb:: - - maintenance packet 3 - - .. note:: - - Now you must kill gdb. Typically you press :kbd:`CTRL-Z` and issue - the command:: - - kill -9 % - -Change from kdb to kgdb -~~~~~~~~~~~~~~~~~~~~~~~ - -There are two ways you can change from kdb to kgdb. You can manually -enter kgdb mode by issuing the kgdb command from the kdb shell prompt, -or you can connect gdb while the kdb shell prompt is active. The kdb -shell looks for the typical first commands that gdb would issue with the -gdb remote protocol and if it sees one of those commands it -automatically changes into kgdb mode. - -1. From kdb issue the command:: - - kgdb - - Now disconnect your terminal program and connect gdb in its place - -2. At the kdb prompt, disconnect the terminal program and connect gdb in - its place. - -Running kdb commands from gdb ------------------------------ - -It is possible to run a limited set of kdb commands from gdb, using the -gdb monitor command. You don't want to execute any of the run control or -breakpoint operations, because it can disrupt the state of the kernel -debugger. You should be using gdb for breakpoints and run control -operations if you have gdb connected. The more useful commands to run -are things like lsmod, dmesg, ps or possibly some of the memory -information commands. To see all the kdb commands you can run -``monitor help``. - -Example:: - - (gdb) monitor ps - 1 idle process (state I) and - 27 sleeping system daemon (state M) processes suppressed, - use 'ps A' to see all. - Task Addr Pid Parent [*] cpu State Thread Command - - 0xc78291d0 1 0 0 0 S 0xc7829404 init - 0xc7954150 942 1 0 0 S 0xc7954384 dropbear - 0xc78789c0 944 1 0 0 S 0xc7878bf4 sh - (gdb) - -kgdb Test Suite -=============== - -When kgdb is enabled in the kernel config you can also elect to enable -the config parameter ``KGDB_TESTS``. Turning this on will enable a special -kgdb I/O module which is designed to test the kgdb internal functions. - -The kgdb tests are mainly intended for developers to test the kgdb -internals as well as a tool for developing a new kgdb architecture -specific implementation. These tests are not really for end users of the -Linux kernel. The primary source of documentation would be to look in -the ``drivers/misc/kgdbts.c`` file. - -The kgdb test suite can also be configured at compile time to run the -core set of tests by setting the kernel config parameter -``KGDB_TESTS_ON_BOOT``. This particular option is aimed at automated -regression testing and does not require modifying the kernel boot config -arguments. If this is turned on, the kgdb test suite can be disabled by -specifying ``kgdbts=`` as a kernel boot argument. - -Kernel Debugger Internals -========================= - -Architecture Specifics ----------------------- - -The kernel debugger is organized into a number of components: - -1. The debug core - - The debug core is found in ``kernel/debugger/debug_core.c``. It - contains: - - - A generic OS exception handler which includes sync'ing the - processors into a stopped state on an multi-CPU system. - - - The API to talk to the kgdb I/O drivers - - - The API to make calls to the arch-specific kgdb implementation - - - The logic to perform safe memory reads and writes to memory while - using the debugger - - - A full implementation for software breakpoints unless overridden - by the arch - - - The API to invoke either the kdb or kgdb frontend to the debug - core. - - - The structures and callback API for atomic kernel mode setting. - - .. note:: kgdboc is where the kms callbacks are invoked. - -2. kgdb arch-specific implementation - - This implementation is generally found in ``arch/*/kernel/kgdb.c``. As - an example, ``arch/x86/kernel/kgdb.c`` contains the specifics to - implement HW breakpoint as well as the initialization to dynamically - register and unregister for the trap handlers on this architecture. - The arch-specific portion implements: - - - contains an arch-specific trap catcher which invokes - kgdb_handle_exception() to start kgdb about doing its work - - - translation to and from gdb specific packet format to struct pt_regs - - - Registration and unregistration of architecture specific trap - hooks - - - Any special exception handling and cleanup - - - NMI exception handling and cleanup - - - (optional) HW breakpoints - -3. gdbstub frontend (aka kgdb) - - The gdbstub is located in ``kernel/debug/gdbstub.c``. It contains: - - - All the logic to implement the gdb serial protocol - -4. kdb frontend - - The kdb debugger shell is broken down into a number of components. - The kdb core is located in kernel/debug/kdb. There are a number of - helper functions in some of the other kernel components to make it - possible for kdb to examine and report information about the kernel - without taking locks that could cause a kernel deadlock. The kdb core - contains implements the following functionality. - - - A simple shell - - - The kdb core command set - - - A registration API to register additional kdb shell commands. - - - A good example of a self-contained kdb module is the ``ftdump`` - command for dumping the ftrace buffer. See: - ``kernel/trace/trace_kdb.c`` - - - For an example of how to dynamically register a new kdb command - you can build the kdb_hello.ko kernel module from - ``samples/kdb/kdb_hello.c``. To build this example you can set - ``CONFIG_SAMPLES=y`` and ``CONFIG_SAMPLE_KDB=m`` in your kernel - config. Later run ``modprobe kdb_hello`` and the next time you - enter the kdb shell, you can run the ``hello`` command. - - - The implementation for kdb_printf() which emits messages directly - to I/O drivers, bypassing the kernel log. - - - SW / HW breakpoint management for the kdb shell - -5. kgdb I/O driver - - Each kgdb I/O driver has to provide an implementation for the - following: - - - configuration via built-in or module - - - dynamic configuration and kgdb hook registration calls - - - read and write character interface - - - A cleanup handler for unconfiguring from the kgdb core - - - (optional) Early debug methodology - - Any given kgdb I/O driver has to operate very closely with the - hardware and must do it in such a way that does not enable interrupts - or change other parts of the system context without completely - restoring them. The kgdb core will repeatedly "poll" a kgdb I/O - driver for characters when it needs input. The I/O driver is expected - to return immediately if there is no data available. Doing so allows - for the future possibility to touch watchdog hardware in such a way - as to have a target system not reset when these are enabled. - -If you are intent on adding kgdb architecture specific support for a new -architecture, the architecture should define ``HAVE_ARCH_KGDB`` in the -architecture specific Kconfig file. This will enable kgdb for the -architecture, and at that point you must create an architecture specific -kgdb implementation. - -There are a few flags which must be set on every architecture in their -``asm/kgdb.h`` file. These are: - -- ``NUMREGBYTES``: - The size in bytes of all of the registers, so that we - can ensure they will all fit into a packet. - -- ``BUFMAX``: - The size in bytes of the buffer GDB will read into. This must - be larger than NUMREGBYTES. - -- ``CACHE_FLUSH_IS_SAFE``: - Set to 1 if it is always safe to call - flush_cache_range or flush_icache_range. On some architectures, - these functions may not be safe to call on SMP since we keep other - CPUs in a holding pattern. - -There are also the following functions for the common backend, found in -``kernel/kgdb.c``, that must be supplied by the architecture-specific -backend unless marked as (optional), in which case a default function -maybe used if the architecture does not need to provide a specific -implementation. - -.. kernel-doc:: include/linux/kgdb.h - :internal: - -kgdboc internals ----------------- - -kgdboc and uarts -~~~~~~~~~~~~~~~~ - -The kgdboc driver is actually a very thin driver that relies on the -underlying low level to the hardware driver having "polling hooks" to -which the tty driver is attached. In the initial implementation of -kgdboc the serial_core was changed to expose a low level UART hook for -doing polled mode reading and writing of a single character while in an -atomic context. When kgdb makes an I/O request to the debugger, kgdboc -invokes a callback in the serial core which in turn uses the callback in -the UART driver. - -When using kgdboc with a UART, the UART driver must implement two -callbacks in the struct uart_ops. -Example from ``drivers/8250.c``:: - - - #ifdef CONFIG_CONSOLE_POLL - .poll_get_char = serial8250_get_poll_char, - .poll_put_char = serial8250_put_poll_char, - #endif - - -Any implementation specifics around creating a polling driver use the -``#ifdef CONFIG_CONSOLE_POLL``, as shown above. Keep in mind that -polling hooks have to be implemented in such a way that they can be -called from an atomic context and have to restore the state of the UART -chip on return such that the system can return to normal when the -debugger detaches. You need to be very careful with any kind of lock you -consider, because failing here is most likely going to mean pressing the -reset button. - -kgdboc and keyboards -~~~~~~~~~~~~~~~~~~~~~~~~ - -The kgdboc driver contains logic to configure communications with an -attached keyboard. The keyboard infrastructure is only compiled into the -kernel when ``CONFIG_KDB_KEYBOARD=y`` is set in the kernel configuration. - -The core polled keyboard driver for PS/2 type keyboards is in -``drivers/char/kdb_keyboard.c``. This driver is hooked into the debug core -when kgdboc populates the callback in the array called -:c:expr:`kdb_poll_funcs[]`. The kdb_get_kbd_char() is the top-level -function which polls hardware for single character input. - -kgdboc and kms -~~~~~~~~~~~~~~~~~~ - -The kgdboc driver contains logic to request the graphics display to -switch to a text context when you are using ``kgdboc=kms,kbd``, provided -that you have a video driver which has a frame buffer console and atomic -kernel mode setting support. - -Every time the kernel debugger is entered it calls -kgdboc_pre_exp_handler() which in turn calls con_debug_enter() -in the virtual console layer. On resuming kernel execution, the kernel -debugger calls kgdboc_post_exp_handler() which in turn calls -con_debug_leave(). - -Any video driver that wants to be compatible with the kernel debugger -and the atomic kms callbacks must implement the ``mode_set_base_atomic``, -``fb_debug_enter`` and ``fb_debug_leave operations``. For the -``fb_debug_enter`` and ``fb_debug_leave`` the option exists to use the -generic drm fb helper functions or implement something custom for the -hardware. The following example shows the initialization of the -.mode_set_base_atomic operation in -drivers/gpu/drm/i915/intel_display.c:: - - - static const struct drm_crtc_helper_funcs intel_helper_funcs = { - [...] - .mode_set_base_atomic = intel_pipe_set_base_atomic, - [...] - }; - - -Here is an example of how the i915 driver initializes the -fb_debug_enter and fb_debug_leave functions to use the generic drm -helpers in ``drivers/gpu/drm/i915/intel_fb.c``:: - - - static struct fb_ops intelfb_ops = { - [...] - .fb_debug_enter = drm_fb_helper_debug_enter, - .fb_debug_leave = drm_fb_helper_debug_leave, - [...] - }; - - -Credits -======= - -The following people have contributed to this document: - -1. Amit Kale <amitkale@linsyssoft.com> - -2. Tom Rini <trini@kernel.crashing.org> - -In March 2008 this document was completely rewritten by: - -- Jason Wessel <jason.wessel@windriver.com> - -In Jan 2010 this document was updated to include kdb. - -- Jason Wessel <jason.wessel@windriver.com> diff --git a/Documentation/dev-tools/kmemleak.rst b/Documentation/dev-tools/kmemleak.rst index 2cb00b53339f..7d784e03f3f9 100644 --- a/Documentation/dev-tools/kmemleak.rst +++ b/Documentation/dev-tools/kmemleak.rst @@ -161,6 +161,7 @@ See the include/linux/kmemleak.h header for the functions prototype. - ``kmemleak_free_percpu`` - notify of a percpu memory block freeing - ``kmemleak_update_trace`` - update object allocation stack trace - ``kmemleak_not_leak`` - mark an object as not a leak +- ``kmemleak_transient_leak`` - mark an object as a transient leak - ``kmemleak_ignore`` - do not scan or report an object as leak - ``kmemleak_scan_area`` - add scan areas inside a memory block - ``kmemleak_no_scan`` - do not scan a memory block diff --git a/Documentation/dev-tools/kmsan.rst b/Documentation/dev-tools/kmsan.rst index 323eedad53cd..0dc668b183f6 100644 --- a/Documentation/dev-tools/kmsan.rst +++ b/Documentation/dev-tools/kmsan.rst @@ -110,6 +110,13 @@ in the Makefile. Think of this as applying ``__no_sanitize_memory`` to every function in the file or directory. Most users won't need KMSAN_SANITIZE, unless their code gets broken by KMSAN (e.g. runs at early boot time). +KMSAN checks can also be temporarily disabled for the current task using +``kmsan_disable_current()`` and ``kmsan_enable_current()`` calls. Each +``kmsan_enable_current()`` call must be preceded by a +``kmsan_disable_current()`` call; these call pairs may be nested. One needs to +be careful with these calls, keeping the regions short and preferring other +ways to disable instrumentation, where possible. + Support ======= @@ -126,7 +133,7 @@ KMSAN shadow memory ------------------- KMSAN associates a metadata byte (also called shadow byte) with every byte of -kernel memory. A bit in the shadow byte is set iff the corresponding bit of the +kernel memory. A bit in the shadow byte is set if the corresponding bit of the kernel memory byte is uninitialized. Marking the memory uninitialized (i.e. setting its shadow bytes to ``0xff``) is called poisoning, marking it initialized (setting the shadow bytes to ``0x00``) is called unpoisoning. @@ -338,11 +345,11 @@ Per-task KMSAN state ~~~~~~~~~~~~~~~~~~~~ Every task_struct has an associated KMSAN task state that holds the KMSAN -context (see above) and a per-task flag disallowing KMSAN reports:: +context (see above) and a per-task counter disallowing KMSAN reports:: struct kmsan_context { ... - bool allow_reporting; + unsigned int depth; struct kmsan_context_state cstate; ... } diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst index ff10dc6eef5d..18c2da67fae4 100644 --- a/Documentation/dev-tools/kselftest.rst +++ b/Documentation/dev-tools/kselftest.rst @@ -31,6 +31,15 @@ kselftest runs as a userspace process. Tests that can be written/run in userspace may wish to use the `Test Harness`_. Tests that need to be run in kernel space may wish to use a `Test Module`_. +Documentation on the tests +========================== + +For documentation on the kselftests themselves, see: + +.. toctree:: + + testing-devices + Running the selftests (hotplug tests are run in limited mode) ============================================================= @@ -183,7 +192,7 @@ expected time it takes to run a test. If you have control over the systems which will run the tests you can configure a test runner on those systems to use a greater or lower timeout on the command line as with the `-o` or the `--override-timeout` argument. For example to use 165 seconds instead -one would use: +one would use:: $ ./run_kselftest.sh --override-timeout 165 @@ -228,6 +237,13 @@ In general, the rules for selftests are * Don't cause the top-level "make run_tests" to fail if your feature is unconfigured. + * The output of tests must conform to the TAP standard to ensure high + testing quality and to capture failures/errors with specific details. + The kselftest.h and kselftest_harness.h headers provide wrappers for + outputting test results. These wrappers should be used for pass, + fail, exit, and skip messages. CI systems can easily parse TAP output + messages to detect test results. + Contributing new tests (details) ================================ @@ -331,7 +347,7 @@ kselftest. We use kselftests for lib/ as an example. 1. Create the test module 2. Create the test script that will run (load/unload) the module - e.g. ``tools/testing/selftests/lib/printf.sh`` + e.g. ``tools/testing/selftests/lib/bitmap.sh`` 3. Add line to config file e.g. ``tools/testing/selftests/lib/config`` diff --git a/Documentation/dev-tools/kunit/api/clk.rst b/Documentation/dev-tools/kunit/api/clk.rst new file mode 100644 index 000000000000..eeaa50089453 --- /dev/null +++ b/Documentation/dev-tools/kunit/api/clk.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======== +Clk API +======== + +The KUnit clk API is used to test clk providers and clk consumers. + +.. kernel-doc:: drivers/clk/clk_kunit_helpers.c + :export: diff --git a/Documentation/dev-tools/kunit/api/index.rst b/Documentation/dev-tools/kunit/api/index.rst index 2d8f756aab56..5cdb552a0808 100644 --- a/Documentation/dev-tools/kunit/api/index.rst +++ b/Documentation/dev-tools/kunit/api/index.rst @@ -9,11 +9,17 @@ API Reference test resource functionredirection + clk + of + platformdevice This page documents the KUnit kernel testing API. It is divided into the following sections: +Core KUnit API +============== + Documentation/dev-tools/kunit/api/test.rst - Documents all of the standard testing API @@ -25,3 +31,18 @@ Documentation/dev-tools/kunit/api/resource.rst Documentation/dev-tools/kunit/api/functionredirection.rst - Documents the KUnit Function Redirection API + +Driver KUnit API +================ + +Documentation/dev-tools/kunit/api/clk.rst + + - Documents the KUnit clk API + +Documentation/dev-tools/kunit/api/of.rst + + - Documents the KUnit device tree (OF) API + +Documentation/dev-tools/kunit/api/platformdevice.rst + + - Documents the KUnit platform device API diff --git a/Documentation/dev-tools/kunit/api/of.rst b/Documentation/dev-tools/kunit/api/of.rst new file mode 100644 index 000000000000..cb4193dcddbb --- /dev/null +++ b/Documentation/dev-tools/kunit/api/of.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================== +Device Tree (OF) API +==================== + +The KUnit device tree API is used to test device tree (of_*) dependent code. + +.. kernel-doc:: include/kunit/of.h + :internal: + +.. kernel-doc:: drivers/of/of_kunit_helpers.c + :export: diff --git a/Documentation/dev-tools/kunit/api/platformdevice.rst b/Documentation/dev-tools/kunit/api/platformdevice.rst new file mode 100644 index 000000000000..49ddd5729003 --- /dev/null +++ b/Documentation/dev-tools/kunit/api/platformdevice.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================== +Platform Device API +=================== + +The KUnit platform device API is used to test platform devices. + +.. kernel-doc:: lib/kunit/platform.c + :export: diff --git a/Documentation/dev-tools/kunit/style.rst b/Documentation/dev-tools/kunit/style.rst index b6d0d7359f00..eac81a714a29 100644 --- a/Documentation/dev-tools/kunit/style.rst +++ b/Documentation/dev-tools/kunit/style.rst @@ -188,15 +188,26 @@ For example, a Kconfig entry might look like: Test File and Module Names ========================== -KUnit tests can often be compiled as a module. These modules should be named -after the test suite, followed by ``_test``. If this is likely to conflict with -non-KUnit tests, the suffix ``_kunit`` can also be used. +KUnit tests are often compiled as a separate module. To avoid conflicting +with regular modules, KUnit modules should be named after the test suite, +followed by ``_kunit`` (e.g. if "foobar" is the core module, then +"foobar_kunit" is the KUnit test module). -The easiest way of achieving this is to name the file containing the test suite -``<suite>_test.c`` (or, as above, ``<suite>_kunit.c``). This file should be -placed next to the code under test. +Test source files, whether compiled as a separate module or an +``#include`` in another source file, are best kept in a ``tests/`` +subdirectory to not conflict with other source files (e.g. for +tab-completion). + +Note that the ``_test`` suffix has also been used in some existing +tests. The ``_kunit`` suffix is preferred, as it makes the distinction +between KUnit and non-KUnit tests clearer. + +So for the common case, name the file containing the test suite +``tests/<suite>_kunit.c``. The ``tests`` directory should be placed at +the same level as the code under test. For example, tests for +``lib/string.c`` live in ``lib/tests/string_kunit.c``. If the suite name contains some or all of the name of the test's parent -directory, it may make sense to modify the source filename to reduce redundancy. -For example, a ``foo_firmware`` suite could be in the ``foo/firmware_test.c`` -file. +directory, it may make sense to modify the source filename to reduce +redundancy. For example, a ``foo_firmware`` suite could be in the +``foo/tests/firmware_kunit.c`` file. diff --git a/Documentation/dev-tools/propeller.rst b/Documentation/dev-tools/propeller.rst new file mode 100644 index 000000000000..92195958e3db --- /dev/null +++ b/Documentation/dev-tools/propeller.rst @@ -0,0 +1,162 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================================== +Using Propeller with the Linux kernel +===================================== + +This enables Propeller build support for the kernel when using Clang +compiler. Propeller is a profile-guided optimization (PGO) method used +to optimize binary executables. Like AutoFDO, it utilizes hardware +sampling to gather information about the frequency of execution of +different code paths within a binary. Unlike AutoFDO, this information +is then used right before linking phase to optimize (among others) +block layout within and across functions. + +A few important notes about adopting Propeller optimization: + +#. Although it can be used as a standalone optimization step, it is + strongly recommended to apply Propeller on top of AutoFDO, + AutoFDO+ThinLTO or Instrument FDO. The rest of this document + assumes this paradigm. + +#. Propeller uses another round of profiling on top of + AutoFDO/AutoFDO+ThinLTO/iFDO. The whole build process involves + "build-afdo - train-afdo - build-propeller - train-propeller - + build-optimized". + +#. Propeller requires LLVM 19 release or later for Clang/Clang++ + and the linker(ld.lld). + +#. In addition to LLVM toolchain, Propeller requires a profiling + conversion tool: https://github.com/google/autofdo with a release + after v0.30.1: https://github.com/google/autofdo/releases/tag/v0.30.1. + +The Propeller optimization process involves the following steps: + +#. Initial building: Build the AutoFDO or AutoFDO+ThinLTO binary as + you would normally do, but with a set of compile-time / link-time + flags, so that a special metadata section is created within the + kernel binary. The special section is only intend to be used by the + profiling tool, it is not part of the runtime image, nor does it + change kernel run time text sections. + +#. Profiling: The above kernel is then run with a representative + workload to gather execution frequency data. This data is collected + using hardware sampling, via perf. Propeller is most effective on + platforms supporting advanced PMU features like LBR on Intel + machines. This step is the same as profiling the kernel for AutoFDO + (the exact perf parameters can be different). + +#. Propeller profile generation: Perf output file is converted to a + pair of Propeller profiles via an offline tool. + +#. Optimized build: Build the AutoFDO or AutoFDO+ThinLTO optimized + binary as you would normally do, but with a compile-time / + link-time flag to pick up the Propeller compile time and link time + profiles. This build step uses 3 profiles - the AutoFDO profile, + the Propeller compile-time profile and the Propeller link-time + profile. + +#. Deployment: The optimized kernel binary is deployed and used + in production environments, providing improved performance + and reduced latency. + +Preparation +=========== + +Configure the kernel with:: + + CONFIG_AUTOFDO_CLANG=y + CONFIG_PROPELLER_CLANG=y + +Customization +============= + +The default CONFIG_PROPELLER_CLANG setting covers kernel space objects +for Propeller builds. One can, however, enable or disable Propeller build +for individual files and directories by adding a line similar to the +following to the respective kernel Makefile: + +- For enabling a single file (e.g. foo.o):: + + PROPELLER_PROFILE_foo.o := y + +- For enabling all files in one directory:: + + PROPELLER_PROFILE := y + +- For disabling one file:: + + PROPELLER_PROFILE_foo.o := n + +- For disabling all files in one directory:: + + PROPELLER__PROFILE := n + + +Workflow +======== + +Here is an example workflow for building an AutoFDO+Propeller kernel: + +1) Assuming an AutoFDO profile is already collected following + instructions in the AutoFDO document, build the kernel on the host + machine, with AutoFDO and Propeller build configs :: + + CONFIG_AUTOFDO_CLANG=y + CONFIG_PROPELLER_CLANG=y + + and :: + + $ make LLVM=1 CLANG_AUTOFDO_PROFILE=<autofdo-profile-name> + +2) Install the kernel on the test machine. + +3) Run the load tests. The '-c' option in perf specifies the sample + event period. We suggest using a suitable prime number, like 500009, + for this purpose. + + - For Intel platforms:: + + $ perf record -e BR_INST_RETIRED.NEAR_TAKEN:k -a -N -b -c <count> -o <perf_file> -- <loadtest> + + - For AMD platforms:: + + $ perf record --pfm-event RETIRED_TAKEN_BRANCH_INSTRUCTIONS:k -a -N -b -c <count> -o <perf_file> -- <loadtest> + + Note you can repeat the above steps to collect multiple <perf_file>s. + +4) (Optional) Download the raw perf file(s) to the host machine. + +5) Use the create_llvm_prof tool (https://github.com/google/autofdo) to + generate Propeller profile. :: + + $ create_llvm_prof --binary=<vmlinux> --profile=<perf_file> + --format=propeller --propeller_output_module_name + --out=<propeller_profile_prefix>_cc_profile.txt + --propeller_symorder=<propeller_profile_prefix>_ld_profile.txt + + "<propeller_profile_prefix>" can be something like "/home/user/dir/any_string". + + This command generates a pair of Propeller profiles: + "<propeller_profile_prefix>_cc_profile.txt" and + "<propeller_profile_prefix>_ld_profile.txt". + + If there are more than 1 perf_file collected in the previous step, + you can create a temp list file "<perf_file_list>" with each line + containing one perf file name and run:: + + $ create_llvm_prof --binary=<vmlinux> --profile=@<perf_file_list> + --format=propeller --propeller_output_module_name + --out=<propeller_profile_prefix>_cc_profile.txt + --propeller_symorder=<propeller_profile_prefix>_ld_profile.txt + +6) Rebuild the kernel using the AutoFDO and Propeller + profiles. :: + + CONFIG_AUTOFDO_CLANG=y + CONFIG_PROPELLER_CLANG=y + + and :: + + $ make LLVM=1 CLANG_AUTOFDO_PROFILE=<profile_file> CLANG_PROPELLER_PROFILE_PREFIX=<propeller_profile_prefix> diff --git a/Documentation/dev-tools/testing-devices.rst b/Documentation/dev-tools/testing-devices.rst new file mode 100644 index 000000000000..ab26adb99051 --- /dev/null +++ b/Documentation/dev-tools/testing-devices.rst @@ -0,0 +1,47 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright (c) 2024 Collabora Ltd + +============================= +Device testing with kselftest +============================= + + +There are a few different kselftests available for testing devices generically, +with some overlap in coverage and different requirements. This document aims to +give an overview of each one. + +Note: Paths in this document are relative to the kselftest folder +(``tools/testing/selftests``). + +Device oriented kselftests: + +* Devicetree (``dt``) + + * **Coverage**: Probe status for devices described in Devicetree + * **Requirements**: None + +* Error logs (``devices/error_logs``) + + * **Coverage**: Error (or more critical) log messages presence coming from any + device + * **Requirements**: None + +* Discoverable bus (``devices/probe``) + + * **Coverage**: Presence and probe status of USB or PCI devices that have been + described in the reference file + * **Requirements**: Manually describe the devices that should be tested in a + YAML reference file (see ``devices/probe/boards/google,spherion.yaml`` for + an example) + +* Exist (``devices/exist``) + + * **Coverage**: Presence of all devices + * **Requirements**: Generate the reference (see ``devices/exist/README.rst`` + for details) on a known-good kernel + +Therefore, the suggestion is to enable the error log and devicetree tests on all +(DT-based) platforms, since they don't have any requirements. Then to greatly +improve coverage, generate the reference for each platform and enable the exist +test. The discoverable bus test can be used to verify the probe status of +specific USB or PCI devices, but is probably not worth it for most cases. diff --git a/Documentation/dev-tools/testing-overview.rst b/Documentation/dev-tools/testing-overview.rst index 0aaf6ea53608..1619e5e5cc9c 100644 --- a/Documentation/dev-tools/testing-overview.rst +++ b/Documentation/dev-tools/testing-overview.rst @@ -104,6 +104,8 @@ Some of these tools are listed below: KASAN and can be used in production. See Documentation/dev-tools/kfence.rst * lockdep is a locking correctness validator. See Documentation/locking/lockdep-design.rst +* Runtime Verification (RV) supports checking specific behaviours for a given + subsystem. See Documentation/trace/rv/runtime-verification.rst * There are several other pieces of debug instrumentation in the kernel, many of which can be found in lib/Kconfig.debug |