diff options
Diffstat (limited to 'Documentation/process')
| -rw-r--r-- | Documentation/process/2.Process.rst | 12 | ||||
| -rw-r--r-- | Documentation/process/4.Coding.rst | 4 | ||||
| -rw-r--r-- | Documentation/process/botching-up-ioctls.rst | 2 | ||||
| -rw-r--r-- | Documentation/process/changes.rst | 6 | ||||
| -rw-r--r-- | Documentation/process/clang-format.rst | 2 | ||||
| -rw-r--r-- | Documentation/process/coding-style.rst | 2 | ||||
| -rw-r--r-- | Documentation/process/deprecated.rst | 136 | ||||
| -rw-r--r-- | Documentation/process/howto.rst | 2 | ||||
| -rw-r--r-- | Documentation/process/index.rst | 4 | ||||
| -rw-r--r-- | Documentation/process/kernel-docs.rst | 28 | ||||
| -rw-r--r-- | Documentation/process/maintainer-pgp-guide.rst | 2 | ||||
| -rw-r--r-- | Documentation/process/submitting-drivers.rst | 22 | ||||
| -rw-r--r-- | Documentation/process/submitting-patches.rst | 9 | ||||
| -rw-r--r-- | Documentation/process/unaligned-memory-access.rst | 265 |
14 files changed, 186 insertions, 310 deletions
diff --git a/Documentation/process/2.Process.rst b/Documentation/process/2.Process.rst index b21b5b245d13..3588f48841eb 100644 --- a/Documentation/process/2.Process.rst +++ b/Documentation/process/2.Process.rst @@ -295,7 +295,7 @@ mainline get there via -mm. The current -mm patch is available in the "mmotm" (-mm of the moment) directory at: - http://www.ozlabs.org/~akpm/mmotm/ + https://www.ozlabs.org/~akpm/mmotm/ Use of the MMOTM tree is likely to be a frustrating experience, though; there is a definite chance that it will not even compile. @@ -306,7 +306,7 @@ the mainline is expected to look like after the next merge window closes. Linux-next trees are announced on the linux-kernel and linux-next mailing lists when they are assembled; they can be downloaded from: - http://www.kernel.org/pub/linux/kernel/next/ + https://www.kernel.org/pub/linux/kernel/next/ Linux-next has become an integral part of the kernel development process; all patches merged during a given merge window should really have found @@ -365,21 +365,21 @@ to keep up with what other developers (and the mainline) are doing. Git is now packaged by almost all Linux distributions. There is a home page at: - http://git-scm.com/ + https://git-scm.com/ That page has pointers to documentation and tutorials. Among the kernel developers who do not use git, the most popular choice is almost certainly Mercurial: - http://www.selenic.com/mercurial/ + https://www.selenic.com/mercurial/ Mercurial shares many features with git, but it provides an interface which many find easier to use. The other tool worth knowing about is Quilt: - http://savannah.nongnu.org/projects/quilt/ + https://savannah.nongnu.org/projects/quilt/ Quilt is a patch management system, rather than a source code management system. It does not track history over time; it is, instead, oriented @@ -494,7 +494,7 @@ Andrew Morton gives this advice for aspiring kernel developers with others on getting things fixed up (this can require persistence!) but that's fine - it's a part of kernel development. -(http://lwn.net/Articles/283982/). +(https://lwn.net/Articles/283982/). In the absence of obvious problems to fix, developers are advised to look at the current lists of regressions and open bugs in general. There is diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst index 13dd893c9f88..c27e59d2f702 100644 --- a/Documentation/process/4.Coding.rst +++ b/Documentation/process/4.Coding.rst @@ -210,7 +210,7 @@ breaks? The best answer to this question was expressed by Linus in July, progress at all. Is it two steps forwards, one step back, or one step forward and two steps back? -(http://lwn.net/Articles/243460/). +(https://lwn.net/Articles/243460/). An especially unwelcome type of regression is any sort of change to the user-space ABI. Once an interface has been exported to user space, it must @@ -323,7 +323,7 @@ other architectures. If you do not happen to have an S/390 system or a Blackfin development board handy, you can still perform the compilation step. A large set of cross compilers for x86 systems can be found at - http://www.kernel.org/pub/tools/crosstool/ + https://www.kernel.org/pub/tools/crosstool/ Some time spent installing and using these compilers will help avoid embarrassment later. diff --git a/Documentation/process/botching-up-ioctls.rst b/Documentation/process/botching-up-ioctls.rst index 2d4829b2fb09..ba4667ab396b 100644 --- a/Documentation/process/botching-up-ioctls.rst +++ b/Documentation/process/botching-up-ioctls.rst @@ -2,7 +2,7 @@ (How to avoid) Botching up ioctls ================================= -From: http://blog.ffwll.ch/2013/11/botching-up-ioctls.html +From: https://blog.ffwll.ch/2013/11/botching-up-ioctls.html By: Daniel Vetter, Copyright © 2013 Intel Corporation diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 8f68e728ae6b..ee741763a3fc 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -129,7 +129,7 @@ Architectural changes --------------------- DevFS has been obsoleted in favour of udev -(http://www.kernel.org/pub/linux/utils/kernel/hotplug/) +(https://www.kernel.org/pub/linux/utils/kernel/hotplug/) 32-bit UID support is now in place. Have fun! @@ -421,7 +421,7 @@ Intel P6 microcode udev ---- -- <http://www.freedesktop.org/software/systemd/man/udev.html> +- <https://www.freedesktop.org/software/systemd/man/udev.html> FUSE ---- @@ -474,4 +474,4 @@ Kernel documentation Sphinx ------ -- <http://www.sphinx-doc.org/> +- <https://www.sphinx-doc.org/> diff --git a/Documentation/process/clang-format.rst b/Documentation/process/clang-format.rst index 6710c0707721..82676e5a7c6e 100644 --- a/Documentation/process/clang-format.rst +++ b/Documentation/process/clang-format.rst @@ -32,7 +32,7 @@ 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: - http://releases.llvm.org/download.html + https://releases.llvm.org/download.html See more information about the tool at: diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 1bee6f8affdb..98227226c4e5 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -1149,7 +1149,7 @@ Addison-Wesley, Inc., 1999. ISBN 0-201-61586-X. GNU manuals - where in compliance with K&R and this text - for cpp, gcc, -gcc internals and indent, all available from http://www.gnu.org/manual/ +gcc internals and indent, all available from https://www.gnu.org/manual/ WG14 is the international standardization working group for the programming language C, URL: http://www.open-std.org/JTC1/SC22/WG14/ diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst index 652e2aa02a66..4a9aa4f0681e 100644 --- a/Documentation/process/deprecated.rst +++ b/Documentation/process/deprecated.rst @@ -51,6 +51,24 @@ to make sure their systems do not continue running in the face of "unreachable" conditions. (For example, see commits like `this one <https://git.kernel.org/linus/d4689846881d160a4d12a514e991a740bcb5d65a>`_.) +uninitialized_var() +------------------- +For any compiler warnings about uninitialized variables, just add +an initializer. Using the uninitialized_var() macro (or similar +warning-silencing tricks) is dangerous as it papers over `real bugs +<https://lore.kernel.org/lkml/20200603174714.192027-1-glider@google.com/>`_ +(or can in the future), and suppresses unrelated compiler warnings +(e.g. "unused variable"). If the compiler thinks it is uninitialized, +either simply initialize the variable or make compiler changes. Keep in +mind that in most cases, if an initialization is obviously redundant, +the compiler's dead-store elimination pass will make sure there are no +needless variable writes. + +As Linus has said, this macro +`must <https://lore.kernel.org/lkml/CA+55aFw+Vbj0i=1TGqCR5vQkCzWJ0QxK6CernOU6eedsudAixw@mail.gmail.com/>`_ +`be <https://lore.kernel.org/lkml/CA+55aFwgbgqhbp1fkxvRKEpzyR5J8n1vKT1VZdz9knmPuXhOeg@mail.gmail.com/>`_ +`removed <https://lore.kernel.org/lkml/CA+55aFz2500WfbKXAx8s67wrm9=yVJu65TpLgN_ybYNv0VEOKA@mail.gmail.com/>`_. + open-coded arithmetic in allocator arguments -------------------------------------------- Dynamic size calculations (especially multiplication) should not be @@ -85,6 +103,11 @@ Instead, use the helper:: header = kzalloc(struct_size(header, item, count), GFP_KERNEL); +.. note:: If you are using struct_size() on a structure containing a zero-length + or a one-element array as a trailing array member, please refactor such + array usage and switch to a `flexible array member + <#zero-length-and-one-element-arrays>`_ instead. + See array_size(), array3_size(), and struct_size(), for more details as well as the related check_add_overflow() and check_mul_overflow() family of functions. @@ -200,3 +223,116 @@ All switch/case blocks must end in one of: * continue; * goto <label>; * return [expression]; + +Zero-length and one-element arrays +---------------------------------- +There is a regular need in the kernel to provide a way to declare having +a dynamically sized set of trailing elements in a structure. Kernel code +should always use `"flexible array members" <https://en.wikipedia.org/wiki/Flexible_array_member>`_ +for these cases. The older style of one-element or zero-length arrays should +no longer be used. + +In older C code, dynamically sized trailing elements were done by specifying +a one-element array at the end of a structure:: + + struct something { + size_t count; + struct foo items[1]; + }; + +This led to fragile size calculations via sizeof() (which would need to +remove the size of the single trailing element to get a correct size of +the "header"). A `GNU C extension <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_ +was introduced to allow for zero-length arrays, to avoid these kinds of +size problems:: + + struct something { + size_t count; + struct foo items[0]; + }; + +But this led to other problems, and didn't solve some problems shared by +both styles, like not being able to detect when such an array is accidentally +being used _not_ at the end of a structure (which could happen directly, or +when such a struct was in unions, structs of structs, etc). + +C99 introduced "flexible array members", which lacks a numeric size for +the array declaration entirely:: + + struct something { + size_t count; + struct foo items[]; + }; + +This is the way the kernel expects dynamically sized trailing elements +to be declared. It allows the compiler to generate errors when the +flexible array does not occur last in the structure, which helps to prevent +some kind of `undefined behavior +<https://git.kernel.org/linus/76497732932f15e7323dc805e8ea8dc11bb587cf>`_ +bugs from being inadvertently introduced to the codebase. It also allows +the compiler to correctly analyze array sizes (via sizeof(), +`CONFIG_FORTIFY_SOURCE`, and `CONFIG_UBSAN_BOUNDS`). For instance, +there is no mechanism that warns us that the following application of the +sizeof() operator to a zero-length array always results in zero:: + + struct something { + size_t count; + struct foo items[0]; + }; + + struct something *instance; + + instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL); + instance->count = count; + + size = sizeof(instance->items) * instance->count; + memcpy(instance->items, source, size); + +At the last line of code above, ``size`` turns out to be ``zero``, when one might +have thought it represents the total size in bytes of the dynamic memory recently +allocated for the trailing array ``items``. Here are a couple examples of this +issue: `link 1 +<https://git.kernel.org/linus/f2cd32a443da694ac4e28fbf4ac6f9d5cc63a539>`_, +`link 2 +<https://git.kernel.org/linus/ab91c2a89f86be2898cee208d492816ec238b2cf>`_. +Instead, `flexible array members have incomplete type, and so the sizeof() +operator may not be applied <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_, +so any misuse of such operators will be immediately noticed at build time. + +With respect to one-element arrays, one has to be acutely aware that `such arrays +occupy at least as much space as a single object of the type +<https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_, +hence they contribute to the size of the enclosing structure. This is prone +to error every time people want to calculate the total size of dynamic memory +to allocate for a structure containing an array of this kind as a member:: + + struct something { + size_t count; + struct foo items[1]; + }; + + struct something *instance; + + instance = kmalloc(struct_size(instance, items, count - 1), GFP_KERNEL); + instance->count = count; + + size = sizeof(instance->items) * instance->count; + memcpy(instance->items, source, size); + +In the example above, we had to remember to calculate ``count - 1`` when using +the struct_size() helper, otherwise we would have --unintentionally-- allocated +memory for one too many ``items`` objects. The cleanest and least error-prone way +to implement this is through the use of a `flexible array member`:: + + struct something { + size_t count; + struct foo items[]; + }; + + struct something *instance; + + instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL); + instance->count = count; + + size = sizeof(instance->items[0]) * instance->count; + memcpy(instance->items, source, size); diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index 70791e153de1..20c9e07e09a4 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -597,7 +597,7 @@ For more details on what this should all look like, please see the ChangeLog section of the document: "The Perfect Patch" - http://www.ozlabs.org/~akpm/stuff/tpp.txt + https://www.ozlabs.org/~akpm/stuff/tpp.txt All of these things are sometimes very hard to do. It can take years to diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index f07c9250c3ac..dd231ffc8422 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -32,7 +32,7 @@ Below are the essential guides that every developer should read. kernel-enforcement-statement kernel-driver-statement -Other guides to the community that are of interest to most developers are: +Other guides to the community that are of interest to most developers are: .. toctree:: :maxdepth: 1 @@ -61,7 +61,7 @@ lack of a better place. botching-up-ioctls clang-format ../riscv/patch-acceptance - unaligned-memory-access + ../core-api/unaligned-memory-access .. only:: subproject and html diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst index 9d6d0ac4fca9..64786e50026c 100644 --- a/Documentation/process/kernel-docs.rst +++ b/Documentation/process/kernel-docs.rst @@ -98,7 +98,7 @@ On-line docs * Title: **Linux Device Drivers, Third Edition** :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman - :URL: http://lwn.net/Kernel/LDD3/ + :URL: https://lwn.net/Kernel/LDD3/ :Date: 2005 :Description: A 600-page book covering the (2.6.10) driver programming API and kernel hacking in general. Available under the @@ -129,7 +129,7 @@ On-line docs * Title: **Linux Kernel Module Programming Guide** :Author: Ori Pomerantz. - :URL: http://tldp.org/LDP/lkmpg/2.6/html/index.html + :URL: https://tldp.org/LDP/lkmpg/2.6/html/index.html :Date: 2001 :Keywords: modules, GPL book, /proc, ioctls, system calls, interrupt handlers . @@ -244,7 +244,7 @@ On-line docs * Title: **I/O Event Handling Under Linux** :Author: Richard Gooch. - :URL: http://web.mit.edu/~yandros/doc/io-events.html + :URL: https://web.mit.edu/~yandros/doc/io-events.html :Date: 1999 :Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness event queues. @@ -295,7 +295,7 @@ On-line docs * Title: **Design and Implementation of the Second Extended Filesystem** :Author: Rémy Card, Theodore Ts'o, Stephen Tweedie. - :URL: http://web.mit.edu/tytso/www/linux/ext2intro.html + :URL: https://web.mit.edu/tytso/www/linux/ext2intro.html :Date: 1998 :Keywords: ext2, linux fs history, inode, directory, link, devices, VFS, physical structure, performance, benchmarks, ext2fs library, @@ -322,7 +322,7 @@ On-line docs * Title: **Linux Kernel Hackers' Guide** :Author: Michael K. Johnson. - :URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html + :URL: https://www.tldp.org/LDP/khg/HyperNews/get/khg.html :Date: 1997 :Keywords: device drivers, files, VFS, kernel interface, character vs block devices, hardware interrupts, scsi, DMA, access to user memory, @@ -375,7 +375,7 @@ On-line docs * Title: **Dissecting Interrupts and Browsing DMA** :Author: Alessandro Rubini and Georg v. Zezschwitz. - :URL: http://www.linuxjournal.com/article.php?sid=1222 + :URL: https://www.linuxjournal.com/article.php?sid=1222 :Date: 1996 :Keywords: interrupts, irqs, DMA, bottom halves, task queues. :Description: Linux Journal Kernel Korner article. @@ -391,7 +391,7 @@ On-line docs * Title: **Device Drivers Concluded** :Author: Georg v. Zezschwitz. - :URL: http://www.linuxjournal.com/article.php?sid=1287 + :URL: https://www.linuxjournal.com/article.php?sid=1287 :Date: 1996 :Keywords: address spaces, pages, pagination, page management, demand loading, swapping, memory protection, memory mapping, mmap, @@ -405,7 +405,7 @@ On-line docs * Title: **Network Buffers And Memory Management** :Author: Alan Cox. - :URL: http://www.linuxjournal.com/article.php?sid=1312 + :URL: https://www.linuxjournal.com/article.php?sid=1312 :Date: 1996 :Keywords: sk_buffs, network devices, protocol/link layer variables, network devices flags, transmit, receive, @@ -418,7 +418,7 @@ On-line docs * Title: **Analysis of the Ext2fs structure** :Author: Louis-Dominique Dubeau. - :URL: http://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/ + :URL: https://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/ :Date: 1994 :Keywords: ext2, filesystem, ext2fs. :Description: Description of ext2's blocks, directories, inodes, @@ -480,7 +480,7 @@ Published books :ISBN: 0-596-00590-3 :Notes: Further information in http://www.oreilly.com/catalog/linuxdrive3/ - PDF format, URL: http://lwn.net/Kernel/LDD3/ + PDF format, URL: https://lwn.net/Kernel/LDD3/ * Title: **Linux Kernel Internals** @@ -561,7 +561,7 @@ Miscellaneous * Name: **Linux Weekly News** - :URL: http://lwn.net + :URL: https://lwn.net :Keywords: latest kernel news. :Description: The title says it all. There's a fixed kernel section summarizing developers' work, bug fixes, new features and versions @@ -570,7 +570,7 @@ Miscellaneous * Name: **The home page of Linux-MM** :Author: The Linux-MM team. - :URL: http://linux-mm.org/ + :URL: https://linux-mm.org/ :Keywords: memory management, Linux-MM, mm patches, TODO, docs, mailing list. :Description: Site devoted to Linux Memory Management development. @@ -579,7 +579,7 @@ Miscellaneous * Name: **Kernel Newbies IRC Channel and Website** - :URL: http://www.kernelnewbies.org + :URL: https://www.kernelnewbies.org :Keywords: IRC, newbies, channel, asking doubts. :Description: #kernelnewbies on irc.oftc.net. #kernelnewbies is an IRC network dedicated to the 'newbie' @@ -605,4 +605,4 @@ Miscellaneous Document last updated on Tue 2016-Sep-20 This document is based on: - http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html + https://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst index 17db11b7ed48..8f8f1fee92b8 100644 --- a/Documentation/process/maintainer-pgp-guide.rst +++ b/Documentation/process/maintainer-pgp-guide.rst @@ -462,7 +462,7 @@ geographical region, and open/proprietary hardware considerations. .. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6 .. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nitrokey-pro-2-3 .. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/ -.. _Gnuk: http://www.fsij.org/doc-gnuk/ +.. _Gnuk: https://www.fsij.org/doc-gnuk/ .. _`LWN has a good review`: https://lwn.net/Articles/736231/ .. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst index 1acaa14903d6..74b35bfc6623 100644 --- a/Documentation/process/submitting-drivers.rst +++ b/Documentation/process/submitting-drivers.rst @@ -5,8 +5,8 @@ Submitting Drivers For The Linux Kernel This document is intended to explain how to submit device drivers to the various kernel trees. Note that if you are interested in video card drivers -you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org -(http://x.org/) instead. +you should probably talk to XFree86 (https://www.xfree86.org/) and/or X.Org +(https://x.org/) instead. .. note:: @@ -25,7 +25,7 @@ Allocating Device Numbers Major and minor numbers for block and character devices are allocated by the Linux assigned name and number authority (currently this is -Torben Mathiasen). The site is http://www.lanana.org/. This +Torben Mathiasen). The site is https://www.lanana.org/. This also deals with allocating numbers for devices that are not going to be submitted to the mainstream kernel. See :ref:`Documentation/admin-guide/devices.rst <admin_devices>` @@ -155,30 +155,30 @@ Linux kernel master tree: where *country_code* == your country code, such as **us**, **uk**, **fr**, etc. - http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git + https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git Linux kernel mailing list: linux-kernel@vger.kernel.org [mail majordomo@vger.kernel.org to subscribe] Linux Device Drivers, Third Edition (covers 2.6.10): - http://lwn.net/Kernel/LDD3/ (free version) + https://lwn.net/Kernel/LDD3/ (free version) LWN.net: - Weekly summary of kernel development activity - http://lwn.net/ + Weekly summary of kernel development activity - https://lwn.net/ 2.6 API changes: - http://lwn.net/Articles/2.6-kernel-api/ + https://lwn.net/Articles/2.6-kernel-api/ Porting drivers from prior kernels to 2.6: - http://lwn.net/Articles/driver-porting/ + https://lwn.net/Articles/driver-porting/ KernelNewbies: Documentation and assistance for new kernel programmers - http://kernelnewbies.org/ + https://kernelnewbies.org/ Linux USB project: http://www.linux-usb.org/ @@ -187,7 +187,7 @@ How to NOT write kernel driver by Arjan van de Ven: http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf Kernel Janitor: - http://kernelnewbies.org/KernelJanitors + https://kernelnewbies.org/KernelJanitors GIT, Fast Version Control System: - http://git-scm.com/ + https://git-scm.com/ diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 1699b7f8e63a..5219bf3cddfc 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -94,7 +94,7 @@ individual patches which modify things in logical stages; see very important if you want your patch accepted. If you're using ``git``, ``git rebase -i`` can help you with this process. If -you're not using ``git``, ``quilt`` <http://savannah.nongnu.org/projects/quilt> +you're not using ``git``, ``quilt`` <https://savannah.nongnu.org/projects/quilt> is another popular alternative. .. _describe_changes: @@ -196,6 +196,11 @@ outputting the above style in the ``git log`` or ``git show`` commands:: [pretty] fixes = Fixes: %h (\"%s\") +An example call:: + + $ git log -1 --pretty=fixes 54a4f0239f2e + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") + .. _split_changes: 3) Separate your changes @@ -892,7 +897,7 @@ References ---------- Andrew Morton, "The perfect patch" (tpp). - <http://www.ozlabs.org/~akpm/stuff/tpp.txt> + <https://www.ozlabs.org/~akpm/stuff/tpp.txt> Jeff Garzik, "Linux kernel patch submission format". <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html> diff --git a/Documentation/process/unaligned-memory-access.rst b/Documentation/process/unaligned-memory-access.rst deleted file mode 100644 index 1ee82419d8aa..000000000000 --- a/Documentation/process/unaligned-memory-access.rst +++ /dev/null @@ -1,265 +0,0 @@ -========================= -Unaligned Memory Accesses -========================= - -:Author: Daniel Drake <dsd@gentoo.org>, -:Author: Johannes Berg <johannes@sipsolutions.net> - -: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 <asm/unaligned.h> 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 |