diff options
| author | Linus Torvalds <torvalds@linux-foundation.org> | 2023-04-24 21:35:49 +0200 |
|---|---|---|
| committer | Linus Torvalds <torvalds@linux-foundation.org> | 2023-04-24 21:35:49 +0200 |
| commit | c23f28975abc2eb02cecc8bc1f2c95473a59ed2e (patch) | |
| tree | d356762219c0d3079d37f1cc3ab3eef5cd37567a /Documentation | |
| parent | Merge tag 'linux-kselftest-kunit-6.4-rc1' of git://git.kernel.org/pub/scm/lin... (diff) | |
| parent | media: Adjust column width for pdfdocs (diff) | |
| download | linux-c23f28975abc2eb02cecc8bc1f2c95473a59ed2e.tar.xz linux-c23f28975abc2eb02cecc8bc1f2c95473a59ed2e.zip | |
Merge tag 'docs-6.4' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet:
"Commit volume in documentation is relatively low this time, but there
is still a fair amount going on, including:
- Reorganize the architecture-specific documentation under
Documentation/arch
This makes the structure match the source directory and helps to
clean up the mess that is the top-level Documentation directory a
bit. This work creates the new directory and moves x86 and most of
the less-active architectures there.
The current plan is to move the rest of the architectures in 6.5,
with the patches going through the appropriate subsystem trees.
- Some more Spanish translations and maintenance of the Italian
translation
- A new "Kernel contribution maturity model" document from Ted
- A new tutorial on quickly building a trimmed kernel from Thorsten
Plus the usual set of updates and fixes"
* tag 'docs-6.4' of git://git.lwn.net/linux: (47 commits)
media: Adjust column width for pdfdocs
media: Fix building pdfdocs
docs: clk: add documentation to log which clocks have been disabled
docs: trace: Fix typo in ftrace.rst
Documentation/process: always CC responsible lists
docs: kmemleak: adjust to config renaming
ELF: document some de-facto PT_* ABI quirks
Documentation: arm: remove stih415/stih416 related entries
docs: turn off "smart quotes" in the HTML build
Documentation: firmware: Clarify firmware path usage
docs/mm: Physical Memory: Fix grammar
Documentation: Add document for false sharing
dma-api-howto: typo fix
docs: move m68k architecture documentation under Documentation/arch/
docs: move parisc documentation under Documentation/arch/
docs: move ia64 architecture docs under Documentation/arch/
docs: Move arc architecture docs under Documentation/arch/
docs: move nios2 documentation under Documentation/arch/
docs: move openrisc documentation under Documentation/arch/
docs: move superh documentation under Documentation/arch/
...
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/admin-guide/hw-vuln/mds.rst | 2 | ||||
| -rw-r--r-- | Documentation/admin-guide/hw-vuln/tsx_async_abort.rst | 2 | ||||
| -rw-r--r-- | Documentation/admin-guide/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/admin-guide/kernel-parameters.rst | 8 | ||||
| -rw-r--r-- | Documentation/admin-guide/kernel-parameters.txt | 341 | ||||
| -rw-r--r-- | Documentation/admin-guide/quickly-build-trimmed-linux.rst | 1092 | ||||
| -rw-r--r-- | Documentation/admin-guide/ras.rst | 2 | ||||
| -rw-r--r-- | Documentation/admin-guide/sysctl/kernel.rst | 4 | ||||
| -rw-r--r-- | Documentation/admin-guide/unicode.rst | 9 | ||||
| -rw-r--r-- | Documentation/arch/arc/arc.rst (renamed from Documentation/arc/arc.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/arc/features.rst (renamed from Documentation/arc/features.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/arc/index.rst (renamed from Documentation/arc/index.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/ia64/aliasing.rst (renamed from Documentation/ia64/aliasing.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/ia64/efirtc.rst (renamed from Documentation/ia64/efirtc.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/ia64/err_inject.rst (renamed from Documentation/ia64/err_inject.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/ia64/features.rst (renamed from Documentation/ia64/features.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/ia64/fsys.rst (renamed from Documentation/ia64/fsys.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/ia64/ia64.rst (renamed from Documentation/ia64/ia64.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/ia64/index.rst (renamed from Documentation/ia64/index.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/ia64/irq-redir.rst (renamed from Documentation/ia64/irq-redir.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/ia64/mca.rst (renamed from Documentation/ia64/mca.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/ia64/serial.rst (renamed from Documentation/ia64/serial.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/index.rst (renamed from Documentation/arch.rst) | 14 | ||||
| -rw-r--r-- | Documentation/arch/m68k/buddha-driver.rst (renamed from Documentation/m68k/buddha-driver.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/m68k/features.rst (renamed from Documentation/m68k/features.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/m68k/index.rst (renamed from Documentation/m68k/index.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/m68k/kernel-options.rst (renamed from Documentation/m68k/kernel-options.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/nios2/features.rst (renamed from Documentation/nios2/features.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/nios2/index.rst (renamed from Documentation/nios2/index.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/nios2/nios2.rst (renamed from Documentation/nios2/nios2.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/openrisc/features.rst (renamed from Documentation/openrisc/features.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/openrisc/index.rst (renamed from Documentation/openrisc/index.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/openrisc/openrisc_port.rst (renamed from Documentation/openrisc/openrisc_port.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/openrisc/todo.rst (renamed from Documentation/openrisc/todo.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/parisc/debugging.rst (renamed from Documentation/parisc/debugging.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/parisc/features.rst (renamed from Documentation/parisc/features.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/parisc/index.rst (renamed from Documentation/parisc/index.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/parisc/registers.rst (renamed from Documentation/parisc/registers.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/sh/booting.rst (renamed from Documentation/sh/booting.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/sh/features.rst (renamed from Documentation/sh/features.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/sh/index.rst (renamed from Documentation/sh/index.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/sh/new-machine.rst (renamed from Documentation/sh/new-machine.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/sh/register-banks.rst (renamed from Documentation/sh/register-banks.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/sparc/adi.rst (renamed from Documentation/sparc/adi.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/sparc/console.rst (renamed from Documentation/sparc/console.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/sparc/features.rst (renamed from Documentation/sparc/features.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/sparc/index.rst (renamed from Documentation/sparc/index.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/sparc/oradax/dax-hv-api.txt (renamed from Documentation/sparc/oradax/dax-hv-api.txt) | 0 | ||||
| -rw-r--r-- | Documentation/arch/sparc/oradax/oracle-dax.rst (renamed from Documentation/sparc/oradax/oracle-dax.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/amd-memory-encryption.rst (renamed from Documentation/x86/amd-memory-encryption.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/amd_hsmp.rst (renamed from Documentation/x86/amd_hsmp.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/boot.rst (renamed from Documentation/x86/boot.rst) | 4 | ||||
| -rw-r--r-- | Documentation/arch/x86/booting-dt.rst (renamed from Documentation/x86/booting-dt.rst) | 2 | ||||
| -rw-r--r-- | Documentation/arch/x86/buslock.rst (renamed from Documentation/x86/buslock.rst) | 10 | ||||
| -rw-r--r-- | Documentation/arch/x86/cpuinfo.rst (renamed from Documentation/x86/cpuinfo.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/earlyprintk.rst (renamed from Documentation/x86/earlyprintk.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/elf_auxvec.rst (renamed from Documentation/x86/elf_auxvec.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/entry_64.rst (renamed from Documentation/x86/entry_64.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/exception-tables.rst (renamed from Documentation/x86/exception-tables.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/features.rst (renamed from Documentation/x86/features.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/i386/IO-APIC.rst (renamed from Documentation/x86/i386/IO-APIC.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/i386/index.rst (renamed from Documentation/x86/i386/index.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/ifs.rst (renamed from Documentation/x86/ifs.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/index.rst (renamed from Documentation/x86/index.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/intel-hfi.rst (renamed from Documentation/x86/intel-hfi.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/intel_txt.rst (renamed from Documentation/x86/intel_txt.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/iommu.rst (renamed from Documentation/x86/iommu.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/kernel-stacks.rst (renamed from Documentation/x86/kernel-stacks.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/mds.rst (renamed from Documentation/x86/mds.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/microcode.rst (renamed from Documentation/x86/microcode.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/mtrr.rst (renamed from Documentation/x86/mtrr.rst) | 2 | ||||
| -rw-r--r-- | Documentation/arch/x86/orc-unwinder.rst (renamed from Documentation/x86/orc-unwinder.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/pat.rst (renamed from Documentation/x86/pat.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/pti.rst (renamed from Documentation/x86/pti.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/resctrl.rst (renamed from Documentation/x86/resctrl.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/sgx.rst (renamed from Documentation/x86/sgx.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/sva.rst (renamed from Documentation/x86/sva.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/tdx.rst (renamed from Documentation/x86/tdx.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/tlb.rst (renamed from Documentation/x86/tlb.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/topology.rst (renamed from Documentation/x86/topology.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/tsx_async_abort.rst (renamed from Documentation/x86/tsx_async_abort.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/usb-legacy-support.rst (renamed from Documentation/x86/usb-legacy-support.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/x86_64/5level-paging.rst (renamed from Documentation/x86/x86_64/5level-paging.rst) | 2 | ||||
| -rw-r--r-- | Documentation/arch/x86/x86_64/boot-options.rst (renamed from Documentation/x86/x86_64/boot-options.rst) | 4 | ||||
| -rw-r--r-- | Documentation/arch/x86/x86_64/cpu-hotplug-spec.rst (renamed from Documentation/x86/x86_64/cpu-hotplug-spec.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/x86_64/fake-numa-for-cpusets.rst (renamed from Documentation/x86/x86_64/fake-numa-for-cpusets.rst) | 2 | ||||
| -rw-r--r-- | Documentation/arch/x86/x86_64/fsgs.rst (renamed from Documentation/x86/x86_64/fsgs.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/x86_64/index.rst (renamed from Documentation/x86/x86_64/index.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/x86_64/machinecheck.rst (renamed from Documentation/x86/x86_64/machinecheck.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/x86_64/mm.rst (renamed from Documentation/x86/x86_64/mm.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/x86_64/uefi.rst (renamed from Documentation/x86/x86_64/uefi.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/xstate.rst (renamed from Documentation/x86/xstate.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/x86/zero-page.rst (renamed from Documentation/x86/zero-page.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/xtensa/atomctl.rst (renamed from Documentation/xtensa/atomctl.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/xtensa/booting.rst (renamed from Documentation/xtensa/booting.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/xtensa/features.rst (renamed from Documentation/xtensa/features.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/xtensa/index.rst (renamed from Documentation/xtensa/index.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arch/xtensa/mmu.rst (renamed from Documentation/xtensa/mmu.rst) | 0 | ||||
| -rw-r--r-- | Documentation/arm/index.rst | 2 | ||||
| -rw-r--r-- | Documentation/arm/sti/overview.rst | 10 | ||||
| -rw-r--r-- | Documentation/arm/sti/stih415-overview.rst | 14 | ||||
| -rw-r--r-- | Documentation/arm/sti/stih416-overview.rst | 13 | ||||
| -rw-r--r-- | Documentation/conf.py | 7 | ||||
| -rw-r--r-- | Documentation/core-api/asm-annotations.rst | 2 | ||||
| -rw-r--r-- | Documentation/core-api/dma-api-howto.rst | 2 | ||||
| -rw-r--r-- | Documentation/dev-tools/kmemleak.rst | 2 | ||||
| -rw-r--r-- | Documentation/driver-api/clk.rst | 5 | ||||
| -rw-r--r-- | Documentation/driver-api/device-io.rst | 2 | ||||
| -rw-r--r-- | Documentation/driver-api/firmware/fw_search_path.rst | 9 | ||||
| -rw-r--r-- | Documentation/filesystems/proc.rst | 44 | ||||
| -rw-r--r-- | Documentation/filesystems/vfs.rst | 105 | ||||
| -rw-r--r-- | Documentation/index.rst | 2 | ||||
| -rw-r--r-- | Documentation/kernel-hacking/false-sharing.rst | 206 | ||||
| -rw-r--r-- | Documentation/kernel-hacking/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/mm/physical_memory.rst | 21 | ||||
| -rw-r--r-- | Documentation/process/coding-style.rst | 2 | ||||
| -rw-r--r-- | Documentation/process/contribution-maturity-model.rst | 109 | ||||
| -rw-r--r-- | Documentation/process/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/process/kernel-docs.rst | 36 | ||||
| -rw-r--r-- | Documentation/process/maintainer-tip.rst | 4 | ||||
| -rw-r--r-- | Documentation/process/submitting-patches.rst | 19 | ||||
| -rw-r--r-- | Documentation/trace/ftrace.rst | 2 | ||||
| -rw-r--r-- | Documentation/translations/it_IT/core-api/symbol-namespaces.rst | 3 | ||||
| -rw-r--r-- | Documentation/translations/it_IT/doc-guide/parse-headers.rst | 5 | ||||
| -rw-r--r-- | Documentation/translations/it_IT/index.rst | 47 | ||||
| -rw-r--r-- | Documentation/translations/it_IT/kernel-hacking/locking.rst | 5 | ||||
| -rw-r--r-- | Documentation/translations/it_IT/process/5.Posting.rst | 13 | ||||
| -rw-r--r-- | Documentation/translations/it_IT/process/changes.rst | 4 | ||||
| -rw-r--r-- | Documentation/translations/it_IT/process/clang-format.rst | 2 | ||||
| -rw-r--r-- | Documentation/translations/it_IT/process/coding-style.rst | 6 | ||||
| -rw-r--r-- | Documentation/translations/it_IT/process/deprecated.rst | 29 | ||||
| -rw-r--r-- | Documentation/translations/it_IT/process/email-clients.rst | 25 | ||||
| -rw-r--r-- | Documentation/translations/it_IT/process/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/translations/it_IT/process/maintainer-pgp-guide.rst | 348 | ||||
| -rw-r--r-- | Documentation/translations/it_IT/process/programming-language.rst | 25 | ||||
| -rw-r--r-- | Documentation/translations/it_IT/process/stable-kernel-rules.rst | 6 | ||||
| -rw-r--r-- | Documentation/translations/it_IT/process/submitting-patches.rst | 4 | ||||
| -rw-r--r-- | Documentation/translations/it_IT/process/volatile-considered-harmful.rst | 4 | ||||
| -rw-r--r-- | Documentation/translations/sp_SP/memory-barriers.txt | 2 | ||||
| -rw-r--r-- | Documentation/translations/sp_SP/process/deprecated.rst | 381 | ||||
| -rw-r--r-- | Documentation/translations/sp_SP/process/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/translations/zh_CN/admin-guide/mm/damon/lru_sort.rst | 2 | ||||
| -rw-r--r-- | Documentation/translations/zh_CN/arch/index.rst (renamed from Documentation/translations/zh_CN/arch.rst) | 8 | ||||
| -rw-r--r-- | Documentation/translations/zh_CN/arch/openrisc/index.rst (renamed from Documentation/translations/zh_CN/openrisc/index.rst) | 4 | ||||
| -rw-r--r-- | Documentation/translations/zh_CN/arch/openrisc/openrisc_port.rst (renamed from Documentation/translations/zh_CN/openrisc/openrisc_port.rst) | 4 | ||||
| -rw-r--r-- | Documentation/translations/zh_CN/arch/openrisc/todo.rst (renamed from Documentation/translations/zh_CN/openrisc/todo.rst) | 4 | ||||
| -rw-r--r-- | Documentation/translations/zh_CN/arch/parisc/debugging.rst (renamed from Documentation/translations/zh_CN/parisc/debugging.rst) | 4 | ||||
| -rw-r--r-- | Documentation/translations/zh_CN/arch/parisc/index.rst (renamed from Documentation/translations/zh_CN/parisc/index.rst) | 4 | ||||
| -rw-r--r-- | Documentation/translations/zh_CN/arch/parisc/registers.rst (renamed from Documentation/translations/zh_CN/parisc/registers.rst) | 4 | ||||
| -rw-r--r-- | Documentation/translations/zh_CN/index.rst | 2 | ||||
| -rw-r--r-- | Documentation/userspace-api/ELF.rst | 34 | ||||
| -rw-r--r-- | Documentation/userspace-api/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/userspace-api/media/v4l/pixfmt-rgb.rst | 5 | ||||
| -rw-r--r-- | Documentation/virt/kvm/api.rst | 2 |
154 files changed, 2547 insertions, 563 deletions
diff --git a/Documentation/admin-guide/hw-vuln/mds.rst b/Documentation/admin-guide/hw-vuln/mds.rst index f491de74ea79..48ca0bd85604 100644 --- a/Documentation/admin-guide/hw-vuln/mds.rst +++ b/Documentation/admin-guide/hw-vuln/mds.rst @@ -58,7 +58,7 @@ Because the buffers are potentially shared between Hyper-Threads cross Hyper-Thread attacks are possible. Deeper technical information is available in the MDS specific x86 -architecture section: :ref:`Documentation/x86/mds.rst <mds>`. +architecture section: :ref:`Documentation/arch/x86/mds.rst <mds>`. Attack scenarios diff --git a/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst b/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst index 76673affd917..014167ef8dd1 100644 --- a/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst +++ b/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst @@ -63,7 +63,7 @@ attacker needs to begin a TSX transaction and raise an asynchronous abort which in turn potentially leaks data stored in the buffers. More detailed technical information is available in the TAA specific x86 -architecture section: :ref:`Documentation/x86/tsx_async_abort.rst <tsx_async_abort>`. +architecture section: :ref:`Documentation/arch/x86/tsx_async_abort.rst <tsx_async_abort>`. Attack scenarios diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 09a563bbe3e7..43ea35613dfc 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -36,6 +36,7 @@ problems and bugs in particular. reporting-issues reporting-regressions + quickly-build-trimmed-linux bug-hunting bug-bisect tainted-kernels diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst index 6ae5f129fbca..1ba8f2a44aac 100644 --- a/Documentation/admin-guide/kernel-parameters.rst +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -132,7 +132,7 @@ parameter is applicable:: LOOP Loopback device support is enabled. M68k M68k architecture is enabled. These options have more detailed description inside of - Documentation/m68k/kernel-options.rst. + Documentation/arch/m68k/kernel-options.rst. MDA MDA console support is enabled. MIPS MIPS architecture is enabled. MOUSE Appropriate mouse support is enabled. @@ -178,7 +178,7 @@ parameter is applicable:: X86-32 X86-32, aka i386 architecture is enabled. X86-64 X86-64 architecture is enabled. More X86-64 boot options can be found in - Documentation/x86/x86_64/boot-options.rst. + Documentation/arch/x86/x86_64/boot-options.rst. X86 Either 32-bit or 64-bit x86 (same as X86-32+X86-64) X86_UV SGI UV support is enabled. XEN Xen support is enabled @@ -193,10 +193,10 @@ In addition, the following text indicates that the option:: Parameters denoted with BOOT are actually interpreted by the boot loader, and have no meaning to the kernel directly. Do not modify the syntax of boot loader parameters without extreme -need or coordination with <Documentation/x86/boot.rst>. +need or coordination with <Documentation/arch/x86/boot.rst>. There are also arch-specific kernel-parameters not documented here. -See for example <Documentation/x86/x86_64/boot-options.rst>. +See for example <Documentation/arch/x86/x86_64/boot-options.rst>. Note that ALL kernel parameters listed below are CASE SENSITIVE, and that a trailing = on the name of any parameter states that that parameter will diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 7016cb12dc4e..10e2e5c3ff0b 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -929,9 +929,6 @@ debug_objects [KNL] Enable object debugging - no_debug_objects - [KNL] Disable object debugging - debug_guardpage_minorder= [KNL] When CONFIG_DEBUG_PAGEALLOC is set, this parameter allows control of the order of pages that will @@ -2976,7 +2973,7 @@ mce [X86-32] Machine Check Exception - mce=option [X86-64] See Documentation/x86/x86_64/boot-options.rst + mce=option [X86-64] See Documentation/arch/x86/x86_64/boot-options.rst md= [HW] RAID subsystems devices and level See Documentation/admin-guide/md.rst. @@ -3184,9 +3181,6 @@ deep - Suspend-To-RAM or equivalent (if supported) See Documentation/admin-guide/pm/sleep-states.rst. - meye.*= [HW] Set MotionEye Camera parameters - See Documentation/admin-guide/media/meye.rst. - mfgpt_irq= [IA-32] Specify the IRQ to use for the Multi-Function General Purpose Timers on AMD Geode platforms. @@ -3428,14 +3422,13 @@ 1 to enable accounting Default value is 0. - nfsaddrs= [NFS] Deprecated. Use ip= instead. - See Documentation/admin-guide/nfs/nfsroot.rst. - - nfsroot= [NFS] nfs root filesystem for disk-less boxes. - See Documentation/admin-guide/nfs/nfsroot.rst. + nfs.cache_getent= + [NFS] sets the pathname to the program which is used + to update the NFS client cache entries. - nfsrootdebug [NFS] enable nfsroot debugging messages. - See Documentation/admin-guide/nfs/nfsroot.rst. + nfs.cache_getent_timeout= + [NFS] sets the timeout after which an attempt to + update a cache entry is deemed to have failed. nfs.callback_nr_threads= [NFSv4] set the total number of threads that the @@ -3446,18 +3439,6 @@ [NFS] set the TCP port on which the NFSv4 callback channel should listen. - nfs.cache_getent= - [NFS] sets the pathname to the program which is used - to update the NFS client cache entries. - - nfs.cache_getent_timeout= - [NFS] sets the timeout after which an attempt to - update a cache entry is deemed to have failed. - - nfs.idmap_cache_timeout= - [NFS] set the maximum lifetime for idmapper cache - entries. - nfs.enable_ino64= [NFS] enable 64-bit inode numbers. If zero, the NFS client will fake up a 32-bit inode @@ -3465,6 +3446,10 @@ of returning the full 64-bit number. The default is to return 64-bit inode numbers. + nfs.idmap_cache_timeout= + [NFS] set the maximum lifetime for idmapper cache + entries. + nfs.max_session_cb_slots= [NFSv4.1] Sets the maximum number of session slots the client will assign to the callback @@ -3492,21 +3477,14 @@ will be autodetected by the client, and it will fall back to using the idmapper. To turn off this behaviour, set the value to '0'. + nfs.nfs4_unique_id= [NFS4] Specify an additional fixed unique ident- ification string that NFSv4 clients can insert into their nfs_client_id4 string. This is typically a UUID that is generated at system install time. - nfs.send_implementation_id = - [NFSv4.1] Send client implementation identification - information in exchange_id requests. - If zero, no implementation identification information - will be sent. - The default is to send the implementation identification - information. - - nfs.recover_lost_locks = + nfs.recover_lost_locks= [NFSv4] Attempt to recover locks that were lost due to a lease timeout on the server. Please note that doing this risks data corruption, since there are @@ -3518,7 +3496,15 @@ The default parameter value of '0' causes the kernel not to attempt recovery of lost locks. - nfs4.layoutstats_timer = + nfs.send_implementation_id= + [NFSv4.1] Send client implementation identification + information in exchange_id requests. + If zero, no implementation identification information + will be sent. + The default is to send the implementation identification + information. + + nfs4.layoutstats_timer= [NFSv4.2] Change the rate at which the kernel sends layoutstats to the pNFS metadata server. @@ -3527,12 +3513,19 @@ driver. A non-zero value sets the minimum interval in seconds between layoutstats transmissions. - nfsd.inter_copy_offload_enable = + nfsd.inter_copy_offload_enable= [NFSv4.2] When set to 1, the server will support server-to-server copies for which this server is the destination of the copy. - nfsd.nfsd4_ssc_umount_timeout = + nfsd.nfs4_disable_idmapping= + [NFSv4] When set to the default of '1', the NFSv4 + server will return only numeric uids and gids to + clients using auth_sys, and will accept numeric uids + and gids from such clients. This is intended to ease + migration from NFSv2/v3. + + nfsd.nfsd4_ssc_umount_timeout= [NFSv4.2] When used as the destination of a server-to-server copy, knfsd temporarily mounts the source server. It caches the mount in case @@ -3540,13 +3533,14 @@ used for the number of milliseconds specified by this parameter. - nfsd.nfs4_disable_idmapping= - [NFSv4] When set to the default of '1', the NFSv4 - server will return only numeric uids and gids to - clients using auth_sys, and will accept numeric uids - and gids from such clients. This is intended to ease - migration from NFSv2/v3. + nfsaddrs= [NFS] Deprecated. Use ip= instead. + See Documentation/admin-guide/nfs/nfsroot.rst. + + nfsroot= [NFS] nfs root filesystem for disk-less boxes. + See Documentation/admin-guide/nfs/nfsroot.rst. + nfsrootdebug [NFS] enable nfsroot debugging messages. + See Documentation/admin-guide/nfs/nfsroot.rst. nmi_backtrace.backtrace_idle [KNL] Dump stacks even of idle CPUs in response to an @@ -3579,7 +3573,21 @@ no5lvl [X86-64] Disable 5-level paging mode. Forces kernel to use 4-level paging instead. - nofsgsbase [X86] Disables FSGSBASE instructions. + noaliencache [MM, NUMA, SLAB] Disables the allocation of alien + caches in the slab allocator. Saves per-node memory, + but will impact performance. + + noalign [KNL,ARM] + + noaltinstr [S390] Disables alternative instructions patching + (CPU alternatives feature). + + noapic [SMP,APIC] Tells the kernel to not make use of any + IOAPICs that may be present in the system. + + noautogroup Disable scheduler automatic task group creation. + + nocache [ARM] no_console_suspend [HW] Never suspend the console @@ -3596,32 +3604,8 @@ /sys/module/printk/parameters/console_suspend) to turn on/off it dynamically. - novmcoredd [KNL,KDUMP] - Disable device dump. Device dump allows drivers to - append dump data to vmcore so you can collect driver - specified debug info. Drivers can append the data - without any limit and this data is stored in memory, - so this may cause significant memory stress. Disabling - device dump can help save memory but the driver debug - data will be no longer available. This parameter - is only available when CONFIG_PROC_VMCORE_DEVICE_DUMP - is set. - - noaliencache [MM, NUMA, SLAB] Disables the allocation of alien - caches in the slab allocator. Saves per-node memory, - but will impact performance. - - noalign [KNL,ARM] - - noaltinstr [S390] Disables alternative instructions patching - (CPU alternatives feature). - - noapic [SMP,APIC] Tells the kernel to not make use of any - IOAPICs that may be present in the system. - - noautogroup Disable scheduler automatic task group creation. - - nocache [ARM] + no_debug_objects + [KNL] Disable object debugging nodsp [SH] Disable hardware DSP at boot time. @@ -3631,14 +3615,6 @@ noexec [IA-64] - nosmap [PPC] - Disable SMAP (Supervisor Mode Access Prevention) - even if it is supported by processor. - - nosmep [PPC64s] - Disable SMEP (Supervisor Mode Execution Prevention) - even if it is supported by processor. - noexec32 [X86-64] This affects only 32-bit executables. noexec32=on: enable non-executable mappings (default) @@ -3646,74 +3622,18 @@ noexec32=off: disable non-executable mappings read implies executable mappings + no_file_caps Tells the kernel not to honor file capabilities. The + only way then for a file to be executed with privilege + is to be setuid root or executed by root. + nofpu [MIPS,SH] Disable hardware FPU at boot time. + nofsgsbase [X86] Disables FSGSBASE instructions. + nofxsr [BUGS=X86-32] Disables x86 floating point extended register save and restore. The kernel will only save legacy floating-point registers on task switch. - nohugeiomap [KNL,X86,PPC,ARM64] Disable kernel huge I/O mappings. - - nohugevmalloc [KNL,X86,PPC,ARM64] Disable kernel huge vmalloc mappings. - - nosmt [KNL,S390] Disable symmetric multithreading (SMT). - Equivalent to smt=1. - - [KNL,X86] Disable symmetric multithreading (SMT). - nosmt=force: Force disable SMT, cannot be undone - via the sysfs control file. - - nospectre_v1 [X86,PPC] Disable mitigations for Spectre Variant 1 - (bounds check bypass). With this option data leaks are - possible in the system. - - nospectre_v2 [X86,PPC_E500,ARM64] Disable all mitigations for - the Spectre variant 2 (indirect branch prediction) - vulnerability. System may allow data leaks with this - option. - - nospectre_bhb [ARM64] Disable all mitigations for Spectre-BHB (branch - history injection) vulnerability. System may allow data leaks - with this option. - - nospec_store_bypass_disable - [HW] Disable all mitigations for the Speculative Store Bypass vulnerability - - no_uaccess_flush - [PPC] Don't flush the L1-D cache after accessing user data. - - noxsave [BUGS=X86] Disables x86 extended register state save - and restore using xsave. The kernel will fallback to - enabling legacy floating-point and sse state. - - noxsaveopt [X86] Disables xsaveopt used in saving x86 extended - register states. The kernel will fall back to use - xsave to save the states. By using this parameter, - performance of saving the states is degraded because - xsave doesn't support modified optimization while - xsaveopt supports it on xsaveopt enabled systems. - - noxsaves [X86] Disables xsaves and xrstors used in saving and - restoring x86 extended register state in compacted - form of xsave area. The kernel will fall back to use - xsaveopt and xrstor to save and restore the states - in standard form of xsave area. By using this - parameter, xsave area per process might occupy more - memory on xsaves enabled systems. - - nohlt [ARM,ARM64,MICROBLAZE,SH] Forces the kernel to busy wait - in do_idle() and not use the arch_cpu_idle() - implementation; requires CONFIG_GENERIC_IDLE_POLL_SETUP - to be effective. This is useful on platforms where the - sleep(SH) or wfi(ARM,ARM64) instructions do not work - correctly or when doing power measurements to evaluate - the impact of the sleep instructions. This is also - useful when using JTAG debugger. - - no_file_caps Tells the kernel not to honor file capabilities. The - only way then for a file to be executed with privilege - is to be setuid root or executed by root. - nohalt [IA-64] Tells the kernel not to use the power saving function PAL_HALT_LIGHT when idle. This increases power-consumption. On the positive side, it reduces @@ -3737,6 +3657,19 @@ nohibernate [HIBERNATION] Disable hibernation and resume. + nohlt [ARM,ARM64,MICROBLAZE,SH] Forces the kernel to busy wait + in do_idle() and not use the arch_cpu_idle() + implementation; requires CONFIG_GENERIC_IDLE_POLL_SETUP + to be effective. This is useful on platforms where the + sleep(SH) or wfi(ARM,ARM64) instructions do not work + correctly or when doing power measurements to evaluate + the impact of the sleep instructions. This is also + useful when using JTAG debugger. + + nohugeiomap [KNL,X86,PPC,ARM64] Disable kernel huge I/O mappings. + + nohugevmalloc [KNL,X86,PPC,ARM64] Disable kernel huge vmalloc mappings. + nohz= [KNL] Boottime enable/disable dynamic ticks Valid arguments: on, off Default: on @@ -3754,16 +3687,6 @@ Note that this argument takes precedence over the CONFIG_RCU_NOCB_CPU_DEFAULT_ALL option. - noiotrap [SH] Disables trapped I/O port accesses. - - noirqdebug [X86-32] Disables the code which attempts to detect and - disable unhandled interrupt sources. - - no_timer_check [X86,APIC] Disables the code which tests for - broken timer IRQ sources. - - noisapnp [ISAPNP] Disables ISA PnP code. - noinitrd [RAM] Tells the kernel not to load any configured initial RAM disk. @@ -3775,6 +3698,13 @@ noinvpcid [X86] Disable the INVPCID cpu feature. + noiotrap [SH] Disables trapped I/O port accesses. + + noirqdebug [X86-32] Disables the code which attempts to detect and + disable unhandled interrupt sources. + + noisapnp [ISAPNP] Disables ISA PnP code. + nojitter [IA-64] Disables jitter checking for ITC timers. nokaslr [KNL] @@ -3782,18 +3712,10 @@ kernel and module base offset ASLR (Address Space Layout Randomization). - no-kvmclock [X86,KVM] Disable paravirtualized KVM clock driver - no-kvmapf [X86,KVM] Disable paravirtualized asynchronous page fault handling. - no-vmw-sched-clock - [X86,PV_OPS] Disable paravirtualized VMware scheduler - clock and use the default one. - - no-steal-acc [X86,PV_OPS,ARM64,PPC/PSERIES] Disable paravirtualized - steal time accounting. steal time is computed, but - won't influence scheduler behaviour + no-kvmclock [X86,KVM] Disable paravirtualized KVM clock driver nolapic [X86-32,APIC] Do not enable or use the local APIC. @@ -3806,10 +3728,6 @@ nomfgpt [X86-32] Disable Multi-Function General Purpose Timer usage (for AMD Geode machines). - nonmi_ipi [X86] Disable using NMI IPIs during panic/reboot to - shutdown the other cpus. Instead use the REBOOT_VECTOR - irq. - nomodeset Disable kernel modesetting. Most systems' firmware sets up a display mode and provides framebuffer memory for output. With nomodeset, DRM and fbdev drivers will @@ -3822,6 +3740,10 @@ nomodule Disable module load + nonmi_ipi [X86] Disable using NMI IPIs during panic/reboot to + shutdown the other cpus. Instead use the REBOOT_VECTOR + irq. + nopat [X86] Disable PAT (page attribute table extension of pagetables) support. @@ -3830,6 +3752,9 @@ nopku [X86] Disable Memory Protection Keys CPU feature found in some Intel CPUs. + nopti [X86-64] + Equivalent to pti=off + nopv= [X86,XEN,KVM,HYPER_V,VMWARE] Disables the PV optimizations forcing the guest to run as generic guest with no PV drivers. Currently support @@ -3849,21 +3774,77 @@ noresume [SWSUSP] Disables resume and restores original swap space. + nosbagart [IA-64] + no-scroll [VGA] Disables scrollback. This is required for the Braillex ib80-piezo Braille reader made by F.H. Papenmeier (Germany). - nosbagart [IA-64] - nosgx [X86-64,SGX] Disables Intel SGX kernel support. + nosmap [PPC] + Disable SMAP (Supervisor Mode Access Prevention) + even if it is supported by processor. + + nosmep [PPC64s] + Disable SMEP (Supervisor Mode Execution Prevention) + even if it is supported by processor. + nosmp [SMP] Tells an SMP kernel to act as a UP kernel, and disable the IO APIC. legacy for "maxcpus=0". + nosmt [KNL,S390] Disable symmetric multithreading (SMT). + Equivalent to smt=1. + + [KNL,X86] Disable symmetric multithreading (SMT). + nosmt=force: Force disable SMT, cannot be undone + via the sysfs control file. + nosoftlockup [KNL] Disable the soft-lockup detector. + nospec_store_bypass_disable + [HW] Disable all mitigations for the Speculative Store Bypass vulnerability + + nospectre_bhb [ARM64] Disable all mitigations for Spectre-BHB (branch + history injection) vulnerability. System may allow data leaks + with this option. + + nospectre_v1 [X86,PPC] Disable mitigations for Spectre Variant 1 + (bounds check bypass). With this option data leaks are + possible in the system. + + nospectre_v2 [X86,PPC_E500,ARM64] Disable all mitigations for + the Spectre variant 2 (indirect branch prediction) + vulnerability. System may allow data leaks with this + option. + + no-steal-acc [X86,PV_OPS,ARM64,PPC/PSERIES] Disable paravirtualized + steal time accounting. steal time is computed, but + won't influence scheduler behaviour + nosync [HW,M68K] Disables sync negotiation for all devices. + no_timer_check [X86,APIC] Disables the code which tests for + broken timer IRQ sources. + + no_uaccess_flush + [PPC] Don't flush the L1-D cache after accessing user data. + + novmcoredd [KNL,KDUMP] + Disable device dump. Device dump allows drivers to + append dump data to vmcore so you can collect driver + specified debug info. Drivers can append the data + without any limit and this data is stored in memory, + so this may cause significant memory stress. Disabling + device dump can help save memory but the driver debug + data will be no longer available. This parameter + is only available when CONFIG_PROC_VMCORE_DEVICE_DUMP + is set. + + no-vmw-sched-clock + [X86,PV_OPS] Disable paravirtualized VMware scheduler + clock and use the default one. + nowatchdog [KNL] Disable both lockup detectors, i.e. soft-lockup and NMI watchdog (hard-lockup). @@ -3875,6 +3856,25 @@ LEGACY_XAPIC_DISABLED bit set in the IA32_XAPIC_DISABLE_STATUS MSR. + noxsave [BUGS=X86] Disables x86 extended register state save + and restore using xsave. The kernel will fallback to + enabling legacy floating-point and sse state. + + noxsaveopt [X86] Disables xsaveopt used in saving x86 extended + register states. The kernel will fall back to use + xsave to save the states. By using this parameter, + performance of saving the states is degraded because + xsave doesn't support modified optimization while + xsaveopt supports it on xsaveopt enabled systems. + + noxsaves [X86] Disables xsaves and xrstors used in saving and + restoring x86 extended register state in compacted + form of xsave area. The kernel will fall back to use + xsaveopt and xrstor to save and restore the states + in standard form of xsave area. By using this + parameter, xsave area per process might occupy more + memory on xsaves enabled systems. + nps_mtm_hs_ctr= [KNL,ARC] This parameter sets the maximum duration, in cycles, each HW thread of the CTOP can run @@ -4410,7 +4410,7 @@ and performance comparison. pirq= [SMP,APIC] Manual mp-table setup - See Documentation/x86/i386/IO-APIC.rst. + See Documentation/arch/x86/i386/IO-APIC.rst. plip= [PPT,NET] Parallel port network link Format: { parport<nr> | timid | 0 } @@ -4582,9 +4582,6 @@ Not specifying this option is equivalent to pti=auto. - nopti [X86-64] - Equivalent to pti=off - pty.legacy_count= [KNL] Number of legacy pty's. Overwrites compiled-in default number. @@ -5591,7 +5588,7 @@ serialnumber [BUGS=X86-32] - sev=option[,option...] [X86-64] See Documentation/x86/x86_64/boot-options.rst + sev=option[,option...] [X86-64] See Documentation/arch/x86/x86_64/boot-options.rst shapers= [NET] Maximal number of shapers. @@ -6770,7 +6767,7 @@ Can be used multiple times for multiple devices. vga= [BOOT,X86-32] Select a particular video mode - See Documentation/x86/boot.rst and + See Documentation/arch/x86/boot.rst and Documentation/admin-guide/svga.rst. Use vga=ask for menu. This is actually a boot loader parameter; the value is diff --git a/Documentation/admin-guide/quickly-build-trimmed-linux.rst b/Documentation/admin-guide/quickly-build-trimmed-linux.rst new file mode 100644 index 000000000000..ff4f4cc8522b --- /dev/null +++ b/Documentation/admin-guide/quickly-build-trimmed-linux.rst @@ -0,0 +1,1092 @@ +.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0) +.. [see the bottom of this file for redistribution information] + +=========================================== +How to quickly build a trimmed Linux kernel +=========================================== + +This guide explains how to swiftly build Linux kernels that are ideal for +testing purposes, but perfectly fine for day-to-day use, too. + +The essence of the process (aka 'TL;DR') +======================================== + +*[If you are new to compiling Linux, ignore this TLDR and head over to the next +section below: it contains a step-by-step guide, which is more detailed, but +still brief and easy to follow; that guide and its accompanying reference +section also mention alternatives, pitfalls, and additional aspects, all of +which might be relevant for you.]* + +If your system uses techniques like Secure Boot, prepare it to permit starting +self-compiled Linux kernels; install compilers and everything else needed for +building Linux; make sure to have 12 Gigabyte free space in your home directory. +Now run the following commands to download fresh Linux mainline sources, which +you then use to configure, build and install your own kernel:: + + git clone --depth 1 -b master \ + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git ~/linux/ + cd ~/linux/ + # Hint: if you want to apply patches, do it at this point. See below for details. + # Hint: it's recommended to tag your build at this point. See below for details. + yes "" | make localmodconfig + # Hint: at this point you might want to adjust the build configuration; you'll + # have to, if you are running Debian. See below for details. + make -j $(nproc --all) + # Note: on many commodity distributions the next command suffices, but on Arch + # Linux, its derivatives, and some others it does not. See below for details. + command -v installkernel && sudo make modules_install install + reboot + +If you later want to build a newer mainline snapshot, use these commands:: + + cd ~/linux/ + git fetch --depth 1 origin + # Note: the next command will discard any changes you did to the code: + git checkout --force --detach origin/master + # Reminder: if you want to (re)apply patches, do it at this point. + # Reminder: you might want to add or modify a build tag at this point. + make olddefconfig + make -j $(nproc --all) + # Reminder: the next command on some distributions does not suffice. + command -v installkernel && sudo make modules_install install + reboot + +Step-by-step guide +================== + +Compiling your own Linux kernel is easy in principle. There are various ways to +do it. Which of them actually work and is the best depends on the circumstances. + +This guide describes a way perfectly suited for those who want to quickly +install Linux from sources without being bothered by complicated details; the +goal is to cover everything typically needed on mainstream Linux distributions +running on commodity PC or server hardware. + +The described approach is great for testing purposes, for example to try a +proposed fix or to check if a problem was already fixed in the latest codebase. +Nonetheless, kernels built this way are also totally fine for day-to-day use +while at the same time being easy to keep up to date. + +The following steps describe the important aspects of the process; a +comprehensive reference section later explains each of them in more detail. It +sometimes also describes alternative approaches, pitfalls, as well as errors +that might occur at a particular point -- and how to then get things rolling +again. + +.. + Note: if you see this note, you are reading the text's source file. You + might want to switch to a rendered version, as it makes it a lot easier to + quickly look something up in the reference section and afterwards jump back + to where you left off. Find a the latest rendered version here: + https://docs.kernel.org/admin-guide/quickly-build-trimmed-linux.html + +.. _backup_sbs: + + * Create a fresh backup and put system repair and restore tools at hand, just + to be prepared for the unlikely case of something going sideways. + + [:ref:`details<backup>`] + +.. _secureboot_sbs: + + * On platforms with 'Secure Boot' or similar techniques, prepare everything to + ensure the system will permit your self-compiled kernel to boot later. The + quickest and easiest way to achieve this on commodity x86 systems is to + disable such techniques in the BIOS setup utility; alternatively, remove + their restrictions through a process initiated by + ``mokutil --disable-validation``. + + [:ref:`details<secureboot>`] + +.. _buildrequires_sbs: + + * Install all software required to build a Linux kernel. Often you will need: + 'bc', 'binutils' ('ld' et al.), 'bison', 'flex', 'gcc', 'git', 'openssl', + 'pahole', 'perl', and the development headers for 'libelf' and 'openssl'. The + reference section shows how to quickly install those on various popular Linux + distributions. + + [:ref:`details<buildrequires>`] + +.. _diskspace_sbs: + + * Ensure to have enough free space for building and installing Linux. For the + latter 150 Megabyte in /lib/ and 100 in /boot/ are a safe bet. For storing + sources and build artifacts 12 Gigabyte in your home directory should + typically suffice. If you have less available, be sure to check the reference + section for the step that explains adjusting your kernels build + configuration: it mentions a trick that reduce the amount of required space + in /home/ to around 4 Gigabyte. + + [:ref:`details<diskspace>`] + +.. _sources_sbs: + + * Retrieve the sources of the Linux version you intend to build; then change + into the directory holding them, as all further commands in this guide are + meant to be executed from there. + + *[Note: the following paragraphs describe how to retrieve the sources by + partially cloning the Linux stable git repository. This is called a shallow + clone. The reference section explains two alternatives:* :ref:`packaged + archives<sources_archive>` *and* :ref:`a full git clone<sources_full>` *; + prefer the latter, if downloading a lot of data does not bother you, as that + will avoid some* :ref:`peculiar characteristics of shallow clones the + reference section explains<sources_shallow>` *.]* + + First, execute the following command to retrieve a fresh mainline codebase:: + + git clone --no-checkout --depth 1 -b master \ + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git ~/linux/ + cd ~/linux/ + + If you want to access recent mainline releases and pre-releases, deepen you + clone's history to the oldest mainline version you are interested in:: + + git fetch --shallow-exclude=v6.0 origin + + In case you want to access a stable/longterm release (say v6.1.5), simply add + the branch holding that series; afterwards fetch the history at least up to + the mainline version that started the series (v6.1):: + + git remote set-branches --add origin linux-6.1.y + git fetch --shallow-exclude=v6.0 origin + + Now checkout the code you are interested in. If you just performed the + initial clone, you will be able to check out a fresh mainline codebase, which + is ideal for checking whether developers already fixed an issue:: + + git checkout --detach origin/master + + If you deepened your clone, you instead of ``origin/master`` can specify the + version you deepened to (``v6.0`` above); later releases like ``v6.1`` and + pre-release like ``v6.2-rc1`` will work, too. Stable or longterm versions + like ``v6.1.5`` work just the same, if you added the appropriate + stable/longterm branch as described. + + [:ref:`details<sources>`] + +.. _patching_sbs: + + * In case you want to apply a kernel patch, do so now. Often a command like + this will do the trick:: + + patch -p1 < ../proposed-fix.patch + + If the ``-p1`` is actually needed, depends on how the patch was created; in + case it does not apply thus try without it. + + If you cloned the sources with git and anything goes sideways, run ``git + reset --hard`` to undo any changes to the sources. + + [:ref:`details<patching>`] + +.. _tagging_sbs: + + * If you patched your kernel or have one of the same version installed already, + better add a unique tag to the one you are about to build:: + + echo "-proposed_fix" > localversion + + Running ``uname -r`` under your kernel later will then print something like + '6.1-rc4-proposed_fix'. + + [:ref:`details<tagging>`] + + .. _configuration_sbs: + + * Create the build configuration for your kernel based on an existing + configuration. + + If you already prepared such a '.config' file yourself, copy it to + ~/linux/ and run ``make olddefconfig``. + + Use the same command, if your distribution or somebody else already tailored + your running kernel to your or your hardware's needs: the make target + 'olddefconfig' will then try to use that kernel's .config as base. + + Using this make target is fine for everybody else, too -- but you often can + save a lot of time by using this command instead:: + + yes "" | make localmodconfig + + This will try to pick your distribution's kernel as base, but then disable + modules for any features apparently superfluous for your setup. This will + reduce the compile time enormously, especially if you are running an + universal kernel from a commodity Linux distribution. + + There is a catch: the make target 'localmodconfig' will disable kernel + features you have not directly or indirectly through some program utilized + since you booted the system. You can reduce or nearly eliminate that risk by + using tricks outlined in the reference section; for quick testing purposes + that risk is often negligible, but it is an aspect you want to keep in mind + in case your kernel behaves oddly. + + [:ref:`details<configuration>`] + +.. _configmods_sbs: + + * Check if you might want to or have to adjust some kernel configuration + options: + + * Evaluate how you want to handle debug symbols. Enable them, if you later + might need to decode a stack trace found for example in a 'panic', 'Oops', + 'warning', or 'BUG'; on the other hand disable them, if you are short on + storage space or prefer a smaller kernel binary. See the reference section + for details on how to do either. If neither applies, it will likely be fine + to simply not bother with this. [:ref:`details<configmods_debugsymbols>`] + + * Are you running Debian? Then to avoid known problems by performing + additional adjustments explained in the reference section. + [:ref:`details<configmods_distros>`]. + + * If you want to influence the other aspects of the configuration, do so now + by using make targets like 'menuconfig' or 'xconfig'. + [:ref:`details<configmods_individual>`]. + +.. _build_sbs: + + * Build the image and the modules of your kernel:: + + make -j $(nproc --all) + + If you want your kernel packaged up as deb, rpm, or tar file, see the + reference section for alternatives. + + [:ref:`details<build>`] + +.. _install_sbs: + + * Now install your kernel:: + + command -v installkernel && sudo make modules_install install + + Often all left for you to do afterwards is a ``reboot``, as many commodity + Linux distributions will then create an initramfs (also known as initrd) and + an entry for your kernel in your bootloader's configuration; but on some + distributions you have to take care of these two steps manually for reasons + the reference section explains. + + On a few distributions like Arch Linux and its derivatives the above command + does nothing at all; in that case you have to manually install your kernel, + as outlined in the reference section. + + [:ref:`details<install>`] + +.. _another_sbs: + + * To later build another kernel you need similar steps, but sometimes slightly + different commands. + + First, switch back into the sources tree:: + + cd ~/linux/ + + In case you want to build a version from a stable/longterm series you have + not used yet (say 6.2.y), tell git to track it:: + + git remote set-branches --add origin linux-6.2.y + + Now fetch the latest upstream changes; you again need to specify the earliest + version you care about, as git otherwise might retrieve the entire commit + history:: + + git fetch --shallow-exclude=v6.1 origin + + If you modified the sources (for example by applying a patch), you now need + to discard those modifications; that's because git otherwise will not be able + to switch to the sources of another version due to potential conflicting + changes:: + + git reset --hard + + Now checkout the version you are interested in, as explained above:: + + git checkout --detach origin/master + + At this point you might want to patch the sources again or set/modify a build + tag, as explained earlier; afterwards adjust the build configuration to the + new codebase and build your next kernel:: + + # reminder: if you want to apply patches, do it at this point + # reminder: you might want to update your build tag at this point + make olddefconfig + make -j $(nproc --all) + + Install the kernel as outlined above:: + + command -v installkernel && sudo make modules_install install + + [:ref:`details<another>`] + +.. _uninstall_sbs: + + * Your kernel is easy to remove later, as its parts are only stored in two + places and clearly identifiable by the kernel's release name. Just ensure to + not delete the kernel you are running, as that might render your system + unbootable. + + Start by deleting the directory holding your kernel's modules, which is named + after its release name -- '6.0.1-foobar' in the following example:: + + sudo rm -rf /lib/modules/6.0.1-foobar + + Now try the following command, which on some distributions will delete all + other kernel files installed while also removing the kernel's entry from the + bootloader configuration:: + + command -v kernel-install && sudo kernel-install -v remove 6.0.1-foobar + + If that command does not output anything or fails, see the reference section; + do the same if any files named '*6.0.1-foobar*' remain in /boot/. + + [:ref:`details<uninstall>`] + +.. _submit_improvements: + +Did you run into trouble following any of the above steps that is not cleared up +by the reference section below? Or do you have ideas how to improve the text? +Then please take a moment of your time and let the maintainer of this document +know by email (Thorsten Leemhuis <linux@leemhuis.info>), ideally while CCing the +Linux docs mailing list (linux-doc@vger.kernel.org). Such feedback is vital to +improve this document further, which is in everybody's interest, as it will +enable more people to master the task described here. + +Reference section for the step-by-step guide +============================================ + +This section holds additional information for each of the steps in the above +guide. + +.. _backup: + +Prepare for emergencies +----------------------- + + *Create a fresh backup and put system repair and restore tools at hand* + [:ref:`... <backup_sbs>`] + +Remember, you are dealing with computers, which sometimes do unexpected things +-- especially if you fiddle with crucial parts like the kernel of an operating +system. That's what you are about to do in this process. Hence, better prepare +for something going sideways, even if that should not happen. + +[:ref:`back to step-by-step guide <backup_sbs>`] + +.. _secureboot: + +Dealing with techniques like Secure Boot +---------------------------------------- + + *On platforms with 'Secure Boot' or similar techniques, prepare everything to + ensure the system will permit your self-compiled kernel to boot later.* + [:ref:`... <secureboot_sbs>`] + +Many modern systems allow only certain operating systems to start; they thus by +default will reject booting self-compiled kernels. + +You ideally deal with this by making your platform trust your self-built kernels +with the help of a certificate and signing. How to do that is not described +here, as it requires various steps that would take the text too far away from +its purpose; 'Documentation/admin-guide/module-signing.rst' and various web +sides already explain this in more detail. + +Temporarily disabling solutions like Secure Boot is another way to make your own +Linux boot. On commodity x86 systems it is possible to do this in the BIOS Setup +utility; the steps to do so are not described here, as they greatly vary between +machines. + +On mainstream x86 Linux distributions there is a third and universal option: +disable all Secure Boot restrictions for your Linux environment. You can +initiate this process by running ``mokutil --disable-validation``; this will +tell you to create a one-time password, which is safe to write down. Now +restart; right after your BIOS performed all self-tests the bootloader Shim will +show a blue box with a message 'Press any key to perform MOK management'. Hit +some key before the countdown exposes. This will open a menu and choose 'Change +Secure Boot state' there. Shim's 'MokManager' will now ask you to enter three +randomly chosen characters from the one-time password specified earlier. Once +you provided them, confirm that you really want to disable the validation. +Afterwards, permit MokManager to reboot the machine. + +[:ref:`back to step-by-step guide <secureboot_sbs>`] + +.. _buildrequires: + +Install build requirements +-------------------------- + + *Install all software required to build a Linux kernel.* + [:ref:`...<buildrequires_sbs>`] + +The kernel is pretty stand-alone, but besides tools like the compiler you will +sometimes need a few libraries to build one. How to install everything needed +depends on your Linux distribution and the configuration of the kernel you are +about to build. + +Here are a few examples what you typically need on some mainstream +distributions: + + * Debian, Ubuntu, and derivatives:: + + sudo apt install bc binutils bison dwarves flex gcc git make openssl \ + pahole perl-base libssl-dev libelf-dev + + * Fedora and derivatives:: + + sudo dnf install binutils /usr/include/{libelf.h,openssl/pkcs7.h} \ + /usr/bin/{bc,bison,flex,gcc,git,openssl,make,perl,pahole} + + * openSUSE and derivatives:: + + sudo zypper install bc binutils bison dwarves flex gcc git make perl-base \ + openssl openssl-devel libelf-dev + +In case you wonder why these lists include openssl and its development headers: +they are needed for the Secure Boot support, which many distributions enable in +their kernel configuration for x86 machines. + +Sometimes you will need tools for compression formats like bzip2, gzip, lz4, +lzma, lzo, xz, or zstd as well. + +You might need additional libraries and their development headers in case you +perform tasks not covered in this guide. For example, zlib will be needed when +building kernel tools from the tools/ directory; adjusting the build +configuration with make targets like 'menuconfig' or 'xconfig' will require +development headers for ncurses or Qt5. + +[:ref:`back to step-by-step guide <buildrequires_sbs>`] + +.. _diskspace: + +Space requirements +------------------ + + *Ensure to have enough free space for building and installing Linux.* + [:ref:`... <diskspace_sbs>`] + +The numbers mentioned are rough estimates with a big extra charge to be on the +safe side, so often you will need less. + +If you have space constraints, remember to read the reference section when you +reach the :ref:`section about configuration adjustments' <configmods>`, as +ensuring debug symbols are disabled will reduce the consumed disk space by quite +a few gigabytes. + +[:ref:`back to step-by-step guide <diskspace_sbs>`] + + +.. _sources: + +Download the sources +-------------------- + + *Retrieve the sources of the Linux version you intend to build.* + [:ref:`...<sources_sbs>`] + +The step-by-step guide outlines how to retrieve Linux' sources using a shallow +git clone. There is :ref:`more to tell about this method<sources_shallow>` and +two alternate ways worth describing: :ref:`packaged archives<sources_archive>` +and :ref:`a full git clone<sources_full>`. And the aspects ':ref:`wouldn't it +be wiser to use a proper pre-release than the latest mainline code +<sources_snapshot>`' and ':ref:`how to get an even fresher mainline codebase +<sources_fresher>`' need elaboration, too. + +Note, to keep things simple the commands used in this guide store the build +artifacts in the source tree. If you prefer to separate them, simply add +something like ``O=~/linux-builddir/`` to all make calls; also adjust the path +in all commands that add files or modify any generated (like your '.config'). + +[:ref:`back to step-by-step guide <sources_sbs>`] + +.. _sources_shallow: + +Noteworthy characteristics of shallow clones +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The step-by-step guide uses a shallow clone, as it is the best solution for most +of this document's target audience. There are a few aspects of this approach +worth mentioning: + + * This document in most places uses ``git fetch`` with ``--shallow-exclude=`` + to specify the earliest version you care about (or to be precise: its git + tag). You alternatively can use the parameter ``--shallow-since=`` to specify + an absolute (say ``'2023-07-15'``) or relative (``'12 months'``) date to + define the depth of the history you want to download. As a second + alternative, you can also specify a certain depth explicitly with a parameter + like ``--depth=1``, unless you add branches for stable/longterm kernels. + + * When running ``git fetch``, remember to always specify the oldest version, + the time you care about, or an explicit depth as shown in the step-by-step + guide. Otherwise you will risk downloading nearly the entire git history, + which will consume quite a bit of time and bandwidth while also stressing the + servers. + + Note, you do not have to use the same version or date all the time. But when + you change it over time, git will deepen or flatten the history to the + specified point. That allows you to retrieve versions you initially thought + you did not need -- or it will discard the sources of older versions, for + example in case you want to free up some disk space. The latter will happen + automatically when using ``--shallow-since=`` or + ``--depth=``. + + * Be warned, when deepening your clone you might encounter an error like + 'fatal: error in object: unshallow cafecaca0c0dacafecaca0c0dacafecaca0c0da'. + In that case run ``git repack -d`` and try again`` + + * In case you want to revert changes from a certain version (say Linux 6.3) or + perform a bisection (v6.2..v6.3), better tell ``git fetch`` to retrieve + objects up to three versions earlier (e.g. 6.0): ``git describe`` will then + be able to describe most commits just like it would in a full git clone. + +[:ref:`back to step-by-step guide <sources_sbs>`] [:ref:`back to section intro <sources>`] + +.. _sources_archive: + +Downloading the sources using a packages archive +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +People new to compiling Linux often assume downloading an archive via the +front-page of https://kernel.org is the best approach to retrieve Linux' +sources. It actually can be, if you are certain to build just one particular +kernel version without changing any code. Thing is: you might be sure this will +be the case, but in practice it often will turn out to be a wrong assumption. + +That's because when reporting or debugging an issue developers will often ask to +give another version a try. They also might suggest temporarily undoing a commit +with ``git revert`` or might provide various patches to try. Sometimes reporters +will also be asked to use ``git bisect`` to find the change causing a problem. +These things rely on git or are a lot easier and quicker to handle with it. + +A shallow clone also does not add any significant overhead. For example, when +you use ``git clone --depth=1`` to create a shallow clone of the latest mainline +codebase git will only retrieve a little more data than downloading the latest +mainline pre-release (aka 'rc') via the front-page of kernel.org would. + +A shallow clone therefore is often the better choice. If you nevertheless want +to use a packaged source archive, download one via kernel.org; afterwards +extract its content to some directory and change to the subdirectory created +during extraction. The rest of the step-by-step guide will work just fine, apart +from things that rely on git -- but this mainly concerns the section on +successive builds of other versions. + +[:ref:`back to step-by-step guide <sources_sbs>`] [:ref:`back to section intro <sources>`] + +.. _sources_full: + +Downloading the sources using a full git clone +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If downloading and storing a lot of data (~4,4 Gigabyte as of early 2023) is +nothing that bothers you, instead of a shallow clone perform a full git clone +instead. You then will avoid the specialties mentioned above and will have all +versions and individual commits at hand at any time:: + + curl -L \ + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/clone.bundle \ + -o linux-stable.git.bundle + git clone clone.bundle ~/linux/ + rm linux-stable.git.bundle + cd ~/linux/ + git remote set-url origin + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git + git fetch origin + git checkout --detach origin/master + +[:ref:`back to step-by-step guide <sources_sbs>`] [:ref:`back to section intro <sources>`] + +.. _sources_snapshot: + +Proper pre-releases (RCs) vs. latest mainline +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When cloning the sources using git and checking out origin/master, you often +will retrieve a codebase that is somewhere between the latest and the next +release or pre-release. This almost always is the code you want when giving +mainline a shot: pre-releases like v6.1-rc5 are in no way special, as they do +not get any significant extra testing before being published. + +There is one exception: you might want to stick to the latest mainline release +(say v6.1) before its successor's first pre-release (v6.2-rc1) is out. That is +because compiler errors and other problems are more likely to occur during this +time, as mainline then is in its 'merge window': a usually two week long phase, +in which the bulk of the changes for the next release is merged. + +[:ref:`back to step-by-step guide <sources_sbs>`] [:ref:`back to section intro <sources>`] + +.. _sources_fresher: + +Avoiding the mainline lag +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The explanations for both the shallow clone and the full clone both retrieve the +code from the Linux stable git repository. That makes things simpler for this +document's audience, as it allows easy access to both mainline and +stable/longterm releases. This approach has just one downside: + +Changes merged into the mainline repository are only synced to the master branch +of the Linux stable repository every few hours. This lag most of the time is +not something to worry about; but in case you really need the latest code, just +add the mainline repo as additional remote and checkout the code from there:: + + git remote add mainline \ + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + git fetch mainline + git checkout --detach mainline/master + +When doing this with a shallow clone, remember to call ``git fetch`` with one +of the parameters described earlier to limit the depth. + +[:ref:`back to step-by-step guide <sources_sbs>`] [:ref:`back to section intro <sources>`] + +.. _patching: + +Patch the sources (optional) +---------------------------- + + *In case you want to apply a kernel patch, do so now.* + [:ref:`...<patching_sbs>`] + +This is the point where you might want to patch your kernel -- for example when +a developer proposed a fix and asked you to check if it helps. The step-by-step +guide already explains everything crucial here. + +[:ref:`back to step-by-step guide <patching_sbs>`] + +.. _tagging: + +Tagging this kernel build (optional, often wise) +------------------------------------------------ + + *If you patched your kernel or already have that kernel version installed, + better tag your kernel by extending its release name:* + [:ref:`...<tagging_sbs>`] + +Tagging your kernel will help avoid confusion later, especially when you patched +your kernel. Adding an individual tag will also ensure the kernel's image and +its modules are installed in parallel to any existing kernels. + +There are various ways to add such a tag. The step-by-step guide realizes one by +creating a 'localversion' file in your build directory from which the kernel +build scripts will automatically pick up the tag. You can later change that file +to use a different tag in subsequent builds or simply remove that file to dump +the tag. + +[:ref:`back to step-by-step guide <tagging_sbs>`] + +.. _configuration: + +Define the build configuration for your kernel +---------------------------------------------- + + *Create the build configuration for your kernel based on an existing + configuration.* [:ref:`... <configuration_sbs>`] + +There are various aspects for this steps that require a more careful +explanation: + +Pitfalls when using another configuration file as base +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Make targets like localmodconfig and olddefconfig share a few common snares you +want to be aware of: + + * These targets will reuse a kernel build configuration in your build directory + (e.g. '~/linux/.config'), if one exists. In case you want to start from + scratch you thus need to delete it. + + * The make targets try to find the configuration for your running kernel + automatically, but might choose poorly. A line like '# using defaults found + in /boot/config-6.0.7-250.fc36.x86_64' or 'using config: + '/boot/config-6.0.7-250.fc36.x86_64' tells you which file they picked. If + that is not the intended one, simply store it as '~/linux/.config' + before using these make targets. + + * Unexpected things might happen if you try to use a config file prepared for + one kernel (say v6.0) on an older generation (say v5.15). In that case you + might want to use a configuration as base which your distribution utilized + when they used that or an slightly older kernel version. + +Influencing the configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The make target olddefconfig and the ``yes "" |`` used when utilizing +localmodconfig will set any undefined build options to their default value. This +among others will disable many kernel features that were introduced after your +base kernel was released. + +If you want to set these configurations options manually, use ``oldconfig`` +instead of ``olddefconfig`` or omit the ``yes "" |`` when utilizing +localmodconfig. Then for each undefined configuration option you will be asked +how to proceed. In case you are unsure what to answer, simply hit 'enter' to +apply the default value. + +Big pitfall when using localmodconfig +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As explained briefly in the step-by-step guide already: with localmodconfig it +can easily happen that your self-built kernel will lack modules for tasks you +did not perform before utilizing this make target. That's because those tasks +require kernel modules that are normally autoloaded when you perform that task +for the first time; if you didn't perform that task at least once before using +localmodonfig, the latter will thus assume these modules are superfluous and +disable them. + +You can try to avoid this by performing typical tasks that often will autoload +additional kernel modules: start a VM, establish VPN connections, loop-mount a +CD/DVD ISO, mount network shares (CIFS, NFS, ...), and connect all external +devices (2FA keys, headsets, webcams, ...) as well as storage devices with file +systems you otherwise do not utilize (btrfs, ext4, FAT, NTFS, XFS, ...). But it +is hard to think of everything that might be needed -- even kernel developers +often forget one thing or another at this point. + +Do not let that risk bother you, especially when compiling a kernel only for +testing purposes: everything typically crucial will be there. And if you forget +something important you can turn on a missing feature later and quickly run the +commands to compile and install a better kernel. + +But if you plan to build and use self-built kernels regularly, you might want to +reduce the risk by recording which modules your system loads over the course of +a few weeks. You can automate this with `modprobed-db +<https://github.com/graysky2/modprobed-db>`_. Afterwards use ``LSMOD=<path>`` to +point localmodconfig to the list of modules modprobed-db noticed being used:: + + yes "" | make LSMOD="${HOME}"/.config/modprobed.db localmodconfig + +Remote building with localmodconfig +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you want to use localmodconfig to build a kernel for another machine, run +``lsmod > lsmod_foo-machine`` on it and transfer that file to your build host. +Now point the build scripts to the file like this: ``yes "" | make +LSMOD=~/lsmod_foo-machine localmodconfig``. Note, in this case +you likely want to copy a base kernel configuration from the other machine over +as well and place it as .config in your build directory. + +[:ref:`back to step-by-step guide <configuration_sbs>`] + +.. _configmods: + +Adjust build configuration +-------------------------- + + *Check if you might want to or have to adjust some kernel configuration + options:* + +Depending on your needs you at this point might want or have to adjust some +kernel configuration options. + +.. _configmods_debugsymbols: + +Debug symbols +~~~~~~~~~~~~~ + + *Evaluate how you want to handle debug symbols.* + [:ref:`...<configmods_sbs>`] + +Most users do not need to care about this, it's often fine to leave everything +as it is; but you should take a closer look at this, if you might need to decode +a stack trace or want to reduce space consumption. + +Having debug symbols available can be important when your kernel throws a +'panic', 'Oops', 'warning', or 'BUG' later when running, as then you will be +able to find the exact place where the problem occurred in the code. But +collecting and embedding the needed debug information takes time and consumes +quite a bit of space: in late 2022 the build artifacts for a typical x86 kernel +configured with localmodconfig consumed around 5 Gigabyte of space with debug +symbols, but less than 1 when they were disabled. The resulting kernel image and +the modules are bigger as well, which increases load times. + +Hence, if you want a small kernel and are unlikely to decode a stack trace +later, you might want to disable debug symbols to avoid above downsides:: + + ./scripts/config --file .config -d DEBUG_INFO \ + -d DEBUG_INFO_DWARF_TOOLCHAIN_DEFAULT -d DEBUG_INFO_DWARF4 \ + -d DEBUG_INFO_DWARF5 -e CONFIG_DEBUG_INFO_NONE + make olddefconfig + +You on the other hand definitely want to enable them, if there is a decent +chance that you need to decode a stack trace later (as explained by 'Decode +failure messages' in Documentation/admin-guide/tainted-kernels.rst in more +detail):: + + ./scripts/config --file .config -d DEBUG_INFO_NONE -e DEBUG_KERNEL + -e DEBUG_INFO -e DEBUG_INFO_DWARF_TOOLCHAIN_DEFAULT -e KALLSYMS -e KALLSYMS_ALL + make olddefconfig + +Note, many mainstream distributions enable debug symbols in their kernel +configurations -- make targets like localmodconfig and olddefconfig thus will +often pick that setting up. + +[:ref:`back to step-by-step guide <configmods_sbs>`] + +.. _configmods_distros: + +Distro specific adjustments +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + *Are you running* [:ref:`... <configmods_sbs>`] + +The following sections help you to avoid build problems that are known to occur +when following this guide on a few commodity distributions. + +**Debian:** + + * Remove a stale reference to a certificate file that would cause your build to + fail:: + + ./scripts/config --file .config --set-str SYSTEM_TRUSTED_KEYS '' + + Alternatively, download the needed certificate and make that configuration + option point to it, as `the Debian handbook explains in more detail + <https://debian-handbook.info/browse/stable/sect.kernel-compilation.html>`_ + -- or generate your own, as explained in + Documentation/admin-guide/module-signing.rst. + +[:ref:`back to step-by-step guide <configmods_sbs>`] + +.. _configmods_individual: + +Individual adjustments +~~~~~~~~~~~~~~~~~~~~~~ + + *If you want to influence the other aspects of the configuration, do so + now* [:ref:`... <configmods_sbs>`] + +You at this point can use a command like ``make menuconfig`` to enable or +disable certain features using a text-based user interface; to use a graphical +configuration utilize, use the make target ``xconfig`` or ``gconfig`` instead. +All of them require development libraries from toolkits they are based on +(ncurses, Qt5, Gtk2); an error message will tell you if something required is +missing. + +[:ref:`back to step-by-step guide <configmods_sbs>`] + +.. _build: + +Build your kernel +----------------- + + *Build the image and the modules of your kernel* [:ref:`... <build_sbs>`] + +A lot can go wrong at this stage, but the instructions below will help you help +yourself. Another subsection explains how to directly package your kernel up as +deb, rpm or tar file. + +Dealing with build errors +~~~~~~~~~~~~~~~~~~~~~~~~~ + +When a build error occurs, it might be caused by some aspect of your machine's +setup that often can be fixed quickly; other times though the problem lies in +the code and can only be fixed by a developer. A close examination of the +failure messages coupled with some research on the internet will often tell you +which of the two it is. To perform such a investigation, restart the build +process like this:: + + make V=1 + +The ``V=1`` activates verbose output, which might be needed to see the actual +error. To make it easier to spot, this command also omits the ``-j $(nproc +--all)`` used earlier to utilize every CPU core in the system for the job -- but +this parallelism also results in some clutter when failures occur. + +After a few seconds the build process should run into the error again. Now try +to find the most crucial line describing the problem. Then search the internet +for the most important and non-generic section of that line (say 4 to 8 words); +avoid or remove anything that looks remotely system-specific, like your username +or local path names like ``/home/username/linux/``. First try your regular +internet search engine with that string, afterwards search Linux kernel mailing +lists via `lore.kernel.org/all/ <https://lore.kernel.org/all/>`_. + +This most of the time will find something that will explain what is wrong; quite +often one of the hits will provide a solution for your problem, too. If you +do not find anything that matches your problem, try again from a different angle +by modifying your search terms or using another line from the error messages. + +In the end, most trouble you are to run into has likely been encountered and +reported by others already. That includes issues where the cause is not your +system, but lies the code. If you run into one of those, you might thus find a +solution (e.g. a patch) or workaround for your problem, too. + +Package your kernel up +~~~~~~~~~~~~~~~~~~~~~~ + +The step-by-step guide uses the default make targets (e.g. 'bzImage' and +'modules' on x86) to build the image and the modules of your kernel, which later +steps of the guide then install. You instead can also directly build everything +and directly package it up by using one of the following targets: + + * ``make -j $(nproc --all) bindeb-pkg`` to generate a deb package + + * ``make -j $(nproc --all) binrpm-pkg`` to generate a rpm package + + * ``make -j $(nproc --all) tarbz2-pkg`` to generate a bz2 compressed tarball + +This is just a selection of available make targets for this purpose, see +``make help`` for others. You can also use these targets after running +``make -j $(nproc --all)``, as they will pick up everything already built. + +If you employ the targets to generate deb or rpm packages, ignore the +step-by-step guide's instructions on installing and removing your kernel; +instead install and remove the packages using the package utility for the format +(e.g. dpkg and rpm) or a package management utility build on top of them (apt, +aptitude, dnf/yum, zypper, ...). Be aware that the packages generated using +these two make targets are designed to work on various distributions utilizing +those formats, they thus will sometimes behave differently than your +distribution's kernel packages. + +[:ref:`back to step-by-step guide <build_sbs>`] + +.. _install: + +Install your kernel +------------------- + + *Now install your kernel* [:ref:`... <install_sbs>`] + +What you need to do after executing the command in the step-by-step guide +depends on the existence and the implementation of an ``installkernel`` +executable. Many commodity Linux distributions ship such a kernel installer in +``/sbin/`` that does everything needed, hence there is nothing left for you +except rebooting. But some distributions contain an installkernel that does +only part of the job -- and a few lack it completely and leave all the work to +you. + +If ``installkernel`` is found, the kernel's build system will delegate the +actual installation of your kernel's image and related files to this executable. +On almost all Linux distributions it will store the image as '/boot/vmlinuz- +<your kernel's release name>' and put a 'System.map-<your kernel's release +name>' alongside it. Your kernel will thus be installed in parallel to any +existing ones, unless you already have one with exactly the same release name. + +Installkernel on many distributions will afterwards generate an 'initramfs' +(often also called 'initrd'), which commodity distributions rely on for booting; +hence be sure to keep the order of the two make targets used in the step-by-step +guide, as things will go sideways if you install your kernel's image before its +modules. Often installkernel will then add your kernel to the bootloader +configuration, too. You have to take care of one or both of these tasks +yourself, if your distributions installkernel doesn't handle them. + +A few distributions like Arch Linux and its derivatives totally lack an +installkernel executable. On those just install the modules using the kernel's +build system and then install the image and the System.map file manually:: + + sudo make modules_install + sudo install -m 0600 $(make -s image_name) /boot/vmlinuz-$(make -s kernelrelease) + sudo install -m 0600 System.map /boot/System.map-$(make -s kernelrelease) + +If your distribution boots with the help of an initramfs, now generate one for +your kernel using the tools your distribution provides for this process. +Afterwards add your kernel to your bootloader configuration and reboot. + +[:ref:`back to step-by-step guide <install_sbs>`] + +.. _another: + +Another round later +------------------- + + *To later build another kernel you need similar, but sometimes slightly + different commands* [:ref:`... <another_sbs>`] + +The process to build later kernels is similar, but at some points slightly +different. You for example do not want to use 'localmodconfig' for succeeding +kernel builds, as you already created a trimmed down configuration you want to +use from now on. Hence instead just use ``oldconfig`` or ``olddefconfig`` to +adjust your build configurations to the needs of the kernel version you are +about to build. + +If you created a shallow-clone with git, remember what the :ref:`section that +explained the setup described in more detail <sources>`: you need to use a +slightly different ``git fetch`` command and when switching to another series +need to add an additional remote branch. + +[:ref:`back to step-by-step guide <another_sbs>`] + +.. _uninstall: + +Uninstall the kernel later +-------------------------- + + *All parts of your installed kernel are identifiable by its release name and + thus easy to remove later.* [:ref:`... <uninstall_sbs>`] + +Do not worry installing your kernel manually and thus bypassing your +distribution's packaging system will totally mess up your machine: all parts of +your kernel are easy to remove later, as files are stored in two places only and +normally identifiable by the kernel's release name. + +One of the two places is a directory in /lib/modules/, which holds the modules +for each installed kernel. This directory is named after the kernel's release +name; hence, to remove all modules for one of your kernels, simply remove its +modules directory in /lib/modules/. + +The other place is /boot/, where typically one to five files will be placed +during installation of a kernel. All of them usually contain the release name in +their file name, but how many files and their name depends somewhat on your +distribution's installkernel executable (:ref:`see above <install>`) and its +initramfs generator. On some distributions the ``kernel-install`` command +mentioned in the step-by-step guide will remove all of these files for you -- +and the entry for your kernel in the bootloader configuration at the same time, +too. On others you have to take care of these steps yourself. The following +command should interactively remove the two main files of a kernel with the +release name '6.0.1-foobar':: + + rm -i /boot/{System.map,vmlinuz}-6.0.1-foobar + +Now remove the belonging initramfs, which often will be called something like +``/boot/initramfs-6.0.1-foobar.img`` or ``/boot/initrd.img-6.0.1-foobar``. +Afterwards check for other files in /boot/ that have '6.0.1-foobar' in their +name and delete them as well. Now remove the kernel from your bootloader's +configuration. + +Note, be very careful with wildcards like '*' when deleting files or directories +for kernels manually: you might accidentally remove files of a 6.0.11 kernel +when all you want is to remove 6.0 or 6.0.1. + +[:ref:`back to step-by-step guide <uninstall_sbs>`] + +.. _faq: + +FAQ +=== + +Why does this 'how-to' not work on my system? +--------------------------------------------- + +As initially stated, this guide is 'designed to cover everything typically +needed [to build a kernel] on mainstream Linux distributions running on +commodity PC or server hardware'. The outlined approach despite this should work +on many other setups as well. But trying to cover every possible use-case in one +guide would defeat its purpose, as without such a focus you would need dozens or +hundreds of constructs along the lines of 'in case you are having <insert +machine or distro>, you at this point have to do <this and that> +<instead|additionally>'. Each of which would make the text longer, more +complicated, and harder to follow. + +That being said: this of course is a balancing act. Hence, if you think an +additional use-case is worth describing, suggest it to the maintainers of this +document, as :ref:`described above <submit_improvements>`. + + +.. + end-of-content +.. + This document is maintained by Thorsten Leemhuis <linux@leemhuis.info>. If + you spot a typo or small mistake, feel free to let him know directly and + he'll fix it. You are free to do the same in a mostly informal way if you + want to contribute changes to the text -- but for copyright reasons please CC + linux-doc@vger.kernel.org and 'sign-off' your contribution as + Documentation/process/submitting-patches.rst explains in the section 'Sign + your work - the Developer's Certificate of Origin'. +.. + This text is available under GPL-2.0+ or CC-BY-4.0, as stated at the top + of the file. If you want to distribute this text under CC-BY-4.0 only, + please use 'The Linux kernel development community' for author attribution + and link this as source: + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/quickly-build-trimmed-linux.rst +.. + Note: Only the content of this RST file as found in the Linux kernel sources + is available under CC-BY-4.0, as versions of this text that were processed + (for example by the kernel's build system) might contain content taken from + files which use a more restrictive license. + diff --git a/Documentation/admin-guide/ras.rst b/Documentation/admin-guide/ras.rst index 7b481b2a368e..8e03751d126d 100644 --- a/Documentation/admin-guide/ras.rst +++ b/Documentation/admin-guide/ras.rst @@ -199,7 +199,7 @@ Architecture (MCA)\ [#f3]_. mode). .. [#f3] For more details about the Machine Check Architecture (MCA), - please read Documentation/x86/x86_64/machinecheck.rst at the Kernel tree. + please read Documentation/arch/x86/x86_64/machinecheck.rst at the Kernel tree. EDAC - Error Detection And Correction ************************************* diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index 4b7bfea28cd7..d85d90f5d000 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -95,7 +95,7 @@ is 0x15 and the full version number is 0x234, this file will contain the value 340 = 0x154. See the ``type_of_loader`` and ``ext_loader_type`` fields in -Documentation/x86/boot.rst for additional information. +Documentation/arch/x86/boot.rst for additional information. bootloader_version (x86 only) @@ -105,7 +105,7 @@ The complete bootloader version number. In the example above, this file will contain the value 564 = 0x234. See the ``type_of_loader`` and ``ext_loader_ver`` fields in -Documentation/x86/boot.rst for additional information. +Documentation/arch/x86/boot.rst for additional information. bpf_stats_enabled diff --git a/Documentation/admin-guide/unicode.rst b/Documentation/admin-guide/unicode.rst index 290fe83ebe82..cba7e5017d36 100644 --- a/Documentation/admin-guide/unicode.rst +++ b/Documentation/admin-guide/unicode.rst @@ -3,11 +3,10 @@ Unicode support Last update: 2005-01-17, version 1.4 -This file is maintained by H. Peter Anvin <unicode@lanana.org> as part -of the Linux Assigned Names And Numbers Authority (LANANA) project. -The current version can be found at: - - http://www.lanana.org/docs/unicode/admin-guide/unicode.rst +Note: The original version of this document, which was maintained at +lanana.org as part of the Linux Assigned Names And Numbers Authority +(LANANA) project, is no longer existent. So, this version in the +mainline Linux kernel is now the maintained main document. Introduction ------------ diff --git a/Documentation/arc/arc.rst b/Documentation/arch/arc/arc.rst index 6c4d978f3f4e..6c4d978f3f4e 100644 --- a/Documentation/arc/arc.rst +++ b/Documentation/arch/arc/arc.rst diff --git a/Documentation/arc/features.rst b/Documentation/arch/arc/features.rst index b793583d688a..b793583d688a 100644 --- a/Documentation/arc/features.rst +++ b/Documentation/arch/arc/features.rst diff --git a/Documentation/arc/index.rst b/Documentation/arch/arc/index.rst index 7b098d4a5e3e..7b098d4a5e3e 100644 --- a/Documentation/arc/index.rst +++ b/Documentation/arch/arc/index.rst diff --git a/Documentation/ia64/aliasing.rst b/Documentation/arch/ia64/aliasing.rst index 36a1e1d4842b..36a1e1d4842b 100644 --- a/Documentation/ia64/aliasing.rst +++ b/Documentation/arch/ia64/aliasing.rst diff --git a/Documentation/ia64/efirtc.rst b/Documentation/arch/ia64/efirtc.rst index fd8328408301..fd8328408301 100644 --- a/Documentation/ia64/efirtc.rst +++ b/Documentation/arch/ia64/efirtc.rst diff --git a/Documentation/ia64/err_inject.rst b/Documentation/arch/ia64/err_inject.rst index 900f71e93a29..900f71e93a29 100644 --- a/Documentation/ia64/err_inject.rst +++ b/Documentation/arch/ia64/err_inject.rst diff --git a/Documentation/ia64/features.rst b/Documentation/arch/ia64/features.rst index d7226fdcf5f8..d7226fdcf5f8 100644 --- a/Documentation/ia64/features.rst +++ b/Documentation/arch/ia64/features.rst diff --git a/Documentation/ia64/fsys.rst b/Documentation/arch/ia64/fsys.rst index a702d2cc94b6..a702d2cc94b6 100644 --- a/Documentation/ia64/fsys.rst +++ b/Documentation/arch/ia64/fsys.rst diff --git a/Documentation/ia64/ia64.rst b/Documentation/arch/ia64/ia64.rst index b725019a9492..b725019a9492 100644 --- a/Documentation/ia64/ia64.rst +++ b/Documentation/arch/ia64/ia64.rst diff --git a/Documentation/ia64/index.rst b/Documentation/arch/ia64/index.rst index 761f2154dfa2..761f2154dfa2 100644 --- a/Documentation/ia64/index.rst +++ b/Documentation/arch/ia64/index.rst diff --git a/Documentation/ia64/irq-redir.rst b/Documentation/arch/ia64/irq-redir.rst index 6bbbbe4f73ef..6bbbbe4f73ef 100644 --- a/Documentation/ia64/irq-redir.rst +++ b/Documentation/arch/ia64/irq-redir.rst diff --git a/Documentation/ia64/mca.rst b/Documentation/arch/ia64/mca.rst index 08270bba44a4..08270bba44a4 100644 --- a/Documentation/ia64/mca.rst +++ b/Documentation/arch/ia64/mca.rst diff --git a/Documentation/ia64/serial.rst b/Documentation/arch/ia64/serial.rst index 1de70c305a79..1de70c305a79 100644 --- a/Documentation/ia64/serial.rst +++ b/Documentation/arch/ia64/serial.rst diff --git a/Documentation/arch.rst b/Documentation/arch/index.rst index 41a66a8b38e4..80ee31016584 100644 --- a/Documentation/arch.rst +++ b/Documentation/arch/index.rst @@ -10,18 +10,18 @@ implementation. :maxdepth: 2 arc/index - arm/index - arm64/index + ../arm/index + ../arm64/index ia64/index - loongarch/index + ../loongarch/index m68k/index - mips/index + ../mips/index nios2/index openrisc/index parisc/index - powerpc/index - riscv/index - s390/index + ../powerpc/index + ../riscv/index + ../s390/index sh/index sparc/index x86/index diff --git a/Documentation/m68k/buddha-driver.rst b/Documentation/arch/m68k/buddha-driver.rst index 20e401413991..20e401413991 100644 --- a/Documentation/m68k/buddha-driver.rst +++ b/Documentation/arch/m68k/buddha-driver.rst diff --git a/Documentation/m68k/features.rst b/Documentation/arch/m68k/features.rst index 5107a2119472..5107a2119472 100644 --- a/Documentation/m68k/features.rst +++ b/Documentation/arch/m68k/features.rst diff --git a/Documentation/m68k/index.rst b/Documentation/arch/m68k/index.rst index 0f890dbb5fe2..0f890dbb5fe2 100644 --- a/Documentation/m68k/index.rst +++ b/Documentation/arch/m68k/index.rst diff --git a/Documentation/m68k/kernel-options.rst b/Documentation/arch/m68k/kernel-options.rst index 2008a20b4329..2008a20b4329 100644 --- a/Documentation/m68k/kernel-options.rst +++ b/Documentation/arch/m68k/kernel-options.rst diff --git a/Documentation/nios2/features.rst b/Documentation/arch/nios2/features.rst index 8449e63f69b2..8449e63f69b2 100644 --- a/Documentation/nios2/features.rst +++ b/Documentation/arch/nios2/features.rst diff --git a/Documentation/nios2/index.rst b/Documentation/arch/nios2/index.rst index 4468fe1a1037..4468fe1a1037 100644 --- a/Documentation/nios2/index.rst +++ b/Documentation/arch/nios2/index.rst diff --git a/Documentation/nios2/nios2.rst b/Documentation/arch/nios2/nios2.rst index 43da3f7cee76..43da3f7cee76 100644 --- a/Documentation/nios2/nios2.rst +++ b/Documentation/arch/nios2/nios2.rst diff --git a/Documentation/openrisc/features.rst b/Documentation/arch/openrisc/features.rst index 3f7c40d219f2..3f7c40d219f2 100644 --- a/Documentation/openrisc/features.rst +++ b/Documentation/arch/openrisc/features.rst diff --git a/Documentation/openrisc/index.rst b/Documentation/arch/openrisc/index.rst index 6879f998b87a..6879f998b87a 100644 --- a/Documentation/openrisc/index.rst +++ b/Documentation/arch/openrisc/index.rst diff --git a/Documentation/openrisc/openrisc_port.rst b/Documentation/arch/openrisc/openrisc_port.rst index 657ac4af7be6..657ac4af7be6 100644 --- a/Documentation/openrisc/openrisc_port.rst +++ b/Documentation/arch/openrisc/openrisc_port.rst diff --git a/Documentation/openrisc/todo.rst b/Documentation/arch/openrisc/todo.rst index 420b18b87eda..420b18b87eda 100644 --- a/Documentation/openrisc/todo.rst +++ b/Documentation/arch/openrisc/todo.rst diff --git a/Documentation/parisc/debugging.rst b/Documentation/arch/parisc/debugging.rst index de1b60402c5b..de1b60402c5b 100644 --- a/Documentation/parisc/debugging.rst +++ b/Documentation/arch/parisc/debugging.rst diff --git a/Documentation/parisc/features.rst b/Documentation/arch/parisc/features.rst index 501d7c450037..501d7c450037 100644 --- a/Documentation/parisc/features.rst +++ b/Documentation/arch/parisc/features.rst diff --git a/Documentation/parisc/index.rst b/Documentation/arch/parisc/index.rst index 240685751825..240685751825 100644 --- a/Documentation/parisc/index.rst +++ b/Documentation/arch/parisc/index.rst diff --git a/Documentation/parisc/registers.rst b/Documentation/arch/parisc/registers.rst index 59c8ecf3e856..59c8ecf3e856 100644 --- a/Documentation/parisc/registers.rst +++ b/Documentation/arch/parisc/registers.rst diff --git a/Documentation/sh/booting.rst b/Documentation/arch/sh/booting.rst index d851c49a01bf..d851c49a01bf 100644 --- a/Documentation/sh/booting.rst +++ b/Documentation/arch/sh/booting.rst diff --git a/Documentation/sh/features.rst b/Documentation/arch/sh/features.rst index f722af3b6c99..f722af3b6c99 100644 --- a/Documentation/sh/features.rst +++ b/Documentation/arch/sh/features.rst diff --git a/Documentation/sh/index.rst b/Documentation/arch/sh/index.rst index c64776738cf6..c64776738cf6 100644 --- a/Documentation/sh/index.rst +++ b/Documentation/arch/sh/index.rst diff --git a/Documentation/sh/new-machine.rst b/Documentation/arch/sh/new-machine.rst index e501c52b3b30..e501c52b3b30 100644 --- a/Documentation/sh/new-machine.rst +++ b/Documentation/arch/sh/new-machine.rst diff --git a/Documentation/sh/register-banks.rst b/Documentation/arch/sh/register-banks.rst index 2bef5c8fcbbc..2bef5c8fcbbc 100644 --- a/Documentation/sh/register-banks.rst +++ b/Documentation/arch/sh/register-banks.rst diff --git a/Documentation/sparc/adi.rst b/Documentation/arch/sparc/adi.rst index dbcd8b6e7bc3..dbcd8b6e7bc3 100644 --- a/Documentation/sparc/adi.rst +++ b/Documentation/arch/sparc/adi.rst diff --git a/Documentation/sparc/console.rst b/Documentation/arch/sparc/console.rst index 73132db83ece..73132db83ece 100644 --- a/Documentation/sparc/console.rst +++ b/Documentation/arch/sparc/console.rst diff --git a/Documentation/sparc/features.rst b/Documentation/arch/sparc/features.rst index c0c92468b0fe..c0c92468b0fe 100644 --- a/Documentation/sparc/features.rst +++ b/Documentation/arch/sparc/features.rst diff --git a/Documentation/sparc/index.rst b/Documentation/arch/sparc/index.rst index ae884224eec2..ae884224eec2 100644 --- a/Documentation/sparc/index.rst +++ b/Documentation/arch/sparc/index.rst diff --git a/Documentation/sparc/oradax/dax-hv-api.txt b/Documentation/arch/sparc/oradax/dax-hv-api.txt index 7ecd0bf4957b..7ecd0bf4957b 100644 --- a/Documentation/sparc/oradax/dax-hv-api.txt +++ b/Documentation/arch/sparc/oradax/dax-hv-api.txt diff --git a/Documentation/sparc/oradax/oracle-dax.rst b/Documentation/arch/sparc/oradax/oracle-dax.rst index d1e14d572918..d1e14d572918 100644 --- a/Documentation/sparc/oradax/oracle-dax.rst +++ b/Documentation/arch/sparc/oradax/oracle-dax.rst diff --git a/Documentation/x86/amd-memory-encryption.rst b/Documentation/arch/x86/amd-memory-encryption.rst index 934310ce7258..934310ce7258 100644 --- a/Documentation/x86/amd-memory-encryption.rst +++ b/Documentation/arch/x86/amd-memory-encryption.rst diff --git a/Documentation/x86/amd_hsmp.rst b/Documentation/arch/x86/amd_hsmp.rst index 440e4b645a1c..440e4b645a1c 100644 --- a/Documentation/x86/amd_hsmp.rst +++ b/Documentation/arch/x86/amd_hsmp.rst diff --git a/Documentation/x86/boot.rst b/Documentation/arch/x86/boot.rst index 240d084782a6..33520ecdb37a 100644 --- a/Documentation/x86/boot.rst +++ b/Documentation/arch/x86/boot.rst @@ -1344,7 +1344,7 @@ follow:: In addition to read/modify/write the setup header of the struct boot_params as that of 16-bit boot protocol, the boot loader should also fill the additional fields of the struct boot_params as -described in chapter Documentation/x86/zero-page.rst. +described in chapter Documentation/arch/x86/zero-page.rst. After setting up the struct boot_params, the boot loader can load the 32/64-bit kernel in the same way as that of 16-bit boot protocol. @@ -1380,7 +1380,7 @@ can be calculated as follows:: In addition to read/modify/write the setup header of the struct boot_params as that of 16-bit boot protocol, the boot loader should also fill the additional fields of the struct boot_params as described -in chapter Documentation/x86/zero-page.rst. +in chapter Documentation/arch/x86/zero-page.rst. After setting up the struct boot_params, the boot loader can load 64-bit kernel in the same way as that of 16-bit boot protocol, but diff --git a/Documentation/x86/booting-dt.rst b/Documentation/arch/x86/booting-dt.rst index 965a374071ab..b089ffd56e6e 100644 --- a/Documentation/x86/booting-dt.rst +++ b/Documentation/arch/x86/booting-dt.rst @@ -7,7 +7,7 @@ DeviceTree Booting the decompressor (the real mode entry point goes to the same 32bit entry point once it switched into protected mode). That entry point supports one calling convention which is documented in - Documentation/x86/boot.rst + Documentation/arch/x86/boot.rst The physical pointer to the device-tree block is passed via setup_data which requires at least boot protocol 2.09. The type filed is defined as diff --git a/Documentation/x86/buslock.rst b/Documentation/arch/x86/buslock.rst index 7c051e714943..31ec0ef78086 100644 --- a/Documentation/x86/buslock.rst +++ b/Documentation/arch/x86/buslock.rst @@ -53,8 +53,14 @@ parameter "split_lock_detect". Here is a summary of different options: |off |Do nothing |Do nothing | +------------------+----------------------------+-----------------------+ |warn |Kernel OOPs |Warn once per task and | -|(default) |Warn once per task and |and continues to run. | -| |disable future checking | | +|(default) |Warn once per task, add a |and continues to run. | +| |delay, add synchronization | | +| |to prevent more than one | | +| |core from executing a | | +| |split lock in parallel. | | +| |sysctl split_lock_mitigate | | +| |can be used to avoid the | | +| |delay and synchronization | | | |When both features are | | | |supported, warn in #AC | | +------------------+----------------------------+-----------------------+ diff --git a/Documentation/x86/cpuinfo.rst b/Documentation/arch/x86/cpuinfo.rst index 08246e8ac835..08246e8ac835 100644 --- a/Documentation/x86/cpuinfo.rst +++ b/Documentation/arch/x86/cpuinfo.rst diff --git a/Documentation/x86/earlyprintk.rst b/Documentation/arch/x86/earlyprintk.rst index 51ef11e8f725..51ef11e8f725 100644 --- a/Documentation/x86/earlyprintk.rst +++ b/Documentation/arch/x86/earlyprintk.rst diff --git a/Documentation/x86/elf_auxvec.rst b/Documentation/arch/x86/elf_auxvec.rst index 18e4744717f9..18e4744717f9 100644 --- a/Documentation/x86/elf_auxvec.rst +++ b/Documentation/arch/x86/elf_auxvec.rst diff --git a/Documentation/x86/entry_64.rst b/Documentation/arch/x86/entry_64.rst index 0afdce3c06f4..0afdce3c06f4 100644 --- a/Documentation/x86/entry_64.rst +++ b/Documentation/arch/x86/entry_64.rst diff --git a/Documentation/x86/exception-tables.rst b/Documentation/arch/x86/exception-tables.rst index efde1fef4fbd..efde1fef4fbd 100644 --- a/Documentation/x86/exception-tables.rst +++ b/Documentation/arch/x86/exception-tables.rst diff --git a/Documentation/x86/features.rst b/Documentation/arch/x86/features.rst index b663f15053ce..b663f15053ce 100644 --- a/Documentation/x86/features.rst +++ b/Documentation/arch/x86/features.rst diff --git a/Documentation/x86/i386/IO-APIC.rst b/Documentation/arch/x86/i386/IO-APIC.rst index ce4d8df15e7c..ce4d8df15e7c 100644 --- a/Documentation/x86/i386/IO-APIC.rst +++ b/Documentation/arch/x86/i386/IO-APIC.rst diff --git a/Documentation/x86/i386/index.rst b/Documentation/arch/x86/i386/index.rst index 8747cf5bbd49..8747cf5bbd49 100644 --- a/Documentation/x86/i386/index.rst +++ b/Documentation/arch/x86/i386/index.rst diff --git a/Documentation/x86/ifs.rst b/Documentation/arch/x86/ifs.rst index 97abb696a680..97abb696a680 100644 --- a/Documentation/x86/ifs.rst +++ b/Documentation/arch/x86/ifs.rst diff --git a/Documentation/x86/index.rst b/Documentation/arch/x86/index.rst index c73d133fd37c..c73d133fd37c 100644 --- a/Documentation/x86/index.rst +++ b/Documentation/arch/x86/index.rst diff --git a/Documentation/x86/intel-hfi.rst b/Documentation/arch/x86/intel-hfi.rst index 49dea58ea4fb..49dea58ea4fb 100644 --- a/Documentation/x86/intel-hfi.rst +++ b/Documentation/arch/x86/intel-hfi.rst diff --git a/Documentation/x86/intel_txt.rst b/Documentation/arch/x86/intel_txt.rst index d83c1a2122c9..d83c1a2122c9 100644 --- a/Documentation/x86/intel_txt.rst +++ b/Documentation/arch/x86/intel_txt.rst diff --git a/Documentation/x86/iommu.rst b/Documentation/arch/x86/iommu.rst index 42c7a6faa39a..42c7a6faa39a 100644 --- a/Documentation/x86/iommu.rst +++ b/Documentation/arch/x86/iommu.rst diff --git a/Documentation/x86/kernel-stacks.rst b/Documentation/arch/x86/kernel-stacks.rst index 6b0bcf027ff1..6b0bcf027ff1 100644 --- a/Documentation/x86/kernel-stacks.rst +++ b/Documentation/arch/x86/kernel-stacks.rst diff --git a/Documentation/x86/mds.rst b/Documentation/arch/x86/mds.rst index 5d4330be200f..5d4330be200f 100644 --- a/Documentation/x86/mds.rst +++ b/Documentation/arch/x86/mds.rst diff --git a/Documentation/x86/microcode.rst b/Documentation/arch/x86/microcode.rst index b627c6f36bcf..b627c6f36bcf 100644 --- a/Documentation/x86/microcode.rst +++ b/Documentation/arch/x86/microcode.rst diff --git a/Documentation/x86/mtrr.rst b/Documentation/arch/x86/mtrr.rst index 9f0b1851771a..f65ef034da7a 100644 --- a/Documentation/x86/mtrr.rst +++ b/Documentation/arch/x86/mtrr.rst @@ -28,7 +28,7 @@ are aligned with platform MTRR setup. If MTRRs are only set up by the platform firmware code though and the OS does not make any specific MTRR mapping requests mtrr_type_lookup() should always return MTRR_TYPE_INVALID. -For details refer to Documentation/x86/pat.rst. +For details refer to Documentation/arch/x86/pat.rst. .. tip:: On Intel P6 family processors (Pentium Pro, Pentium II and later) diff --git a/Documentation/x86/orc-unwinder.rst b/Documentation/arch/x86/orc-unwinder.rst index cdb257015bd9..cdb257015bd9 100644 --- a/Documentation/x86/orc-unwinder.rst +++ b/Documentation/arch/x86/orc-unwinder.rst diff --git a/Documentation/x86/pat.rst b/Documentation/arch/x86/pat.rst index 5d901771016d..5d901771016d 100644 --- a/Documentation/x86/pat.rst +++ b/Documentation/arch/x86/pat.rst diff --git a/Documentation/x86/pti.rst b/Documentation/arch/x86/pti.rst index 4b858a9bad8d..4b858a9bad8d 100644 --- a/Documentation/x86/pti.rst +++ b/Documentation/arch/x86/pti.rst diff --git a/Documentation/x86/resctrl.rst b/Documentation/arch/x86/resctrl.rst index 387ccbcb558f..387ccbcb558f 100644 --- a/Documentation/x86/resctrl.rst +++ b/Documentation/arch/x86/resctrl.rst diff --git a/Documentation/x86/sgx.rst b/Documentation/arch/x86/sgx.rst index 2bcbffacbed5..2bcbffacbed5 100644 --- a/Documentation/x86/sgx.rst +++ b/Documentation/arch/x86/sgx.rst diff --git a/Documentation/x86/sva.rst b/Documentation/arch/x86/sva.rst index 2e9b8b0f9a0f..2e9b8b0f9a0f 100644 --- a/Documentation/x86/sva.rst +++ b/Documentation/arch/x86/sva.rst diff --git a/Documentation/x86/tdx.rst b/Documentation/arch/x86/tdx.rst index dc8d9fd2c3f7..dc8d9fd2c3f7 100644 --- a/Documentation/x86/tdx.rst +++ b/Documentation/arch/x86/tdx.rst diff --git a/Documentation/x86/tlb.rst b/Documentation/arch/x86/tlb.rst index 82ec58ae63a8..82ec58ae63a8 100644 --- a/Documentation/x86/tlb.rst +++ b/Documentation/arch/x86/tlb.rst diff --git a/Documentation/x86/topology.rst b/Documentation/arch/x86/topology.rst index 7f58010ea86a..7f58010ea86a 100644 --- a/Documentation/x86/topology.rst +++ b/Documentation/arch/x86/topology.rst diff --git a/Documentation/x86/tsx_async_abort.rst b/Documentation/arch/x86/tsx_async_abort.rst index 583ddc185ba2..583ddc185ba2 100644 --- a/Documentation/x86/tsx_async_abort.rst +++ b/Documentation/arch/x86/tsx_async_abort.rst diff --git a/Documentation/x86/usb-legacy-support.rst b/Documentation/arch/x86/usb-legacy-support.rst index e01c08b7c981..e01c08b7c981 100644 --- a/Documentation/x86/usb-legacy-support.rst +++ b/Documentation/arch/x86/usb-legacy-support.rst diff --git a/Documentation/x86/x86_64/5level-paging.rst b/Documentation/arch/x86/x86_64/5level-paging.rst index b792bbdc0b01..71f882f4a173 100644 --- a/Documentation/x86/x86_64/5level-paging.rst +++ b/Documentation/arch/x86/x86_64/5level-paging.rst @@ -20,7 +20,7 @@ physical address space. This "ought to be enough for anybody" ©. QEMU 2.9 and later support 5-level paging. Virtual memory layout for 5-level paging is described in -Documentation/x86/x86_64/mm.rst +Documentation/arch/x86/x86_64/mm.rst Enabling 5-level paging diff --git a/Documentation/x86/x86_64/boot-options.rst b/Documentation/arch/x86/x86_64/boot-options.rst index cbd14124a667..137432d34109 100644 --- a/Documentation/x86/x86_64/boot-options.rst +++ b/Documentation/arch/x86/x86_64/boot-options.rst @@ -9,7 +9,7 @@ only the AMD64 specific ones are listed here. Machine check ============= -Please see Documentation/x86/x86_64/machinecheck.rst for sysfs runtime tunables. +Please see Documentation/arch/x86/x86_64/machinecheck.rst for sysfs runtime tunables. mce=off Disable machine check @@ -82,7 +82,7 @@ APICs Don't use the local APIC (alias for i386 compatibility) pirq=... - See Documentation/x86/i386/IO-APIC.rst + See Documentation/arch/x86/i386/IO-APIC.rst noapictimer Don't set up the APIC timer diff --git a/Documentation/x86/x86_64/cpu-hotplug-spec.rst b/Documentation/arch/x86/x86_64/cpu-hotplug-spec.rst index 8d1c91f0c880..8d1c91f0c880 100644 --- a/Documentation/x86/x86_64/cpu-hotplug-spec.rst +++ b/Documentation/arch/x86/x86_64/cpu-hotplug-spec.rst diff --git a/Documentation/x86/x86_64/fake-numa-for-cpusets.rst b/Documentation/arch/x86/x86_64/fake-numa-for-cpusets.rst index ff9bcfd2cc14..ba74617d4999 100644 --- a/Documentation/x86/x86_64/fake-numa-for-cpusets.rst +++ b/Documentation/arch/x86/x86_64/fake-numa-for-cpusets.rst @@ -18,7 +18,7 @@ For more information on the features of cpusets, see Documentation/admin-guide/cgroup-v1/cpusets.rst. There are a number of different configurations you can use for your needs. For more information on the numa=fake command line option and its various ways of -configuring fake nodes, see Documentation/x86/x86_64/boot-options.rst. +configuring fake nodes, see Documentation/arch/x86/x86_64/boot-options.rst. For the purposes of this introduction, we'll assume a very primitive NUMA emulation setup of "numa=fake=4*512,". This will split our system memory into diff --git a/Documentation/x86/x86_64/fsgs.rst b/Documentation/arch/x86/x86_64/fsgs.rst index 50960e09e1f6..50960e09e1f6 100644 --- a/Documentation/x86/x86_64/fsgs.rst +++ b/Documentation/arch/x86/x86_64/fsgs.rst diff --git a/Documentation/x86/x86_64/index.rst b/Documentation/arch/x86/x86_64/index.rst index a56070fc8e77..a56070fc8e77 100644 --- a/Documentation/x86/x86_64/index.rst +++ b/Documentation/arch/x86/x86_64/index.rst diff --git a/Documentation/x86/x86_64/machinecheck.rst b/Documentation/arch/x86/x86_64/machinecheck.rst index cea12ee97200..cea12ee97200 100644 --- a/Documentation/x86/x86_64/machinecheck.rst +++ b/Documentation/arch/x86/x86_64/machinecheck.rst diff --git a/Documentation/x86/x86_64/mm.rst b/Documentation/arch/x86/x86_64/mm.rst index 35e5e18c83d0..35e5e18c83d0 100644 --- a/Documentation/x86/x86_64/mm.rst +++ b/Documentation/arch/x86/x86_64/mm.rst diff --git a/Documentation/x86/x86_64/uefi.rst b/Documentation/arch/x86/x86_64/uefi.rst index fbc30c9a071d..fbc30c9a071d 100644 --- a/Documentation/x86/x86_64/uefi.rst +++ b/Documentation/arch/x86/x86_64/uefi.rst diff --git a/Documentation/x86/xstate.rst b/Documentation/arch/x86/xstate.rst index 5cec7fb558d6..5cec7fb558d6 100644 --- a/Documentation/x86/xstate.rst +++ b/Documentation/arch/x86/xstate.rst diff --git a/Documentation/x86/zero-page.rst b/Documentation/arch/x86/zero-page.rst index 45aa9cceb4f1..45aa9cceb4f1 100644 --- a/Documentation/x86/zero-page.rst +++ b/Documentation/arch/x86/zero-page.rst diff --git a/Documentation/xtensa/atomctl.rst b/Documentation/arch/xtensa/atomctl.rst index 1ecbd0ba9a2e..1ecbd0ba9a2e 100644 --- a/Documentation/xtensa/atomctl.rst +++ b/Documentation/arch/xtensa/atomctl.rst diff --git a/Documentation/xtensa/booting.rst b/Documentation/arch/xtensa/booting.rst index e1b83707e5b6..e1b83707e5b6 100644 --- a/Documentation/xtensa/booting.rst +++ b/Documentation/arch/xtensa/booting.rst diff --git a/Documentation/xtensa/features.rst b/Documentation/arch/xtensa/features.rst index 6b92c7bfa19d..6b92c7bfa19d 100644 --- a/Documentation/xtensa/features.rst +++ b/Documentation/arch/xtensa/features.rst diff --git a/Documentation/xtensa/index.rst b/Documentation/arch/xtensa/index.rst index 69952446a9be..69952446a9be 100644 --- a/Documentation/xtensa/index.rst +++ b/Documentation/arch/xtensa/index.rst diff --git a/Documentation/xtensa/mmu.rst b/Documentation/arch/xtensa/mmu.rst index 450573afa31a..450573afa31a 100644 --- a/Documentation/xtensa/mmu.rst +++ b/Documentation/arch/xtensa/mmu.rst diff --git a/Documentation/arm/index.rst b/Documentation/arm/index.rst index ae42fe886f0d..8890ec4314c2 100644 --- a/Documentation/arm/index.rst +++ b/Documentation/arm/index.rst @@ -69,11 +69,9 @@ SoC-specific documents spear/overview - sti/stih416-overview sti/stih407-overview sti/stih418-overview sti/overview - sti/stih415-overview vfp/release-notes diff --git a/Documentation/arm/sti/overview.rst b/Documentation/arm/sti/overview.rst index 70743617a74f..ae16aced800f 100644 --- a/Documentation/arm/sti/overview.rst +++ b/Documentation/arm/sti/overview.rst @@ -7,22 +7,18 @@ Introduction The ST Microelectronics Multimedia and Application Processors range of CortexA9 System-on-Chip are supported by the 'STi' platform of - ARM Linux. Currently STiH415, STiH416 SOCs are supported with both - B2000 and B2020 Reference boards. + ARM Linux. Currently STiH407, STiH410 and STiH418 are supported. configuration ------------- - A generic configuration is provided for both STiH415/416, and can be used as the - default by:: - - make stih41x_defconfig + The configuration for the STi platform is supported via the multi_v7_defconfig. Layout ------ - All the files for multiple machine families (STiH415, STiH416, and STiG125) + All the files for multiple machine families (STiH407, STiH410, and STiH418) are located in the platform code contained in arch/arm/mach-sti There is a generic board board-dt.c in the mach folder which support diff --git a/Documentation/arm/sti/stih415-overview.rst b/Documentation/arm/sti/stih415-overview.rst deleted file mode 100644 index b67452d610c4..000000000000 --- a/Documentation/arm/sti/stih415-overview.rst +++ /dev/null @@ -1,14 +0,0 @@ -================ -STiH415 Overview -================ - -Introduction ------------- - - The STiH415 is the next generation of HD, AVC set-top box processors - for satellite, cable, terrestrial and IP-STB markets. - - Features: - - - ARM Cortex-A9 1.0 GHz, dual-core CPU - - SATA2x2,USB 2.0x3, PCIe, Gbit Ethernet MACx2 diff --git a/Documentation/arm/sti/stih416-overview.rst b/Documentation/arm/sti/stih416-overview.rst deleted file mode 100644 index 93f17d74d8db..000000000000 --- a/Documentation/arm/sti/stih416-overview.rst +++ /dev/null @@ -1,13 +0,0 @@ -================ -STiH416 Overview -================ - -Introduction ------------- - - The STiH416 is the next generation of HD, AVC set-top box processors - for satellite, cable, terrestrial and IP-STB markets. - - Features - - ARM Cortex-A9 1.2 GHz dual core CPU - - SATA2x2,USB 2.0x3, PCIe, Gbit Ethernet MACx2 diff --git a/Documentation/conf.py b/Documentation/conf.py index db16814f182f..37314afd1ac8 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -343,9 +343,10 @@ sys.stderr.write("Using %s theme\n" % html_theme) # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['sphinx-static'] -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -html_use_smartypants = False +# If true, Docutils "smart quotes" will be used to convert quotes and dashes +# to typographically correct entities. This will convert "--" to "—", +# which is not always what we want, so disable it. +smartquotes = False # Custom sidebar templates, maps document names to template names. # Note that the RTD theme ignores this diff --git a/Documentation/core-api/asm-annotations.rst b/Documentation/core-api/asm-annotations.rst index bc514ed59887..11c96d3f9ad6 100644 --- a/Documentation/core-api/asm-annotations.rst +++ b/Documentation/core-api/asm-annotations.rst @@ -44,7 +44,7 @@ information. In particular, on properly annotated objects, ``objtool`` can be run to check and fix the object if needed. Currently, ``objtool`` can report missing frame pointer setup/destruction in functions. It can also automatically generate annotations for the ORC unwinder -(Documentation/x86/orc-unwinder.rst) +(Documentation/arch/x86/orc-unwinder.rst) for most code. Both of these are especially important to support reliable stack traces which are in turn necessary for kernel live patching (Documentation/livepatch/livepatch.rst). diff --git a/Documentation/core-api/dma-api-howto.rst b/Documentation/core-api/dma-api-howto.rst index 828846804e25..72f6cdb6be1c 100644 --- a/Documentation/core-api/dma-api-howto.rst +++ b/Documentation/core-api/dma-api-howto.rst @@ -185,7 +185,7 @@ device struct of your device is embedded in the bus-specific device struct of your device. For example, &pdev->dev is a pointer to the device struct of a PCI device (pdev is a pointer to the PCI device struct of your device). -These calls usually return zero to indicated your device can perform DMA +These calls usually return zero to indicate your device can perform DMA properly on the machine given the address mask you provided, but they might return an error if the mask is too small to be supportable on the given system. If it returns non-zero, your device cannot perform DMA properly on diff --git a/Documentation/dev-tools/kmemleak.rst b/Documentation/dev-tools/kmemleak.rst index 5483fd39ef29..2cb00b53339f 100644 --- a/Documentation/dev-tools/kmemleak.rst +++ b/Documentation/dev-tools/kmemleak.rst @@ -227,7 +227,7 @@ Testing with kmemleak-test -------------------------- To check if you have all set up to use kmemleak, you can use the kmemleak-test -module, a module that deliberately leaks memory. Set CONFIG_DEBUG_KMEMLEAK_TEST +module, a module that deliberately leaks memory. Set CONFIG_SAMPLE_KMEMLEAK as module (it can't be used as built-in) and boot the kernel with kmemleak enabled. Load the module and perform a scan with:: diff --git a/Documentation/driver-api/clk.rst b/Documentation/driver-api/clk.rst index 3cad45d14187..93bab5336dfd 100644 --- a/Documentation/driver-api/clk.rst +++ b/Documentation/driver-api/clk.rst @@ -258,6 +258,11 @@ clocks properly but rely on them being on from the bootloader, bypassing the disabling means that the driver will remain functional while the issues are sorted out. +You can see which clocks have been disabled by booting your kernel with these +parameters:: + + tp_printk trace_event=clk:clk_disable + To bypass this disabling, include "clk_ignore_unused" in the bootargs to the kernel. diff --git a/Documentation/driver-api/device-io.rst b/Documentation/driver-api/device-io.rst index 4d2baac0311c..2c7abd234f4e 100644 --- a/Documentation/driver-api/device-io.rst +++ b/Documentation/driver-api/device-io.rst @@ -410,7 +410,7 @@ ioremap_uc() ioremap_uc() behaves like ioremap() except that on the x86 architecture without 'PAT' mode, it marks memory as uncached even when the MTRR has designated -it as cacheable, see Documentation/x86/pat.rst. +it as cacheable, see Documentation/arch/x86/pat.rst. Portable drivers should avoid the use of ioremap_uc(). diff --git a/Documentation/driver-api/firmware/fw_search_path.rst b/Documentation/driver-api/firmware/fw_search_path.rst index a360f1009fa3..d7cb1e8f0076 100644 --- a/Documentation/driver-api/firmware/fw_search_path.rst +++ b/Documentation/driver-api/firmware/fw_search_path.rst @@ -22,5 +22,10 @@ can use the file: * /sys/module/firmware_class/parameters/path -You would echo into it your custom path and firmware requested will be -searched for there first. +You would echo into it your custom path and firmware requested will be searched +for there first. Be aware that newline characters will be taken into account +and may not produce the intended effects. For instance you might want to use: + +echo -n /path/to/script > /sys/module/firmware_class/parameters/path + +to ensure that your script is being used. diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index 9d5fd9424e8b..59db0bed35e1 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -85,7 +85,7 @@ contact Bodo Bauer at bb@ricochet.net. We'll be happy to add them to this document. The latest version of this document is available online at -http://tldp.org/LDP/Linux-Filesystem-Hierarchy/html/proc.html +https://www.kernel.org/doc/html/latest/filesystems/proc.html If the above direction does not works for you, you could try the kernel mailing list at linux-kernel@vger.kernel.org and/or try to reach me at @@ -232,7 +232,7 @@ asynchronous manner and the value may not be very precise. To see a precise snapshot of a moment, you can see /proc/<pid>/smaps file and scan page table. It's slow but very precise. -.. table:: Table 1-2: Contents of the status files (as of 4.19) +.. table:: Table 1-2: Contents of the status fields (as of 4.19) ========================== =================================================== Field Content @@ -305,7 +305,7 @@ It's slow but very precise. ========================== =================================================== -.. table:: Table 1-3: Contents of the statm files (as of 2.6.8-rc3) +.. table:: Table 1-3: Contents of the statm fields (as of 2.6.8-rc3) ======== =============================== ============================== Field Content @@ -323,7 +323,7 @@ It's slow but very precise. ======== =============================== ============================== -.. table:: Table 1-4: Contents of the stat files (as of 2.6.30-rc7) +.. table:: Table 1-4: Contents of the stat fields (as of 2.6.30-rc7) ============= =============================================================== Field Content @@ -1321,9 +1321,9 @@ many times the slaves link has failed. 1.4 SCSI info ------------- -If you have a SCSI host adapter in your system, you'll find a subdirectory -named after the driver for this adapter in /proc/scsi. You'll also see a list -of all recognized SCSI devices in /proc/scsi:: +If you have a SCSI or ATA host adapter in your system, you'll find a +subdirectory named after the driver for this adapter in /proc/scsi. +You'll also see a list of all recognized SCSI devices in /proc/scsi:: >cat /proc/scsi/scsi Attached devices: @@ -1449,16 +1449,18 @@ Various pieces of information about kernel activity are available in the since the system first booted. For a quick look, simply cat the file:: > cat /proc/stat - cpu 2255 34 2290 22625563 6290 127 456 0 0 0 - cpu0 1132 34 1441 11311718 3675 127 438 0 0 0 - cpu1 1123 0 849 11313845 2614 0 18 0 0 0 - intr 114930548 113199788 3 0 5 263 0 4 [... lots more numbers ...] - ctxt 1990473 - btime 1062191376 - processes 2915 - procs_running 1 + cpu 237902850 368826709 106375398 1873517540 1135548 0 14507935 0 0 0 + cpu0 60045249 91891769 26331539 468411416 495718 0 5739640 0 0 0 + cpu1 59746288 91759249 26609887 468860630 312281 0 4384817 0 0 0 + cpu2 59489247 92985423 26904446 467808813 171668 0 2268998 0 0 0 + cpu3 58622065 92190267 26529524 468436680 155879 0 2114478 0 0 0 + intr 8688370575 8 3373 0 0 0 0 0 0 1 40791 0 0 353317 0 0 0 0 224789828 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 190974333 41958554 123983334 43 0 224593 0 0 0 <more 0's deleted> + ctxt 22848221062 + btime 1605316999 + processes 746787147 + procs_running 2 procs_blocked 0 - softirq 183433 0 21755 12 39 1137 231 21459 2263 + softirq 12121874454 100099120 3938138295 127375644 2795979 187870761 0 173808342 3072582055 52608 224184354 The very first "cpu" line aggregates the numbers in all of the other "cpuN" lines. These numbers identify the amount of time the CPU has spent performing @@ -1520,8 +1522,8 @@ softirq. Information about mounted ext4 file systems can be found in /proc/fs/ext4. Each mounted filesystem will have a directory in /proc/fs/ext4 based on its device name (i.e., /proc/fs/ext4/hdc or -/proc/fs/ext4/dm-0). The files in each per-device directory are shown -in Table 1-12, below. +/proc/fs/ext4/sda9 or /proc/fs/ext4/dm-0). The files in each per-device +directory are shown in Table 1-12, below. .. table:: Table 1-12: Files in /proc/fs/ext4/<devname> @@ -1601,12 +1603,12 @@ can inadvertently disrupt your system, it is advisable to read both documentation and source before actually making adjustments. In any case, be very careful when writing to any of these files. The entries in /proc may change slightly between the 2.1.* and the 2.2 kernel, so if there is any doubt -review the kernel documentation in the directory /usr/src/linux/Documentation. +review the kernel documentation in the directory linux/Documentation. This chapter is heavily based on the documentation included in the pre 2.2 kernels, and became part of it in version 2.2.1 of the Linux kernel. -Please see: Documentation/admin-guide/sysctl/ directory for descriptions of these -entries. +Please see: Documentation/admin-guide/sysctl/ directory for descriptions of +these entries. Summary ------- diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst index f3b344f0c0a4..769be5230210 100644 --- a/Documentation/filesystems/vfs.rst +++ b/Documentation/filesystems/vfs.rst @@ -107,7 +107,7 @@ file /proc/filesystems. struct file_system_type ----------------------- -This describes the filesystem. As of kernel 2.6.39, the following +This describes the filesystem. The following members are defined: .. code-block:: c @@ -115,14 +115,24 @@ members are defined: struct file_system_type { const char *name; int fs_flags; + int (*init_fs_context)(struct fs_context *); + const struct fs_parameter_spec *parameters; struct dentry *(*mount) (struct file_system_type *, int, - const char *, void *); + const char *, void *); void (*kill_sb) (struct super_block *); struct module *owner; struct file_system_type * next; - struct list_head fs_supers; + struct hlist_head fs_supers; + struct lock_class_key s_lock_key; struct lock_class_key s_umount_key; + struct lock_class_key s_vfs_rename_key; + struct lock_class_key s_writers_key[SB_FREEZE_LEVELS]; + + struct lock_class_key i_lock_key; + struct lock_class_key i_mutex_key; + struct lock_class_key invalidate_lock_key; + struct lock_class_key i_mutex_dir_key; }; ``name`` @@ -132,6 +142,15 @@ members are defined: ``fs_flags`` various flags (i.e. FS_REQUIRES_DEV, FS_NO_DCACHE, etc.) +``init_fs_context`` + Initializes 'struct fs_context' ->ops and ->fs_private fields with + filesystem-specific data. + +``parameters`` + Pointer to the array of filesystem parameters descriptors + 'struct fs_parameter_spec'. + More info in Documentation/filesystems/mount_api.rst. + ``mount`` the method to call when a new instance of this filesystem should be mounted @@ -148,7 +167,11 @@ members are defined: ``next`` for internal VFS use: you should initialize this to NULL - s_lock_key, s_umount_key: lockdep-specific +``fs_supers`` + for internal VFS use: hlist of filesystem instances (superblocks) + + s_lock_key, s_umount_key, s_vfs_rename_key, s_writers_key, + i_lock_key, i_mutex_key, invalidate_lock_key, i_mutex_dir_key: lockdep-specific The mount() method has the following arguments: @@ -222,33 +245,42 @@ struct super_operations ----------------------- This describes how the VFS can manipulate the superblock of your -filesystem. As of kernel 2.6.22, the following members are defined: +filesystem. The following members are defined: .. code-block:: c struct super_operations { struct inode *(*alloc_inode)(struct super_block *sb); void (*destroy_inode)(struct inode *); + void (*free_inode)(struct inode *); void (*dirty_inode) (struct inode *, int flags); - int (*write_inode) (struct inode *, int); - void (*drop_inode) (struct inode *); - void (*delete_inode) (struct inode *); + int (*write_inode) (struct inode *, struct writeback_control *wbc); + int (*drop_inode) (struct inode *); + void (*evict_inode) (struct inode *); void (*put_super) (struct super_block *); int (*sync_fs)(struct super_block *sb, int wait); + int (*freeze_super) (struct super_block *); int (*freeze_fs) (struct super_block *); + int (*thaw_super) (struct super_block *); int (*unfreeze_fs) (struct super_block *); int (*statfs) (struct dentry *, struct kstatfs *); int (*remount_fs) (struct super_block *, int *, char *); - void (*clear_inode) (struct inode *); void (*umount_begin) (struct super_block *); int (*show_options)(struct seq_file *, struct dentry *); + int (*show_devname)(struct seq_file *, struct dentry *); + int (*show_path)(struct seq_file *, struct dentry *); + int (*show_stats)(struct seq_file *, struct dentry *); ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t); ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t); - int (*nr_cached_objects)(struct super_block *); - void (*free_cached_objects)(struct super_block *, int); + struct dquot **(*get_dquots)(struct inode *); + + long (*nr_cached_objects)(struct super_block *, + struct shrink_control *); + long (*free_cached_objects)(struct super_block *, + struct shrink_control *); }; All methods are called without any locks being held, unless otherwise @@ -269,6 +301,11 @@ or bottom half). ->alloc_inode was defined and simply undoes anything done by ->alloc_inode. +``free_inode`` + this method is called from RCU callback. If you use call_rcu() + in ->destroy_inode to free 'struct inode' memory, then it's + better to release memory in this method. + ``dirty_inode`` this method is called by the VFS when an inode is marked dirty. This is specifically for the inode itself being marked dirty, @@ -296,8 +333,12 @@ or bottom half). practice of using "force_delete" in the put_inode() case, but does not have the races that the "force_delete()" approach had. -``delete_inode`` - called when the VFS wants to delete an inode +``evict_inode`` + called when the VFS wants to evict an inode. Caller does + *not* evict the pagecache or inode-associated metadata buffers; + the method has to use truncate_inode_pages_final() to get rid + of those. Caller makes sure async writeback cannot be running for + the inode while (or after) ->evict_inode() is called. Optional. ``put_super`` called when the VFS wishes to free the superblock @@ -308,14 +349,25 @@ or bottom half). superblock. The second parameter indicates whether the method should wait until the write out has been completed. Optional. +``freeze_super`` + Called instead of ->freeze_fs callback if provided. + Main difference is that ->freeze_super is called without taking + down_write(&sb->s_umount). If filesystem implements it and wants + ->freeze_fs to be called too, then it has to call ->freeze_fs + explicitly from this callback. Optional. + ``freeze_fs`` called when VFS is locking a filesystem and forcing it into a consistent state. This method is currently used by the Logical - Volume Manager (LVM). + Volume Manager (LVM) and ioctl(FIFREEZE). Optional. + +``thaw_super`` + called when VFS is unlocking a filesystem and making it writable + again after ->freeze_super. Optional. ``unfreeze_fs`` called when VFS is unlocking a filesystem and making it writable - again. + again after ->freeze_fs. Optional. ``statfs`` called when the VFS needs to get filesystem statistics. @@ -324,22 +376,37 @@ or bottom half). called when the filesystem is remounted. This is called with the kernel lock held -``clear_inode`` - called then the VFS clears the inode. Optional - ``umount_begin`` called when the VFS is unmounting a filesystem. ``show_options`` - called by the VFS to show mount options for /proc/<pid>/mounts. + called by the VFS to show mount options for /proc/<pid>/mounts + and /proc/<pid>/mountinfo. (see "Mount Options" section) +``show_devname`` + Optional. Called by the VFS to show device name for + /proc/<pid>/{mounts,mountinfo,mountstats}. If not provided then + '(struct mount).mnt_devname' will be used. + +``show_path`` + Optional. Called by the VFS (for /proc/<pid>/mountinfo) to show + the mount root dentry path relative to the filesystem root. + +``show_stats`` + Optional. Called by the VFS (for /proc/<pid>/mountstats) to show + filesystem-specific mount statistics. + ``quota_read`` called by the VFS to read from filesystem quota file. ``quota_write`` called by the VFS to write to filesystem quota file. +``get_dquots`` + called by quota to get 'struct dquot' array for a particular inode. + Optional. + ``nr_cached_objects`` called by the sb cache shrinking function for the filesystem to return the number of freeable cached objects it contains. diff --git a/Documentation/index.rst b/Documentation/index.rst index 76d1a3ec9be3..9dfdc826618c 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -99,7 +99,7 @@ Architecture-specific documentation .. toctree:: :maxdepth: 2 - arch + arch/index Other documentation diff --git a/Documentation/kernel-hacking/false-sharing.rst b/Documentation/kernel-hacking/false-sharing.rst new file mode 100644 index 000000000000..122b0e124656 --- /dev/null +++ b/Documentation/kernel-hacking/false-sharing.rst @@ -0,0 +1,206 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============= +False Sharing +============= + +What is False Sharing +===================== +False sharing is related with cache mechanism of maintaining the data +coherence of one cache line stored in multiple CPU's caches; then +academic definition for it is in [1]_. Consider a struct with a +refcount and a string:: + + struct foo { + refcount_t refcount; + ... + char name[16]; + } ____cacheline_internodealigned_in_smp; + +Member 'refcount'(A) and 'name'(B) _share_ one cache line like below:: + + +-----------+ +-----------+ + | CPU 0 | | CPU 1 | + +-----------+ +-----------+ + / | + / | + V V + +----------------------+ +----------------------+ + | A B | Cache 0 | A B | Cache 1 + +----------------------+ +----------------------+ + | | + ---------------------------+------------------+----------------------------- + | | + +----------------------+ + | | + +----------------------+ + Main Memory | A B | + +----------------------+ + +'refcount' is modified frequently, but 'name' is set once at object +creation time and is never modified. When many CPUs access 'foo' at +the same time, with 'refcount' being only bumped by one CPU frequently +and 'name' being read by other CPUs, all those reading CPUs have to +reload the whole cache line over and over due to the 'sharing', even +though 'name' is never changed. + +There are many real-world cases of performance regressions caused by +false sharing. One of these is a rw_semaphore 'mmap_lock' inside +mm_struct struct, whose cache line layout change triggered a +regression and Linus analyzed in [2]_. + +There are two key factors for a harmful false sharing: + +* A global datum accessed (shared) by many CPUs +* In the concurrent accesses to the data, there is at least one write + operation: write/write or write/read cases. + +The sharing could be from totally unrelated kernel components, or +different code paths of the same kernel component. + + +False Sharing Pitfalls +====================== +Back in time when one platform had only one or a few CPUs, hot data +members could be purposely put in the same cache line to make them +cache hot and save cacheline/TLB, like a lock and the data protected +by it. But for recent large system with hundreds of CPUs, this may +not work when the lock is heavily contended, as the lock owner CPU +could write to the data, while other CPUs are busy spinning the lock. + +Looking at past cases, there are several frequently occurring patterns +for false sharing: + +* lock (spinlock/mutex/semaphore) and data protected by it are + purposely put in one cache line. +* global data being put together in one cache line. Some kernel + subsystems have many global parameters of small size (4 bytes), + which can easily be grouped together and put into one cache line. +* data members of a big data structure randomly sitting together + without being noticed (cache line is usually 64 bytes or more), + like 'mem_cgroup' struct. + +Following 'mitigation' section provides real-world examples. + +False sharing could easily happen unless they are intentionally +checked, and it is valuable to run specific tools for performance +critical workloads to detect false sharing affecting performance case +and optimize accordingly. + + +How to detect and analyze False Sharing +======================================== +perf record/report/stat are widely used for performance tuning, and +once hotspots are detected, tools like 'perf-c2c' and 'pahole' can +be further used to detect and pinpoint the possible false sharing +data structures. 'addr2line' is also good at decoding instruction +pointer when there are multiple layers of inline functions. + +perf-c2c can capture the cache lines with most false sharing hits, +decoded functions (line number of file) accessing that cache line, +and in-line offset of the data. Simple commands are:: + + $ perf c2c record -ag sleep 3 + $ perf c2c report --call-graph none -k vmlinux + +When running above during testing will-it-scale's tlb_flush1 case, +perf reports something like:: + + Total records : 1658231 + Locked Load/Store Operations : 89439 + Load Operations : 623219 + Load Local HITM : 92117 + Load Remote HITM : 139 + + #---------------------------------------------------------------------- + 4 0 2374 0 0 0 0xff1100088366d880 + #---------------------------------------------------------------------- + 0.00% 42.29% 0.00% 0.00% 0.00% 0x8 1 1 0xffffffff81373b7b 0 231 129 5312 64 [k] __mod_lruvec_page_state [kernel.vmlinux] memcontrol.h:752 1 + 0.00% 13.10% 0.00% 0.00% 0.00% 0x8 1 1 0xffffffff81374718 0 226 97 3551 64 [k] folio_lruvec_lock_irqsave [kernel.vmlinux] memcontrol.h:752 1 + 0.00% 11.20% 0.00% 0.00% 0.00% 0x8 1 1 0xffffffff812c29bf 0 170 136 555 64 [k] lru_add_fn [kernel.vmlinux] mm_inline.h:41 1 + 0.00% 7.62% 0.00% 0.00% 0.00% 0x8 1 1 0xffffffff812c3ec5 0 175 108 632 64 [k] release_pages [kernel.vmlinux] mm_inline.h:41 1 + 0.00% 23.29% 0.00% 0.00% 0.00% 0x10 1 1 0xffffffff81372d0a 0 234 279 1051 64 [k] __mod_memcg_lruvec_state [kernel.vmlinux] memcontrol.c:736 1 + +A nice introduction for perf-c2c is [3]_. + +'pahole' decodes data structure layouts delimited in cache line +granularity. Users can match the offset in perf-c2c output with +pahole's decoding to locate the exact data members. For global +data, users can search the data address in System.map. + + +Possible Mitigations +==================== +False sharing does not always need to be mitigated. False sharing +mitigations should balance performance gains with complexity and +space consumption. Sometimes, lower performance is OK, and it's +unnecessary to hyper-optimize every rarely used data structure or +a cold data path. + +False sharing hurting performance cases are seen more frequently with +core count increasing. Because of these detrimental effects, many +patches have been proposed across variety of subsystems (like +networking and memory management) and merged. Some common mitigations +(with examples) are: + +* Separate hot global data in its own dedicated cache line, even if it + is just a 'short' type. The downside is more consumption of memory, + cache line and TLB entries. + + - Commit 91b6d3256356 ("net: cache align tcp_memory_allocated, tcp_sockets_allocated") + +* Reorganize the data structure, separate the interfering members to + different cache lines. One downside is it may introduce new false + sharing of other members. + + - Commit 802f1d522d5f ("mm: page_counter: re-layout structure to reduce false sharing") + +* Replace 'write' with 'read' when possible, especially in loops. + Like for some global variable, use compare(read)-then-write instead + of unconditional write. For example, use:: + + if (!test_bit(XXX)) + set_bit(XXX); + + instead of directly "set_bit(XXX);", similarly for atomic_t data:: + + if (atomic_read(XXX) == AAA) + atomic_set(XXX, BBB); + + - Commit 7b1002f7cfe5 ("bcache: fixup bcache_dev_sectors_dirty_add() multithreaded CPU false sharing") + - Commit 292648ac5cf1 ("mm: gup: allow FOLL_PIN to scale in SMP") + +* Turn hot global data to 'per-cpu data + global data' when possible, + or reasonably increase the threshold for syncing per-cpu data to + global data, to reduce or postpone the 'write' to that global data. + + - Commit 520f897a3554 ("ext4: use percpu_counters for extent_status cache hits/misses") + - Commit 56f3547bfa4d ("mm: adjust vm_committed_as_batch according to vm overcommit policy") + +Surely, all mitigations should be carefully verified to not cause side +effects. To avoid introducing false sharing when coding, it's better +to: + +* Be aware of cache line boundaries +* Group mostly read-only fields together +* Group things that are written at the same time together +* Separate frequently read and frequently written fields on + different cache lines. + +and better add a comment stating the false sharing consideration. + +One note is, sometimes even after a severe false sharing is detected +and solved, the performance may still have no obvious improvement as +the hotspot switches to a new place. + + +Miscellaneous +============= +One open issue is that kernel has an optional data structure +randomization mechanism, which also randomizes the situation of cache +line sharing of data members. + + +.. [1] https://en.wikipedia.org/wiki/False_sharing +.. [2] https://lore.kernel.org/lkml/CAHk-=whoqV=cX5VC80mmR9rr+Z+yQ6fiQZm36Fb-izsanHg23w@mail.gmail.com/ +.. [3] https://joemario.github.io/blog/2016/09/01/c2c-blog/ diff --git a/Documentation/kernel-hacking/index.rst b/Documentation/kernel-hacking/index.rst index f53027652290..79c03bac99a2 100644 --- a/Documentation/kernel-hacking/index.rst +++ b/Documentation/kernel-hacking/index.rst @@ -9,3 +9,4 @@ Kernel Hacking Guides hacking locking + false-sharing diff --git a/Documentation/mm/physical_memory.rst b/Documentation/mm/physical_memory.rst index 1bc888d36ea1..531e73b003dd 100644 --- a/Documentation/mm/physical_memory.rst +++ b/Documentation/mm/physical_memory.rst @@ -19,7 +19,7 @@ a bank of memory very suitable for DMA near peripheral devices. Each bank is called a node and the concept is represented under Linux by a ``struct pglist_data`` even if the architecture is UMA. This structure is -always referenced to by it's typedef ``pg_data_t``. ``A pg_data_t`` structure +always referenced by its typedef ``pg_data_t``. A ``pg_data_t`` structure for a particular node can be referenced by ``NODE_DATA(nid)`` macro where ``nid`` is the ID of that node. @@ -114,6 +114,25 @@ RAM equally split between two nodes, there will be ``ZONE_DMA32``, | DMA32 | NORMAL | MOVABLE | | NORMAL | MOVABLE | +---------+----------+-----------+ +------------+-------------+ + +Memory banks may belong to interleaving nodes. In the example below an x86 +machine has 16 Gbytes of RAM in 4 memory banks, even banks belong to node 0 +and odd banks belong to node 1:: + + + 0 4G 8G 12G 16G + +-------------+ +-------------+ +-------------+ +-------------+ + | node 0 | | node 1 | | node 0 | | node 1 | + +-------------+ +-------------+ +-------------+ +-------------+ + + 0 16M 4G + +-----+-------+ +-------------+ +-------------+ +-------------+ + | DMA | DMA32 | | NORMAL | | NORMAL | | NORMAL | + +-----+-------+ +-------------+ +-------------+ +-------------+ + +In this case node 0 will span from 0 to 12 Gbytes and node 1 will span from +4 to 16 Gbytes. + .. _nodes: Nodes diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 007e49ef6cec..6db37a46d305 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -1267,5 +1267,5 @@ 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/ -Kernel :ref:`process/coding-style.rst <codingstyle>`, by greg@kroah.com at OLS 2002: +Kernel CodingStyle, by greg@kroah.com at OLS 2002: http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/process/contribution-maturity-model.rst b/Documentation/process/contribution-maturity-model.rst new file mode 100644 index 000000000000..b87ab34de22c --- /dev/null +++ b/Documentation/process/contribution-maturity-model.rst @@ -0,0 +1,109 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================== +Linux Kernel Contribution Maturity Model +======================================== + + +Background +========== + +As a part of the 2021 Linux Kernel Maintainers’ Summit, there was a +`discussion <https://lwn.net/Articles/870581/>`_ about the challenges in +recruiting kernel maintainers as well as maintainer succession. Some of +the conclusions from that discussion included that companies which are a +part of the Linux Kernel community need to allow engineers to be +maintainers as part of their job, so they can grow into becoming +respected leaders and eventually, kernel maintainers. To support a +strong talent pipeline, developers should be allowed and encouraged to +take on upstream contributions such as reviewing other people’s patches, +refactoring kernel infrastructure, and writing documentation. + +To that end, the Linux Foundation Technical Advisory Board (TAB) +proposes this Linux Kernel Contribution Maturity Model. These common +expectations for upstream community engagement aim to increase the +influence of individual developers, increase the collaboration of +organizations, and improve the overall health of the Linux Kernel +ecosystem. + +The TAB urges organizations to continuously evaluate their Open Source +maturity model and commit to improvements to align with this model. To +be effective, this evaluation should incorporate feedback from across +the organization, including management and developers at all seniority +levels. In the spirit of Open Source, we encourage organizations to +publish their evaluations and plans to improve their engagement with the +upstream community. + +Level 0 +======= + +* Software Engineers are not allowed to contribute patches to the Linux + kernel. + + +Level 1 +======= + +* Software Engineers are allowed to contribute patches to the Linux + kernel, either as part of their job responsibilities or on their own + time. + +Level 2 +======= + +* Software Engineers are expected to contribute to the Linux Kernel as + part of their job responsibilities. +* Software Engineers will be supported to attend Linux-related + conferences as a part of their job. +* A Software Engineer’s upstream code contributions will be considered + in promotion and performance reviews. + +Level 3 +======= + +* Software Engineers are expected to review patches (including patches + authored by engineers from other companies) as part of their job + responsibilities +* Contributing presentations or papers to Linux-related or academic + conferences (such those organized by the Linux Foundation, Usenix, + ACM, etc.), are considered part of an engineer’s work. +* A Software Engineer’s community contributions will be considered in + promotion and performance reviews. +* Organizations will regularly report metrics of their open source + contributions and track these metrics over time. These metrics may be + published only internally within the organization, or at the + organization’s discretion, some or all may be published externally. + Metrics that are strongly suggested include: + + * The number of upstream kernel contributions by team or organization + (e.g., all people reporting up to a manager, director, or VP). + * The percentage of kernel developers who have made upstream + contributions relative to the total kernel developers in the + organization. + * The time interval between kernels used in the organization’s servers + and/or products, and the publication date of the upstream kernel + upon which the internal kernel is based. + * The number of out-of-tree commits present in internal kernels. + +Level 4 +======= + +* Software Engineers are encouraged to spend a portion of their work + time focused on Upstream Work, which is defined as reviewing patches, + serving on program committees, improving core project infrastructure + such as writing or maintaining tests, upstream tech debt reduction, + writing documentation, etc. +* Software Engineers are supported in helping to organize Linux-related + conferences. +* Organizations will consider community member feedback in official + performance reviews. + +Level 5 +======= + +* Upstream kernel development is considered a formal job position, with + at least a third of the engineer’s time spent doing Upstream Work. +* Organizations will actively seek out community member feedback as a + factor in official performance reviews. +* Organizations will regularly report internally on the ratio of + Upstream Work to work focused on directly pursuing business goals. diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 565df595152e..b501cd977053 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -57,6 +57,7 @@ Other guides to the community that are of interest to most developers are: deprecated maintainers researcher-guidelines + contribution-maturity-model These are some overall technical guides that have been put here for now for lack of a better place. diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst index 1c6e2ab92f4e..46f927aae6eb 100644 --- a/Documentation/process/kernel-docs.rst +++ b/Documentation/process/kernel-docs.rst @@ -75,13 +75,39 @@ On-line docs Published books --------------- + * Title: **Linux Kernel Debugging: Leverage proven tools and advanced techniques to effectively debug Linux kernels and kernel modules** + + :Author: Kaiwan N Billimoria + :Publisher: Packt Publishing Ltd + :Date: August, 2022 + :Pages: 638 + :ISBN: 978-1801075039 + :Notes: Debugging book + * Title: **Linux Kernel Programming: A Comprehensive Guide to Kernel Internals, Writing Kernel Modules, and Kernel Synchronization** - :Author: Kaiwan N. Billimoria - :Publisher: Packt Publishing Ltd - :Date: 2021 - :Pages: 754 - :ISBN: 978-1789953435 + :Author: Kaiwan N Billimoria + :Publisher: Packt Publishing Ltd + :Date: March, 2021 + :Pages: 754 + :ISBN: 978-1789953435 + + * Title: **Linux Kernel Programming Part 2 - Char Device Drivers and Kernel Synchronization: Create user-kernel interfaces, work with peripheral I/O, and handle hardware interrupts** + + :Author: Kaiwan N Billimoria + :Publisher: Packt Publishing Ltd + :Date: March, 2021 + :Pages: 452 + :ISBN: 978-1801079518 + + * Title: **Linux System Programming: Talking Directly to the Kernel and C Library** + + :Author: Robert Love + :Publisher: O'Reilly Media + :Date: June, 2013 + :Pages: 456 + :ISBN: 978-1449339531 + :Notes: Foundational book * Title: **Linux Kernel Development, 3rd Edition** diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst index 572a3289c9cb..178c95fd17dc 100644 --- a/Documentation/process/maintainer-tip.rst +++ b/Documentation/process/maintainer-tip.rst @@ -128,8 +128,8 @@ uppercase letter and should be written in imperative tone. Changelog ^^^^^^^^^ -The general rules about changelogs in the process documentation, see -:ref:`Documentation/process/ <submittingpatches>`, apply. +The general rules about changelogs in the :ref:`Submitting patches guide +<describe_changes>`, apply. The tip tree maintainers set value on following these rules, especially on the request to write changelogs in imperative mood and not impersonating diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 828997bc9ff9..7a5619fecb38 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -223,20 +223,17 @@ patch. Select the recipients for your patch ------------------------------------ -You should always copy the appropriate subsystem maintainer(s) on any patch -to code that they maintain; look through the MAINTAINERS file and the -source code revision history to see who those maintainers are. The -script scripts/get_maintainer.pl can be very useful at this step (pass paths to -your patches as arguments to scripts/get_maintainer.pl). If you cannot find a +You should always copy the appropriate subsystem maintainer(s) and list(s) on +any patch to code that they maintain; look through the MAINTAINERS file and the +source code revision history to see who those maintainers are. The script +scripts/get_maintainer.pl can be very useful at this step (pass paths to your +patches as arguments to scripts/get_maintainer.pl). If you cannot find a maintainer for the subsystem you are working on, Andrew Morton (akpm@linux-foundation.org) serves as a maintainer of last resort. -You should also normally choose at least one mailing list to receive a copy -of your patch set. linux-kernel@vger.kernel.org should be used by default -for all patches, but the volume on that list has caused a number of -developers to tune it out. Look in the MAINTAINERS file for a -subsystem-specific list; your patch will probably get more attention there. -Please do not spam unrelated lists, though. +linux-kernel@vger.kernel.org should be used by default for all patches, but the +volume on that list has caused a number of developers to tune it out. Please +do not spam unrelated lists and unrelated people, though. Many kernel-related lists are hosted on vger.kernel.org; you can find a list of them at http://vger.kernel.org/vger-lists.html. There are diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst index b927fb2b94dc..e8bca5fea7cc 100644 --- a/Documentation/trace/ftrace.rst +++ b/Documentation/trace/ftrace.rst @@ -3510,7 +3510,7 @@ directories, the rmdir will fail with EBUSY. Stack trace ----------- Since the kernel has a fixed sized stack, it is important not to -waste it in functions. A kernel developer must be conscience of +waste it in functions. A kernel developer must be conscious of what they allocate on the stack. If they add too much, the system can be in danger of a stack overflow, and corruption will occur, usually leading to a system panic. diff --git a/Documentation/translations/it_IT/core-api/symbol-namespaces.rst b/Documentation/translations/it_IT/core-api/symbol-namespaces.rst index 0f6898860d6d..17abc25ee4c1 100644 --- a/Documentation/translations/it_IT/core-api/symbol-namespaces.rst +++ b/Documentation/translations/it_IT/core-api/symbol-namespaces.rst @@ -1,7 +1,6 @@ .. include:: ../disclaimer-ita.rst -:Original: :doc:`../../../core-api/symbol-namespaces` -:Translator: Federico Vaga <federico.vaga@vaga.pv.it> +:Original: Documentation/core-api/symbol-namespaces.rst =========================== Spazio dei nomi dei simboli diff --git a/Documentation/translations/it_IT/doc-guide/parse-headers.rst b/Documentation/translations/it_IT/doc-guide/parse-headers.rst index 993d549ee2b8..c7076a21667a 100644 --- a/Documentation/translations/it_IT/doc-guide/parse-headers.rst +++ b/Documentation/translations/it_IT/doc-guide/parse-headers.rst @@ -1,7 +1,6 @@ .. include:: ../disclaimer-ita.rst -.. note:: Per leggere la documentazione originale in inglese: - :ref:`Documentation/doc-guide/index.rst <doc_guide>` +:Original: Documentation/doc-guide/index.rst ========================================= Includere gli i file di intestazione uAPI @@ -190,7 +189,7 @@ COPYRIGHT Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>. -Licenza GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>. +Licenza GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>. Questo è software libero: siete liberi di cambiarlo e ridistribuirlo. Non c'è alcuna garanzia, nei limiti permessi dalla legge. diff --git a/Documentation/translations/it_IT/index.rst b/Documentation/translations/it_IT/index.rst index fc5f39814e83..b95dfa1ded04 100644 --- a/Documentation/translations/it_IT/index.rst +++ b/Documentation/translations/it_IT/index.rst @@ -2,9 +2,9 @@ .. _it_linux_doc: -=================== -Traduzione italiana -=================== +================================== +La documentazione del kernel Linux +================================== .. raw:: latex @@ -12,6 +12,18 @@ Traduzione italiana :manutentore: Federico Vaga <federico.vaga@vaga.pv.it> +Questo è il livello principale della documentazione del kernel in +lingua italiana. La traduzione è incompleta, noterete degli avvisi +che vi segnaleranno la mancanza di una traduzione o di un gruppo di +traduzioni. + +Più in generale, la documentazione, come il kernel stesso, sono in +costante sviluppo; particolarmente vero in quanto stiamo lavorando +alla riorganizzazione della documentazione in modo più coerente. +I miglioramenti alla documentazione sono sempre i benvenuti; per cui, +se vuoi aiutare, iscriviti alla lista di discussione linux-doc presso +vger.kernel.org. + .. _it_disclaimer: Avvertenze @@ -54,23 +66,8 @@ Se avete bisogno d'aiuto per comunicare con la comunità Linux ma non vi sentite a vostro agio nello scrivere in inglese, potete chiedere aiuto al manutentore della traduzione. -La documentazione del kernel Linux -================================== - -Questo è il livello principale della documentazione del kernel in -lingua italiana. La traduzione è incompleta, noterete degli avvisi -che vi segnaleranno la mancanza di una traduzione o di un gruppo di -traduzioni. - -Più in generale, la documentazione, come il kernel stesso, sono in -costante sviluppo; particolarmente vero in quanto stiamo lavorando -alla riorganizzazione della documentazione in modo più coerente. -I miglioramenti alla documentazione sono sempre i benvenuti; per cui, -se vuoi aiutare, iscriviti alla lista di discussione linux-doc presso -vger.kernel.org. - Lavorare con la comunità di sviluppo ------------------------------------- +==================================== Le guide fondamentali per l'interazione con la comunità di sviluppo del kernel e su come vedere il proprio lavoro integrato. @@ -85,7 +82,7 @@ su come vedere il proprio lavoro integrato. Manuali sull'API interna ------------------------- +======================== Di seguito una serie di manuali per gli sviluppatori che hanno bisogno di interfacciarsi con il resto del kernel. @@ -96,7 +93,7 @@ interfacciarsi con il resto del kernel. core-api/index Strumenti e processi per lo sviluppo ------------------------------------- +==================================== Di seguito una serie di manuali contenenti informazioni utili a tutti gli sviluppatori del kernel. @@ -109,7 +106,7 @@ sviluppatori del kernel. kernel-hacking/index Documentazione per gli utenti ------------------------------ +============================= Di seguito una serie di manuali per gli *utenti* del kernel - ovvero coloro che stanno cercando di farlo funzionare al meglio per un dato sistema, ma anche @@ -120,16 +117,16 @@ Consultate anche `Linux man pages <https://www.kernel.org/doc/man-pages/>`_, che vengono mantenuti separatamente dalla documentazione del kernel Linux Documentazione relativa ai firmware ------------------------------------ +=================================== Di seguito informazioni sulle aspettative del kernel circa i firmware. Documentazione specifica per architettura ------------------------------------------ +========================================= Documentazione varia --------------------- +==================== Ci sono documenti che sono difficili da inserire nell'attuale organizzazione della documentazione; altri hanno bisogno di essere migliorati e/o convertiti diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst index 05d362b16bf0..a9e781d2e323 100644 --- a/Documentation/translations/it_IT/kernel-hacking/locking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst @@ -1029,6 +1029,11 @@ Dato che questo è un problema abbastanza comune con una propensione alle corse critiche, dovreste usare timer_delete_sync() (``include/linux/timer.h``) per gestire questo caso. +Prima di rilasciare un temporizzatore dovreste chiamare la funzione +timer_shutdown() o timer_shutdown_sync() di modo che non venga più ricarmato. +Ogni successivo tentativo di riarmare il temporizzatore verrà silenziosamente +ignorato. + Velocità della sincronizzazione =============================== diff --git a/Documentation/translations/it_IT/process/5.Posting.rst b/Documentation/translations/it_IT/process/5.Posting.rst index cf92a16ed7e5..a7e2a3238415 100644 --- a/Documentation/translations/it_IT/process/5.Posting.rst +++ b/Documentation/translations/it_IT/process/5.Posting.rst @@ -265,15 +265,18 @@ Le etichette in uso più comuni sono: :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>` - Reported-by: menziona l'utente che ha riportato il problema corretto da - questa patch; quest'etichetta viene usata per dare credito alle persone - che hanno verificato il codice e ci hanno fatto sapere quando le cose non - funzionavano correttamente. + questa patch; quest'etichetta viene usata per dare credito alle persone che + hanno verificato il codice e ci hanno fatto sapere quando le cose non + funzionavano correttamente. Se esiste un rapporto disponibile sul web, allora + L'etichetta dovrebbe essere seguita da un collegamento al suddetto rapporto. - Cc: la persona menzionata ha ricevuto una copia della patch ed ha avuto l'opportunità di commentarla. -State attenti ad aggiungere queste etichette alla vostra patch: solo -"Cc:" può essere aggiunta senza il permesso esplicito della persona menzionata. +State attenti ad aggiungere queste etichette alla vostra patch: solo "Cc:" può +essere aggiunta senza il permesso esplicito della persona menzionata. Il più +delle volte anche Reported-by: va bene, ma è sempre meglio chiedere specialmente +se il baco è stato riportato in una comunicazione privata. Inviare la modifica ------------------- diff --git a/Documentation/translations/it_IT/process/changes.rst b/Documentation/translations/it_IT/process/changes.rst index 473ec2cc558e..f37c53f8b524 100644 --- a/Documentation/translations/it_IT/process/changes.rst +++ b/Documentation/translations/it_IT/process/changes.rst @@ -36,7 +36,7 @@ GNU C 5.1 gcc --version Clang/LLVM (optional) 11.0.0 clang --version GNU make 3.81 make --version bash 4.2 bash --version -binutils 2.23 ld -v +binutils 2.25 ld -v flex 2.5.35 flex --version bison 2.0 bison --version pahole 1.16 pahole --version @@ -97,7 +97,7 @@ Questo richiede bash 4.2 o successivo. Binutils -------- -Per generare il kernel è necessario avere Binutils 2.23 o superiore. +Per generare il kernel è necessario avere Binutils 2.25 o superiore. pkg-config ---------- diff --git a/Documentation/translations/it_IT/process/clang-format.rst b/Documentation/translations/it_IT/process/clang-format.rst index 77eac809a639..29f83c198025 100644 --- a/Documentation/translations/it_IT/process/clang-format.rst +++ b/Documentation/translations/it_IT/process/clang-format.rst @@ -40,7 +40,7 @@ Linux più popolari. Cercate ``clang-format`` nel vostro repositorio. Altrimenti, potete scaricare una versione pre-generata dei binari di LLVM/clang oppure generarlo dai codici sorgenti: - http://releases.llvm.org/download.html + https://releases.llvm.org/download.html Troverete più informazioni ai seguenti indirizzi: diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst index a393ee4182af..5f244e16f511 100644 --- a/Documentation/translations/it_IT/process/coding-style.rst +++ b/Documentation/translations/it_IT/process/coding-style.rst @@ -1204,10 +1204,10 @@ ISBN 0-201-61586-X. Manuali GNU - nei casi in cui sono compatibili con K&R e questo documento - per indent, cpp, gcc e i suoi dettagli interni, tutto disponibile qui -http://www.gnu.org/manual/ +https://www.gnu.org/manual/ WG14 è il gruppo internazionale di standardizzazione per il linguaggio C, -URL: http://www.open-std.org/JTC1/SC22/WG14/ +URL: https://www.open-std.org/JTC1/SC22/WG14/ -Kernel process/coding-style.rst, by greg@kroah.com at OLS 2002: +Kernel CodingStyle, by greg@kroah.com at OLS 2002: http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/translations/it_IT/process/deprecated.rst b/Documentation/translations/it_IT/process/deprecated.rst index febf83897783..57b501f0dfa4 100644 --- a/Documentation/translations/it_IT/process/deprecated.rst +++ b/Documentation/translations/it_IT/process/deprecated.rst @@ -332,7 +332,7 @@ zero come risultato:: Il valore di ``size`` nell'ultima riga sarà ``zero``, quando uno invece si aspetterebbe che il suo valore sia la dimensione totale in -byte dell'allocazione dynamica che abbiamo appena fatto per l'array +byte dell'allocazione dinamica che abbiamo appena fatto per l'array ``items``. Qui un paio di esempi reali del problema: `collegamento 1 <https://git.kernel.org/linus/f2cd32a443da694ac4e28fbf4ac6f9d5cc63a539>`_, `collegamento 2 @@ -381,4 +381,29 @@ combinazione con struct_size() e flex_array_size():: instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL); instance->count = count; - memcpy(instance->items, source, flex_array_size(instance, items, instance->count)); + memcpy(instance->items, source, flex_array_size(instance, items, instance->count)); + +Ci sono due casi speciali dove è necessario usare la macro DECLARE_FLEX_ARRAY() +(da notare che la stessa macro è chiamata __DECLARE_FLEX_ARRAY() nei file di +intestazione UAPI). Uno è quando l'array flessibile è l'unico elemento di una +struttura, e l'altro è quando è parti un unione. Per motivi non tecnici, entrambi +i casi d'uso non sono permessi dalla specifica C99. Per esempio, per +convertire il seguente codice:: + + struct something { + ... + union { + struct type1 one[0]; + struct type2 two[0]; + }; + }; + +La macro di supporto dev'essere usata:: + + struct something { + ... + union { + DECLARE_FLEX_ARRAY(struct type1, one); + DECLARE_FLEX_ARRAY(struct type2, two); + }; + }; diff --git a/Documentation/translations/it_IT/process/email-clients.rst b/Documentation/translations/it_IT/process/email-clients.rst index 970671cd91af..76ca3226c8cd 100644 --- a/Documentation/translations/it_IT/process/email-clients.rst +++ b/Documentation/translations/it_IT/process/email-clients.rst @@ -364,3 +364,28 @@ un editor esterno. Un altro problema è che Gmail usa la codifica base64 per tutti quei messaggi che contengono caratteri non ASCII. Questo include cose tipo i nomi europei. + +Proton Mail +*********** + +Il servizio Proton Mail ha una funzionalità che cripta tutti i messaggi verso +ogni destinatario per cui è possibile trovare una chiave usando il *Web Key +Directory* (WKD). Il servizio kernel.org pubblica il WKD per ogni sviluppatore +in possesso di un conto kernel.org. Di conseguenza, tutti i messaggi inviati +usando Proton Mail verso indirizzi kernel.org verranno criptati. + +Proton Mail non fornisce alcun meccanismo per disabilitare questa funzionalità +perché verrebbe considerato un problema per la riservatezza. Questa funzionalità +è attiva anche quando si inviano messaggi usando il Proton Mail Bridge. Dunque +tutta la posta in uscita verrà criptata, incluse le patch inviate con ``git +send-email``. + +I messaggi criptati sono una fonte di problemi; altri sviluppatori potrebbero +non aver configurato i loro programmi, o strumenti, per gestire messaggi +criptati; inoltre, alcuni programmi di posta elettronica potrebbero criptare le +risposte a messaggi criptati per tutti i partecipanti alla discussione, inclusa +la lista di discussione stessa. + +A meno che non venga introdotta una maniera per disabilitare questa +funzionalità, non è consigliato usare Proton Mail per contribuire allo sviluppo +del kernel. diff --git a/Documentation/translations/it_IT/process/index.rst b/Documentation/translations/it_IT/process/index.rst index 25602c1a97d1..cd7977905fb8 100644 --- a/Documentation/translations/it_IT/process/index.rst +++ b/Documentation/translations/it_IT/process/index.rst @@ -10,6 +10,7 @@ .. _it_process_index: +=============================================== Lavorare con la comunità di sviluppo del kernel =============================================== diff --git a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst index 5526bcabeb0a..cdc43c4a9b0b 100644 --- a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst +++ b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst @@ -68,42 +68,24 @@ stesso. Strumenti PGP ============= -Usare GnuPG v2 --------------- +Usare GnuPG 2.2 o successivo +---------------------------- La vostra distribuzione potrebbe avere già installato GnuPG, dovete solo -verificare che stia utilizzando la versione 2.x e non la serie 1.4 -- -molte distribuzioni forniscono entrambe, di base il comando ''gpg'' -invoca GnuPG v.1. Per controllate usate:: +verificare che stia utilizzando la versione abbastanza recente. Per controllate +usate:: $ gpg --version | head -n1 -Se visualizzate ``gpg (GnuPG) 1.4.x``, allora state usando GnuPG v.1. -Provate il comando ``gpg2`` (se non lo avete, potreste aver bisogno -di installare il pacchetto gnupg2):: - - $ gpg2 --version | head -n1 - -Se visualizzate ``gpg (GnuPG) 2.x.x``, allora siete pronti a partire. -Questa guida assume che abbiate la versione 2.2.(o successiva) di GnuPG. -Se state usando la versione 2.0, alcuni dei comandi indicati qui non -funzioneranno, in questo caso considerate un aggiornamento all'ultima versione, -la 2.2. Versioni di gnupg-2.1.11 e successive dovrebbero essere compatibili -per gli obiettivi di questa guida. - -Se avete entrambi i comandi: ``gpg`` e ``gpg2``, assicuratevi di utilizzare -sempre la versione V2, e non quella vecchia. Per evitare errori potreste creare -un alias:: - - $ alias gpg=gpg2 - -Potete mettere questa opzione nel vostro ``.bashrc`` in modo da essere sicuri. +Se state utilizzando la version 2.2 o successiva, allora siete pronti a partire. +Se invece state usando una versione precedente, allora alcuni comandi elencati +in questa guida potrebbero non funzionare. Configurare le opzioni di gpg-agent ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ L'agente GnuPG è uno strumento di aiuto che partirà automaticamente ogni volta -che userete il comando ``gpg`` e funzionerà in background con l'obiettivo di +che userete il comando ``gpg`` e funzionerà in *background* con l'obiettivo di individuare la passphrase. Ci sono due opzioni che dovreste conoscere per personalizzare la scadenza della passphrase nella cache: @@ -131,19 +113,7 @@ valori:: riguarda vecchie le versioni di GnuPG, poiché potrebbero non svolgere più bene il loro compito. -Impostare un *refresh* con cronjob -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Potreste aver bisogno di rinfrescare regolarmente il vostro portachiavi in -modo aggiornare le chiavi pubbliche di altre persone, lavoro che è svolto -al meglio con un cronjob giornaliero:: - - @daily /usr/bin/gpg2 --refresh >/dev/null 2>&1 - -Controllate il percorso assoluto del vostro comando ``gpg`` o ``gpg2`` e usate -il comando ``gpg2`` se per voi ``gpg`` corrisponde alla versione GnuPG v.1. - -.. _it_master_key: +.. _it_protect_your_key: Proteggere la vostra chiave PGP primaria ======================================== @@ -155,55 +125,62 @@ al documento "`Protecting Code Integrity`_" che abbiamo menzionato prima. Dovreste inoltre creare una nuova chiave se quella attuale è inferiore a 2048 bit (RSA). -Chiave principale o sottochiavi -------------------------------- - -Le sottochiavi sono chiavi PGP totalmente indipendenti, e sono collegate alla -chiave principale attraverso firme certificate. È quindi importante -comprendere i seguenti punti: - -1. Non ci sono differenze tecniche tra la chiave principale e la sottochiave. -2. In fase di creazione, assegniamo limitazioni funzionali ad ogni chiave - assegnando capacità specifiche. -3. Una chiave PGP può avere 4 capacità: +Le sottochiavi PGP +------------------ - - **[S]** può essere usata per firmare - - **[E]** può essere usata per criptare - - **[A]** può essere usata per autenticare - - **[C]** può essere usata per certificare altre chiavi +Raramente le chiavi PGP sono composte da una singola coppia -- solitamente, sono +una collezione di sottochiavi indipendenti usate per diversi scopi in funzione +delle capacità assegnate al momento della creazione. Una chiave PGP può avere +quattro capacità: + +- **[S]** può essere usata per firmare +- **[E]** può essere usata per criptare +- **[A]** può essere usata per autenticare +- **[C]** può essere usata per certificare altre chiavi + +La chiave con la capacità **[C]** viene spesso chiamata chiave "passepartout" +(*master key*), ma è una terminologia fuorviante perché lascia intendere che la +chiave di certificato possa essere usate in sostituzione delle altre (proprio +come le vere chiavi passpartout in grado di aprire diverse serrature). Dato che +questo non è il caso, per evitare fraintendimenti, in questa guida ci riferiremo +a questa chiave chiamandola "La chiave di certificazione". + +I seguenti punti sono molto importanti: + +1. Tutte le sottochiavi sono indipendenti. Se perdete una sottochiave privata + non potrete recuperarla usando le altre. +2. Ad eccezione della chiave di certificazione, ci possono essere più + sottochiavi con le stesse capacità (per esempio, potete avere 2 sottochiavi + per criptare, 3 per firmare, ma solo una per una sola per certificare). Tutte + le sottochiavi sono indipendenti -- un messaggio criptato usando una chiave + **[E]** non può essere decriptato usano altre sottochiavi **[E]**. +3. Una sottochiave può avere più capacità (per esempio, la chiave **[C]** può + anche essere una chiave **[S]**). + +La chiave con capacità **[C]** (certificazione) è la sola che può essere usata +per indicare relazioni fra chiavi. Solo la chiave **[C]** può essere usata per: + +- aggiungere o revocare altre chiavi (sottochiavi) che hanno capacità S/E/A; +- aggiungere, modificare o eliminare le identità (unids) associate alla chiave; +- aggiungere o modificare la propria data di scadenza o delle sottochiavi; +- firmare le chiavi di altre persone a scopo di creare una rete di fiducia. -4. Una singola chiave può avere più capacità -5. Una sottochiave è completamente indipendente dalla chiave principale. - Un messaggio criptato con la sottochiave non può essere decrittato con - quella principale. Se perdete la vostra sottochiave privata, non può - essere rigenerata in nessun modo da quella principale. +Di base, alla creazione di nuove chiavi, GnuPG genera quanto segue: -La chiave con capacità **[C]** (certify) è identificata come la chiave -principale perché è l'unica che può essere usata per indicare la relazione -con altre chiavi. Solo la chiave **[C]** può essere usata per: +- Una chiave la capacità di certificazione che quella di firma (**[SC]**) +- Una sottochiave separata con capacità di criptare (**[E]**) -- Aggiungere o revocare altre chiavi (sottochiavi) che hanno capacità S/E/A -- Aggiungere, modificare o eliminare le identità (unids) associate alla chiave -- Aggiungere o modificare la data di termine di sé stessa o di ogni sottochiave -- Firmare le chiavi di altre persone a scopo di creare una rete di fiducia -Di base, alla creazione di nuove chiavi, GnuPG genera quanto segue: -- Una chiave madre che porta sia la capacità di certificazione che quella - di firma (**[SC]**) -- Una sottochiave separata con capacità di criptaggio (**[E]**) -Se avete usato i parametri di base per generare la vostra chiave, quello +Se avete usato i parametri predefiniti per generare la vostra chiave, quello sarà il risultato. Potete verificarlo utilizzando ``gpg --list-secret-keys``, per esempio:: - sec rsa2048 2018-01-23 [SC] [expires: 2020-01-23] + sec ed25519 2022-12-20 [SC] [expires: 2024-12-19] 000000000000000000000000AAAABBBBCCCCDDDD uid [ultimate] Alice Dev <adev@kernel.org> - ssb rsa2048 2018-01-23 [E] [expires: 2020-01-23] - -Qualsiasi chiave che abbia la capacità **[C]** è la vostra chiave madre, -indipendentemente da quali altre capacità potreste averle assegnato. + ssb cv25519 2022-12-20 [E] [expires: 2024-12-19] La lunga riga sotto la voce ``sec`` è la vostra impronta digitale -- negli esempi che seguono, quando vedere ``[fpr]`` ci si riferisce a questa @@ -238,20 +215,10 @@ possano ricevere la vostra nuova sottochiave:: $ gpg --send-key [fpr] .. note:: Supporto ECC in GnuPG - GnuPG 2.1 e successivi supportano pienamente *Elliptic Curve Cryptography*, - con la possibilità di combinare sottochiavi ECC con le tradizionali chiavi - primarie RSA. Il principale vantaggio della crittografia ECC è che è molto - più veloce da calcolare e crea firme più piccole se confrontate byte per - byte con le chiavi RSA a più di 2048 bit. A meno che non pensiate di - utilizzare un dispositivo smartcard che non supporta le operazioni ECC, vi - raccomandiamo ti creare sottochiavi di firma ECC per il vostro lavoro col - kernel. - - Se per qualche ragione preferite rimanere con sottochiavi RSA, nel comando - precedente, sostituite "ed25519" con "rsa2048". In aggiunta, se avete - intenzione di usare un dispositivo hardware che non supporta le chiavi - ED25519 ECC, come la Nitrokey Pro o la Yubikey, allora dovreste usare - "nistp256" al posto di "ed25519". + + Tenete presente che se avete intenzione di usare un dispositivo che non + supporta chiavi ED25519 ECC, allora dovreste usare "nistp256" al posto di + "ed25519". Più avanti ci sono alcune raccomandazioni per i dispositivi. Copia di riserva della chiave primaria per gestire il recupero da disastro -------------------------------------------------------------------------- @@ -360,13 +327,13 @@ Per prima cosa, identificate il keygrip della vostra chiave primaria:: L'output assomiglierà a questo:: - pub rsa2048 2018-01-24 [SC] [expires: 2020-01-24] + pub ed25519 2022-12-20 [SC] [expires: 2022-12-19] 000000000000000000000000AAAABBBBCCCCDDDD Keygrip = 1111000000000000000000000000000000000000 uid [ultimate] Alice Dev <adev@kernel.org> - sub rsa2048 2018-01-24 [E] [expires: 2020-01-24] + sub cv25519 2022-12-20 [E] [expires: 2022-12-19] Keygrip = 2222000000000000000000000000000000000000 - sub ed25519 2018-01-24 [S] + sub ed25519 2022-12-20 [S] Keygrip = 3333000000000000000000000000000000000000 Trovate la voce keygrid che si trova sotto alla riga ``pub`` (appena sotto @@ -389,11 +356,11 @@ Ora, se eseguite il comando ``--list-secret-keys``, vedrete che la chiave primaria non compare più (il simbolo ``#`` indica che non è disponibile):: $ gpg --list-secret-keys - sec# rsa2048 2018-01-24 [SC] [expires: 2020-01-24] + sec# ed25519 2022-12-20 [SC] [expires: 2024-12-19] 000000000000000000000000AAAABBBBCCCCDDDD uid [ultimate] Alice Dev <adev@kernel.org> - ssb rsa2048 2018-01-24 [E] [expires: 2020-01-24] - ssb ed25519 2018-01-24 [S] + ssb cv25519 2022-12-20 [E] [expires: 2024-12-19] + ssb ed25519 2022-12-20 [S] Dovreste rimuovere anche i file ``secring.gpg`` che si trovano nella cartella ``~/.gnupg``, in quanto rimasugli delle versioni precedenti di GnuPG. @@ -461,18 +428,20 @@ soluzioni disponibili: computer portatili più recenti. In aggiunta, offre altre funzionalità di sicurezza come FIDO, U2F, e ora supporta anche le chiavi ECC (NISTP) -`Su LWN c'è una buona recensione`_ dei modelli elencati qui sopra e altri. -La scelta dipenderà dal costo, dalla disponibilità nella vostra area -geografica e vostre considerazioni sull'hardware aperto/proprietario. +La vostra scelta dipenderà dal costo, la disponibilità nella vostra regione, e +sulla scelta fra dispositivi aperti e proprietari. -Se volete usare chiavi ECC, la vostra migliore scelta sul mercato è la -Nitrokey Start. +.. note:: + + Se siete nella lista MAINTAINERS o avete un profilo su kernel.org, allora + `potrete avere gratuitamente una Nitrokey Start`_ grazie alla fondazione + Linux. .. _`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/product/yubikey-5-overview/ -.. _Gnuk: http://www.fsij.org/doc-gnuk/ -.. _`Su LWN c'è una buona recensione`: https://lwn.net/Articles/736231/ +.. _Gnuk: https://www.fsij.org/doc-gnuk/ +.. _`potrete avere gratuitamente una Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html Configurare il vostro dispositivo smartcard ------------------------------------------- @@ -513,6 +482,12 @@ altre informazioni sulla carta che potrebbero trapelare in caso di smarrimento. A dispetto del nome "PIN", né il PIN utente né quello dell'amministratore devono essere esclusivamente numerici. +.. warning:: + + Alcuni dispositivi richiedono la presenza delle sottochiavi nel dispositivo + stesso prima che possiate cambiare la passphare. Verificate la + documentazione del produttore. + Spostare le sottochiavi sulla smartcard --------------------------------------- @@ -525,11 +500,11 @@ dell'amministratore:: Secret subkeys are available. - pub rsa2048/AAAABBBBCCCCDDDD - created: 2018-01-23 expires: 2020-01-23 usage: SC + pub ed25519/AAAABBBBCCCCDDDD + created: 2022-12-20 expires: 2024-12-19 usage: SC trust: ultimate validity: ultimate - ssb rsa2048/1111222233334444 - created: 2018-01-23 expires: never usage: E + ssb cv25519/1111222233334444 + created: 2022-12-20 expires: never usage: E ssb ed25519/5555666677778888 created: 2017-12-07 expires: never usage: S [ultimate] (1). Alice Dev <adev@kernel.org> @@ -594,11 +569,11 @@ Ora, se doveste usare l'opzione ``--list-secret-keys``, vedrete una sottile differenza nell'output:: $ gpg --list-secret-keys - sec# rsa2048 2018-01-24 [SC] [expires: 2020-01-24] + sec# ed25519 2022-12-20 [SC] [expires: 2024-12-19] 000000000000000000000000AAAABBBBCCCCDDDD uid [ultimate] Alice Dev <adev@kernel.org> - ssb> rsa2048 2018-01-24 [E] [expires: 2020-01-24] - ssb> ed25519 2018-01-24 [S] + ssb> cv25519 2022-12-20 [E] [expires: 2024-12-19] + ssb> ed25519 2022-12-20 [S] Il simbolo ``>`` in ``ssb>`` indica che la sottochiave è disponibile solo nella smartcard. Se tornate nella vostra cartella delle chiavi segrete e @@ -661,7 +636,7 @@ eseguite:: Se per voi è più facile da memorizzare, potete anche utilizzare una data specifica (per esempio, il vostro compleanno o capodanno):: - $ gpg --quick-set-expire [fpr] 2020-07-01 + $ gpg --quick-set-expire [fpr] 2025-07-01 Ricordatevi di inviare l'aggiornamento ai keyserver:: @@ -676,6 +651,21 @@ dovreste importarle nella vostra cartella di lavoro abituale:: $ gpg --export | gpg --homedir ~/.gnupg --import $ unset GNUPGHOME +Usare gpg-agent con ssh +~~~~~~~~~~~~~~~~~~~~~~~ + +Se dovete firmare tag o commit su un sistema remoto, potete ridirezionare il +vostro gpg-agent attraverso ssh. Consultate le istruzioni disponibili nella wiki +GnuPG: + +- `Agent Forwarding over SSH`_ + +Funziona senza troppi intoppi se avete la possibilità di modificare le +impostazioni di sshd sul sistema remoto. + +.. _`Agent Forwarding over SSH`: https://wiki.gnupg.org/AgentForwarding + +.. _it_pgp_with_git: Usare PGP con Git ================= @@ -709,11 +699,6 @@ avere più chiavi segrete, potete dire a git quale dovrebbe usare (``[fpg]`` $ git config --global user.signingKey [fpr] -**IMPORTANTE**: se avete una comando dedicato per ``gpg2``, allora dovreste -dire a git di usare sempre quello piuttosto che il vecchio comando ``gpg``:: - - $ git config --global gpg.program gpg2 - Come firmare i tag ------------------ @@ -812,6 +797,61 @@ Potete dire a git di firmare sempre i commit:: .. _it_verify_identities: +Come lavorare con patch firmate +------------------------------- + +Esiste la possibilità di usare la vostra chiave PGP per firmare le patch che +invierete alla liste di discussione del kernel. I meccanismi esistenti per la +firma delle email (PGP-Mime o PGP-inline) tendono a causare problemi +nell'attività di revisione del codice. Si suggerisce, invece, di utilizare lo +strumento sviluppato da kernel.org che mette nell'intestazione del messaggio +un'attestazione delle firme crittografiche (tipo DKIM): + +- `Patatt Patch Attestation`_ + +.. _`Patatt Patch Attestation`: https://pypi.org/project/patatt/ + +Installare e configurate patatt +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Lo strumento patatt è disponibile per diverse distribuzioni, dunque cercatelo +prima lì. Oppure potete installarlo usano pypi "``pip install patatt``" + +Se avete già configurato git con la vostra chiave PGP (usando +``user.signingKey``), allora patatt non ha bisogno di alcuna configurazione +aggiuntiva. Potete iniziare a firmare le vostre patch aggiungendo un aggancio a +git-send-email nel vostro repositorio:: + + patatt install-hook + +Ora, qualsiasi patch che invierete con ``git send-email`` verrà automaticamente +firmata usando la vostra firma crittografica. + +Verificare le firme di patatt +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Se usate ``b4`` per verificare ed applicare le patch, allora tenterà +automaticamente di verificare tutte le firme DKIM e patatt disponibili. Per +esempio:: + + $ b4 am 20220720205013.890942-1-broonie@kernel.org + [...] + Checking attestation on all messages, may take a moment... + --- + ✓ [PATCH v1 1/3] kselftest/arm64: Correct buffer allocation for SVE Z registers + ✓ [PATCH v1 2/3] arm64/sve: Document our actual ABI for clearing registers on syscall + ✓ [PATCH v1 3/3] kselftest/arm64: Enforce actual ABI for SVE syscalls + --- + ✓ Signed: openpgp/broonie@kernel.org + ✓ Signed: DKIM/kernel.org + +.. note:: + + Lo sviluppo di patatt e b4 è piuttosto attivo. Si consiglia di verificare la + documentazione più recente. + +.. _it_kernel_identities: + Come verificare l'identità degli sviluppatori del kernel ======================================================== @@ -884,64 +924,18 @@ di base di GnuPG v2). Per farlo, aggiungete (o modificate) l'impostazione trust-model tofu+pgp -Come usare i keyserver in sicurezza ------------------------------------ -Se ottenete l'errore "No public key" quando cercate di validate il tag di -qualcuno, allora dovreste cercare quella chiave usando un keyserver. È -importante tenere bene a mente che non c'è alcuna garanzia che la chiave -che avete recuperato da un keyserver PGP appartenga davvero alla persona -reale -- è progettato così. Dovreste usare il Web of Trust per assicurarvi -che la chiave sia valida. - -Come mantenere il Web of Trust va oltre gli scopi di questo documento, -semplicemente perché farlo come si deve richiede sia sforzi che perseveranza -che tendono ad andare oltre al livello di interesse della maggior parte degli -esseri umani. Qui di seguito alcuni rapidi suggerimenti per aiutarvi a ridurre -il rischio di importare chiavi maligne. - -Primo, diciamo che avete provato ad eseguire ``git verify-tag`` ma restituisce -un errore dicendo che la chiave non è stata trovata:: - - $ git verify-tag sunxi-fixes-for-4.15-2 - gpg: Signature made Sun 07 Jan 2018 10:51:55 PM EST - gpg: using RSA key DA73759BF8619E484E5A3B47389A54219C0F2430 - gpg: issuer "wens@...org" - gpg: Can't check signature: No public key - -Cerchiamo nel keyserver per maggiori informazioni sull'impronta digitale -della chiave (l'impronta digitale, probabilmente, appartiene ad una -sottochiave, dunque non possiamo usarla direttamente senza trovare prima -l'ID della chiave primaria associata ad essa):: - - $ gpg --search DA73759BF8619E484E5A3B47389A54219C0F2430 - gpg: data source: hkp://keys.gnupg.net - (1) Chen-Yu Tsai <wens@...org> - 4096 bit RSA key C94035C21B4F2AEB, created: 2017-03-14, expires: 2019-03-15 - Keys 1-1 of 1 for "DA73759BF8619E484E5A3B47389A54219C0F2430". Enter number(s), N)ext, or Q)uit > q - -Localizzate l'ID della chiave primaria, nel nostro esempio -``C94035C21B4F2AEB``. Ora visualizzate le chiavi di Linus Torvalds -che avete nel vostro portachiavi:: - - $ gpg --list-key torvalds@kernel.org - pub rsa2048 2011-09-20 [SC] - ABAF11C65A2970B130ABE3C479BE3E4300411886 - uid [ unknown] Linus Torvalds <torvalds@kernel.org> - sub rsa2048 2011-09-20 [E] - -Poi, cercate un percorso affidabile da Linux Torvalds alla chiave che avete -trovato con ``gpg --search`` usando la chiave sconosciuta.Per farlo potete usare -diversi strumenti come https://github.com/mricon/wotmate, -https://git.kernel.org/pub/scm/docs/kernel/pgpkeys.git/tree/graphs, e -https://the.earth.li/~noodles/pathfind.html. - -Se trovate un paio di percorsi affidabili è un buon segno circa la validità -della chiave. Ora, potete aggiungerla al vostro portachiavi dal keyserver:: - - $ gpg --recv-key C94035C21B4F2AEB - -Questa procedura non è perfetta, e ovviamente state riponendo la vostra -fiducia nell'amministratore del servizio *PGP Pathfinder* sperando che non -sia malintenzionato (infatti, questo va contro :ref:`it_devs_not_infra`). -Tuttavia, se mantenete con cura la vostra rete di fiducia sarà un deciso -miglioramento rispetto alla cieca fiducia nei keyserver. +Usare il repositorio kernel.org per il web of trust +--------------------------------------------------- + +Il progetto kernel.org mantiene un repositorio git con le chiavi pubbliche degli sviluppatori in alternativa alla replica dei server di chiavi che negli ultimi anni sono spariti. La documentazione completa su come impostare il repositorio come vostra sorgente di chiavi pubbliche può essere trovato qui: + +- `Kernel developer PGP Keyring`_ + +Se siete uno sviluppatore del kernel, per favore valutate l'idea di inviare la +vostra chiave per l'inclusione in quel portachiavi. + + +If you are a kernel developer, please consider submitting your key for +inclusion into that keyring. + +.. _`Kernel developer PGP Keyring`: https://korg.docs.kernel.org/pgpkeys.html diff --git a/Documentation/translations/it_IT/process/programming-language.rst b/Documentation/translations/it_IT/process/programming-language.rst index c1a9b481a6f9..5bc5b9d42f31 100644 --- a/Documentation/translations/it_IT/process/programming-language.rst +++ b/Documentation/translations/it_IT/process/programming-language.rst @@ -18,10 +18,6 @@ Linux supporta anche ``clang`` [it-clang]_, leggete la documentazione Questo dialetto contiene diverse estensioni al linguaggio [it-gnu-extensions]_, e molte di queste vengono usate sistematicamente dal kernel. -Il kernel offre un certo livello di supporto per la compilazione con -``icc`` [it-icc]_ su diverse architetture, tuttavia in questo momento -il supporto non è completo e richiede delle patch aggiuntive. - Attributi --------- @@ -43,11 +39,30 @@ possono usare e/o per accorciare il codice. Per maggiori informazioni consultate il file d'intestazione ``include/linux/compiler_attributes.h``. +Rust +---- + +Il kernel supporta sperimentalmente il linguaggio di programmazione Rust +[it-rust-language]_ abilitando l'opzione di configurazione ``CONFIG_RUST``. Il +codice verrà compilato usando ``rustc`` [it-rustc]_ con l'opzione +``--edition=2021`` [it-rust-editions]_. Le edizioni Rust sono un modo per +introdurre piccole modifiche senza compatibilità all'indietro._ + +In aggiunta, nel kernel vengono utilizzate alcune funzionalità considerate +instabili [it-rust-unstable-features]_. Queste funzionalità potrebbero cambiare +in futuro, dunque è un'obiettivo importante è quello di far uso solo di +funzionalità stabili. + +Per maggiori informazioni fate riferimento a Documentation/rust/index.rst . + .. [it-c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards .. [it-gcc] https://gcc.gnu.org .. [it-clang] https://clang.llvm.org -.. [it-icc] https://software.intel.com/en-us/c-compilers .. [it-gcc-c-dialect-options] https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html .. [it-gnu-extensions] https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html .. [it-gcc-attribute-syntax] https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html .. [it-n2049] http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2049.pdf +.. [it-rust-language] https://www.rust-lang.org +.. [it-rustc] https://doc.rust-lang.org/rustc/ +.. [it-rust-editions] https://doc.rust-lang.org/edition-guide/editions/ +.. [it-rust-unstable-features] https://github.com/Rust-for-Linux/linux/issues/2 diff --git a/Documentation/translations/it_IT/process/stable-kernel-rules.rst b/Documentation/translations/it_IT/process/stable-kernel-rules.rst index 0be675b03199..248bf1e4b171 100644 --- a/Documentation/translations/it_IT/process/stable-kernel-rules.rst +++ b/Documentation/translations/it_IT/process/stable-kernel-rules.rst @@ -106,6 +106,12 @@ al messaggio della patch, così: commit <sha1> upstream. +o in alternativa: + +.. code-block:: none + + [ Upstream commit <sha1> ] + In aggiunta, alcune patch inviate attraverso l':ref:`it_option_1` potrebbero dipendere da altre che devo essere incluse. Questa situazione può essere indicata nel seguente modo nell'area dedicata alle firme: diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst index 167fce813032..447b18792e61 100644 --- a/Documentation/translations/it_IT/process/submitting-patches.rst +++ b/Documentation/translations/it_IT/process/submitting-patches.rst @@ -429,7 +429,7 @@ poi dovete solo aggiungere una riga che dice:: Signed-off-by: Random J Developer <random@developer.example.org> -usando il vostro vero nome (spiacenti, non si accettano pseudonimi o +usando il vostro vero nome (spiacenti, non si accettano contributi anonimi). Questo verrà fatto automaticamente se usate ``git commit -s``. Anche il ripristino di uno stato precedente dovrebbe includere "Signed-off-by", se usate ``git revert -s`` questo verrà @@ -785,7 +785,7 @@ Riferimenti ----------- Andrew Morton, "La patch perfetta" (tpp). - <http://www.ozlabs.org/~akpm/stuff/tpp.txt> + <https://www.ozlabs.org/~akpm/stuff/tpp.txt> Jeff Garzik, "Formato per la sottomissione di patch per il kernel Linux" <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html> diff --git a/Documentation/translations/it_IT/process/volatile-considered-harmful.rst b/Documentation/translations/it_IT/process/volatile-considered-harmful.rst index efc640cac596..4fff9a59b548 100644 --- a/Documentation/translations/it_IT/process/volatile-considered-harmful.rst +++ b/Documentation/translations/it_IT/process/volatile-considered-harmful.rst @@ -119,9 +119,9 @@ concorrenza siano stati opportunamente considerati. Riferimenti =========== -[1] http://lwn.net/Articles/233481/ +[1] https://lwn.net/Articles/233481/ -[2] http://lwn.net/Articles/233482/ +[2] https://lwn.net/Articles/233482/ Crediti ======= diff --git a/Documentation/translations/sp_SP/memory-barriers.txt b/Documentation/translations/sp_SP/memory-barriers.txt index f62bd797216d..27097a808c88 100644 --- a/Documentation/translations/sp_SP/memory-barriers.txt +++ b/Documentation/translations/sp_SP/memory-barriers.txt @@ -604,7 +604,7 @@ READ_ONCE() para DEC Alpha, lo que significa que las únicas personas que necesitan prestar atención a esta sección son aquellas que trabajan en el código específico de la arquitectura DEC Alpha y aquellas que trabajan en READ_ONCE() por dentro. Para aquellos que lo necesitan, y para aquellos que -estén interesados desde un punto de vista histórico, aquí está la historia +estén interesados desde un punto de vista histórico, aquí está la historia de las barreras de dependencia de dirección. [!] Si bien las dependencias de direcciones se observan tanto en carga a diff --git a/Documentation/translations/sp_SP/process/deprecated.rst b/Documentation/translations/sp_SP/process/deprecated.rst new file mode 100644 index 000000000000..d52120e0d753 --- /dev/null +++ b/Documentation/translations/sp_SP/process/deprecated.rst @@ -0,0 +1,381 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/deprecated.rst <deprecated>` +:Translator: Sergio Gonzalez <sergio.collado@gmail.com> + +.. _sp_deprecated: + +============================================================================ +Interfaces obsoletos, Características del lenguaje, Atributos y Convenciones +============================================================================ + +En un mundo perfecto, sería posible convertir todas las instancias de +alguna API obsoleta en una nueva API y quitar la API anterior en un +único ciclo de desarrollo. Desafortunadamente, debido al tamaño del kernel, +la jerarquía de mantenimiento, y el tiempo, no siempre es posible hacer +estos cambios de una única vez. Esto significa que las nuevas instancias +han de ir creándose en el kernel, mientras que las antiguas se quitan, +haciendo que la cantidad de trabajo para limpiar las APIs crezca. Para +informar a los desarrolladores sobre qué ha sido declarado obsoleto y por +qué, ha sido creada esta lista como un lugar donde indicar cuando los usos +obsoletos son propuestos para incluir en el kernel. + +__deprecated +------------ +Mientras que este atributo señala visualmente que un interface ha sido +declarado obsoleto, este `no produce más avisos durante las compilaciones +<https://git.kernel.org/linus/771c035372a036f83353eef46dbb829780330234>`_ +porque uno de los objetivos del kernel es que compile sin avisos, y +nadie ha hecho nada para quitar estos interfaces obsoletos. Mientras +que usar `__deprecated` es sencillo para anotar una API obsoleta en +un archivo de cabecera, no es la solución completa. Dichos interfaces +deben o bien ser quitados por completo, o añadidos a este archivo para +desanimar a otros a usarla en el futuro. + +BUG() y BUG_ON() +---------------- +Use WARN() y WARN_ON() en su lugar, y gestione las condiciones de error +"imposibles" tan elegantemente como se pueda. Mientras que la familia de +funciones BUG() fueron originalmente diseñadas para actuar como una +"situación imposible", confirmar y disponer de un hilo del kernel de forma +"segura", estas funciones han resultado ser demasiado arriesgadas. (e.g. +"¿en qué orden se necesitan liberar los locks? ¿Se han restaurado sus +estados?). La popular función BUG() desestabilizará el sistema o lo romperá +totalmente, lo cual hace imposible depurarlo o incluso generar reportes de +crash. Linus tiene una `opinión muy fuerte +<https://lore.kernel.org/lkml/CA+55aFy6jNLsywVYdGp83AMrXBo_P-pkjkphPGrO=82SPKCpLQ@mail.gmail.com/>`_ +y sentimientos `sobre esto +<https://lore.kernel.org/lkml/CAHk-=whDHsbK3HTOpTF=ue_o04onRwTEaK_ZoJp_fjbqq4+=Jw@mail.gmail.com/>`_. + +Nótese que la familia de funciones WARN() únicamente debería ser usada +en situaciones que se "esperan no sean alcanzables". Si se quiere +avisar sobre situaciones "alcanzables pero no deseadas", úsese la familia +de funciones pr_warn(). Los responsables del sistema pueden haber definido +*panic_on_warn* sysctl para asegurarse que sus sistemas no continúan +ejecutándose en presencia del condiciones "no alcanzables". (Por ejemplo, +véase commits como `este +<https://git.kernel.org/linus/d4689846881d160a4d12a514e991a740bcb5d65a>`_.) + +Operaciones aritméticas en los argumentos de reserva de memoria +--------------------------------------------------------------- +Los cálculos dinámicos de tamaño (especialmente multiplicaciones) no +deberían realizarse en los argumentos de reserva de memoria (o similares) +debido al riesgo de desbordamiento. Esto puede llevar a valores rotando y +que se realicen reservas de memoria menores que las que se esperaban. El +uso de esas reservas puede llevar a desbordamientos en el 'heap' de memoria +y otros funcionamientos incorrectos. (Una excepción a esto son los valores +literales donde el compilador si puede avisar si estos puede desbordarse. +De todos modos, el método recomendado en estos caso es reescribir el código +como se sugiere a continuación para evitar las operaciones aritméticas en +la reserva de memoria.) + +Por ejemplo, no utilice `count * size`` como argumento, como en:: + + foo = kmalloc(count * size, GFP_KERNEL); + +En vez de eso, utilice la reserva con dos argumentos:: + + foo = kmalloc_array(count, size, GFP_KERNEL); + +Específicamente, kmalloc() puede ser sustituido con kmalloc_array(), +kzalloc() puede ser sustituido con kcalloc(). + +Si no existen funciones con dos argumentos, utilice las funciones que se +saturan, en caso de desbordamiento:: + + bar = vmalloc(array_size(count, size)); + +Otro caso común a evitar es calcular el tamaño de una estructura com +la suma de otras estructuras, como en:: + + header = kzalloc(sizeof(*header) + count * sizeof(*header->item), + GFP_KERNEL); + +En vez de eso emplee:: + + header = kzalloc(struct_size(header, item, count), GFP_KERNEL); + +.. note:: Si se usa struct_size() en una estructura que contiene un elemento + de longitud cero o un array de un único elemento como un array miembro, + por favor reescribir ese uso y cambiar a un `miembro array flexible + <#zero-length-and-one-element-arrays>`_ + + +Para otros cálculos, por favor use las funciones de ayuda: size_mul(), +size_add(), and size_sub(). Por ejemplo, en el caso de:: + + foo = krealloc(current_size + chunk_size * (count - 3), GFP_KERNEL); + +Re-escríbase, como:: + + foo = krealloc(size_add(current_size, + size_mul(chunk_size, + size_sub(count, 3))), GFP_KERNEL); + +Para más detalles, mire también array3_size() y flex_array_size(), +como también la familia de funciones relacionadas check_mul_overflow(), +check_add_overflow(), check_sub_overflow(), y check_shl_overflow(). + + +simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull() +---------------------------------------------------------------------- +Las funciones: simple_strtol(), simple_strtoll(), simple_strtoul(), y +simple_strtoull() explícitamente ignoran los desbordamientos, lo que puede +llevar a resultados inesperados por las funciones que las llaman. Las +funciones respectivas kstrtol(), kstrtoll(), kstrtoul(), y kstrtoull() +tienden a ser reemplazos correctos, aunque nótese que necesitarán que la +cadena de caracteres termine en NUL o en el carácter de línea nueva. + + +strcpy() +-------- +strcpy() no realiza verificaciones de los límites del buffer de destino. +Esto puede resultar en desbordamientos lineals más allá del fin del buffer, +causando todo tipo de errores. Mientras `CONFIG_FORTIFY_SOURCE=y` otras +varias opciones de compilación reducen el riesgo de usar esta función, no +hay ninguna buena razón para añadir nuevos usos de esta. El remplazo seguro +es la función strscpy(), aunque se ha de tener cuidado con cualquier caso +en el el valor retornado por strcpy() sea usado, ya que strscpy() no +devuelve un puntero a el destino, sino el número de caracteres no nulos +compilados (o el valor negativo de errno cuando se trunca la cadena de +caracteres). + +strncpy() en cadenas de caracteres terminadas en NUL +---------------------------------------------------- +El uso de strncpy() no garantiza que el buffer de destino esté terminado en +NUL. Esto puede causar varios errores de desbordamiento en lectura y otros +tipos de funcionamiento erróneo debido a que falta la terminación en NUL. +Esta función también termina la cadena de caracteres en NUL en el buffer de +destino si la cadena de origen es más corta que el buffer de destino, lo +cual puede ser una penalización innecesaria para funciones usen esta +función con cadenas de caracteres que sí están terminadas en NUL. + +Cuando se necesita que la cadena de destino sea terminada en NUL, +el mejor reemplazo es usar la función strscpy(), aunque se ha de tener +cuidado en los casos en los que el valor de strncpy() fuera usado, ya que +strscpy() no devuelve un puntero al destino, sino el número de +caracteres no nulos copiados (o el valor negativo de errno cuando se trunca +la cadena de caracteres). Cualquier caso restante que necesitase todavía +ser terminado en el caracter nulo, debería usar strscpy_pad(). + +Si una función usa cadenas de caracteres que no necesitan terminar en NUL, +debería usarse strtomem(), y el destino debería señalarse con el atributo +`__nonstring +<https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html>`_ +para evitar avisos futuros en el compilador. Para casos que todavía +necesitan cadenas de caracteres que se rellenen al final con el +caracter NUL, usar strtomem_pad(). + +strlcpy() +--------- +strlcpy() primero lee por completo el buffer de origen (ya que el valor +devuelto intenta ser el mismo que el de strlen()). Esta lectura puede +sobrepasar el límite de tamaño del destino. Esto ineficiente y puede causar +desbordamientos de lectura si la cadena de origen no está terminada en el +carácter NUL. El reemplazo seguro de esta función es strscpy(), pero se ha +de tener cuidado que en los casos en lso que se usase el valor devuelto de +strlcpy(), ya que strscpy() devolverá valores negativos de erno cuando se +produzcan truncados. + +Especificación de formato %p +---------------------------- +Tradicionalmente,el uso de "%p" en el formato de cadenas de caracteres +resultaría en exponer esas direcciones en dmesg, proc, sysfs, etc. En vez +de dejar que sean una vulnerabilidad, todos los "%p" que se usan en el +kernel se imprimen como un hash, haciéndolos efectivamente inutilizables +para usarlos como direcciones de memoria. Nuevos usos de "%p" no deberían +ser añadidos al kernel. Para textos de direcciones, usar "%pS" es +mejor, ya que resulta en el nombre del símbolo. Para prácticamente el +resto de casos, mejor no usar "%p" en absoluto. + +Parafraseando las actuales `direcciones de Linus <https://lore.kernel.org/lkml/CA+55aFwQEd_d40g4mUCSsVRZzrFPUJt74vc6PPpb675hYNXcKw@mail.gmail.com/>`_: + +- Si el valor "hasheado" "%p" no tienen ninguna finalidad, preguntarse si el + puntero es realmente importante. ¿Quizás se podría quitar totalmente? +- Si realmente se piensa que el valor del puntero es importante, ¿porqué + algún estado del sistema o nivel de privilegio de usuario es considerado + "especial"? Si piensa que puede justificarse (en comentarios y mensajes + del commit), de forma suficiente como para pasar el escrutinio de Linux, + quizás pueda usar el "%p", a la vez que se asegura que tiene los permisos + correspondientes. + +Si está depurando algo donde el "%p" hasheado está causando problemas, +se puede arrancar temporalmente con la opción de depuración "`no_hash_pointers +<https://git.kernel.org/linus/5ead723a20e0447bc7db33dc3070b420e5f80aa6>`_". + + +Arrays de longitud variable (VLAs) +---------------------------------- +Usando VLA en la pila (stack) produce un código mucho peor que los arrays +de tamaño estático. Mientras que estos errores no triviales de `rendimiento +<https://git.kernel.org/linus/02361bc77888>`_ son razón suficiente +para no usar VLAs, esto además son un riesgo de seguridad. El crecimiento +dinámico del array en la pila, puede exceder la memoria restante en +el segmento de la pila. Esto podría llevara a un fallo, posible sobre-escritura +de contenido al final de la pila (cuando se construye sin +`CONFIG_THREAD_INFO_IN_TASK=y`), o sobre-escritura de la memoria adyacente +a la pila (cuando se construye sin `CONFIG_VMAP_STACK=y`). + + +Switch case fall-through implícito +---------------------------------- +El lenguaje C permite a las sentencias 'switch' saltar de un caso al +siguiente caso cuando la sentencia de ruptura "break" no aparece al final +del caso. Esto, introduce ambigüedad en el código, ya que no siempre está +claro si el 'break' que falta es intencionado o un olvido. Por ejemplo, no +es obvio solamente mirando al código si `STATE_ONE` está escrito para +intencionadamente saltar en `STATE_TWO`:: + + switch (value) { + case STATE_ONE: + do_something(); + case STATE_TWO: + do_other(); + break; + default: + WARN("unknown state"); + } + +Ya que ha habido una larga lista de defectos `debidos a declaraciones de "break" +que faltan <https://cwe.mitre.org/data/definitions/484.html>`_, no se +permiten 'fall-through' implícitos. Para identificar 'fall-through' +intencionados, se ha adoptado la pseudo-palabra-clave macro "falltrhrough", +que expande las extensiones de gcc `__attribute__((__fallthrough__)) +<https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html>`_. +(Cuando la sintaxis de C17/c18 `[[fallthrough]]` sea más comúnmente +soportadas por los compiladores de C, analizadores estáticos, e IDEs, +se puede cambiar a usar esa sintaxis para esa pseudo-palabra-clave. + +Todos los bloques switch/case deben acabar en uno de: + +* break; +* fallthrough; +* continue; +* goto <label>; +* return [expression]; + + +Arrays de longitud cero y un elemento +------------------------------------- +Hay una necesidad habitual en el kernel de proveer una forma para declarar +un grupo de elementos consecutivos de tamaño dinámico en una estructura. +El código del kernel debería usar siempre `"miembros array flexible" <https://en.wikipedia.org/wiki/Flexible_array_member>`_ +en estos casos. El estilo anterior de arrays de un elemento o de longitud +cero, no deben usarse más. + +En el código C más antiguo, los elementos finales de tamaño dinámico se +obtenían especificando un array de un elemento al final de una estructura:: + + struct something { + size_t count; + struct foo items[1]; + }; + +En código C más antiguo, elementos seguidos de tamaño dinámico eran creados +especificando una array de un único elemento al final de una estructura:: + + struct something { + size_t count; + struct foo items[1]; + }; + +Esto llevó a resultados incorrectos en los cálculos de tamaño mediante +sizeof() (el cual hubiera necesitado eliminar el tamaño del último elemento +para tener un tamaño correcto de la "cabecera"). Una `extensión de GNU C +<https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_ se empezó a usar +para permitir los arrays de longitud cero, para evitar estos tipos de +problemas de tamaño:: + + struct something { + size_t count; + struct foo items[0]; + }; + +Pero esto llevó a otros problemas, y no solucionó algunos otros problemas +compartidos por ambos estilos, como no ser capaz de detectar cuando ese array +accidentalmente _no_ es usado al final de la estructura (lo que podía pasar +directamente, o cuando dicha estructura era usada en uniones, estructuras +de estructuras, etc). + +C99 introdujo "los arrays miembros flexibles", los cuales carecen de un +tamaño numérico en su declaración del array:: + + struct something { + size_t count; + struct foo items[]; + }; + +Esta es la forma en la que el kernel espera que se declaren los elementos +de tamaño dinámico concatenados. Esto permite al compilador generar +errores, cuando el array flexible no es declarado en el último lugar de la +estructura, lo que ayuda a prevenir errores en él código del tipo +`comportamiento indefinido <https://git.kernel.org/linus/76497732932f15e7323dc805e8ea8dc11bb587cf>`_. +Esto también permite al compilador analizar correctamente los tamaños de +los arrays (via sizeof(), `CONFIG_FORTIFY_SOURCE`, y `CONFIG_UBSAN_BOUNDS`). +Por ejemplo, si no hay un mecanismo que avise que el siguiente uso de +sizeof() en un array de longitud cero, siempre resulta en cero:: + + 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); + +En la última línea del código anterior, ``zero`` vale ``cero``, cuando uno +podría esperar que representa el tamaño total en bytes de la memoria dinámica +reservada para el array consecutivo ``items``. Aquí hay un par de ejemplos +más sobre este tema: `link 1 +<https://git.kernel.org/linus/f2cd32a443da694ac4e28fbf4ac6f9d5cc63a539>`_, +`link 2 +<https://git.kernel.org/linus/ab91c2a89f86be2898cee208d492816ec238b2cf>`_. +Sin embargo, los array de miembros flexibles tienen un type incompleto, y +no se ha de aplicar el operador sizeof()<https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_, +así cualquier mal uso de dichos operadores será detectado inmediatamente en +el momento de compilación. + +Con respecto a los arrays de un único elemento, se ha de ser consciente de +que dichos arrays ocupan al menos tanto espacio como un único objeto del +tipo https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_, de ahí que +estos contribuyan al tamaño de la estructura que los contiene. Esto es +proclive a errores cada vez que se quiere calcular el tamaño total de la +memoria dinámica para reservar una estructura que contenga un array de este +tipo como su miembro:: + + 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); + +En el ejemplo anterior, hemos de recordar calcular ``count - 1``, cuando se +usa la función de ayuda struct_size(), de otro modo estaríamos +--desintencionadamente--reservando memoria para un ``items`` de más. La +forma más clara y menos proclive a errores es implementar esto mediante el +uso de `array miembro flexible`, junto con las funciones de ayuda: +struct_size() y flex_array_size():: + + struct something { + size_t count; + struct foo items[]; + }; + + struct something *instance; + + instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL); + instance->count = count; + + memcpy(instance->items, source, flex_array_size(instance, items, instance->count)); diff --git a/Documentation/translations/sp_SP/process/index.rst b/Documentation/translations/sp_SP/process/index.rst index 0f1e131b3bb1..3b0c32593726 100644 --- a/Documentation/translations/sp_SP/process/index.rst +++ b/Documentation/translations/sp_SP/process/index.rst @@ -18,3 +18,4 @@ email-clients magic-number programming-language + deprecated diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/lru_sort.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/lru_sort.rst index 812ef315c8f6..03d33c710604 100644 --- a/Documentation/translations/zh_CN/admin-guide/mm/damon/lru_sort.rst +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/lru_sort.rst @@ -250,7 +250,7 @@ LRU的优先级的提升，同时降低那些超过120秒无人访问的内存 理被限制在最多1%的CPU以避免DAMON_LRU_SORT消费过多CPU时间。在系统空闲内存超过50% 时DAMON_LRU_SORT停止工作，并在低于40%时重新开始工作。如果DAMON_RECLAIM没有取得 进展且空闲内存低于20%，再次让DAMON_LRU_SORT停止工作，以此回退到以LRU链表为基础 -以页面为单位的内存回收上。 +以页面为单位的内存回收上。 :: # cd /sys/modules/damon_lru_sort/parameters # echo 500 > hot_thres_access_freq diff --git a/Documentation/translations/zh_CN/arch.rst b/Documentation/translations/zh_CN/arch/index.rst index 690e173d8b2a..908ea131bb1c 100644 --- a/Documentation/translations/zh_CN/arch.rst +++ b/Documentation/translations/zh_CN/arch/index.rst @@ -8,12 +8,12 @@ .. toctree:: :maxdepth: 2 - mips/index - arm64/index - riscv/index + ../mips/index + ../arm64/index + ../riscv/index openrisc/index parisc/index - loongarch/index + ../loongarch/index TODOList: diff --git a/Documentation/translations/zh_CN/openrisc/index.rst b/Documentation/translations/zh_CN/arch/openrisc/index.rst index 9ad6cc600884..da21f8ab894b 100644 --- a/Documentation/translations/zh_CN/openrisc/index.rst +++ b/Documentation/translations/zh_CN/arch/openrisc/index.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/openrisc/index.rst +:Original: Documentation/arch/openrisc/index.rst :翻译: diff --git a/Documentation/translations/zh_CN/openrisc/openrisc_port.rst b/Documentation/translations/zh_CN/arch/openrisc/openrisc_port.rst index b8a67670492d..cadc580fa23b 100644 --- a/Documentation/translations/zh_CN/openrisc/openrisc_port.rst +++ b/Documentation/translations/zh_CN/arch/openrisc/openrisc_port.rst @@ -1,6 +1,6 @@ -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/openrisc/openrisc_port.rst +:Original: Documentation/arch/openrisc/openrisc_port.rst :翻译: diff --git a/Documentation/translations/zh_CN/openrisc/todo.rst b/Documentation/translations/zh_CN/arch/openrisc/todo.rst index 63c38717edb1..1f6f95616633 100644 --- a/Documentation/translations/zh_CN/openrisc/todo.rst +++ b/Documentation/translations/zh_CN/arch/openrisc/todo.rst @@ -1,6 +1,6 @@ -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/openrisc/todo.rst +:Original: Documentation/arch/openrisc/todo.rst :翻译: diff --git a/Documentation/translations/zh_CN/parisc/debugging.rst b/Documentation/translations/zh_CN/arch/parisc/debugging.rst index 68b73eb57105..c6b9de6d3175 100644 --- a/Documentation/translations/zh_CN/parisc/debugging.rst +++ b/Documentation/translations/zh_CN/arch/parisc/debugging.rst @@ -1,6 +1,6 @@ -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/parisc/debugging.rst +:Original: Documentation/arch/parisc/debugging.rst :翻译: diff --git a/Documentation/translations/zh_CN/parisc/index.rst b/Documentation/translations/zh_CN/arch/parisc/index.rst index 0cc553fc8272..9f69283bd1c9 100644 --- a/Documentation/translations/zh_CN/parisc/index.rst +++ b/Documentation/translations/zh_CN/arch/parisc/index.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/parisc/index.rst +:Original: Documentation/arch/parisc/index.rst :翻译: diff --git a/Documentation/translations/zh_CN/parisc/registers.rst b/Documentation/translations/zh_CN/arch/parisc/registers.rst index d2ab1874a602..a55250afcc27 100644 --- a/Documentation/translations/zh_CN/parisc/registers.rst +++ b/Documentation/translations/zh_CN/arch/parisc/registers.rst @@ -1,6 +1,6 @@ -.. include:: ../disclaimer-zh_CN.rst +.. include:: ../../disclaimer-zh_CN.rst -:Original: Documentation/parisc/registers.rst +:Original: Documentation/arch/parisc/registers.rst :翻译: diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst index 7c3216845b71..299704c0818d 100644 --- a/Documentation/translations/zh_CN/index.rst +++ b/Documentation/translations/zh_CN/index.rst @@ -120,7 +120,7 @@ TODOList: .. toctree:: :maxdepth: 2 - arch + arch/index 其他文档 -------- diff --git a/Documentation/userspace-api/ELF.rst b/Documentation/userspace-api/ELF.rst new file mode 100644 index 000000000000..ac8aeacd458d --- /dev/null +++ b/Documentation/userspace-api/ELF.rst @@ -0,0 +1,34 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================= +Linux-specific ELF idiosyncrasies +================================= + +Definitions +=========== + +"First" program header is the one with the smallest offset in the file: +e_phoff. + +"Last" program header is the one with the biggest offset in the file: +e_phoff + (e_phnum - 1) * sizeof(Elf_Phdr). + +PT_INTERP +========= + +First PT_INTERP program header is used to locate the filename of ELF +interpreter. Other PT_INTERP headers are ignored (since Linux 2.4.11). + +PT_GNU_STACK +============ + +Last PT_GNU_STACK program header defines userspace stack executability +(since Linux 2.6.6). Other PT_GNU_STACK headers are ignored. + +PT_GNU_PROPERTY +=============== + +ELF interpreter's last PT_GNU_PROPERTY program header is used (since +Linux 5.8). If interpreter doesn't have one, then the last PT_GNU_PROPERTY +program header of an executable is used. Other PT_GNU_PROPERTY headers +are ignored. diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index f16337bdb852..72a65db0c498 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -23,6 +23,7 @@ place where this information is gathered. spec_ctrl accelerators/ocxl ebpf/index + ELF ioctl/index iommu iommufd diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst index d330aeb4d3eb..d9d7b7621d8c 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst @@ -778,7 +778,7 @@ number of bits for each component. \tiny \setlength{\tabcolsep}{2pt} -.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| +.. tabularcolumns:: |p{3.2cm}|p{0.8cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}| .. flat-table:: RGB Formats 10 Bits Per Color Component @@ -868,7 +868,6 @@ number of bits for each component. - r\ :sub:`4` - r\ :sub:`3` - r\ :sub:`2` - - * .. _V4L2-PIX-FMT-RGBA1010102: - ``V4L2_PIX_FMT_RGBA1010102`` @@ -909,7 +908,6 @@ number of bits for each component. - r\ :sub:`4` - r\ :sub:`3` - r\ :sub:`2` - - * .. _V4L2-PIX-FMT-ARGB2101010: - ``V4L2_PIX_FMT_ARGB2101010`` @@ -950,7 +948,6 @@ number of bits for each component. - r\ :sub:`6` - r\ :sub:`5` - r\ :sub:`4` - - .. raw:: latex diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index a5c803f39832..841e9d1987bd 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -7456,7 +7456,7 @@ system fingerprint. To prevent userspace from circumventing such restrictions by running an enclave in a VM, KVM prevents access to privileged attributes by default. -See Documentation/x86/sgx.rst for more details. +See Documentation/arch/x86/sgx.rst for more details. 7.26 KVM_CAP_PPC_RPT_INVALIDATE ------------------------------- |