From 5d8e5aee0e9391141fe2ab892d0ac98de5783537 Mon Sep 17 00:00:00 2001 From: Stephen Kitt Date: Sun, 15 Mar 2020 13:26:48 +0100 Subject: docs: sysctl/kernel: document BPF entries Based on the implementation in kernel/bpf/syscall.c, kernel/bpf/trampoline.c, include/linux/filter.h, and the documentation in bpftool-prog.rst. Signed-off-by: Stephen Kitt Link: https://lore.kernel.org/r/20200315122648.20558-1-steve@sk2.org Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/sysctl/kernel.rst | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) (limited to 'Documentation/admin-guide/sysctl') diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index 0d427fd10941..55b24eada13c 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -102,6 +102,20 @@ See the ``type_of_loader`` and ``ext_loader_ver`` fields in :doc:`/x86/boot` for additional information. +bpf_stats_enabled +================= + +Controls whether the kernel should collect statistics on BPF programs +(total time spent running, number of times run...). Enabling +statistics causes a slight reduction in performance on each program +run. The statistics can be seen using ``bpftool``. + += =================================== +0 Don't collect statistics (default). +1 Collect statistics. += =================================== + + cap_last_cap ============ @@ -1178,6 +1192,16 @@ NMI switch that most IA32 servers have fires unknown NMI up, for example. If a system hangs up, try pressing the NMI switch. +unprivileged_bpf_disabled +========================= + +Writing 1 to this entry will disable unprivileged calls to ``bpf()``; +once disabled, calling ``bpf()`` without ``CAP_SYS_ADMIN`` will return +``-EPERM``. + +Once set, this can't be cleared. + + watchdog ======== -- cgit v1.2.3 From 6bc47621cbf357a9b7bab3890489804f38916a35 Mon Sep 17 00:00:00 2001 From: Stephen Kitt Date: Thu, 23 Apr 2020 20:36:49 +0200 Subject: docs: sysctl/kernel: document cad_pid Based on the implementation in kernel/sysctl.c (the proc_do_cad_pid() function), kernel/reboot.c, and include/linux/sched/signal.h. Signed-off-by: Stephen Kitt Link: https://lore.kernel.org/r/20200423183651.15365-1-steve@sk2.org Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/sysctl/kernel.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'Documentation/admin-guide/sysctl') diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index 55b24eada13c..82bfd5892663 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -116,6 +116,16 @@ run. The statistics can be seen using ``bpftool``. = =================================== +cad_pid +======= + +This is the pid which will be signalled on reboot (notably, by +Ctrl-Alt-Delete). Writing a value to this file which doesn't +correspond to a running process will result in ``-ESRCH``. + +See also `ctrl-alt-del`_. + + cap_last_cap ============ -- cgit v1.2.3 From 01478b833176761e188a465fc7a22bd4e07d040e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 27 Apr 2020 23:17:02 +0200 Subject: docs: filesystems: convert devpts.txt to ReST - Add a SPDX header; - Add a document title; - Some whitespace fixes and new line breaks; - Mark literal blocks as such; - Add it to filesystems/index.rst. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/4ac8f3a7edd4d817acf0d173ead7ef74fe010c6c.1588021877.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/sysctl/kernel.rst | 2 +- Documentation/filesystems/devpts.rst | 36 +++++++++++++++++++++++++++++ Documentation/filesystems/devpts.txt | 26 --------------------- Documentation/filesystems/index.rst | 1 + 4 files changed, 38 insertions(+), 27 deletions(-) create mode 100644 Documentation/filesystems/devpts.rst delete mode 100644 Documentation/filesystems/devpts.txt (limited to 'Documentation/admin-guide/sysctl') diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index 82bfd5892663..706c2158ad25 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -895,7 +895,7 @@ this sysctl interface anymore. pty === -See Documentation/filesystems/devpts.txt. +See Documentation/filesystems/devpts.rst. randomize_va_space diff --git a/Documentation/filesystems/devpts.rst b/Documentation/filesystems/devpts.rst new file mode 100644 index 000000000000..a03248ddfb4c --- /dev/null +++ b/Documentation/filesystems/devpts.rst @@ -0,0 +1,36 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +The Devpts Filesystem +===================== + +Each mount of the devpts filesystem is now distinct such that ptys +and their indicies allocated in one mount are independent from ptys +and their indicies in all other mounts. + +All mounts of the devpts filesystem now create a ``/dev/pts/ptmx`` node +with permissions ``0000``. + +To retain backwards compatibility the a ptmx device node (aka any node +created with ``mknod name c 5 2``) when opened will look for an instance +of devpts under the name ``pts`` in the same directory as the ptmx device +node. + +As an option instead of placing a ``/dev/ptmx`` device node at ``/dev/ptmx`` +it is possible to place a symlink to ``/dev/pts/ptmx`` at ``/dev/ptmx`` or +to bind mount ``/dev/ptx/ptmx`` to ``/dev/ptmx``. If you opt for using +the devpts filesystem in this manner devpts should be mounted with +the ``ptmxmode=0666``, or ``chmod 0666 /dev/pts/ptmx`` should be called. + +Total count of pty pairs in all instances is limited by sysctls:: + + kernel.pty.max = 4096 - global limit + kernel.pty.reserve = 1024 - reserved for filesystems mounted from the initial mount namespace + kernel.pty.nr - current count of ptys + +Per-instance limit could be set by adding mount option ``max=``. + +This feature was added in kernel 3.4 together with +``sysctl kernel.pty.reserve``. + +In kernels older than 3.4 sysctl ``kernel.pty.max`` works as per-instance limit. diff --git a/Documentation/filesystems/devpts.txt b/Documentation/filesystems/devpts.txt deleted file mode 100644 index 9f94fe276dea..000000000000 --- a/Documentation/filesystems/devpts.txt +++ /dev/null @@ -1,26 +0,0 @@ -Each mount of the devpts filesystem is now distinct such that ptys -and their indicies allocated in one mount are independent from ptys -and their indicies in all other mounts. - -All mounts of the devpts filesystem now create a /dev/pts/ptmx node -with permissions 0000. - -To retain backwards compatibility the a ptmx device node (aka any node -created with "mknod name c 5 2") when opened will look for an instance -of devpts under the name "pts" in the same directory as the ptmx device -node. - -As an option instead of placing a /dev/ptmx device node at /dev/ptmx -it is possible to place a symlink to /dev/pts/ptmx at /dev/ptmx or -to bind mount /dev/ptx/ptmx to /dev/ptmx. If you opt for using -the devpts filesystem in this manner devpts should be mounted with -the ptmxmode=0666, or chmod 0666 /dev/pts/ptmx should be called. - -Total count of pty pairs in all instances is limited by sysctls: -kernel.pty.max = 4096 - global limit -kernel.pty.reserve = 1024 - reserved for filesystems mounted from the initial mount namespace -kernel.pty.nr - current count of ptys - -Per-instance limit could be set by adding mount option "max=". -This feature was added in kernel 3.4 together with sysctl kernel.pty.reserve. -In kernels older than 3.4 sysctl kernel.pty.max works as per-instance limit. diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index ec6e308587e1..43717f11d10b 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -24,6 +24,7 @@ algorithms work. splice locking directory-locking + devpts automount-support -- cgit v1.2.3 From 50cdae76b8d021f31ea07af3bb30983486b79df8 Mon Sep 17 00:00:00 2001 From: Stephen Kitt Date: Wed, 29 Apr 2020 22:57:56 +0200 Subject: docs: sysctl/kernel: document ftrace entries Based on the ftrace documentation, the tp_printk boot parameter documentation, and the implementation in kernel/trace/trace.c. Signed-off-by: Stephen Kitt Acked-by: Steven Rostedt (VMware) Link: https://lore.kernel.org/r/20200429205757.8677-1-steve@sk2.org Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/sysctl/kernel.rst | 48 +++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) (limited to 'Documentation/admin-guide/sysctl') diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index 706c2158ad25..5de73768f14e 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -265,6 +265,27 @@ domain names are in general different. For a detailed discussion see the ``hostname(1)`` man page. +ftrace_dump_on_oops +=================== + +Determines whether ``ftrace_dump()`` should be called on an oops (or +kernel panic). This will output the contents of the ftrace buffers to +the console. This is very useful for capturing traces that lead to +crashes and outputting them to a serial console. + += =================================================== +0 Disabled (default). +1 Dump buffers of all CPUs. +2 Dump the buffer of the CPU that triggered the oops. += =================================================== + + +ftrace_enabled, stack_tracer_enabled +==================================== + +See :doc:`/trace/ftrace`. + + hardlockup_all_cpu_backtrace ============================ @@ -1191,6 +1212,33 @@ If a value outside of this range is written to ``threads-max`` an ``EINVAL`` error occurs. +traceoff_on_warning +=================== + +When set, disables tracing (see :doc:`/trace/ftrace`) when a +``WARN()`` is hit. + + +tracepoint_printk +================= + +When tracepoints are sent to printk() (enabled by the ``tp_printk`` +boot parameter), this entry provides runtime control:: + + echo 0 > /proc/sys/kernel/tracepoint_printk + +will stop tracepoints from being sent to printk(), and:: + + echo 1 > /proc/sys/kernel/tracepoint_printk + +will send them to printk() again. + +This only works if the kernel was booted with ``tp_printk`` enabled. + +See :doc:`/admin-guide/kernel-parameters` and +:doc:`/trace/boottime-trace`. + + unknown_nmi_panic ================= -- cgit v1.2.3 From d75829c182609f9cc6ebdbab486500f638a871df Mon Sep 17 00:00:00 2001 From: Stephen Kitt Date: Wed, 29 Apr 2020 22:57:57 +0200 Subject: docs: sysctl/kernel: document firmware_config Based on the firmware fallback mechanisms documentation and the implementation in drivers/base/firmware_loader/fallback.c. Signed-off-by: Stephen Kitt Link: https://lore.kernel.org/r/20200429205757.8677-2-steve@sk2.org Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/sysctl/kernel.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'Documentation/admin-guide/sysctl') diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index 5de73768f14e..eb6bc9cc0318 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -265,6 +265,19 @@ domain names are in general different. For a detailed discussion see the ``hostname(1)`` man page. +firmware_config +=============== + +See :doc:`/driver-api/firmware/fallback-mechanisms`. + +The entries in this directory allow the firmware loader helper +fallback to be controlled: + +* ``force_sysfs_fallback``, when set to 1, forces the use of the + fallback; +* ``ignore_sysfs_fallback``, when set to 1, ignores any fallback. + + ftrace_dump_on_oops =================== -- cgit v1.2.3 From 2f4c33063ad713e3a5b63002cf8362846e78bd71 Mon Sep 17 00:00:00 2001 From: Stephen Kitt Date: Fri, 15 May 2020 18:02:22 +0200 Subject: docs: sysctl/kernel: document ngroups_max This is a read-only export of NGROUPS_MAX, so this patch also changes the declarations in kernel/sysctl.c to const. Signed-off-by: Stephen Kitt Reviewed-by: Kees Cook Link: https://lore.kernel.org/r/20200515160222.7994-1-steve@sk2.org Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/sysctl/kernel.rst | 9 +++++++++ kernel/sysctl.c | 4 ++-- 2 files changed, 11 insertions(+), 2 deletions(-) (limited to 'Documentation/admin-guide/sysctl') diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index eb6bc9cc0318..6b313b6d42d5 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -517,6 +517,15 @@ Notes: successful IPC object allocation. If an IPC object allocation syscall fails, it is undefined if the value remains unmodified or is reset to -1. + +ngroups_max +=========== + +Maximum number of supplementary groups, _i.e._ the maximum size which +``setgroups`` will accept. Exports ``NGROUPS_MAX`` from the kernel. + + + nmi_watchdog ============ diff --git a/kernel/sysctl.c b/kernel/sysctl.c index 8a176d8727a3..2ba9f449d273 100644 --- a/kernel/sysctl.c +++ b/kernel/sysctl.c @@ -146,7 +146,7 @@ static unsigned long dirty_bytes_min = 2 * PAGE_SIZE; static int maxolduid = 65535; static int minolduid; -static int ngroups_max = NGROUPS_MAX; +static const int ngroups_max = NGROUPS_MAX; static const int cap_last_cap = CAP_LAST_CAP; /* @@ -883,7 +883,7 @@ static struct ctl_table kern_table[] = { #endif { .procname = "ngroups_max", - .data = &ngroups_max, + .data = (void *)&ngroups_max, .maxlen = sizeof (int), .mode = 0444, .proc_handler = proc_dointvec, -- cgit v1.2.3 From fdb1b5e08929f21d29aedd447233b32f497b8999 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 18 May 2020 06:19:25 -0600 Subject: Revert "docs: sysctl/kernel: document ngroups_max" This reverts commit 2f4c33063ad713e3a5b63002cf8362846e78bd71. The changes here were fine, but there's a non-documentation change to sysctl.c that makes messes elsewhere; those changes should have been done independently. Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/sysctl/kernel.rst | 9 --------- kernel/sysctl.c | 4 ++-- 2 files changed, 2 insertions(+), 11 deletions(-) (limited to 'Documentation/admin-guide/sysctl') diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index 6b313b6d42d5..eb6bc9cc0318 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -517,15 +517,6 @@ Notes: successful IPC object allocation. If an IPC object allocation syscall fails, it is undefined if the value remains unmodified or is reset to -1. - -ngroups_max -=========== - -Maximum number of supplementary groups, _i.e._ the maximum size which -``setgroups`` will accept. Exports ``NGROUPS_MAX`` from the kernel. - - - nmi_watchdog ============ diff --git a/kernel/sysctl.c b/kernel/sysctl.c index 2ba9f449d273..8a176d8727a3 100644 --- a/kernel/sysctl.c +++ b/kernel/sysctl.c @@ -146,7 +146,7 @@ static unsigned long dirty_bytes_min = 2 * PAGE_SIZE; static int maxolduid = 65535; static int minolduid; -static const int ngroups_max = NGROUPS_MAX; +static int ngroups_max = NGROUPS_MAX; static const int cap_last_cap = CAP_LAST_CAP; /* @@ -883,7 +883,7 @@ static struct ctl_table kern_table[] = { #endif { .procname = "ngroups_max", - .data = (void *)&ngroups_max, + .data = &ngroups_max, .maxlen = sizeof (int), .mode = 0444, .proc_handler = proc_dointvec, -- cgit v1.2.3 From 17444d9b0b5bf7ba1d7e19411d0cb5883eac40b4 Mon Sep 17 00:00:00 2001 From: Stephen Kitt Date: Mon, 18 May 2020 16:58:36 +0200 Subject: docs: sysctl/kernel: document ngroups_max This is a read-only export of NGROUPS_MAX. Signed-off-by: Stephen Kitt Link: https://lore.kernel.org/r/20200518145836.15816-1-steve@sk2.org Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/sysctl/kernel.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'Documentation/admin-guide/sysctl') diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index eb6bc9cc0318..6b313b6d42d5 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -517,6 +517,15 @@ Notes: successful IPC object allocation. If an IPC object allocation syscall fails, it is undefined if the value remains unmodified or is reset to -1. + +ngroups_max +=========== + +Maximum number of supplementary groups, _i.e._ the maximum size which +``setgroups`` will accept. Exports ``NGROUPS_MAX`` from the kernel. + + + nmi_watchdog ============ -- cgit v1.2.3 From 997c798e1444ad02e8af8b18c869fff5c61867da Mon Sep 17 00:00:00 2001 From: Stephen Kitt Date: Fri, 15 May 2020 23:24:44 +0200 Subject: docs: sysctl/kernel: document unaligned controls This documents ignore-unaligned-usertrap, unaligned-dump-stack, and unaligned-trap, based on arch/arc/kernel/unaligned.c, arch/ia64/kernel/unaligned.c, and arch/parisc/kernel/unaligned.c. While we're at it, integrate unaligned-memory-access.txt into the docs tree. Signed-off-by: Stephen Kitt Link: https://lore.kernel.org/r/20200515212443.5012-1-steve@sk2.org Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/sysctl/kernel.rst | 51 +++++ Documentation/process/index.rst | 1 + Documentation/process/unaligned-memory-access.rst | 265 ++++++++++++++++++++++ Documentation/unaligned-memory-access.txt | 265 ---------------------- 4 files changed, 317 insertions(+), 265 deletions(-) create mode 100644 Documentation/process/unaligned-memory-access.rst delete mode 100644 Documentation/unaligned-memory-access.txt (limited to 'Documentation/admin-guide/sysctl') diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index 6b313b6d42d5..4752d9a79235 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -402,6 +402,25 @@ Controls whether the panic kmsg data should be reported to Hyper-V. = ========================================================= +ignore-unaligned-usertrap +========================= + +On architectures where unaligned accesses cause traps, and where this +feature is supported (``CONFIG_SYSCTL_ARCH_UNALIGN_NO_WARN``; +currently, ``arc`` and ``ia64``), controls whether all unaligned traps +are logged. + += ============================================================= +0 Log all unaligned accesses. +1 Only warn the first time a process traps. This is the default + setting. += ============================================================= + +See also `unaligned-trap`_ and `unaligned-dump-stack`_. On ``ia64``, +this allows system administrators to override the +``IA64_THREAD_UAC_NOPRINT`` ``prctl`` and avoid logs being flooded. + + kexec_load_disabled =================== @@ -1261,6 +1280,38 @@ See :doc:`/admin-guide/kernel-parameters` and :doc:`/trace/boottime-trace`. +.. _unaligned-dump-stack: + +unaligned-dump-stack (ia64) +=========================== + +When logging unaligned accesses, controls whether the stack is +dumped. + += =================================================== +0 Do not dump the stack. This is the default setting. +1 Dump the stack. += =================================================== + +See also `ignore-unaligned-usertrap`_. + + +unaligned-trap +============== + +On architectures where unaligned accesses cause traps, and where this +feature is supported (``CONFIG_SYSCTL_ARCH_UNALIGN_ALLOW``; currently, +``arc`` and ``parisc``), controls whether unaligned traps are caught +and emulated (instead of failing). + += ======================================================== +0 Do not emulate unaligned accesses. +1 Emulate unaligned accesses. This is the default setting. += ======================================================== + +See also `ignore-unaligned-usertrap`_. + + unknown_nmi_panic ================= diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 6399d92f0b21..f07c9250c3ac 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -61,6 +61,7 @@ lack of a better place. botching-up-ioctls clang-format ../riscv/patch-acceptance + unaligned-memory-access .. only:: subproject and html diff --git a/Documentation/process/unaligned-memory-access.rst b/Documentation/process/unaligned-memory-access.rst new file mode 100644 index 000000000000..1ee82419d8aa --- /dev/null +++ b/Documentation/process/unaligned-memory-access.rst @@ -0,0 +1,265 @@ +========================= +Unaligned Memory Accesses +========================= + +:Author: Daniel Drake , +:Author: Johannes Berg + +:With help from: Alan Cox, Avuton Olrich, Heikki Orsila, Jan Engelhardt, + Kyle McMartin, Kyle Moffett, Randy Dunlap, Robert Hancock, Uli Kunitz, + Vadim Lobanov + + +Linux runs on a wide variety of architectures which have varying behaviour +when it comes to memory access. This document presents some details about +unaligned accesses, why you need to write code that doesn't cause them, +and how to write such code! + + +The definition of an unaligned access +===================================== + +Unaligned memory accesses occur when you try to read N bytes of data starting +from an address that is not evenly divisible by N (i.e. addr % N != 0). +For example, reading 4 bytes of data from address 0x10004 is fine, but +reading 4 bytes of data from address 0x10005 would be an unaligned memory +access. + +The above may seem a little vague, as memory access can happen in different +ways. The context here is at the machine code level: certain instructions read +or write a number of bytes to or from memory (e.g. movb, movw, movl in x86 +assembly). As will become clear, it is relatively easy to spot C statements +which will compile to multiple-byte memory access instructions, namely when +dealing with types such as u16, u32 and u64. + + +Natural alignment +================= + +The rule mentioned above forms what we refer to as natural alignment: +When accessing N bytes of memory, the base memory address must be evenly +divisible by N, i.e. addr % N == 0. + +When writing code, assume the target architecture has natural alignment +requirements. + +In reality, only a few architectures require natural alignment on all sizes +of memory access. However, we must consider ALL supported architectures; +writing code that satisfies natural alignment requirements is the easiest way +to achieve full portability. + + +Why unaligned access is bad +=========================== + +The effects of performing an unaligned memory access vary from architecture +to architecture. It would be easy to write a whole document on the differences +here; a summary of the common scenarios is presented below: + + - Some architectures are able to perform unaligned memory accesses + transparently, but there is usually a significant performance cost. + - Some architectures raise processor exceptions when unaligned accesses + happen. The exception handler is able to correct the unaligned access, + at significant cost to performance. + - Some architectures raise processor exceptions when unaligned accesses + happen, but the exceptions do not contain enough information for the + unaligned access to be corrected. + - Some architectures are not capable of unaligned memory access, but will + silently perform a different memory access to the one that was requested, + resulting in a subtle code bug that is hard to detect! + +It should be obvious from the above that if your code causes unaligned +memory accesses to happen, your code will not work correctly on certain +platforms and will cause performance problems on others. + + +Code that does not cause unaligned access +========================================= + +At first, the concepts above may seem a little hard to relate to actual +coding practice. After all, you don't have a great deal of control over +memory addresses of certain variables, etc. + +Fortunately things are not too complex, as in most cases, the compiler +ensures that things will work for you. For example, take the following +structure:: + + struct foo { + u16 field1; + u32 field2; + u8 field3; + }; + +Let us assume that an instance of the above structure resides in memory +starting at address 0x10000. With a basic level of understanding, it would +not be unreasonable to expect that accessing field2 would cause an unaligned +access. You'd be expecting field2 to be located at offset 2 bytes into the +structure, i.e. address 0x10002, but that address is not evenly divisible +by 4 (remember, we're reading a 4 byte value here). + +Fortunately, the compiler understands the alignment constraints, so in the +above case it would insert 2 bytes of padding in between field1 and field2. +Therefore, for standard structure types you can always rely on the compiler +to pad structures so that accesses to fields are suitably aligned (assuming +you do not cast the field to a type of different length). + +Similarly, you can also rely on the compiler to align variables and function +parameters to a naturally aligned scheme, based on the size of the type of +the variable. + +At this point, it should be clear that accessing a single byte (u8 or char) +will never cause an unaligned access, because all memory addresses are evenly +divisible by one. + +On a related topic, with the above considerations in mind you may observe +that you could reorder the fields in the structure in order to place fields +where padding would otherwise be inserted, and hence reduce the overall +resident memory size of structure instances. The optimal layout of the +above example is:: + + struct foo { + u32 field2; + u16 field1; + u8 field3; + }; + +For a natural alignment scheme, the compiler would only have to add a single +byte of padding at the end of the structure. This padding is added in order +to satisfy alignment constraints for arrays of these structures. + +Another point worth mentioning is the use of __attribute__((packed)) on a +structure type. This GCC-specific attribute tells the compiler never to +insert any padding within structures, useful when you want to use a C struct +to represent some data that comes in a fixed arrangement 'off the wire'. + +You might be inclined to believe that usage of this attribute can easily +lead to unaligned accesses when accessing fields that do not satisfy +architectural alignment requirements. However, again, the compiler is aware +of the alignment constraints and will generate extra instructions to perform +the memory access in a way that does not cause unaligned access. Of course, +the extra instructions obviously cause a loss in performance compared to the +non-packed case, so the packed attribute should only be used when avoiding +structure padding is of importance. + + +Code that causes unaligned access +================================= + +With the above in mind, let's move onto a real life example of a function +that can cause an unaligned memory access. The following function taken +from include/linux/etherdevice.h is an optimized routine to compare two +ethernet MAC addresses for equality:: + + bool ether_addr_equal(const u8 *addr1, const u8 *addr2) + { + #ifdef CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS + u32 fold = ((*(const u32 *)addr1) ^ (*(const u32 *)addr2)) | + ((*(const u16 *)(addr1 + 4)) ^ (*(const u16 *)(addr2 + 4))); + + return fold == 0; + #else + const u16 *a = (const u16 *)addr1; + const u16 *b = (const u16 *)addr2; + return ((a[0] ^ b[0]) | (a[1] ^ b[1]) | (a[2] ^ b[2])) == 0; + #endif + } + +In the above function, when the hardware has efficient unaligned access +capability, there is no issue with this code. But when the hardware isn't +able to access memory on arbitrary boundaries, the reference to a[0] causes +2 bytes (16 bits) to be read from memory starting at address addr1. + +Think about what would happen if addr1 was an odd address such as 0x10003. +(Hint: it'd be an unaligned access.) + +Despite the potential unaligned access problems with the above function, it +is included in the kernel anyway but is understood to only work normally on +16-bit-aligned addresses. It is up to the caller to ensure this alignment or +not use this function at all. This alignment-unsafe function is still useful +as it is a decent optimization for the cases when you can ensure alignment, +which is true almost all of the time in ethernet networking context. + + +Here is another example of some code that could cause unaligned accesses:: + + void myfunc(u8 *data, u32 value) + { + [...] + *((u32 *) data) = cpu_to_le32(value); + [...] + } + +This code will cause unaligned accesses every time the data parameter points +to an address that is not evenly divisible by 4. + +In summary, the 2 main scenarios where you may run into unaligned access +problems involve: + + 1. Casting variables to types of different lengths + 2. Pointer arithmetic followed by access to at least 2 bytes of data + + +Avoiding unaligned accesses +=========================== + +The easiest way to avoid unaligned access is to use the get_unaligned() and +put_unaligned() macros provided by the header file. + +Going back to an earlier example of code that potentially causes unaligned +access:: + + void myfunc(u8 *data, u32 value) + { + [...] + *((u32 *) data) = cpu_to_le32(value); + [...] + } + +To avoid the unaligned memory access, you would rewrite it as follows:: + + void myfunc(u8 *data, u32 value) + { + [...] + value = cpu_to_le32(value); + put_unaligned(value, (u32 *) data); + [...] + } + +The get_unaligned() macro works similarly. Assuming 'data' is a pointer to +memory and you wish to avoid unaligned access, its usage is as follows:: + + u32 value = get_unaligned((u32 *) data); + +These macros work for memory accesses of any length (not just 32 bits as +in the examples above). Be aware that when compared to standard access of +aligned memory, using these macros to access unaligned memory can be costly in +terms of performance. + +If use of such macros is not convenient, another option is to use memcpy(), +where the source or destination (or both) are of type u8* or unsigned char*. +Due to the byte-wise nature of this operation, unaligned accesses are avoided. + + +Alignment vs. Networking +======================== + +On architectures that require aligned loads, networking requires that the IP +header is aligned on a four-byte boundary to optimise the IP stack. For +regular ethernet hardware, the constant NET_IP_ALIGN is used. On most +architectures this constant has the value 2 because the normal ethernet +header is 14 bytes long, so in order to get proper alignment one needs to +DMA to an address which can be expressed as 4*n + 2. One notable exception +here is powerpc which defines NET_IP_ALIGN to 0 because DMA to unaligned +addresses can be very expensive and dwarf the cost of unaligned loads. + +For some ethernet hardware that cannot DMA to unaligned addresses like +4*n+2 or non-ethernet hardware, this can be a problem, and it is then +required to copy the incoming frame into an aligned buffer. Because this is +unnecessary on architectures that can do unaligned accesses, the code can be +made dependent on CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS like so:: + + #ifdef CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS + skb = original skb + #else + skb = copy skb + #endif diff --git a/Documentation/unaligned-memory-access.txt b/Documentation/unaligned-memory-access.txt deleted file mode 100644 index 1ee82419d8aa..000000000000 --- a/Documentation/unaligned-memory-access.txt +++ /dev/null @@ -1,265 +0,0 @@ -========================= -Unaligned Memory Accesses -========================= - -:Author: Daniel Drake , -:Author: Johannes Berg - -:With help from: Alan Cox, Avuton Olrich, Heikki Orsila, Jan Engelhardt, - Kyle McMartin, Kyle Moffett, Randy Dunlap, Robert Hancock, Uli Kunitz, - Vadim Lobanov - - -Linux runs on a wide variety of architectures which have varying behaviour -when it comes to memory access. This document presents some details about -unaligned accesses, why you need to write code that doesn't cause them, -and how to write such code! - - -The definition of an unaligned access -===================================== - -Unaligned memory accesses occur when you try to read N bytes of data starting -from an address that is not evenly divisible by N (i.e. addr % N != 0). -For example, reading 4 bytes of data from address 0x10004 is fine, but -reading 4 bytes of data from address 0x10005 would be an unaligned memory -access. - -The above may seem a little vague, as memory access can happen in different -ways. The context here is at the machine code level: certain instructions read -or write a number of bytes to or from memory (e.g. movb, movw, movl in x86 -assembly). As will become clear, it is relatively easy to spot C statements -which will compile to multiple-byte memory access instructions, namely when -dealing with types such as u16, u32 and u64. - - -Natural alignment -================= - -The rule mentioned above forms what we refer to as natural alignment: -When accessing N bytes of memory, the base memory address must be evenly -divisible by N, i.e. addr % N == 0. - -When writing code, assume the target architecture has natural alignment -requirements. - -In reality, only a few architectures require natural alignment on all sizes -of memory access. However, we must consider ALL supported architectures; -writing code that satisfies natural alignment requirements is the easiest way -to achieve full portability. - - -Why unaligned access is bad -=========================== - -The effects of performing an unaligned memory access vary from architecture -to architecture. It would be easy to write a whole document on the differences -here; a summary of the common scenarios is presented below: - - - Some architectures are able to perform unaligned memory accesses - transparently, but there is usually a significant performance cost. - - Some architectures raise processor exceptions when unaligned accesses - happen. The exception handler is able to correct the unaligned access, - at significant cost to performance. - - Some architectures raise processor exceptions when unaligned accesses - happen, but the exceptions do not contain enough information for the - unaligned access to be corrected. - - Some architectures are not capable of unaligned memory access, but will - silently perform a different memory access to the one that was requested, - resulting in a subtle code bug that is hard to detect! - -It should be obvious from the above that if your code causes unaligned -memory accesses to happen, your code will not work correctly on certain -platforms and will cause performance problems on others. - - -Code that does not cause unaligned access -========================================= - -At first, the concepts above may seem a little hard to relate to actual -coding practice. After all, you don't have a great deal of control over -memory addresses of certain variables, etc. - -Fortunately things are not too complex, as in most cases, the compiler -ensures that things will work for you. For example, take the following -structure:: - - struct foo { - u16 field1; - u32 field2; - u8 field3; - }; - -Let us assume that an instance of the above structure resides in memory -starting at address 0x10000. With a basic level of understanding, it would -not be unreasonable to expect that accessing field2 would cause an unaligned -access. You'd be expecting field2 to be located at offset 2 bytes into the -structure, i.e. address 0x10002, but that address is not evenly divisible -by 4 (remember, we're reading a 4 byte value here). - -Fortunately, the compiler understands the alignment constraints, so in the -above case it would insert 2 bytes of padding in between field1 and field2. -Therefore, for standard structure types you can always rely on the compiler -to pad structures so that accesses to fields are suitably aligned (assuming -you do not cast the field to a type of different length). - -Similarly, you can also rely on the compiler to align variables and function -parameters to a naturally aligned scheme, based on the size of the type of -the variable. - -At this point, it should be clear that accessing a single byte (u8 or char) -will never cause an unaligned access, because all memory addresses are evenly -divisible by one. - -On a related topic, with the above considerations in mind you may observe -that you could reorder the fields in the structure in order to place fields -where padding would otherwise be inserted, and hence reduce the overall -resident memory size of structure instances. The optimal layout of the -above example is:: - - struct foo { - u32 field2; - u16 field1; - u8 field3; - }; - -For a natural alignment scheme, the compiler would only have to add a single -byte of padding at the end of the structure. This padding is added in order -to satisfy alignment constraints for arrays of these structures. - -Another point worth mentioning is the use of __attribute__((packed)) on a -structure type. This GCC-specific attribute tells the compiler never to -insert any padding within structures, useful when you want to use a C struct -to represent some data that comes in a fixed arrangement 'off the wire'. - -You might be inclined to believe that usage of this attribute can easily -lead to unaligned accesses when accessing fields that do not satisfy -architectural alignment requirements. However, again, the compiler is aware -of the alignment constraints and will generate extra instructions to perform -the memory access in a way that does not cause unaligned access. Of course, -the extra instructions obviously cause a loss in performance compared to the -non-packed case, so the packed attribute should only be used when avoiding -structure padding is of importance. - - -Code that causes unaligned access -================================= - -With the above in mind, let's move onto a real life example of a function -that can cause an unaligned memory access. The following function taken -from include/linux/etherdevice.h is an optimized routine to compare two -ethernet MAC addresses for equality:: - - bool ether_addr_equal(const u8 *addr1, const u8 *addr2) - { - #ifdef CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS - u32 fold = ((*(const u32 *)addr1) ^ (*(const u32 *)addr2)) | - ((*(const u16 *)(addr1 + 4)) ^ (*(const u16 *)(addr2 + 4))); - - return fold == 0; - #else - const u16 *a = (const u16 *)addr1; - const u16 *b = (const u16 *)addr2; - return ((a[0] ^ b[0]) | (a[1] ^ b[1]) | (a[2] ^ b[2])) == 0; - #endif - } - -In the above function, when the hardware has efficient unaligned access -capability, there is no issue with this code. But when the hardware isn't -able to access memory on arbitrary boundaries, the reference to a[0] causes -2 bytes (16 bits) to be read from memory starting at address addr1. - -Think about what would happen if addr1 was an odd address such as 0x10003. -(Hint: it'd be an unaligned access.) - -Despite the potential unaligned access problems with the above function, it -is included in the kernel anyway but is understood to only work normally on -16-bit-aligned addresses. It is up to the caller to ensure this alignment or -not use this function at all. This alignment-unsafe function is still useful -as it is a decent optimization for the cases when you can ensure alignment, -which is true almost all of the time in ethernet networking context. - - -Here is another example of some code that could cause unaligned accesses:: - - void myfunc(u8 *data, u32 value) - { - [...] - *((u32 *) data) = cpu_to_le32(value); - [...] - } - -This code will cause unaligned accesses every time the data parameter points -to an address that is not evenly divisible by 4. - -In summary, the 2 main scenarios where you may run into unaligned access -problems involve: - - 1. Casting variables to types of different lengths - 2. Pointer arithmetic followed by access to at least 2 bytes of data - - -Avoiding unaligned accesses -=========================== - -The easiest way to avoid unaligned access is to use the get_unaligned() and -put_unaligned() macros provided by the header file. - -Going back to an earlier example of code that potentially causes unaligned -access:: - - void myfunc(u8 *data, u32 value) - { - [...] - *((u32 *) data) = cpu_to_le32(value); - [...] - } - -To avoid the unaligned memory access, you would rewrite it as follows:: - - void myfunc(u8 *data, u32 value) - { - [...] - value = cpu_to_le32(value); - put_unaligned(value, (u32 *) data); - [...] - } - -The get_unaligned() macro works similarly. Assuming 'data' is a pointer to -memory and you wish to avoid unaligned access, its usage is as follows:: - - u32 value = get_unaligned((u32 *) data); - -These macros work for memory accesses of any length (not just 32 bits as -in the examples above). Be aware that when compared to standard access of -aligned memory, using these macros to access unaligned memory can be costly in -terms of performance. - -If use of such macros is not convenient, another option is to use memcpy(), -where the source or destination (or both) are of type u8* or unsigned char*. -Due to the byte-wise nature of this operation, unaligned accesses are avoided. - - -Alignment vs. Networking -======================== - -On architectures that require aligned loads, networking requires that the IP -header is aligned on a four-byte boundary to optimise the IP stack. For -regular ethernet hardware, the constant NET_IP_ALIGN is used. On most -architectures this constant has the value 2 because the normal ethernet -header is 14 bytes long, so in order to get proper alignment one needs to -DMA to an address which can be expressed as 4*n + 2. One notable exception -here is powerpc which defines NET_IP_ALIGN to 0 because DMA to unaligned -addresses can be very expensive and dwarf the cost of unaligned loads. - -For some ethernet hardware that cannot DMA to unaligned addresses like -4*n+2 or non-ethernet hardware, this can be a problem, and it is then -required to copy the incoming frame into an aligned buffer. Because this is -unnecessary on architectures that can do unaligned accesses, the code can be -made dependent on CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS like so:: - - #ifdef CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS - skb = original skb - #else - skb = copy skb - #endif -- cgit v1.2.3