Skip to content

L
linux
Commit c23f2897 authored by Linus Torvalds's avatar Linus Torvalds
Browse files
Options

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/
  ...
parents 1be89faa 7e8472c8
Hide whitespace changes
Inline Side-by-side
Showing with 2622 additions and 629 deletions
CREDITS
View file @ c23f2897
......@@ -229,6 +229,10 @@ S: University of Notre Dame
S: Notre Dame, Indiana
S: USA
N: Kai Bankett
E: chaosman@ontika.net
D: QNX6 filesystem
N: Greg Banks
E: gnb@alphalink.com.au
D: IDT77105 ATM network driver
......@@ -886,6 +890,10 @@ W: http://jdelvare.nerim.net/
D: Several hardware monitoring drivers
S: France
N: Frank "Jedi/Sector One" Denis
E: j@pureftpd.org
D: QNX4 filesystem
N: Peter Denison
E: peterd@pnd-pc.demon.co.uk
W: http://www.pnd-pc.demon.co.uk/promise/
......@@ -1259,6 +1267,10 @@ S: USA
N: Adam Fritzler
E: mid@zigamorph.net
N: Richard "Scuba" A. Frowijn
E: scuba@wxs.nl
D: QNX4 filesystem
N: Fernando Fuganti
E: fuganti@conectiva.com.br
E: fuganti@netbank.com.br
......@@ -2218,6 +2230,10 @@ D: Digiboard PC/Xe and PC/Xi, Digiboard EPCA
D: NUMA support, Slab allocators, Page migration
D: Scalability, Time subsystem
N: Anders Larsen
E: al@alarsen.net
D: QNX4 filesystem
N: Paul Laufer
E: paul@laufernet.com
D: Soundblaster driver fixes, ISAPnP quirk
......
Documentation/admin-guide/hw-vuln/mds.rst
View file @ c23f2897
......@@ -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
......
Documentation/admin-guide/hw-vuln/tsx_async_abort.rst
View file @ c23f2897
......@@ -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
......
Documentation/admin-guide/index.rst
View file @ c23f2897
......@@ -36,6 +36,7 @@ problems and bugs in particular.
reporting-issues
reporting-regressions
quickly-build-trimmed-linux
bug-hunting
bug-bisect
tainted-kernels
......
Documentation/admin-guide/kernel-parameters.rst
View file @ c23f2897
......@@ -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
......
Documentation/admin-guide/kernel-parameters.txt
View file @ c23f2897
......@@ -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
......
Documentation/admin-guide/quickly-build-trimmed-linux.rst 0 → 100644
View file @ c23f2897
.. 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.
Documentation/admin-guide/ras.rst
View file @ c23f2897
......@@ -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
*************************************
......
Documentation/admin-guide/sysctl/kernel.rst
View file @ c23f2897
......@@ -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
......
Documentation/admin-guide/unicode.rst
View file @ c23f2897
......@@ -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
------------
......
Documentation/arch.rst → Documentation/arch/index.rst
View file @ c23f2897
......@@ -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
......
Documentation/x86/boot.rst → Documentation/arch/x86/boot.rst
View file @ c23f2897
......@@ -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
......
Documentation/x86/booting-dt.rst → Documentation/arch/x86/booting-dt.rst
View file @ c23f2897
......@@ -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
......
Documentation/x86/buslock.rst → Documentation/arch/x86/buslock.rst
View file @ c23f2897
......@@ -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 | |
+------------------+----------------------------+-----------------------+
......
Documentation/x86/mtrr.rst → Documentation/arch/x86/mtrr.rst
View file @ c23f2897
......@@ -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)
......
Documentation/x86/x86_64/5level-paging.rst → Documentation/arch/x86/x86_64/5level-paging.rst
View file @ c23f2897
......@@ -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
......
Documentation/x86/x86_64/boot-options.rst → Documentation/arch/x86/x86_64/boot-options.rst
View file @ c23f2897
......@@ -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
......
Documentation/x86/x86_64/fake-numa-for-cpusets.rst → Documentation/arch/x86/x86_64/fake-numa-for-cpusets.rst
View file @ c23f2897
......@@ -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
......
Documentation/arm/index.rst
View file @ c23f2897
......@@ -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
......
Documentation/arm/sti/overview.rst
View file @ c23f2897
......@@ -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
......
Documentation/arm/sti/stih415-overview.rst deleted 100644 → 0
View file @ 1be89faa
================
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
Documentation/arm/sti/stih416-overview.rst deleted 100644 → 0
View file @ 1be89faa
================
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
Documentation/conf.py
View file @ c23f2897
......@@ -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
......
Documentation/core-api/asm-annotations.rst
View file @ c23f2897
......@@ -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).
......
Documentation/core-api/dma-api-howto.rst
View file @ c23f2897
......@@ -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
......
Documentation/dev-tools/kmemleak.rst
View file @ c23f2897
......@@ -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::
......
Documentation/driver-api/clk.rst
View file @ c23f2897
......@@ -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.
......
Documentation/driver-api/device-io.rst
View file @ c23f2897
......@@ -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().
......
Documentation/driver-api/firmware/fw_search_path.rst
View file @ c23f2897
......@@ -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.
Documentation/filesystems/proc.rst
View file @ c23f2897
......@@ -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
-------
......
Documentation/filesystems/vfs.rst
View file @ c23f2897
......@@ -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.
......
Documentation/index.rst
View file @ c23f2897
......@@ -99,7 +99,7 @@ Architecture-specific documentation
.. toctree::
:maxdepth: 2
arch
arch/index
Other documentation
......
Documentation/kernel-hacking/false-sharing.rst 0 → 100644
View file @ c23f2897
.. 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/
Documentation/kernel-hacking/index.rst
View file @ c23f2897
......@@ -9,3 +9,4 @@ Kernel Hacking Guides
hacking
locking
false-sharing
Documentation/mm/physical_memory.rst
View file @ c23f2897
......@@ -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
......
Documentation/process/coding-style.rst
View file @ c23f2897
......@@ -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/
Documentation/process/contribution-maturity-model.rst 0 → 100644
View file @ c23f2897
.. 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.
Documentation/process/index.rst
View file @ c23f2897
......@@ -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.
......
Documentation/process/kernel-docs.rst
View file @ c23f2897
......@@ -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**
......
Documentation/process/maintainer-tip.rst
View file @ c23f2897
......@@ -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
......
Documentation/process/submitting-patches.rst
View file @ c23f2897
......@@ -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
......
Documentation/trace/ftrace.rst
View file @ c23f2897
......@@ -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.
......
Documentation/translations/it_IT/core-api/symbol-namespaces.rst
View file @ c23f2897
.. 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
......
Documentation/translations/it_IT/doc-guide/parse-headers.rst
View file @ c23f2897
.. 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.
Documentation/translations/it_IT/index.rst
View file @ c23f2897
......@@ -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
......
Documentation/translations/it_IT/kernel-hacking/locking.rst
View file @ c23f2897
......@@ -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
===============================
......
Documentation/translations/it_IT/process/5.Posting.rst
View file @ c23f2897
......@@ -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
-------------------
......
Documentation/translations/it_IT/process/changes.rst
View file @ c23f2897
......@@ -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
----------
......
Documentation/translations/it_IT/process/clang-format.rst
View file @ c23f2897
......@@ -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:
......
Documentation/translations/it_IT/process/coding-style.rst
View file @ c23f2897
......@@ -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/
Documentation/translations/it_IT/process/deprecated.rst
View file @ c23f2897
......@@ -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);
};
};
Documentation/translations/it_IT/process/email-clients.rst
View file @ c23f2897
......@@ -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.
Documentation/translations/it_IT/process/index.rst
View file @ c23f2897
......@@ -10,6 +10,7 @@
.. _it_process_index:
===============================================
Lavorare con la comunità di sviluppo del kernel
===============================================
......
Documentation/translations/it_IT/process/maintainer-pgp-guide.rst
View file @ c23f2897
......@@ -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
Documentation/translations/it_IT/process/programming-language.rst
View file @ c23f2897
......@@ -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
Documentation/translations/it_IT/process/stable-kernel-rules.rst
View file @ c23f2897
......@@ -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:
......
Documentation/translations/it_IT/process/submitting-patches.rst
View file @ c23f2897
......@@ -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>
......
Documentation/translations/it_IT/process/volatile-considered-harmful.rst
View file @ c23f2897
......@@ -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
=======
......
Documentation/translations/sp_SP/memory-barriers.txt
View file @ c23f2897
......@@ -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
......
Documentation/translations/sp_SP/process/deprecated.rst 0 → 100644
View file @ c23f2897
.. 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));
Documentation/translations/sp_SP/process/index.rst
View file @ c23f2897
......@@ -18,3 +18,4 @@
email-clients
magic-number
programming-language
deprecated
Documentation/translations/zh_CN/admin-guide/mm/damon/lru_sort.rst
View file @ c23f2897
......@@ -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
......
Documentation/translations/zh_CN/arch.rst → Documentation/translations/zh_CN/arch/index.rst
View file @ c23f2897
......@@ -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:
......
Documentation/translations/zh_CN/openrisc/index.rst → Documentation/translations/zh_CN/arch/openrisc/index.rst
View file @ c23f2897
.. 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
:翻译:
......
Documentation/translations/zh_CN/openrisc/openrisc_port.rst → Documentation/translations/zh_CN/arch/openrisc/openrisc_port.rst
View file @ c23f2897
.. include:: ../disclaimer-zh_CN.rst
.. include:: ../../disclaimer-zh_CN.rst
:Original: Documentation/openrisc/openrisc_port.rst
:Original: Documentation/arch/openrisc/openrisc_port.rst
:翻译:
......
Documentation/translations/zh_CN/openrisc/todo.rst → Documentation/translations/zh_CN/arch/openrisc/todo.rst
View file @ c23f2897
.. include:: ../disclaimer-zh_CN.rst
.. include:: ../../disclaimer-zh_CN.rst
:Original: Documentation/openrisc/todo.rst
:Original: Documentation/arch/openrisc/todo.rst
:翻译:
......
Documentation/translations/zh_CN/parisc/debugging.rst → Documentation/translations/zh_CN/arch/parisc/debugging.rst
View file @ c23f2897
.. include:: ../disclaimer-zh_CN.rst
.. include:: ../../disclaimer-zh_CN.rst
:Original: Documentation/parisc/debugging.rst
:Original: Documentation/arch/parisc/debugging.rst
:翻译:
......
Documentation/translations/zh_CN/parisc/index.rst → Documentation/translations/zh_CN/arch/parisc/index.rst
View file @ c23f2897
.. 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
:翻译:
......
Documentation/translations/zh_CN/parisc/registers.rst → Documentation/translations/zh_CN/arch/parisc/registers.rst
View file @ c23f2897
.. include:: ../disclaimer-zh_CN.rst
.. include:: ../../disclaimer-zh_CN.rst
:Original: Documentation/parisc/registers.rst
:Original: Documentation/arch/parisc/registers.rst
:翻译:
......
Documentation/translations/zh_CN/index.rst
View file @ c23f2897
......@@ -120,7 +120,7 @@ TODOList:
.. toctree::
:maxdepth: 2
arch
arch/index
其他文档
--------
......
Documentation/userspace-api/ELF.rst 0 → 100644
View file @ c23f2897
.. 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.
Documentation/userspace-api/index.rst
View file @ c23f2897
......@@ -23,6 +23,7 @@ place where this information is gathered.
spec_ctrl
accelerators/ocxl
ebpf/index
ELF
ioctl/index
iommu
iommufd
......
Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
View file @ c23f2897
......@@ -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
......
Documentation/virt/kvm/api.rst
View file @ c23f2897
......@@ -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
-------------------------------
......
MAINTAINERS
View file @ c23f2897
......@@ -1071,7 +1071,7 @@ M: Naveen Krishna Chatradhi <naveenkrishna.chatradhi@amd.com>
R: Carlos Bilbao <carlos.bilbao@amd.com>
L: platform-driver-x86@vger.kernel.org
S: Maintained
F: Documentation/x86/amd_hsmp.rst
F: Documentation/arch/x86/amd_hsmp.rst
F: arch/x86/include/asm/amd_hsmp.h
F: arch/x86/include/uapi/asm/amd_hsmp.h
F: drivers/platform/x86/amd/hsmp.c
......@@ -5940,11 +5940,6 @@ F: drivers/devfreq/event/
F: include/dt-bindings/pmu/exynos_ppmu.h
F: include/linux/devfreq-event.h
DEVICE NUMBER REGISTRY
M: Torben Mathiasen <device@lanana.org>
S: Maintained
W: http://lanana.org/docs/device-list/index.html
DEVICE RESOURCE MANAGEMENT HELPERS
M: Hans de Goede <hdegoede@redhat.com>
R: Matti Vaittinen <mazziesaccount@gmail.com>
......@@ -6207,6 +6202,7 @@ DOCUMENTATION REPORTING ISSUES
M: Thorsten Leemhuis <linux@leemhuis.info>
L: linux-doc@vger.kernel.org
S: Maintained
F: Documentation/admin-guide/quickly-build-trimmed-linux.rst
F: Documentation/admin-guide/reporting-issues.rst
DOCUMENTATION SCRIPTS
......@@ -9729,7 +9725,7 @@ F: include/linux/i3c/
IA64 (Itanium) PLATFORM
L: linux-ia64@vger.kernel.org
S: Orphan
F: Documentation/ia64/
F: Documentation/arch/ia64/
F: arch/ia64/
IBM Operation Panel Input Driver
......@@ -10648,7 +10644,7 @@ L: tboot-devel@lists.sourceforge.net
S: Supported
W: http://tboot.sourceforge.net
T: hg http://tboot.hg.sourceforge.net:8000/hgroot/tboot/tboot
F: Documentation/x86/intel_txt.rst
F: Documentation/arch/x86/intel_txt.rst
F: arch/x86/kernel/tboot.c
F: include/linux/tboot.h
......@@ -10659,7 +10655,7 @@ L: linux-sgx@vger.kernel.org
S: Supported
Q: https://patchwork.kernel.org/project/intel-sgx/list/
T: git git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip.git x86/sgx
F: Documentation/x86/sgx.rst
F: Documentation/arch/x86/sgx.rst
F: arch/x86/entry/vdso/vsgx.S
F: arch/x86/include/asm/sgx.h
F: arch/x86/include/uapi/asm/sgx.h
......@@ -15640,7 +15636,7 @@ S: Maintained
W: http://openrisc.io
T: git https://github.com/openrisc/linux.git
F: Documentation/devicetree/bindings/openrisc/
F: Documentation/openrisc/
F: Documentation/arch/openrisc/
F: arch/openrisc/
F: drivers/irqchip/irq-ompic.c
F: drivers/irqchip/irq-or1k-*
......@@ -15836,7 +15832,7 @@ W: https://parisc.wiki.kernel.org
Q: http://patchwork.kernel.org/project/linux-parisc/list/
T: git git://git.kernel.org/pub/scm/linux/kernel/git/jejb/parisc-2.6.git
T: git git://git.kernel.org/pub/scm/linux/kernel/git/deller/parisc-linux.git
F: Documentation/parisc/
F: Documentation/arch/parisc/
F: arch/parisc/
F: drivers/char/agp/parisc-agp.c
F: drivers/input/misc/hp_sdc_rtc.c
......@@ -17167,6 +17163,12 @@ F: fs/qnx4/
F: include/uapi/linux/qnx4_fs.h
F: include/uapi/linux/qnxtypes.h
QNX6 FILESYSTEM
S: Orphan
F: Documentation/filesystems/qnx6.rst
F: fs/qnx6/
F: include/linux/qnx6_fs.h
QORIQ DPAA2 FSL-MC BUS DRIVER
M: Stuart Yoder <stuyoder@gmail.com>
M: Laurentiu Tudor <laurentiu.tudor@nxp.com>
......@@ -17627,7 +17629,7 @@ M: Fenghua Yu <fenghua.yu@intel.com>
M: Reinette Chatre <reinette.chatre@intel.com>
L: linux-kernel@vger.kernel.org
S: Supported
F: Documentation/x86/resctrl*
F: Documentation/arch/x86/resctrl*
F: arch/x86/include/asm/resctrl.h
F: arch/x86/kernel/cpu/resctrl/
F: tools/testing/selftests/resctrl/
......@@ -20115,7 +20117,7 @@ M: John Paul Adrian Glaubitz <glaubitz@physik.fu-berlin.de>
L: linux-sh@vger.kernel.org
S: Maintained
Q: http://patchwork.kernel.org/project/linux-sh/list/
F: Documentation/sh/
F: Documentation/arch/sh/
F: arch/sh/
F: drivers/sh/
......@@ -20175,7 +20177,7 @@ M: Vineet Gupta <vgupta@kernel.org>
L: linux-snps-arc@lists.infradead.org
S: Supported
T: git git://git.kernel.org/pub/scm/linux/kernel/git/vgupta/arc.git
F: Documentation/arc/
F: Documentation/arch/arc
F: Documentation/devicetree/bindings/arc/*
F: Documentation/devicetree/bindings/interrupt-controller/snps,arc*
F: arch/arc/
......@@ -21234,6 +21236,14 @@ S: Maintained
F: Documentation/tools/rtla/
F: tools/tracing/rtla/
TECHNICAL ADVISORY BOARD PROCESS DOCS
M: "Theodore Ts'o" <tytso@mit.edu>
M: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
L: tech-board-discuss@lists.linux-foundation.org
S: Maintained
F: Documentation/process/researcher-guidelines.rst
F: Documentation/process/contribution-maturity-model.rst
TRADITIONAL CHINESE DOCUMENTATION
M: Hu Haowen <src.res@email.cn>
L: linux-doc-tw-discuss@lists.sourceforge.net (moderated for non-subscribers)
......@@ -22641,7 +22651,7 @@ L: linux-kernel@vger.kernel.org
S: Maintained
T: git git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip.git x86/core
F: Documentation/devicetree/bindings/x86/
F: Documentation/x86/
F: Documentation/arch/x86/
F: arch/x86/
X86 ENTRY CODE
......@@ -22657,7 +22667,7 @@ M: Borislav Petkov <bp@alien8.de>
L: linux-edac@vger.kernel.org
S: Maintained
F: Documentation/ABI/testing/sysfs-mce
F: Documentation/x86/x86_64/machinecheck.rst
F: Documentation/arch/x86/x86_64/machinecheck.rst
F: arch/x86/kernel/cpu/mce/*
X86 MICROCODE UPDATE SUPPORT
......
arch/arm/Kconfig
View file @ c23f2897
......@@ -986,7 +986,7 @@ config SMP
uniprocessor machines. On a uniprocessor machine, the kernel
will run faster if you say N here.
See also <file:Documentation/x86/i386/IO-APIC.rst>,
See also <file:Documentation/arch/x86/i386/IO-APIC.rst>,
<file:Documentation/admin-guide/lockup-watchdogs.rst> and the SMP-HOWTO available at
<http://tldp.org/HOWTO/SMP-HOWTO.html>.
......
arch/ia64/kernel/efi.c
View file @ c23f2897
......@@ -853,7 +853,7 @@ valid_phys_addr_range (phys_addr_t phys_addr, unsigned long size)
* /dev/mem reads and writes use copy_to_user(), which implicitly
* uses a granule-sized kernel identity mapping. It's really
* only safe to do this for regions in kern_memmap. For more
* details, see Documentation/ia64/aliasing.rst.
* details, see Documentation/arch/ia64/aliasing.rst.
*/
attr = kern_mem_attribute(phys_addr, size);
if (attr & EFI_MEMORY_WB || attr & EFI_MEMORY_UC)
......
arch/ia64/kernel/fsys.S
View file @ c23f2897
......@@ -28,7 +28,7 @@
#include <asm/native/inst.h>
/*
* See Documentation/ia64/fsys.rst for details on fsyscalls.
* See Documentation/arch/ia64/fsys.rst for details on fsyscalls.
*
* On entry to an fsyscall handler:
* r10 = 0 (i.e., defaults to "successful syscall return")
......
arch/ia64/mm/ioremap.c
View file @ c23f2897
......@@ -43,7 +43,7 @@ ioremap (unsigned long phys_addr, unsigned long size)
/*
* For things in kern_memmap, we must use the same attribute
* as the rest of the kernel. For more details, see
* Documentation/ia64/aliasing.rst.
* Documentation/arch/ia64/aliasing.rst.
*/
attr = kern_mem_attribute(phys_addr, size);
if (attr & EFI_MEMORY_WB)
......
arch/ia64/pci/pci.c
View file @ c23f2897
......@@ -448,7 +448,7 @@ pci_mmap_legacy_page_range(struct pci_bus *bus, struct vm_area_struct *vma,
return -ENOSYS;
/*
* Avoid attribute aliasing. See Documentation/ia64/aliasing.rst
* Avoid attribute aliasing. See Documentation/arch/ia64/aliasing.rst
* for more details.
*/
if (!valid_mmap_phys_addr_range(vma->vm_pgoff, size))
......
arch/m68k/Kconfig.machine
View file @ c23f2897
......@@ -11,7 +11,7 @@ config AMIGA
help
This option enables support for the Amiga series of computers. If
you plan to use this kernel on an Amiga, say Y here and browse the
material available in <file:Documentation/m68k>; otherwise say N.
material available in <file:Documentation/arch/m68k>; otherwise say N.
config ATARI
bool "Atari support"
......@@ -23,7 +23,7 @@ config ATARI
This option enables support for the 68000-based Atari series of
computers (including the TT, Falcon and Medusa). If you plan to use
this kernel on an Atari, say Y here and browse the material
available in <file:Documentation/m68k>; otherwise say N.
available in <file:Documentation/arch/m68k>; otherwise say N.
config ATARI_KBD_CORE
bool
......
arch/sh/Kconfig.cpu
View file @ c23f2897
......@@ -85,7 +85,7 @@ config CPU_HAS_SR_RB
that are lacking this bit must have another method in place for
accomplishing what is taken care of by the banked registers.
See <file:Documentation/sh/register-banks.rst> for further
See <file:Documentation/arch/sh/register-banks.rst> for further
information on SR.RB and register banking in the kernel in general.
config CPU_HAS_PTEAEX
......
arch/x86/Kconfig
View file @ c23f2897
......@@ -433,7 +433,7 @@ config SMP
Y to "Enhanced Real Time Clock Support", below. The "Advanced Power
Management" code will be disabled if you say Y here.
See also <file:Documentation/x86/i386/IO-APIC.rst>,
See also <file:Documentation/arch/x86/i386/IO-APIC.rst>,
<file:Documentation/admin-guide/lockup-watchdogs.rst> and the SMP-HOWTO available at
<http://www.tldp.org/docs.html#howto>.
......@@ -1323,7 +1323,7 @@ config MICROCODE
the Linux kernel.
The preferred method to load microcode from a detached initrd is described
in Documentation/x86/microcode.rst. For that you need to enable
in Documentation/arch/x86/microcode.rst. For that you need to enable
CONFIG_BLK_DEV_INITRD in order for the loader to be able to scan the
initrd for microcode blobs.
......@@ -1509,7 +1509,7 @@ config X86_5LEVEL
A kernel with the option enabled can be booted on machines that
support 4- or 5-level paging.
See Documentation/x86/x86_64/5level-paging.rst for more
See Documentation/arch/x86/x86_64/5level-paging.rst for more
information.
Say N if unsure.
......@@ -1773,7 +1773,7 @@ config MTRR
You can safely say Y even if your machine doesn't have MTRRs, you'll
just add about 9 KB to your kernel.
See <file:Documentation/x86/mtrr.rst> for more information.
See <file:Documentation/arch/x86/mtrr.rst> for more information.
config MTRR_SANITIZER
def_bool y
......@@ -2549,7 +2549,7 @@ config PAGE_TABLE_ISOLATION
ensuring that the majority of kernel addresses are not mapped
into userspace.
See Documentation/x86/pti.rst for more details.
See Documentation/arch/x86/pti.rst for more details.
config RETPOLINE
bool "Avoid speculative indirect branches in kernel"
......
arch/x86/Kconfig.debug
View file @ c23f2897
......@@ -97,7 +97,7 @@ config IOMMU_DEBUG
code. When you use it make sure you have a big enough
IOMMU/AGP aperture. Most of the options enabled by this can
be set more finegrained using the iommu= command line
options. See Documentation/x86/x86_64/boot-options.rst for more
options. See Documentation/arch/x86/x86_64/boot-options.rst for more
details.
config IOMMU_LEAK
......
arch/x86/boot/header.S
View file @ c23f2897
......@@ -321,7 +321,7 @@ start_sys_seg: .word SYSSEG # obsolete and meaningless, but just
type_of_loader: .byte 0 # 0 means ancient bootloader, newer
# bootloaders know to change this.
# See Documentation/x86/boot.rst for
# See Documentation/arch/x86/boot.rst for
# assigned ids
# flags, unused bits must be zero (RFU) bit within loadflags
......
arch/x86/entry/entry_64.S
View file @ c23f2897
......@@ -8,7 +8,7 @@
*
* entry.S contains the system-call and fault low-level handling routines.
*
* Some of this is documented in Documentation/x86/entry_64.rst
* Some of this is documented in Documentation/arch/x86/entry_64.rst
*
* A note on terminology:
* - iret frame: Architecture defined interrupt frame from SS to RIP
......
arch/x86/include/asm/bootparam_utils.h
View file @ c23f2897
......@@ -38,7 +38,7 @@ static void sanitize_boot_params(struct boot_params *boot_params)
* IMPORTANT NOTE TO BOOTLOADER AUTHORS: do not simply clear
* this field. The purpose of this field is to guarantee
* compliance with the x86 boot spec located in
* Documentation/x86/boot.rst . That spec says that the
* Documentation/arch/x86/boot.rst . That spec says that the
* *whole* structure should be cleared, after which only the
* portion defined by struct setup_header (boot_params->hdr)
* should be copied in.
......
arch/x86/include/asm/page_64_types.h
View file @ c23f2897
......@@ -49,7 +49,7 @@
#define __START_KERNEL_map _AC(0xffffffff80000000, UL)
/* See Documentation/x86/x86_64/mm.rst for a description of the memory map. */
/* See Documentation/arch/x86/x86_64/mm.rst for a description of the memory map. */
#define __PHYSICAL_MASK_SHIFT 52
......
arch/x86/include/asm/pgtable_64_types.h
View file @ c23f2897
......@@ -104,7 +104,7 @@ extern unsigned int ptrs_per_p4d;
#define PGDIR_MASK (~(PGDIR_SIZE - 1))
/*
* See Documentation/x86/x86_64/mm.rst for a description of the memory map.
* See Documentation/arch/x86/x86_64/mm.rst for a description of the memory map.
*
* Be very careful vs. KASLR when changing anything here. The KASLR address
* range must not overlap with anything except the KASAN shadow area, which
......
arch/x86/kernel/cpu/microcode/amd.c
View file @ c23f2897
......@@ -61,7 +61,7 @@ static u8 amd_ucode_patch[MAX_NUMNODES][PATCH_MAX_SIZE];
/*
* Microcode patch container file is prepended to the initrd in cpio
* format. See Documentation/x86/microcode.rst
* format. See Documentation/arch/x86/microcode.rst
*/
static const char
ucode_path[] __maybe_unused = "kernel/x86/microcode/AuthenticAMD.bin";
......
arch/x86/kernel/cpu/resctrl/monitor.c
View file @ c23f2897
......@@ -76,7 +76,7 @@ unsigned int resctrl_rmid_realloc_limit;
#define CF(cf) ((unsigned long)(1048576 * (cf) + 0.5))
/*
* The correction factor table is documented in Documentation/x86/resctrl.rst.
* The correction factor table is documented in Documentation/arch/x86/resctrl.rst.
* If rmid > rmid threshold, MBM total and local values should be multiplied
* by the correction factor.
*
......
arch/x86/kernel/cpu/sgx/sgx.h
View file @ c23f2897
......@@ -15,7 +15,7 @@
#define EREMOVE_ERROR_MESSAGE \
"EREMOVE returned %d (0x%x) and an EPC page was leaked. SGX may become unusable. " \
"Refer to Documentation/x86/sgx.rst for more information."
"Refer to Documentation/arch/x86/sgx.rst for more information."
#define SGX_MAX_EPC_SECTIONS 8
#define SGX_EEXTEND_BLOCK_SIZE 256
......
arch/x86/kernel/kexec-bzimage64.c
View file @ c23f2897
......@@ -476,7 +476,7 @@ static void *bzImage64_load(struct kimage *image, char *kernel,
efi_map_offset = params_cmdline_sz;
efi_setup_data_offset = efi_map_offset + ALIGN(efi_map_sz, 16);
/* Copy setup header onto bootparams. Documentation/x86/boot.rst */
/* Copy setup header onto bootparams. Documentation/arch/x86/boot.rst */
setup_header_size = 0x0202 + kernel[0x0201] - setup_hdr_offset;
/* Is there a limit on setup header size? */
......
arch/x86/kernel/pci-dma.c
View file @ c23f2897
......@@ -124,7 +124,7 @@ void __init pci_iommu_alloc(void)
}
/*
* See <Documentation/x86/x86_64/boot-options.rst> for the iommu kernel
* See <Documentation/arch/x86/x86_64/boot-options.rst> for the iommu kernel
* parameter documentation.
*/
static __init int iommu_setup(char *p)
......
arch/x86/mm/pat/set_memory.c
View file @ c23f2897
......@@ -234,7 +234,7 @@ within_inclusive(unsigned long addr, unsigned long start, unsigned long end)
* take full advantage of the the limited (s32) immediate addressing range (2G)
* of x86_64.
*
* See Documentation/x86/x86_64/mm.rst for more detail.
* See Documentation/arch/x86/x86_64/mm.rst for more detail.
*/
static inline unsigned long highmap_start_pfn(void)
......
arch/x86/mm/tlb.c
View file @ c23f2897
......@@ -925,7 +925,7 @@ void flush_tlb_multi(const struct cpumask *cpumask,
}
/*
* See Documentation/x86/tlb.rst for details. We choose 33
* See Documentation/arch/x86/tlb.rst for details. We choose 33
* because it is large enough to cover the vast majority (at
* least 95%) of allocations, and is small enough that we are
* confident it will not cause too much overhead. Each single
......
arch/x86/platform/pvh/enlighten.c
View file @ c23f2897
......@@ -86,7 +86,7 @@ static void __init init_pvh_bootparams(bool xen_guest)
}
/*
* See Documentation/x86/boot.rst.
* See Documentation/arch/x86/boot.rst.
*
* Version 2.12 supports Xen entry point but we will use default x86/PC
* environment (i.e. hardware_subarch 0).
......
arch/xtensa/include/asm/initialize_mmu.h
View file @ c23f2897
......@@ -43,7 +43,7 @@
#if XCHAL_HAVE_S32C1I && (XCHAL_HW_MIN_VERSION >= XTENSA_HWVERSION_RC_2009_0)
/*
* We Have Atomic Operation Control (ATOMCTL) Register; Initialize it.
* For details see Documentation/xtensa/atomctl.rst
* For details see Documentation/arch/xtensa/atomctl.rst
*/
#if XCHAL_DCACHE_IS_COHERENT
movi a3, 0x25 /* For SMP/MX -- internal for writeback,
......
drivers/sbus/char/oradax.c
View file @ c23f2897
......@@ -18,7 +18,7 @@
* the recommended way for applications to use the coprocessor, and
* the driver interface is not intended for general use.
*
* See Documentation/sparc/oradax/oracle-dax.rst for more details.
* See Documentation/arch/sparc/oradax/oracle-dax.rst for more details.
*/
#include <linux/uaccess.h>
......
drivers/vhost/vhost.c
View file @ c23f2897
......@@ -1831,7 +1831,7 @@ EXPORT_SYMBOL_GPL(vhost_dev_ioctl);
/* TODO: This is really inefficient. We need something like get_user()
* (instruction directly accesses the data, with an exception table entry
* returning -EFAULT). See Documentation/x86/exception-tables.rst.
* returning -EFAULT). See Documentation/arch/x86/exception-tables.rst.
*/
static int set_bit_to_user(int nr, void __user *addr)
{
......
fs/qnx4/README deleted 100644 → 0
View file @ 1be89faa
This is a snapshot of the QNX4 filesystem for Linux.
Please send diffs and remarks to <al@alarsen.net> .
Credits :
Richard "Scuba" A. Frowijn <scuba@wxs.nl>
Frank "Jedi/Sector One" Denis <j@pureftpd.org>
Anders Larsen <al@alarsen.net> (Maintainer)
fs/qnx6/README deleted 100644 → 0
View file @ 1be89faa
This is a snapshot of the QNX6 filesystem for Linux.
Please send diffs and remarks to <chaosman@ontika.net> .
Credits :
Al Viro <viro@ZenIV.linux.org.uk> (endless patience with me & support ;))
Kai Bankett <chaosman@ontika.net> (Maintainer)
security/Kconfig
View file @ c23f2897
......@@ -105,7 +105,7 @@ config INTEL_TXT
See <https://www.intel.com/technology/security/> for more information
about Intel(R) TXT.
See <http://tboot.sourceforge.net> for more information about tboot.
See Documentation/x86/intel_txt.rst for a description of how to enable
See Documentation/arch/x86/intel_txt.rst for a description of how to enable
Intel TXT support in a kernel boot.
If you are unsure as to whether this is required, answer N.
......
tools/include/linux/err.h
View file @ c23f2897
......@@ -20,7 +20,7 @@
* Userspace note:
* The same principle works for userspace, because 'error' pointers
* fall down to the unused hole far from user space, as described
* in Documentation/x86/x86_64/mm.rst for x86_64 arch:
* in Documentation/arch/x86/x86_64/mm.rst for x86_64 arch:
*
* 0000000000000000 - 00007fffffffffff (=47 bits) user space, different per mm hole caused by [48:63] sign extension
* ffffffffffe00000 - ffffffffffffffff (=2 MB) unused hole
......
tools/objtool/Documentation/objtool.txt
View file @ c23f2897
......@@ -181,7 +181,7 @@ b) ORC (Oops Rewind Capability) unwind table generation
band. So it doesn't affect runtime performance and it can be
reliable even when interrupts or exceptions are involved.
For more details, see Documentation/x86/orc-unwinder.rst.
For more details, see Documentation/arch/x86/orc-unwinder.rst.
c) Higher live patching compatibility rate
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7