diff options
| author | Linus Torvalds <torvalds@linux-foundation.org> | 2023-02-22 12:00:20 -0800 |
|---|---|---|
| committer | Linus Torvalds <torvalds@linux-foundation.org> | 2023-02-22 12:00:20 -0800 |
| commit | 70756b49be4ea8bf36a664322df6e7e89895fa60 (patch) | |
| tree | fdbbf14342cf0124e08665e144678ccbbda6a1dc | |
| parent | bc009f9382bd0704273c9a0c1cbf72020bbbe1f7 (diff) | |
| parent | cc29eadef921fe52aa58f32536a93d9ea0ca3eb7 (diff) | |
Merge tag 'docs-6.3' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet:
"It has been a moderately calm cycle for documentation; the significant
changes include:
- Some significant additions to the memory-management documentation
- Some improvements to navigation in the HTML-rendered docs
- More Spanish and Chinese translations
... and the usual set of typo fixes and such"
* tag 'docs-6.3' of git://git.lwn.net/linux: (68 commits)
Documentation/watchdog/hpwdt: Fix Format
Documentation/watchdog/hpwdt: Fix Reference
Documentation: core-api: padata: correct spelling
docs/mm: Physical Memory: correct spelling in reference to CONFIG_PAGE_EXTENSION
docs: Use HTML comments for the kernel-toc SPDX line
docs: Add more information to the HTML sidebar
Documentation: KVM: Update AMD memory encryption link
printk: Document that CONFIG_BOOT_PRINTK_DELAY required for boot_delay=
Documentation: userspace-api: correct spelling
Documentation: sparc: correct spelling
Documentation: driver-api: correct spelling
Documentation: admin-guide: correct spelling
docs: add workload-tracing document to admin-guide
docs/admin-guide/mm: remove useless markup
docs/mm: remove useless markup
docs/mm: Physical Memory: remove useless markup
docs/sp_SP: Add process magic-number translation
docs: ftrace: always use canonical ftrace path
Doc/damon: fix the data path error
dma-buf: Add "dma-buf" to title of documentation
...
199 files changed, 3345 insertions, 904 deletions
diff --git a/Documentation/Kconfig b/Documentation/Kconfig index 252bfc164dbd..3a0e7ac0c4e3 100644 --- a/Documentation/Kconfig +++ b/Documentation/Kconfig @@ -1,6 +1,9 @@ +if COMPILE_TEST + +menu "Documentation" + config WARN_MISSING_DOCUMENTS bool "Warn if there's a missing documentation file" - depends on COMPILE_TEST help It is not uncommon that a document gets renamed. This option makes the Kernel to check for missing dependencies, @@ -11,7 +14,6 @@ config WARN_MISSING_DOCUMENTS config WARN_ABI_ERRORS bool "Warn if there are errors at ABI files" - depends on COMPILE_TEST help The files under Documentation/ABI should follow what's described at Documentation/ABI/README. Yet, as they're manually @@ -20,3 +22,7 @@ config WARN_ABI_ERRORS scripts/get_abi.pl. Add a check to verify them. If unsure, select 'N'. + +endmenu + +endif diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst index c17c87af1968..e73f84aebde3 100644 --- a/Documentation/PCI/index.rst +++ b/Documentation/PCI/index.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -======================= -Linux PCI Bus Subsystem -======================= +================= +PCI Bus Subsystem +================= .. toctree:: :maxdepth: 2 diff --git a/Documentation/accel/introduction.rst b/Documentation/accel/introduction.rst index 6f31af14b1fc..11cade51f387 100644 --- a/Documentation/accel/introduction.rst +++ b/Documentation/accel/introduction.rst @@ -69,7 +69,7 @@ The accelerator devices will be exposed to the user space with the dedicated - device char files - /dev/accel/accel* - sysfs - /sys/class/accel/accel*/ -- debugfs - /sys/kernel/debug/accel/accel*/ +- debugfs - /sys/kernel/debug/accel/*/ Getting Started =============== diff --git a/Documentation/admin-guide/bcache.rst b/Documentation/admin-guide/bcache.rst index 8d3a2d045c0a..bb5032a99234 100644 --- a/Documentation/admin-guide/bcache.rst +++ b/Documentation/admin-guide/bcache.rst @@ -204,7 +204,7 @@ For example:: This should present your unmodified backing device data in /dev/loop0 If your cache is in writethrough mode, then you can safely discard the -cache device without loosing data. +cache device without losing data. E) Wiping a cache device diff --git a/Documentation/admin-guide/cgroup-v1/blkio-controller.rst b/Documentation/admin-guide/cgroup-v1/blkio-controller.rst index 16253eda192e..dabb80cdd25a 100644 --- a/Documentation/admin-guide/cgroup-v1/blkio-controller.rst +++ b/Documentation/admin-guide/cgroup-v1/blkio-controller.rst @@ -106,7 +106,7 @@ Proportional weight policy files see Documentation/block/bfq-iosched.rst. blkio.bfq.weight_device - Specifes per cgroup per device weights, overriding the default group + Specifies per cgroup per device weights, overriding the default group weight. For more details, see Documentation/block/bfq-iosched.rst. Following is the format:: diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index 5db4c4dd5bb4..f67c0829350b 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -624,7 +624,7 @@ and is an example of this type. Limits ------ -A child can only consume upto the configured amount of the resource. +A child can only consume up to the configured amount of the resource. Limits can be over-committed - the sum of the limits of children can exceed the amount of resource available to the parent. @@ -642,11 +642,11 @@ on an IO device and is an example of this type. Protections ----------- -A cgroup is protected upto the configured amount of the resource +A cgroup is protected up to the configured amount of the resource as long as the usages of all its ancestors are under their protected levels. Protections can be hard guarantees or best effort soft boundaries. Protections can also be over-committed in which case -only upto the amount available to the parent is protected among +only up to the amount available to the parent is protected among children. Protections are in the range [0, max] and defaults to 0, which is @@ -1079,7 +1079,7 @@ All time durations are in microseconds. $MAX $PERIOD - which indicates that the group may consume upto $MAX in each + which indicates that the group may consume up to $MAX in each $PERIOD duration. "max" for $MAX indicates no limit. If only one number is written, $MAX is updated. @@ -2289,7 +2289,7 @@ Cpuset Interface Files For a valid partition root with the sibling cpu exclusivity rule enabled, changes made to "cpuset.cpus" that violate the exclusivity rule will invalidate the partition as well as its - sibiling partitions with conflicting cpuset.cpus values. So + sibling partitions with conflicting cpuset.cpus values. So care must be taking in changing "cpuset.cpus". A valid non-root parent partition may distribute out all its CPUs diff --git a/Documentation/admin-guide/cifs/usage.rst b/Documentation/admin-guide/cifs/usage.rst index ed3b8dc854ec..2e151cd8c2e4 100644 --- a/Documentation/admin-guide/cifs/usage.rst +++ b/Documentation/admin-guide/cifs/usage.rst @@ -399,7 +399,7 @@ A partial list of the supported mount options follows: sep if first mount option (after the -o), overrides the comma as the separator between the mount - parms. e.g.:: + parameters. e.g.:: -o user=myname,password=mypassword,domain=mydom @@ -765,7 +765,7 @@ cifsFYI If set to non-zero value, additional debug information Some debugging statements are not compiled into the cifs kernel unless CONFIG_CIFS_DEBUG2 is enabled in the kernel configuration. cifsFYI may be set to one or - nore of the following flags (7 sets them all):: + more of the following flags (7 sets them all):: +-----------------------------------------------+------+ | log cifs informational messages | 0x01 | diff --git a/Documentation/admin-guide/device-mapper/cache-policies.rst b/Documentation/admin-guide/device-mapper/cache-policies.rst index b17fe352fc41..13da4d831d46 100644 --- a/Documentation/admin-guide/device-mapper/cache-policies.rst +++ b/Documentation/admin-guide/device-mapper/cache-policies.rst @@ -70,7 +70,7 @@ the entries (each hotspot block covers a larger area than a single cache block). All this means smq uses ~25bytes per cache block. Still a lot of -memory, but a substantial improvement nontheless. +memory, but a substantial improvement nonetheless. Level balancing ^^^^^^^^^^^^^^^ diff --git a/Documentation/admin-guide/device-mapper/dm-ebs.rst b/Documentation/admin-guide/device-mapper/dm-ebs.rst index 534fa38e8862..c09f66db5621 100644 --- a/Documentation/admin-guide/device-mapper/dm-ebs.rst +++ b/Documentation/admin-guide/device-mapper/dm-ebs.rst @@ -31,7 +31,7 @@ Mandatory parameters: Optional parameter: - <underyling sectors>: + <underlying sectors>: Number of sectors defining the logical block size of <dev path>. 2^N supported, e.g. 8 = emulate 8 sectors of 512 bytes = 4KiB. If not provided, the logical block size of <dev path> will be used. diff --git a/Documentation/admin-guide/device-mapper/dm-zoned.rst b/Documentation/admin-guide/device-mapper/dm-zoned.rst index 0fac051caeac..932383fe6e88 100644 --- a/Documentation/admin-guide/device-mapper/dm-zoned.rst +++ b/Documentation/admin-guide/device-mapper/dm-zoned.rst @@ -46,7 +46,7 @@ just like conventional zones. The zones of the device(s) are separated into 2 types: 1) Metadata zones: these are conventional zones used to store metadata. -Metadata zones are not reported as useable capacity to the user. +Metadata zones are not reported as usable capacity to the user. 2) Data zones: all remaining zones, the vast majority of which will be sequential zones used exclusively to store user data. The conventional diff --git a/Documentation/admin-guide/device-mapper/unstriped.rst b/Documentation/admin-guide/device-mapper/unstriped.rst index 0a8d3eb3f072..5772ccdd1f5f 100644 --- a/Documentation/admin-guide/device-mapper/unstriped.rst +++ b/Documentation/admin-guide/device-mapper/unstriped.rst @@ -35,7 +35,7 @@ An example of undoing an existing dm-stripe This small bash script will setup 4 loop devices and use the existing striped target to combine the 4 devices into one. It then will use -the unstriped target ontop of the striped device to access the +the unstriped target on top of the striped device to access the individual backing loop devices. We write data to the newly exposed unstriped devices and verify the data written matches the correct underlying device on the striped array:: @@ -110,8 +110,8 @@ to get a 92% reduction in read latency using this device mapper target. Example dmsetup usage ===================== -unstriped ontop of Intel NVMe device that has 2 cores ------------------------------------------------------ +unstriped on top of Intel NVMe device that has 2 cores +------------------------------------------------------ :: @@ -124,8 +124,8 @@ respectively:: /dev/mapper/nvmset0 /dev/mapper/nvmset1 -unstriped ontop of striped with 4 drives using 128K chunk size --------------------------------------------------------------- +unstriped on top of striped with 4 drives using 128K chunk size +--------------------------------------------------------------- :: diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst index faa22f77847a..8dc668cc1216 100644 --- a/Documentation/admin-guide/dynamic-debug-howto.rst +++ b/Documentation/admin-guide/dynamic-debug-howto.rst @@ -330,7 +330,7 @@ Examples // boot-args example, with newlines and comments for readability Kernel command line: ... - // see whats going on in dyndbg=value processing + // see what's going on in dyndbg=value processing dynamic_debug.verbose=3 // enable pr_debugs in the btrfs module (can be builtin or loadable) btrfs.dyndbg="+p" diff --git a/Documentation/admin-guide/gpio/gpio-sim.rst b/Documentation/admin-guide/gpio/gpio-sim.rst index d8a90c81b9ee..1cc5567a4bbe 100644 --- a/Documentation/admin-guide/gpio/gpio-sim.rst +++ b/Documentation/admin-guide/gpio/gpio-sim.rst @@ -123,7 +123,7 @@ Each simulated GPIO chip creates a separate sysfs group under its device directory for each exposed line (e.g. ``/sys/devices/platform/gpio-sim.X/gpiochipY/``). The name of each group is of the form: ``'sim_gpioX'`` where X is the offset of the line. Inside each -group there are two attibutes: +group there are two attributes: ``pull`` - allows to read and set the current simulated pull setting for every line, when writing the value must be one of: ``'pull-up'``, diff --git a/Documentation/admin-guide/hw-vuln/mds.rst b/Documentation/admin-guide/hw-vuln/mds.rst index 2d19c9f4c1fe..f491de74ea79 100644 --- a/Documentation/admin-guide/hw-vuln/mds.rst +++ b/Documentation/admin-guide/hw-vuln/mds.rst @@ -64,8 +64,8 @@ architecture section: :ref:`Documentation/x86/mds.rst <mds>`. Attack scenarios ---------------- -Attacks against the MDS vulnerabilities can be mounted from malicious non -priviledged user space applications running on hosts or guest. Malicious +Attacks against the MDS vulnerabilities can be mounted from malicious non- +privileged user space applications running on hosts or guest. Malicious guest OSes can obviously mount attacks as well. Contrary to other speculation based vulnerabilities the MDS vulnerability diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 0571938ecdc8..0ad7e7ec0d27 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -56,6 +56,17 @@ ABI will be found here. sysfs-rules +This is the beginning of a section with information of interest to +application developers and system integrators doing analysis of the +Linux kernel for safety critical applications. Documents supporting +analysis of kernel interactions with applications, and key kernel +subsystems expectations will be found here. + +.. toctree:: + :maxdepth: 1 + + workload-tracing + The rest of this manual consists of various unordered guides on how to configure specific aspects of kernel behavior to your liking. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 5e4ee29cf393..fae4cf7e78a6 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -378,18 +378,16 @@ autoconf= [IPV6] See Documentation/networking/ipv6.rst. - show_lapic= [APIC,X86] Advanced Programmable Interrupt Controller - Limit apic dumping. The parameter defines the maximal - number of local apics being dumped. Also it is possible - to set it to "all" by meaning -- no limit here. - Format: { 1 (default) | 2 | ... | all }. - The parameter valid if only apic=debug or - apic=verbose is specified. - Example: apic=debug show_lapic=all - apm= [APM] Advanced Power Management See header of arch/x86/kernel/apm_32.c. + apparmor= [APPARMOR] Disable or enable AppArmor at boot time + Format: { "0" | "1" } + See security/apparmor/Kconfig help text + 0 -- disable. + 1 -- enable. + Default value is set via kernel config option. + arcrimi= [HW,NET] ARCnet - "RIM I" (entirely mem-mapped) cards Format: <io>,<irq>,<nodeID> @@ -480,8 +478,10 @@ See Documentation/block/cmdline-partition.rst boot_delay= Milliseconds to delay each printk during boot. - Values larger than 10 seconds (10000) are changed to - no delay (0). + Only works if CONFIG_BOOT_PRINTK_DELAY is enabled, + and you may also have to specify "lpj=". Boot_delay + values larger than 10 seconds (10000) are assumed + erroneous and ignored. Format: integer bootconfig [KNL] @@ -673,7 +673,7 @@ Sets the size of kernel per-numa memory area for contiguous memory allocations. A value of 0 disables per-numa CMA altogether. And If this option is not - specificed, the default value is 0. + specified, the default value is 0. With per-numa CMA enabled, DMA users on node nid will first try to allocate buffer from the pernuma area which is located in node nid, if the allocation fails, @@ -945,7 +945,7 @@ driver code when a CPU writes to (or reads from) a random memory location. Note that there exists a class of memory corruptions problems caused by buggy H/W or - F/W or by drivers badly programing DMA (basically when + F/W or by drivers badly programming DMA (basically when memory is written at bus level and the CPU MMU is bypassed) which are not detectable by CONFIG_DEBUG_PAGEALLOC, hence this option will not help @@ -1046,26 +1046,12 @@ can be useful when debugging issues that require an SLB miss to occur. - stress_slb [PPC] - Limits the number of kernel SLB entries, and flushes - them frequently to increase the rate of SLB faults - on kernel addresses. - - stress_hpt [PPC] - Limits the number of kernel HPT entries in the hash - page table to increase the rate of hash page table - faults on kernel addresses. - disable= [IPV6] See Documentation/networking/ipv6.rst. disable_radix [PPC] Disable RADIX MMU mode on POWER9 - radix_hcall_invalidate=on [PPC/PSERIES] - Disable RADIX GTSE feature and use hcall for TLB - invalidate. - disable_tlbie [PPC] Disable TLBIE instruction. Currently does not work with KVM, with HASH MMU, or with coherent accelerators. @@ -1167,16 +1153,6 @@ Documentation/admin-guide/dynamic-debug-howto.rst for details. - nopku [X86] Disable Memory Protection Keys CPU feature found - in some Intel CPUs. - - <module>.async_probe[=<bool>] [KNL] - If no <bool> value is specified or if the value - specified is not a valid <bool>, enable asynchronous - probe on this module. Otherwise, enable/disable - asynchronous probe on this module as indicated by the - <bool> value. See also: module.async_probe - early_ioremap_debug [KNL] Enable debug messages in early_ioremap support. This is useful for tracking down temporary early mappings @@ -1753,7 +1729,7 @@ boot-time allocation of gigantic hugepages is skipped. hugetlb_free_vmemmap= - [KNL] Reguires CONFIG_HUGETLB_PAGE_OPTIMIZE_VMEMMAP + [KNL] Requires CONFIG_HUGETLB_PAGE_OPTIMIZE_VMEMMAP enabled. Control if HugeTLB Vmemmap Optimization (HVO) is enabled. Allows heavy hugetlb users to free up some more @@ -1792,12 +1768,6 @@ which allow the hypervisor to 'idle' the guest on lock contention. - keep_bootcon [KNL] - Do not unregister boot console at start. This is only - useful for debugging when something happens in the window - between unregistering the boot console and initializing - the real console. - i2c_bus= [HW] Override the default board specific I2C bus speed or register an additional I2C bus that is not registered from board initialization code. @@ -2367,17 +2337,18 @@ js= [HW,JOY] Analog joystick See Documentation/input/joydev/joystick.rst. - nokaslr [KNL] - When CONFIG_RANDOMIZE_BASE is set, this disables - kernel and module base offset ASLR (Address Space - Layout Randomization). - kasan_multi_shot [KNL] Enforce KASAN (Kernel Address Sanitizer) to print report on every invalid memory access. Without this parameter KASAN will print report only for the first invalid access. + keep_bootcon [KNL] + Do not unregister boot console at start. This is only + useful for debugging when something happens in the window + between unregistering the boot console and initializing + the real console. + keepinitrd [HW,ARM] kernelcore= [KNL,X86,IA-64,PPC] @@ -3326,6 +3297,13 @@ For details see: Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst + <module>.async_probe[=<bool>] [KNL] + If no <bool> value is specified or if the value + specified is not a valid <bool>, enable asynchronous + probe on this module. Otherwise, enable/disable + asynchronous probe on this module as indicated by the + <bool> value. See also: module.async_probe + module.async_probe=<bool> [KNL] When set to true, modules will use async probing by default. To enable/disable async probing for a @@ -3709,7 +3687,7 @@ 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 evalute + correctly or when doing power measurements to evaluate the impact of the sleep instructions. This is also useful when using JTAG debugger. @@ -3780,6 +3758,11 @@ nojitter [IA-64] Disables jitter checking for ITC timers. + nokaslr [KNL] + When CONFIG_RANDOMIZE_BASE is set, this disables + 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 @@ -3825,6 +3808,19 @@ nopcid [X86-64] Disable the PCID cpu feature. + nopku [X86] Disable Memory Protection Keys CPU feature found + in some Intel CPUs. + + 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 + XEN HVM, KVM, HYPER_V and VMWARE guest. + + nopvspin [X86,XEN,KVM] + Disables the qspinlock slow path using PV optimizations + which allow the hypervisor to 'idle' the guest on lock + contention. + norandmaps Don't use address space randomization. Equivalent to echo 0 > /proc/sys/kernel/randomize_va_space @@ -4592,6 +4588,10 @@ r128= [HW,DRM] + radix_hcall_invalidate=on [PPC/PSERIES] + Disable RADIX GTSE feature and use hcall for TLB + invalidate. + raid= [HW,RAID] See Documentation/admin-guide/md.rst. @@ -5584,13 +5584,6 @@ 1 -- enable. Default value is 1. - apparmor= [APPARMOR] Disable or enable AppArmor at boot time - Format: { "0" | "1" } - See security/apparmor/Kconfig help text - 0 -- disable. - 1 -- enable. - Default value is set via kernel config option. - serialnumber [BUGS=X86-32] sev=option[,option...] [X86-64] See Documentation/x86/x86_64/boot-options.rst @@ -5598,6 +5591,15 @@ shapers= [NET] Maximal number of shapers. + show_lapic= [APIC,X86] Advanced Programmable Interrupt Controller + Limit apic dumping. The parameter defines the maximal + number of local apics being dumped. Also it is possible + to set it to "all" by meaning -- no limit here. + Format: { 1 (default) | 2 | ... | all }. + The parameter valid if only apic=debug or + apic=verbose is specified. + Example: apic=debug show_lapic=all + simeth= [IA-64] simscsi= @@ -6037,6 +6039,16 @@ be used to filter out binaries which have not yet been made aware of AT_MINSIGSTKSZ. + stress_hpt [PPC] + Limits the number of kernel HPT entries in the hash + page table to increase the rate of hash page table + faults on kernel addresses. + + stress_slb [PPC] + Limits the number of kernel SLB entries, and flushes + them frequently to increase the rate of SLB faults + on kernel addresses. + sunrpc.min_resvport= sunrpc.max_resvport= [NFS,SUNRPC] @@ -6290,7 +6302,7 @@ that can be enabled or disabled just as if you were to echo the option name into - /sys/kernel/debug/tracing/trace_options + /sys/kernel/tracing/trace_options For example, to enable stacktrace option (to dump the stack trace of each event), add to the command line: @@ -6323,7 +6335,7 @@ [FTRACE] enable this option to disable tracing when a warning is hit. This turns off "tracing_on". Tracing can be enabled again by echoing '1' into the "tracing_on" - file located in /sys/kernel/debug/tracing/ + file located in /sys/kernel/tracing/ This option is useful, as it disables the trace before the WARNING dump is called, which prevents the trace to @@ -6778,11 +6790,11 @@ functions are at fixed addresses, they make nice targets for exploits that can control RIP. - emulate [default] Vsyscalls turn into traps and are - emulated reasonably safely. The vsyscall - page is readable. + emulate Vsyscalls turn into traps and are emulated + reasonably safely. The vsyscall page is + readable. - xonly Vsyscalls turn into traps and are + xonly [default] Vsyscalls turn into traps and are emulated reasonably safely. The vsyscall page is not readable. @@ -6979,16 +6991,6 @@ fairer and the number of possible event channels is much higher. Default is on (use fifo events). - 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 - XEN HVM, KVM, HYPER_V and VMWARE guest. - - nopvspin [X86,XEN,KVM] - Disables the qspinlock slow path using PV optimizations - which allow the hypervisor to 'idle' the guest on lock - contention. - xirc2ps_cs= [NET,PCMCIA] Format: <irq>,<irq_mask>,<io>,<full_duplex>,<do_sound>,<lockup_hack>[,<irq2>[,<irq3>[,<irq4>]]] diff --git a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst index e4a5fc26f1a9..993c2a05f5ee 100644 --- a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst +++ b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst @@ -25,7 +25,7 @@ References - In order to locate kernel-generated OS jitter on CPU N: - cd /sys/kernel/debug/tracing + cd /sys/kernel/tracing echo 1 > max_graph_depth # Increase the "1" for more detail echo function_graph > current_tracer # run workload diff --git a/Documentation/admin-guide/laptops/thinkpad-acpi.rst b/Documentation/admin-guide/laptops/thinkpad-acpi.rst index 475eb0e81e4a..e27a1c3f634e 100644 --- a/Documentation/admin-guide/laptops/thinkpad-acpi.rst +++ b/Documentation/admin-guide/laptops/thinkpad-acpi.rst @@ -1488,7 +1488,7 @@ Example of command to set keyboard language is mentioned below:: Text corresponding to keyboard layout to be set in sysfs are: be(Belgian), cz(Czech), da(Danish), de(German), en(English), es(Spain), et(Estonian), fr(French), fr-ch(French(Switzerland)), hu(Hungarian), it(Italy), jp (Japan), -nl(Dutch), nn(Norway), pl(Polish), pt(portugese), sl(Slovenian), sv(Sweden), +nl(Dutch), nn(Norway), pl(Polish), pt(portuguese), sl(Slovenian), sv(Sweden), tr(Turkey) WWAN Antenna type diff --git a/Documentation/admin-guide/md.rst b/Documentation/admin-guide/md.rst index d8fc9a59c086..4ff2cc291d18 100644 --- a/Documentation/admin-guide/md.rst +++ b/Documentation/admin-guide/md.rst @@ -317,7 +317,7 @@ All md devices contain: suspended (not supported yet) All IO requests will block. The array can be reconfigured. - Writing this, if accepted, will block until array is quiessent + Writing this, if accepted, will block until array is quiescent readonly no resync can happen. no superblocks get written. diff --git a/Documentation/admin-guide/media/bttv.rst b/Documentation/admin-guide/media/bttv.rst index 125f6f47123d..58cbaf6df694 100644 --- a/Documentation/admin-guide/media/bttv.rst +++ b/Documentation/admin-guide/media/bttv.rst @@ -909,7 +909,7 @@ DE hat diverse Treiber fuer diese Modelle (Stand 09/2002): - TVPhone98 (Bt878) - AVerTV und TVCapture98 w/VCR (Bt 878) - AVerTVStudio und TVPhone98 w/VCR (Bt878) - - AVerTV GO Serie (Kein SVideo Input) + - AVerTV GO Series (Kein SVideo Input) - AVerTV98 (BT-878 chip) - AVerTV98 mit Fernbedienung (BT-878 chip) - AVerTV/FM98 (BT-878 chip) diff --git a/Documentation/admin-guide/media/building.rst b/Documentation/admin-guide/media/building.rst index 2d660b76caea..a06473429916 100644 --- a/Documentation/admin-guide/media/building.rst +++ b/Documentation/admin-guide/media/building.rst @@ -137,7 +137,7 @@ The ``LIRC user interface`` option adds enhanced functionality when using the from remote controllers. The ``Support for eBPF programs attached to lirc devices`` option allows -the usage of special programs (called eBPF) that would allow aplications +the usage of special programs (called eBPF) that would allow applications to add extra remote controller decoding functionality to the Linux Kernel. The ``Remote controller decoders`` option allows selecting the diff --git a/Documentation/admin-guide/media/si476x.rst b/Documentation/admin-guide/media/si476x.rst index 87062301d6a1..c8882ee9f208 100644 --- a/Documentation/admin-guide/media/si476x.rst +++ b/Documentation/admin-guide/media/si476x.rst @@ -142,7 +142,7 @@ The drivers exposes following files: indicator 0x18 lassi Signed Low side adjacent Channel Strength indicator - 0x19 hassi ditto fpr High side + 0x19 hassi ditto for High side 0x20 mult Multipath indicator 0x21 dev Frequency deviation 0x24 assi Adjacent channel SSI diff --git a/Documentation/admin-guide/media/vivid.rst b/Documentation/admin-guide/media/vivid.rst index 672a8371f6ad..58ac25b2c385 100644 --- a/Documentation/admin-guide/media/vivid.rst +++ b/Documentation/admin-guide/media/vivid.rst @@ -580,7 +580,7 @@ Metadata Capture ---------------- The Metadata capture generates UVC format metadata. The PTS and SCR are -transmitted based on the values set in vivid contols. +transmitted based on the values set in vivid controls. The Metadata device will only work for the Webcam input, it will give back an error for all other inputs. diff --git a/Documentation/admin-guide/mm/concepts.rst b/Documentation/admin-guide/mm/concepts.rst index c79f1e336222..e796b0a7e4a5 100644 --- a/Documentation/admin-guide/mm/concepts.rst +++ b/Documentation/admin-guide/mm/concepts.rst @@ -1,5 +1,3 @@ -.. _mm_concepts: - ================= Concepts overview ================= @@ -86,16 +84,15 @@ memory with the huge pages. The first one is `HugeTLB filesystem`, or hugetlbfs. It is a pseudo filesystem that uses RAM as its backing store. For the files created in this filesystem the data resides in the memory and mapped using huge pages. The hugetlbfs is described at -:ref:`Documentation/admin-guide/mm/hugetlbpage.rst <hugetlbpage>`. +Documentation/admin-guide/mm/hugetlbpage.rst. Another, more recent, mechanism that enables use of the huge pages is called `Transparent HugePages`, or THP. Unlike the hugetlbfs that requires users and/or system administrators to configure what parts of the system memory should and can be mapped by the huge pages, THP manages such mappings transparently to the user and hence the -name. See -:ref:`Documentation/admin-guide/mm/transhuge.rst <admin_guide_transhuge>` -for more details about THP. +name. See Documentation/admin-guide/mm/transhuge.rst for more details +about THP. Zones ===== @@ -125,8 +122,8 @@ processor. Each bank is referred to as a `node` and for each node Linux constructs an independent memory management subsystem. A node has its own set of zones, lists of free and used pages and various statistics counters. You can find more details about NUMA in -:ref:`Documentation/mm/numa.rst <numa>` and in -:ref:`Documentation/admin-guide/mm/numa_memory_policy.rst <numa_memory_policy>`. +Documentation/mm/numa.rst` and in +Documentation/admin-guide/mm/numa_memory_policy.rst. Page cache ========== diff --git a/Documentation/admin-guide/mm/damon/lru_sort.rst b/Documentation/admin-guide/mm/damon/lru_sort.rst index c09cace80651..7b0775d281b4 100644 --- a/Documentation/admin-guide/mm/damon/lru_sort.rst +++ b/Documentation/admin-guide/mm/damon/lru_sort.rst @@ -54,7 +54,7 @@ that is built with ``CONFIG_DAMON_LRU_SORT=y``. To let sysadmins enable or disable it and tune for the given system, DAMON_LRU_SORT utilizes module parameters. That is, you can put ``damon_lru_sort.<parameter>=<value>`` on the kernel boot command line or write -proper values to ``/sys/modules/damon_lru_sort/parameters/<parameter>`` files. +proper values to ``/sys/module/damon_lru_sort/parameters/<parameter>`` files. Below are the description of each parameter. @@ -283,7 +283,7 @@ doesn't make progress and therefore the free memory rate becomes lower than 20%, it asks DAMON_LRU_SORT to do nothing again, so that we can fall back to the LRU-list based page granularity reclamation. :: - # cd /sys/modules/damon_lru_sort/parameters + # cd /sys/module/damon_lru_sort/parameters # echo 500 > hot_thres_access_freq # echo 120000000 > cold_min_age # echo 10 > quota_ms diff --git a/Documentation/admin-guide/mm/damon/reclaim.rst b/Documentation/admin-guide/mm/damon/reclaim.rst index 4f1479a11e63..d2ccd9c21b9a 100644 --- a/Documentation/admin-guide/mm/damon/reclaim.rst +++ b/Documentation/admin-guide/mm/damon/reclaim.rst @@ -46,7 +46,7 @@ that is built with ``CONFIG_DAMON_RECLAIM=y``. To let sysadmins enable or disable it and tune for the given system, DAMON_RECLAIM utilizes module parameters. That is, you can put ``damon_reclaim.<parameter>=<value>`` on the kernel boot command line or write -proper values to ``/sys/modules/damon_reclaim/parameters/<parameter>`` files. +proper values to ``/sys/module/damon_reclaim/parameters/<parameter>`` files. Below are the description of each parameter. @@ -251,7 +251,7 @@ therefore the free memory rate becomes lower than 20%, it asks DAMON_RECLAIM to do nothing again, so that we can fall back to the LRU-list based page granularity reclamation. :: - # cd /sys/modules/damon_reclaim/parameters + # cd /sys/module/damon_reclaim/parameters # echo 30000000 > min_age # echo $((1 * 1024 * 1024 * 1024)) > quota_sz # echo 1000 > quota_reset_interval_ms diff --git a/Documentation/admin-guide/mm/hugetlbpage.rst b/Documentation/admin-guide/mm/hugetlbpage.rst index 19f27c0d92e0..bca00cb6f43a 100644 --- a/Documentation/admin-guide/mm/hugetlbpage.rst +++ b/Documentation/admin-guide/mm/hugetlbpage.rst @@ -1,5 +1,3 @@ -.. _hugetlbpage: - ============= HugeTLB Pages ============= @@ -86,7 +84,7 @@ by increasing or decreasing the value of ``nr_hugepages``. Note: When the feature of freeing unused vmemmap pages associated with each hugetlb page is enabled, we can fail to free the huge pages triggered by -the user when ths system is under memory pressure. Please try again later. +the user when the system is under memory pressure. Please try again later. Pages that are used as huge pages are reserved inside the kernel and cannot be used for other purposes. Huge pages cannot be swapped out under @@ -313,7 +311,7 @@ memory policy mode--bind, preferred, local or interleave--may be used. The resulting effect on persistent huge page allocation is as follows: #. Regardless of mempolicy mode [see - :ref:`Documentation/admin-guide/mm/numa_memory_policy.rst <numa_memory_policy>`], + Documentation/admin-guide/mm/numa_memory_policy.rst], persistent huge pages will be distributed across the node or nodes specified in the mempolicy as if "interleave" had been specified. However, if a node in the policy does not contain sufficient contiguous diff --git a/Documentation/admin-guide/mm/idle_page_tracking.rst b/Documentation/admin-guide/mm/idle_page_tracking.rst index df9394fb39c2..b5a285bd73fd 100644 --- a/Documentation/admin-guide/mm/idle_page_tracking.rst +++ b/Documentation/admin-guide/mm/idle_page_tracking.rst @@ -1,5 +1,3 @@ -.. _idle_page_tracking: - ================== Idle Page Tracking ================== @@ -70,9 +68,8 @@ If the tool is run initially with the appropriate option, it will mark all the queried pages as idle. Subsequent runs of the tool can then show which pages have their idle flag cleared in the interim. -See :ref:`Documentation/admin-guide/mm/pagemap.rst <pagemap>` for more -information about ``/proc/pid/pagemap``, ``/proc/kpageflags``, and -``/proc/kpagecgroup``. +See Documentation/admin-guide/mm/pagemap.rst for more information about +``/proc/pid/pagemap``, ``/proc/kpageflags``, and ``/proc/kpagecgroup``. .. _impl_details: diff --git a/Documentation/admin-guide/mm/index.rst b/Documentation/admin-guide/mm/index.rst index d1064e0ba34a..1f883abf3f00 100644 --- a/Documentation/admin-guide/mm/index.rst +++ b/Documentation/admin-guide/mm/index.rst @@ -16,8 +16,7 @@ are described in Documentation/admin-guide/sysctl/vm.rst and in `man 5 proc`_. .. _man 5 proc: http://man7.org/linux/man-pages/man5/proc.5.html Linux memory management has its own jargon and if you are not yet -familiar with it, consider reading -:ref:`Documentation/admin-guide/mm/concepts.rst <mm_concepts>`. +familiar with it, consider reading Documentation/admin-guide/mm/concepts.rst. Here we document in detail how to interact with various mechanisms in the Linux memory management. diff --git a/Documentation/admin-guide/mm/ksm.rst b/Documentation/admin-guide/mm/ksm.rst index fb6ba2002a4b..eed51a910c94 100644 --- a/Documentation/admin-guide/mm/ksm.rst +++ b/Documentation/admin-guide/mm/ksm.rst @@ -1,5 +1,3 @@ -.. _admin_guide_ksm: - ======================= Kernel Samepage Merging ======================= diff --git a/Documentation/admin-guide/mm/memory-hotplug.rst b/Documentation/admin-guide/mm/memory-hotplug.rst index a3c9e8ad8fa0..1b02fe5807cc 100644 --- a/Documentation/admin-guide/mm/memory-hotplug.rst +++ b/Documentation/admin-guide/mm/memory-hotplug.rst @@ -1,5 +1,3 @@ -.. _admin_guide_memory_hotplug: - ================== Memory Hot(Un)Plug ================== diff --git a/Documentation/admin-guide/mm/numa_memory_policy.rst b/Documentation/admin-guide/mm/numa_memory_policy.rst index 5a6afecbb0d0..46515ad2337f 100644 --- a/Documentation/admin-guide/mm/numa_memory_policy.rst +++ b/Documentation/admin-guide/mm/numa_memory_policy.rst @@ -1,5 +1,3 @@ -.. _numa_memory_policy: - ================== NUMA Memory Policy ================== @@ -246,7 +244,7 @@ MPOL_INTERLEAVED interleaved system default policy works in this mode. MPOL_PREFERRED_MANY - This mode specifices that the allocation should be preferrably + This mode specifies that the allocation should be preferably satisfied from the nodemask specified in the policy. If there is a memory pressure on all nodes in the nodemask, the allocation can fall back to all existing numa nodes. This is effectively @@ -360,7 +358,7 @@ and NUMA nodes. "Usage" here means one of the following: 2) examination of the policy to determine the policy mode and associated node or node lists, if any, for page allocation. This is considered a "hot path". Note that for MPOL_BIND, the "usage" extends across the entire - allocation process, which may sleep during page reclaimation, because the + allocation process, which may sleep during page reclamation, because the BIND policy nodemask is used, by reference, to filter ineligible nodes. We can avoid taking an extra reference during the usages listed above as diff --git a/Documentation/admin-guide/mm/numaperf.rst b/Documentation/admin-guide/mm/numaperf.rst index 166697325947..24e63e740420 100644 --- a/Documentation/admin-guide/mm/numaperf.rst +++ b/Documentation/admin-guide/mm/numaperf.rst @@ -1,5 +1,3 @@ -.. _numaperf: - ============= NUMA Locality ============= diff --git a/Documentation/admin-guide/mm/pagemap.rst b/Documentation/admin-guide/mm/pagemap.rst index 6e2e416af783..1a22674ab18e 100644 --- a/Documentation/admin-guide/mm/pagemap.rst +++ b/Documentation/admin-guide/mm/pagemap.rst @@ -1,5 +1,3 @@ -.. _pagemap: - ============================= Examining Process Page Tables ============================= @@ -19,10 +17,10 @@ There are four components to pagemap: * Bits 0-4 swap type if swapped * Bits 5-54 swap offset if swapped * Bit 55 pte is soft-dirty (see - :ref:`Documentation/admin-guide/mm/soft-dirty.rst <soft_dirty>`) + Documentation/admin-guide/mm/soft-dirty.rst) * Bit 56 page exclusively mapped (since 4.2) * Bit 57 pte is uffd-wp write-protected (since 5.13) (see - :ref:`Documentation/admin-guide/mm/userfaultfd.rst <userfaultfd>`) + Documentation/admin-guide/mm/userfaultfd.rst) * Bits 58-60 zero * Bit 61 page is file-page or shared-anon (since 3.5) * Bit 62 page swapped @@ -105,8 +103,7 @@ Short descriptions to the page flags A compound page with order N consists of 2^N physically contiguous pages. A compound page with order 2 takes the form of "HTTT", where H donates its head page and T donates its tail page(s). The major consumers of compound - pages are hugeTLB pages - (:ref:`Documentation/admin-guide/mm/hugetlbpage.rst <hugetlbpage>`), + pages are hugeTLB pages (Documentation/admin-guide/mm/hugetlbpage.rst), the SLUB etc. memory allocators and various device drivers. However in this interface, only huge/giga pages are made visible to end users. @@ -128,7 +125,7 @@ Short descriptions to the page flags Zero page for pfn_zero or huge_zero page. 25 - IDLE The page has not been accessed since it was marked idle (see - :ref:`Documentation/admin-guide/mm/idle_page_tracking.rst <idle_page_tracking>`). + Documentation/admin-guide/mm/idle_page_tracking.rst). Note that this flag may be stale in case the page was accessed via a PTE. To make sure the flag is up-to-date one has to read ``/sys/kernel/mm/page_idle/bitmap`` first. diff --git a/Documentation/admin-guide/mm/shrinker_debugfs.rst b/Documentation/admin-guide/mm/shrinker_debugfs.rst index 3887f0b294fe..c582033bd113 100644 --- a/Documentation/admin-guide/mm/shrinker_debugfs.rst +++ b/Documentation/admin-guide/mm/shrinker_debugfs.rst @@ -1,5 +1,3 @@ -.. _shrinker_debugfs: - ========================== Shrinker Debugfs Interface ========================== diff --git a/Documentation/admin-guide/mm/soft-dirty.rst b/Documentation/admin-guide/mm/soft-dirty.rst index cb0cfd6672fa..aeea936caa44 100644 --- a/Documentation/admin-guide/mm/soft-dirty.rst +++ b/Documentation/admin-guide/mm/soft-dirty.rst @@ -1,5 +1,3 @@ -.. _soft_dirty: - =============== Soft-Dirty PTEs =============== diff --git a/Documentation/admin-guide/mm/swap_numa.rst b/Documentation/admin-guide/mm/swap_numa.rst index e0466f2db8fa..2e630627bcee 100644 --- a/Documentation/admin-guide/mm/swap_numa.rst +++ b/Documentation/admin-guide/mm/swap_numa.rst @@ -1,5 +1,3 @@ -.. _swap_numa: - =========================================== Automatically bind swap device to numa node =========================================== diff --git a/Documentation/admin-guide/mm/transhuge.rst b/Documentation/admin-guide/mm/transhuge.rst index 8ee78ec232eb..b0cc8243e093 100644 --- a/Documentation/admin-guide/mm/transhuge.rst +++ b/Documentation/admin-guide/mm/transhuge.rst @@ -1,5 +1,3 @@ -.. _admin_guide_transhuge: - ============================ Transparent Hugepage Support ============================ diff --git a/Documentation/admin-guide/mm/userfaultfd.rst b/Documentation/admin-guide/mm/userfaultfd.rst index 83f31919ebb3..7dc823b56ca4 100644 --- a/Documentation/admin-guide/mm/userfaultfd.rst +++ b/Documentation/admin-guide/mm/userfaultfd.rst @@ -1,5 +1,3 @@ -.. _userfaultfd: - =========== Userfaultfd =========== diff --git a/Documentation/admin-guide/mm/zswap.rst b/Documentation/admin-guide/mm/zswap.rst index 6dd74a18268b..c5c2c7dbb155 100644 --- a/Documentation/admin-guide/mm/zswap.rst +++ b/Documentation/admin-guide/mm/zswap.rst @@ -1,5 +1,3 @@ -.. _zswap: - ===== zswap ===== diff --git a/Documentation/admin-guide/perf/hns3-pmu.rst b/Documentation/admin-guide/perf/hns3-pmu.rst index 578407e487d6..75a40846d47f 100644 --- a/Documentation/admin-guide/perf/hns3-pmu.rst +++ b/Documentation/admin-guide/perf/hns3-pmu.rst @@ -53,7 +53,7 @@ two events have same value of bits 0~15 of config, that means they are event pair. And the bit 16 of config indicates getting counter 0 or counter 1 of hardware event. -After getting two values of event pair in usersapce, the formula of +After getting two values of event pair in userspace, the formula of computation to calculate real performance data is::: counter 0 / counter 1 diff --git a/Documentation/admin-guide/pm/amd-pstate.rst b/Documentation/admin-guide/pm/amd-pstate.rst index d143e72cf93e..6e5298b521b1 100644 --- a/Documentation/admin-guide/pm/amd-pstate.rst +++ b/Documentation/admin-guide/pm/amd-pstate.rst @@ -473,7 +473,7 @@ Unit Tests for amd-pstate * We can introduce more functional or performance tests to align the result together, it will benefit power and performance scale optimization. -1. Test case decriptions +1. Test case descriptions 1). Basic tests diff --git a/Documentation/admin-guide/pm/intel_pstate.rst b/Documentation/admin-guide/pm/intel_pstate.rst index d5043cd8d2f5..bf13ad25a32f 100644 --- a/Documentation/admin-guide/pm/intel_pstate.rst +++ b/Documentation/admin-guide/pm/intel_pstate.rst @@ -712,7 +712,7 @@ it works in the `active mode <Active Mode_>`_. The following sequence of shell commands can be used to enable them and see their output (if the kernel is generally configured to support event tracing):: - # cd /sys/kernel/debug/tracing/ + # cd /sys/kernel/tracing/ # echo 1 > events/power/pstate_sample/enable # echo 1 > events/power/cpu_frequency/enable # cat trace @@ -732,7 +732,7 @@ The ``ftrace`` interface can be used for low-level diagnostics of P-state is called, the ``ftrace`` filter can be set to :c:func:`intel_pstate_set_pstate`:: - # cd /sys/kernel/debug/tracing/ + # cd /sys/kernel/tracing/ # cat available_filter_functions | grep -i pstate intel_pstate_set_pstate intel_pstate_cpu_init diff --git a/Documentation/admin-guide/spkguide.txt b/Documentation/admin-guide/spkguide.txt index 1265c1eab31c..74ea7f391942 100644 --- a/Documentation/admin-guide/spkguide.txt +++ b/Documentation/admin-guide/spkguide.txt @@ -1105,8 +1105,8 @@ speakup load Alternatively, you can add the above line to your file ~/.bashrc or ~/.bash_profile. -If your system administrator ran himself the script, all the users will be able -to change from English to the language choosed by root and do directly +If your system administrator himself ran the script, all the users will be able +to change from English to the language chosen by root and do directly speakupconf load (or add this to the ~/.bashrc or ~/.bash_profile file). If there are several languages to handle, the administrator (or every user) will have to run the first steps until speakupconf diff --git a/Documentation/admin-guide/sysctl/vm.rst b/Documentation/admin-guide/sysctl/vm.rst index 988f6a4c8084..45ba1f4dc004 100644 --- a/Documentation/admin-guide/sysctl/vm.rst +++ b/Documentation/admin-guide/sysctl/vm.rst @@ -356,7 +356,7 @@ The lowmem_reserve_ratio is an array. You can see them by reading this file:: But, these values are not used directly. The kernel calculates # of protection pages for each zones from them. These are shown as array of protection pages -in /proc/zoneinfo like followings. (This is an example of x86-64 box). +in /proc/zoneinfo like the following. (This is an example of x86-64 box). Each zone has an array of protection pages like this:: Node 0, zone DMA @@ -433,7 +433,7 @@ a 2bit error in a memory module) is detected in the background by hardware that cannot be handled by the kernel. In some cases (like the page still having a valid copy on disk) the kernel will handle the failure transparently without affecting any applications. But if there is -no other uptodate copy of the data it will kill to prevent any data +no other up-to-date copy of the data it will kill to prevent any data corruptions from propagating. 1: Kill all processes that have the corrupted and not reloadable page mapped diff --git a/Documentation/admin-guide/sysrq.rst b/Documentation/admin-guide/sysrq.rst index 0a178ef0111d..51906e47327b 100644 --- a/Documentation/admin-guide/sysrq.rst +++ b/Documentation/admin-guide/sysrq.rst @@ -138,7 +138,7 @@ Command Function ``v`` Forcefully restores framebuffer console ``v`` Causes ETM buffer dump [ARM-specific] -``w`` Dumps tasks that are in uninterruptable (blocked) state. +``w`` Dumps tasks that are in uninterruptible (blocked) state. ``x`` Used by xmon interface on ppc/powerpc platforms. Show global PMU Registers on sparc64. diff --git a/Documentation/admin-guide/thermal/intel_powerclamp.rst b/Documentation/admin-guide/thermal/intel_powerclamp.rst index 3ce96043af17..08509b978af4 100644 --- a/Documentation/admin-guide/thermal/intel_powerclamp.rst +++ b/Documentation/admin-guide/thermal/intel_powerclamp.rst @@ -87,7 +87,7 @@ migrated, unless the CPU is taken offline. In this case, threads belong to the offlined CPUs will be terminated immediately. Running as SCHED_FIFO and relatively high priority, also allows such -scheme to work for both preemptable and non-preemptable kernels. +scheme to work for both preemptible and non-preemptible kernels. Alignment of idle time around jiffies ensures scalability for HZ values. This effect can be better visualized using a Perf timechart. The following diagram shows the behavior of kernel thread diff --git a/Documentation/admin-guide/workload-tracing.rst b/Documentation/admin-guide/workload-tracing.rst new file mode 100644 index 000000000000..b2e254ec8ee8 --- /dev/null +++ b/Documentation/admin-guide/workload-tracing.rst @@ -0,0 +1,606 @@ +.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0) + +====================================================== +Discovering Linux kernel subsystems used by a workload +====================================================== + +:Authors: - Shuah Khan <skhan@linuxfoundation.org> + - Shefali Sharma <sshefali021@gmail.com> +:maintained-by: Shuah Khan <skhan@linuxfoundation.org> + +Key Points +========== + + * Understanding system resources necessary to build and run a workload + is important. + * Linux tracing and strace can be used to discover the system resources + in use by a workload. The completeness of the system usage information + depends on the completeness of coverage of a workload. + * Performance and security of the operating system can be analyzed with + the help of tools such as: + `perf <https://man7.org/linux/man-pages/man1/perf.1.html>`_, + `stress-ng <https://www.mankier.com/1/stress-ng>`_, + `paxtest <https://github.com/opntr/paxtest-freebsd>`_. + * Once we discover and understand the workload needs, we can focus on them + to avoid regressions and use it to evaluate safety considerations. + +Methodology +=========== + +`strace <https://man7.org/linux/man-pages/man1/strace.1.html>`_ is a +diagnostic, instructional, and debugging tool and can be used to discover +the system resources in use by a workload. Once we discover and understand +the workload needs, we can focus on them to avoid regressions and use it +to evaluate safety considerations. We use strace tool to trace workloads. + +This method of tracing using strace tells us the system calls invoked by +the workload and doesn't include all the system calls that can be invoked +by it. In addition, this tracing method tells us just the code paths within +these system calls that are invoked. As an example, if a workload opens a +file and reads from it successfully, then the success path is the one that +is traced. Any error paths in that system call will not be traced. If there +is a workload that provides full coverage of a workload then the method +outlined here will trace and find all possible code paths. The completeness +of the system usage information depends on the completeness of coverage of a +workload. + +The goal is tracing a workload on a system running a default kernel without +requiring custom kernel installs. + +How do we gather fine-grained system information? +================================================= + +strace tool can be used to trace system calls made by a process and signals +it receives. System calls are the fundamental interface between an +application and the operating system kernel. They enable a program to +request services from the kernel. For instance, the open() system call in +Linux is used to provide access to a file in the file system. strace enables +us to track all the system calls made by an application. It lists all the +system calls made by a process and their resulting output. + +You can generate profiling data combining strace and perf record tools to +record the events and information associated with a process. This provides +insight into the process. "perf annotate" tool generates the statistics of +each instruction of the program. This document goes over the details of how +to gather fine-grained information on a workload's usage of system resources. + +We used strace to trace the perf, stress-ng, paxtest workloads to illustrate +our methodology to discover resources used by a workload. This process can +be applied to trace other workloads. + +Getting the system ready for tracing +==================================== + +Before we can get started we will show you how to get your system ready. +We assume that you have a Linux distribution running on a physical system +or a virtual machine. Most distributions will include strace command. Let’s +install other tools that aren’t usually included to build Linux kernel. +Please note that the following works on Debian based distributions. You +might have to find equivalent packages on other Linux distributions. + +Install tools to build Linux kernel and tools in kernel repository. +scripts/ver_linux is a good way to check if your system already has +the necessary tools:: + + sudo apt-get build-essentials flex bison yacc + sudo apt install libelf-dev systemtap-sdt-dev libaudit-dev libslang2-dev libperl-dev libdw-dev + +cscope is a good tool to browse kernel sources. Let's install it now:: + + sudo apt-get install cscope + +Install stress-ng and paxtest:: + + apt-get install stress-ng + apt-get install paxtest + +Workload overview +================= + +As mentioned earlier, we used strace to trace perf bench, stress-ng and +paxtest workloads to show how to analyze a workload and identify Linux +subsystems used by these workloads. Let's start with an overview of these +three workloads to get a better understanding of what they do and how to +use them. + +perf bench (all) workload +------------------------- + +The perf bench command contains multiple multi-threaded microkernel +benchmarks for executing different subsystems in the Linux kernel and +system calls. This allows us to easily measure the impact of changes, +which can help mitigate performance regressions. It also acts as a common +benchmarking framework, enabling developers to easily create test cases, +integrate transparently, and use performance-rich tooling subsystems. + +Stress-ng netdev stressor workload +---------------------------------- + +stress-ng is used for performing stress testing on the kernel. It allows +you to exercise various physical subsystems of the computer, as well as +interfaces of the OS kernel, using "stressor-s". They are available for +CPU, CPU cache, devices, I/O, interrupts, file system, memory, network, +operating system, pipelines, schedulers, and virtual machines. Please refer +to the `stress-ng man-page <https://www.mankier.com/1/stress-ng>`_ to +find the description of all the available stressor-s. The netdev stressor +starts specified number (N) of workers that exercise various netdevice +ioctl commands across all the available network devices. + +paxtest kiddie workload +----------------------- + +paxtest is a program that tests buffer overflows in the kernel. It tests +kernel enforcements over memory usage. Generally, execution in some memory +segments makes buffer overflows possible. It runs a set of programs that +attempt to subvert memory usage. It is used as a regression test suite for +PaX, but might be useful to test other memory protection patches for the +kernel. We used paxtest kiddie mode which looks for simple vulnerabilities. + +What is strace and how do we use it? +==================================== + +As mentioned earlier, strace which is a useful diagnostic, instructional, +and debugging tool and can be used to discover the system resources in use +by a workload. It can be used: + + * To see how a process interacts with the kernel. + * To see why a process is failing or hanging. + * For reverse engineering a process. + * To find the files on which a program depends. + * For analyzing the performance of an application. + * For troubleshooting various problems related to the operating system. + +In addition, strace can generate run-time statistics on times, calls, and +errors for each system call and report a summary when program exits, +suppressing the regular output. This attempts to show system time (CPU time +spent running in the kernel) independent of wall clock time. We plan to use +these features to get information on workload system usage. + +strace command supports basic, verbose, and stats modes. strace command when +run in verbose mode gives more detailed information about the system calls +invoked by a process. + +Running strace -c generates a report of the percentage of time spent in each +system call, the total time in seconds, the microseconds per call, the total +number of calls, the count of each system call that has failed with an error +and the type of system call made. + + * Usage: strace <command we want to trace> + * Verbose mode usage: strace -v <command> + * Gather statistics: strace -c <command> + +We used the “-c” option to gather fine-grained run-time statistics in use +by three workloads we have chose for this analysis. + + * perf + * stress-ng + * paxtest + +What is cscope and how do we use it? +==================================== + +Now let’s look at `cscope <https://cscope.sourceforge.net/>`_, a command +line tool for browsing C, C++ or Java code-bases. We can use it to find +all the references to a symbol, global definitions, functions called by a +function, functions calling a function, text strings, regular expression +patterns, files including a file. + +We can use cscope to find which system call belongs to which subsystem. +This way we can find the kernel subsystems used by a process when it is +executed. + +Let’s checkout the latest Linux repository and build cscope database:: + + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git linux + cd linux + cscope -R -p10 # builds cscope.out database before starting browse session + cscope -d -p10 # starts browse session on cscope.out database + +Note: Run "cscope -R -p10" to build the database and c"scope -d -p10" to +enter into the browsing session. cscope by default cscope.out database. +To get out of this mode press ctrl+d. -p option is used to specify the +number of file path components to display. -p10 is optimal for browsing +kernel sources. + +What is perf and how do we use it? +================================== + +Perf is an analysis tool based on Linux 2.6+ systems, which abstracts the +CPU hardware difference in performance measurement in Linux, and provides +a simple command line interface. Perf is based on the perf_events interface +exported by the kernel. It is very useful for profiling the system and +finding performance bottlenecks in an application. + +If you haven't already checked out the Linux mainline repository, you can do +so and then build kernel and perf tool:: + + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git linux + cd linux + make -j3 all + cd tools/perf + make + +Note: The perf command can be built without building the kernel in the +repository and can be run on older kernels. However matching the kernel +and perf revisions gives more accurate information on the subsystem usage. + +We used "perf stat" and "perf bench" options. For a detailed information on +the perf tool, run "perf -h". + +perf stat +--------- +The perf stat command generates a report of various hardware and software +events. It does so with the help of hardware counter registers found in +modern CPUs that keep the count of these activities. "perf stat cal" shows +stats for cal command. + +Perf bench +---------- +The perf bench command contains multiple multi-threaded microkernel +benchmarks for executing different subsystems in the Linux kernel and +system calls. This allows us to easily measure the impact of changes, +which can help mitigate performance regressions. It also acts as a common +benchmarking framework, enabling developers to easily create test cases, +integrate transparently, and use performance-rich tooling. + +"perf bench all" command runs the following benchmarks: + + * sched/messaging + * sched/pipe + * syscall/basic + * mem/memcpy + * mem/memset + +What is stress-ng and how do we use it? +======================================= + +As mentioned earlier, stress-ng is used for performing stress testing on +the kernel. It allows you to exercise various physical subsystems of the +computer, as well as interfaces of the OS kernel, using stressor-s. They +are available for CPU, CPU cache, devices, I/O, interrupts, file system, +memory, network, operating system, pipelines, schedulers, and virtual +machines. + +The netdev stressor starts N workers that exercise various netdevice ioctl +commands across all the available network devices. The following ioctls are +exercised: + + * SIOCGIFCONF, SIOCGIFINDEX, SIOCGIFNAME, SIOCGIFFLAGS + * SIOCGIFADDR, SIOCGIFNETMASK, SIOCGIFMETRIC, SIOCGIFMTU + * SIOCGIFHWADDR, SIOCGIFMAP, SIOCGIFTXQLEN + +The following command runs the stressor:: + + stress-ng --netdev 1 -t 60 --metrics command. + +We can use the perf record command to record the events and information +associated with a process. This command records the profiling data in the +perf.data file in the same directory. + +Using the following commands you can record the events associated with the +netdev stressor, view the generated report perf.data and annotate the to +view the statistics of each instruction of the program:: + + perf record stress-ng --netdev 1 -t 60 --metrics command. + perf report + perf annotate + +What is paxtest and how do we use it? +===================================== + +paxtest is a program that tests buffer overflows in the kernel. It tests +kernel enforcements over memory usage. Generally, execution in some memory +segments makes buffer overflows possible. It runs a set of programs that +attempt to subvert memory usage. It is used as a regression test suite for +PaX, and will be useful to test other memory protection patches for the +kernel. + +paxtest provides kiddie and blackhat modes. The paxtest kiddie mode runs +in normal mode, whereas the blackhat mode tries to get around the protection +of the kernel testing for vulnerabilities. We focus on the kiddie mode here +and combine "paxtest kiddie" run with "perf record" to collect CPU stack +traces for the paxtest kiddie run to see which function is calling other +functions in the performance profile. Then the "dwarf" (DWARF's Call Frame +Information) mode can be used to unwind the stack. + +The following command can be used to view resulting report in call-graph +format:: + + perf record --call-graph dwarf paxtest kiddie + perf report --stdio + +Tracing workloads +================= + +Now that we understand the workloads, let's start tracing them. + +Tracing perf bench all workload +------------------------------- + +Run the following command to trace perf bench all workload:: + + strace -c perf bench all + +**System Calls made by the workload** + +The below table shows the system calls invoked by the workload, number of +times each system call is invoked, and the corresponding Linux subsystem. + ++-------------------+-----------+-----------------+-------------------------+ +| System Call | # calls | Linux Subsystem | System Call (API) | ++===================+===========+=================+=========================+ +| getppid | 10000001 | Process Mgmt | sys_getpid() | ++-------------------+-----------+-----------------+-------------------------+ +| clone | 1077 | Process Mgmt. | sys_clone() | ++-------------------+-----------+-----------------+-------------------------+ +| prctl | 23 | Process Mgmt. | sys_prctl() | ++-------------------+-----------+-----------------+-------------------------+ +| prlimit64 | 7 | Process Mgmt. | sys_prlimit64() | ++-------------------+-----------+-----------------+-------------------------+ +| getpid | 10 | Process Mgmt. | sys_getpid() | ++-------------------+-----------+-----------------+-------------------------+ +| uname | 3 | Process Mgmt. | sys_uname() | ++-------------------+-----------+-----------------+-------------------------+ +| sysinfo | 1 | Process Mgmt. | sys_sysinfo() | ++-------------------+-----------+-----------------+-------------------------+ +| getuid | 1 | Process Mgmt. | sys_getuid() | ++-------------------+-----------+-----------------+-------------------------+ +| getgid | 1 | Process Mgmt. | sys_getgid() | ++-------------------+-----------+-----------------+-------------------------+ +| geteuid | 1 | Process Mgmt. | sys_geteuid() | ++-------------------+-----------+-----------------+-------------------------+ +| getegid | 1 | Process Mgmt. | sys_getegid | ++-------------------+-----------+-----------------+-------------------------+ +| close | 49951 | Filesystem | sys_close() | ++-------------------+-----------+-----------------+-------------------------+ +| pipe | 604 | Filesystem | sys_pipe() | ++-------------------+-----------+-----------------+-------------------------+ +| openat | 48560 | Filesystem | sys_opennat() | ++-------------------+-----------+-----------------+-------------------------+ +| fstat | 8338 | Filesystem | sys_fstat() | ++-------------------+-----------+-----------------+-------------------------+ +| stat | 1573 | Filesystem | sys_stat() | ++-------------------+-----------+-----------------+-------------------------+ +| pread64 | 9646 | Filesystem | sys_pread64() | ++-------------------+-----------+-----------------+-------------------------+ +| getdents64 | 1873 | Filesystem | sys_getdents64() | ++-------------------+-----------+-----------------+-------------------------+ +| access | 3 | Filesystem | sys_access() | ++-------------------+-----------+-----------------+-------------------------+ +| lstat | 1880 | Filesystem | sys_lstat() | ++-------------------+-----------+-----------------+-------------------------+ +| lseek | 6 | Filesystem | sys_lseek() | ++-------------------+-----------+-----------------+-------------------------+ +| ioctl | 3 | Filesystem | sys_ioctl() | ++-------------------+-----------+-----------------+-------------------------+ +| dup2 | 1 | Filesystem | sys_dup2() | ++-------------------+-----------+-----------------+-------------------------+ +| execve | 2 | Filesystem | sys_execve() | ++-------------------+-----------+-----------------+-------------------------+ +| fcntl | 8779 | Filesystem | sys_fcntl() | ++-------------------+-----------+-----------------+-------------------------+ +| statfs | 1 | Filesystem | sys_statfs() | ++-------------------+-----------+-----------------+-------------------------+ +| epoll_create | 2 | Filesystem | sys_epoll_create() | ++-------------------+-----------+-----------------+-------------------------+ +| epoll_ctl | 64 | Filesystem | sys_epoll_ctl() | ++-------------------+-----------+-----------------+-------------------------+ +| newfstatat | 8318 | Filesystem | sys_newfstatat() | ++-------------------+-----------+-----------------+-------------------------+ +| eventfd2 | 192 | Filesystem | sys_eventfd2() | ++-------------------+-----------+-----------------+-------------------------+ +| mmap | 243 | Memory Mgmt. | sys_mmap() | ++-------------------+-----------+-----------------+-------------------------+ +| mprotect | 32 | Memory Mgmt. | sys_mprotect() | ++-------------------+-----------+-----------------+-------------------------+ +| brk | 21 | Memory Mgmt. | sys_brk() | ++-------------------+-----------+-----------------+-------------------------+ +| munmap | 128 | Memory Mgmt. | sys_munmap() | ++-------------------+-----------+-----------------+-------------------------+ +| set_mempolicy | 156 | Memory Mgmt. | sys_set_mempolicy() | ++-------------------+-----------+-----------------+-------------------------+ +| set_tid_address | 1 | Process Mgmt. | sys_set_tid_address() | ++-------------------+-----------+-----------------+-------------------------+ +| set_robust_list | 1 | Futex | sys_set_robust_list() | ++-------------------+-----------+-----------------+-------------------------+ +| futex | 341 | Futex | sys_futex() | ++-------------------+-----------+-----------------+-------------------------+ +| sched_getaffinity | 79 | Scheduler | sys_sched_getaffinity() | ++-------------------+-----------+-----------------+-------------------------+ +| sched_setaffinity | 223 | Scheduler | sys_sched_setaffinity() | ++-------------------+-----------+-----------------+-------------------------+ +| socketpair | 202 | Network | sys_socketpair() | ++-------------------+-----------+-----------------+-------------------------+ +| rt_sigprocmask | 21 | Signal | sys_rt_sigprocmask() | ++-------------------+-----------+-----------------+-------------------------+ +| rt_sigaction | 36 | Signal | sys_rt_sigaction() | ++-------------------+-----------+-----------------+-------------------------+ +| rt_sigreturn | 2 | Signal | sys_rt_sigreturn() | ++-------------------+-----------+-----------------+-------------------------+ +| wait4 | 889 | Time | sys_wait4() | ++-------------------+-----------+-----------------+-------------------------+ +| clock_nanosleep | 37 | Time | sys_clock_nanosleep() | ++-------------------+-----------+-----------------+-------------------------+ +| capget | 4 | Capability | sys_capget() | ++-------------------+-----------+-----------------+-------------------------+ + +Tracing stress-ng netdev stressor workload +------------------------------------------ + +Run the following command to trace stress-ng netdev stressor workload:: + + strace -c stress-ng --netdev 1 -t 60 --metrics + +**System Calls made by the workload** + +The below table shows the system calls invoked by the workload, number of +times each system call is invoked, and the corresponding Linux subsystem. + ++-------------------+-----------+-----------------+-------------------------+ +| System Call | # calls | Linux Subsystem | System Call (API) | ++===================+===========+=================+=========================+ +| openat | 74 | Filesystem | sys_openat() | ++-------------------+-----------+-----------------+-------------------------+ +| close | 75 | Filesystem | sys_close() | ++-------------------+-----------+-----------------+-------------------------+ +| read | 58 | Filesystem | sys_read() | ++-------------------+-----------+-----------------+-------------------------+ +| fstat | 20 | Filesystem | sys_fstat() | ++-------------------+-----------+-----------------+-------------------------+ +| flock | 10 | Filesystem | sys_flock() | ++-------------------+-----------+-----------------+-------------------------+ +| write | 7 | Filesystem | sys_write() | ++-------------------+-----------+-----------------+-------------------------+ +| getdents64 | 8 | Filesystem | sys_getdents64() | ++-------------------+-----------+-----------------+-------------------------+ +| pread64 | 8 | Filesystem | sys_pread64() | ++-------------------+-----------+-----------------+-------------------------+ +| lseek | 1 | Filesystem | sys_lseek() | ++-------------------+-----------+-----------------+-------------------------+ +| access | 2 | Filesystem | sys_access() | ++-------------------+-----------+-----------------+-------------------------+ +| getcwd | 1 | Filesystem | sys_getcwd() | ++-------------------+-----------+-----------------+-------------------------+ +| execve | 1 | Filesystem | sys_execve() | ++-------------------+-----------+-----------------+-------------------------+ +| mmap | 61 | Memory Mgmt. | sys_mmap() | ++-------------------+-----------+-----------------+-------------------------+ +| munmap | 3 | Memory Mgmt. | sys_munmap() | ++-------------------+-----------+-----------------+-------------------------+ +| mprotect | 20 | Memory Mgmt. | sys_mprotect() | ++-------------------+-----------+-----------------+-------------------------+ +| mlock | 2 | Memory Mgmt. | sys_mlock() | ++-------------------+-----------+-----------------+-------------------------+ +| brk | 3 | Memory Mgmt. | sys_brk() | ++-------------------+-----------+-----------------+-------------------------+ +| rt_sigaction | 21 | Signal | sys_rt_sigaction() | ++-------------------+-----------+-----------------+-------------------------+ +| rt_sigprocmask | 1 | Signal | sys_rt_sigprocmask() | ++-------------------+-----------+-----------------+-------------------------+ +| sigaltstack | 1 | Signal | sys_sigaltstack() | ++-------------------+-----------+-----------------+-------------------------+ +| rt_sigreturn | 1 | Signal | sys_rt_sigreturn() | ++-------------------+-----------+-----------------+-------------------------+ +| getpid | 8 | Process Mgmt. | sys_getpid() | ++-------------------+-----------+-----------------+-------------------------+ +| prlimit64 | 5 | Process Mgmt. | sys_prlimit64() | ++-------------------+-----------+-----------------+-------------------------+ +| arch_prctl | 2 | Process Mgmt. | sys_arch_prctl() | ++-------------------+-----------+-----------------+-------------------------+ +| sysinfo | 2 | Process Mgmt. | sys_sysinfo() | ++-------------------+-----------+-----------------+-------------------------+ +| getuid | 2 | Process Mgmt. | sys_getuid() | ++-------------------+-----------+-----------------+-------------------------+ +| uname | 1 | Process Mgmt. | sys_uname() | ++-------------------+-----------+-----------------+-------------------------+ +| setpgid | 1 | Process Mgmt. | sys_setpgid() | ++-------------------+-----------+-----------------+-------------------------+ +| getrusage | 1 | Process Mgmt. | sys_getrusage() | ++-------------------+-----------+-----------------+-------------------------+ +| geteuid | 1 | Process Mgmt. | sys_geteuid() | ++-------------------+-----------+-----------------+-------------------------+ +| getppid | 1 | Process Mgmt. | sys_getppid() | ++-------------------+-----------+-----------------+-------------------------+ +| sendto | 3 | Network | sys_sendto() | ++-------------------+-----------+-----------------+-------------------------+ +| connect | 1 | Network | sys_connect() | ++-------------------+-----------+-----------------+-------------------------+ +| socket | 1 | Network | sys_socket() | ++-------------------+-----------+-----------------+-------------------------+ +| clone | 1 | Process Mgmt. | sys_clone() | ++-------------------+-----------+-----------------+-------------------------+ +| set_tid_address | 1 | Process Mgmt. | sys_set_tid_address() | ++-------------------+-----------+-----------------+-------------------------+ +| wait4 | 2 | Time | sys_wait4() | ++-------------------+-----------+-----------------+-------------------------+ +| alarm | 1 | Time | sys_alarm() | ++-------------------+-----------+-----------------+-------------------------+ +| set_robust_list | 1 | Futex | sys_set_robust_list() | ++-------------------+-----------+-----------------+-------------------------+ + +Tracing paxtest kiddie workload +------------------------------- + +Run the following command to trace paxtest kiddie workload:: + + strace -c paxtest kiddie + +**System Calls made by the workload** + +The below table shows the system calls invoked by the workload, number of +times each system call is invoked, and the corresponding Linux subsystem. + ++-------------------+-----------+-----------------+----------------------+ +| System Call | # calls | Linux Subsystem | System Call (API) | ++===================+===========+=================+======================+ +| read | 3 | Filesystem | sys_read() | ++-------------------+-----------+-----------------+----------------------+ +| write | 11 | Filesystem | sys_write() | ++-------------------+-----------+-----------------+----------------------+ +| close | 41 | Filesystem | sys_close() | ++-------------------+-----------+-----------------+----------------------+ +| stat | 24 | Filesystem | sys_stat() | ++-------------------+-----------+-----------------+----------------------+ +| fstat | 2 | Filesystem | sys_fstat() | ++-------------------+-----------+-----------------+----------------------+ +| pread64 | 6 | Filesystem | sys_pread64() | ++-------------------+-----------+-----------------+----------------------+ +| access | 1 | Filesystem | sys_access() | ++-------------------+-----------+-----------------+----------------------+ +| pipe | 1 | Filesystem | sys_pipe() | ++-------------------+-----------+-----------------+----------------------+ +| dup2 | 24 | Filesystem | sys_dup2() | ++-------------------+-----------+-----------------+----------------------+ +| execve | 1 | Filesystem | sys_execve() | ++-------------------+-----------+-----------------+----------------------+ +| fcntl | 26 | Filesystem | sys_fcntl() | ++-------------------+-----------+-----------------+----------------------+ +| openat | 14 | Filesystem | sys_openat() | ++-------------------+-----------+-----------------+----------------------+ +| rt_sigaction | 7 | Signal | sys_rt_sigaction() | ++-------------------+-----------+-----------------+----------------------+ +| rt_sigreturn | 38 | Signal | sys_rt_sigreturn() | ++-------------------+-----------+-----------------+----------------------+ +| clone | 38 | Process Mgmt. | sys_clone() | ++-------------------+-----------+-----------------+----------------------+ +| wait4 | 44 | Time | sys_wait4() | ++-------------------+-----------+-----------------+----------------------+ +| mmap | 7 | Memory Mgmt. | sys_mmap() | ++-------------------+-----------+-----------------+----------------------+ +| mprotect | 3 | Memory Mgmt. | sys_mprotect() | ++-------------------+-----------+-----------------+----------------------+ +| munmap | 1 | Memory Mgmt. | sys_munmap() | ++-------------------+-----------+-----------------+----------------------+ +| brk | 3 | Memory Mgmt. | sys_brk() | ++-------------------+-----------+-----------------+----------------------+ +| getpid | 1 | Process Mgmt. | sys_getpid() | ++-------------------+-----------+-----------------+----------------------+ +| getuid | 1 | Process Mgmt. | sys_getuid() | ++-------------------+-----------+-----------------+----------------------+ +| getgid | 1 | Process Mgmt. | sys_getgid() | ++-------------------+-----------+-----------------+----------------------+ +| geteuid | 2 | Process Mgmt. | sys_geteuid() | ++-------------------+-----------+-----------------+----------------------+ +| getegid | 1 | Process Mgmt. | sys_getegid() | ++-------------------+-----------+-----------------+----------------------+ +| getppid | 1 | Process Mgmt. | sys_getppid() | ++-------------------+-----------+-----------------+----------------------+ +| arch_prctl | 2 | Process Mgmt. | sys_arch_prctl() | ++-------------------+-----------+-----------------+----------------------+ + +Conclusion +========== + +This document is intended to be used as a guide on how to gather fine-grained +information on the resources in use by workloads using strace. + +References +========== + + * `Discovery Linux Kernel Subsystems used by OpenAPS <https://elisa.tech/blog/2022/02/02/discovery-linux-kernel-subsystems-used-by-openaps>`_ + * `ELISA-White-Papers-Discovering Linux kernel subsystems used by a workload <https://github.com/elisa-tech/ELISA-White-Papers/blob/master/Processes/Discovering_Linux_kernel_subsystems_used_by_a_workload.md>`_ + * `strace <https://man7.org/linux/man-pages/man1/strace.1.html>`_ + * `perf <https://man7.org/linux/man-pages/man1/perf.1.html>`_ + * `paxtest README <https://github.com/opntr/paxtest-freebsd/blob/hardenedbsd/0.9.14-hbsd/README>`_ + * `stress-ng <https://www.mankier.com/1/stress-ng>`_ + * `Monitoring and managing system status and performance <https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/monitoring_and_managing_system_status_and_performance/index>`_ diff --git a/Documentation/conf.py b/Documentation/conf.py index 8b4e5451a02d..db16814f182f 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -156,7 +156,7 @@ else: math_renderer = 'mathjax' # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ['sphinx/templates'] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: @@ -331,6 +331,7 @@ if html_theme == 'alabaster': 'description': get_cline_version(), 'page_width': '65em', 'sidebar_width': '15em', + 'fixed_sidebar': 'true', 'font_size': 'inherit', 'font_family': 'serif', } @@ -348,7 +349,7 @@ html_use_smartypants = False # Custom sidebar templates, maps document names to template names. # Note that the RTD theme ignores this -html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']} +html_sidebars = { '**': ['searchbox.html', 'kernel-toc.html', 'sourcelink.html']} # about.html is available for alabaster theme. Add it at the front. if html_theme == 'alabaster': diff --git a/Documentation/core-api/padata.rst b/Documentation/core-api/padata.rst index 35175710b43c..05b73c6c105f 100644 --- a/Documentation/core-api/padata.rst +++ b/Documentation/core-api/padata.rst @@ -42,7 +42,7 @@ padata_shells associated with it, each allowing a separate series of jobs. Modifying cpumasks ------------------ -The CPUs used to run jobs can be changed in two ways, programatically with +The CPUs used to run jobs can be changed in two ways, programmatically with padata_set_cpumask() or via sysfs. The former is defined:: int padata_set_cpumask(struct padata_instance *pinst, int cpumask_type, diff --git a/Documentation/core-api/workqueue.rst b/Documentation/core-api/workqueue.rst index 3b22ed137662..8ec4d6270b24 100644 --- a/Documentation/core-api/workqueue.rst +++ b/Documentation/core-api/workqueue.rst @@ -370,8 +370,8 @@ of possible problems: The first one can be tracked using tracing: :: - $ echo workqueue:workqueue_queue_work > /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace_pipe > out.txt + $ echo workqueue:workqueue_queue_work > /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace_pipe > out.txt (wait a few secs) ^C diff --git a/Documentation/cpu-freq/index.rst b/Documentation/cpu-freq/index.rst index 2fe32dad562a..de25740651f7 100644 --- a/Documentation/cpu-freq/index.rst +++ b/Documentation/cpu-freq/index.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -============================================================================== -Linux CPUFreq - CPU frequency and voltage scaling code in the Linux(TM) kernel -============================================================================== +======================================================================== +CPUFreq - CPU frequency and voltage scaling code in the Linux(TM) kernel +======================================================================== Author: Dominik Brodowski <linux@brodo.de> diff --git a/Documentation/crypto/index.rst b/Documentation/crypto/index.rst index 21338fa92642..da5d5ad2bdf3 100644 --- a/Documentation/crypto/index.rst +++ b/Documentation/crypto/index.rst @@ -1,6 +1,6 @@ -======================= -Linux Kernel Crypto API -======================= +========== +Crypto API +========== :Author: Stephan Mueller :Author: Marek Vasut diff --git a/Documentation/dev-tools/coccinelle.rst b/Documentation/dev-tools/coccinelle.rst index d9976069ed12..535ce126fb4f 100644 --- a/Documentation/dev-tools/coccinelle.rst +++ b/Documentation/dev-tools/coccinelle.rst @@ -219,7 +219,7 @@ instance:: cat cocci.err You can use SPFLAGS to add debugging flags; for instance you may want to -add both --profile --show-trying to SPFLAGS when debugging. For example +add both ``--profile --show-trying`` to SPFLAGS when debugging. For example you may want to use:: rm -f err.log @@ -248,7 +248,7 @@ variables for .cocciconfig is as follows: - Your current user's home directory is processed first - Your directory from which spatch is called is processed next -- The directory provided with the --dir option is processed last, if used +- The directory provided with the ``--dir`` option is processed last, if used Since coccicheck runs through make, it naturally runs from the kernel proper dir; as such the second rule above would be implied for picking up a @@ -265,8 +265,8 @@ The kernel coccicheck script has:: fi KBUILD_EXTMOD is set when an explicit target with M= is used. For both cases -the spatch --dir argument is used, as such third rule applies when whether M= -is used or not, and when M= is used the target directory can have its own +the spatch ``--dir`` argument is used, as such third rule applies when whether +M= is used or not, and when M= is used the target directory can have its own .cocciconfig file. When M= is not passed as an argument to coccicheck the target directory is the same as the directory from where spatch was called. diff --git a/Documentation/dev-tools/gdb-kernel-debugging.rst b/Documentation/dev-tools/gdb-kernel-debugging.rst index 8e0f1fe8d17a..895285c037c7 100644 --- a/Documentation/dev-tools/gdb-kernel-debugging.rst +++ b/Documentation/dev-tools/gdb-kernel-debugging.rst @@ -39,6 +39,10 @@ Setup this mode. In this case, you should build the kernel with CONFIG_RANDOMIZE_BASE disabled if the architecture supports KASLR. +- Build the gdb scripts (required on kernels v5.1 and above):: + + make scripts_gdb + - Enable the gdb stub of QEMU/KVM, either - at VM startup time by appending "-s" to the QEMU command line diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst index 622b8156d212..2e8dfd1a66b6 100644 --- a/Documentation/driver-api/dma-buf.rst +++ b/Documentation/driver-api/dma-buf.rst @@ -1,5 +1,5 @@ -Buffer Sharing and Synchronization -================================== +Buffer Sharing and Synchronization (dma-buf) +============================================ The dma-buf subsystem provides the framework for sharing buffers for hardware (DMA) access across multiple device drivers and subsystems, and @@ -264,7 +264,7 @@ through memory management dependencies which userspace is unaware of, which randomly hangs workloads until the timeout kicks in. Workloads, which from userspace's perspective, do not contain a deadlock. In such a mixed fencing architecture there is no single entity with knowledge of all dependencies. -Thefore preventing such deadlocks from within the kernel is not possible. +Therefore preventing such deadlocks from within the kernel is not possible. The only solution to avoid dependencies loops is by not allowing indefinite fences in the kernel. This means: diff --git a/Documentation/driver-api/dmaengine/client.rst b/Documentation/driver-api/dmaengine/client.rst index bfd057b21a00..ecf139f73da4 100644 --- a/Documentation/driver-api/dmaengine/client.rst +++ b/Documentation/driver-api/dmaengine/client.rst @@ -175,7 +175,7 @@ The details of these operations are: driver can ask for the pointer, maximum size and the currently used size of the metadata and can directly update or read it. - Becasue the DMA driver manages the memory area containing the metadata, + Because the DMA driver manages the memory area containing the metadata, clients must make sure that they do not try to access or get the pointer after their transfer completion callback has run for the descriptor. If no completion callback has been defined for the transfer, then the diff --git a/Documentation/driver-api/dmaengine/dmatest.rst b/Documentation/driver-api/dmaengine/dmatest.rst index cf9859cd0b43..e2a63cefd783 100644 --- a/Documentation/driver-api/dmaengine/dmatest.rst +++ b/Documentation/driver-api/dmaengine/dmatest.rst @@ -89,7 +89,7 @@ The following command returns the state of the test. :: % cat /sys/module/dmatest/parameters/run -To wait for test completion userpace can poll 'run' until it is false, or use +To wait for test completion userspace can poll 'run' until it is false, or use the wait parameter. Specifying 'wait=1' when loading the module causes module initialization to pause until a test run has completed, while reading /sys/module/dmatest/parameters/wait waits for any running test to complete diff --git a/Documentation/driver-api/hsi.rst b/Documentation/driver-api/hsi.rst index f9cec02b72a1..01b6bebfbd1a 100644 --- a/Documentation/driver-api/hsi.rst +++ b/Documentation/driver-api/hsi.rst @@ -4,7 +4,7 @@ High Speed Synchronous Serial Interface (HSI) Introduction --------------- -High Speed Syncronous Interface (HSI) is a fullduplex, low latency protocol, +High Speed Synchronous Interface (HSI) is a full duplex, low latency protocol, that is optimized for die-level interconnect between an Application Processor and a Baseband chipset. It has been specified by the MIPI alliance in 2003 and implemented by multiple vendors since then. @@ -52,7 +52,7 @@ hsi-char Device ------------------ Each port automatically registers a generic client driver called hsi_char, -which provides a charecter device for userspace representing the HSI port. +which provides a character device for userspace representing the HSI port. It can be used to communicate via HSI from userspace. Userspace may configure the hsi_char device using the following ioctl commands: diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index d3a58f77328e..7a2584ab63c4 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -1,6 +1,8 @@ -======================================== -The Linux driver implementer's API guide -======================================== +.. SPDX-License-Identifier: GPL-2.0 + +============================== +Driver implementer's API guide +============================== The kernel offers a wide variety of interfaces to support the development of device drivers. This document is an only somewhat organized collection diff --git a/Documentation/driver-api/io-mapping.rst b/Documentation/driver-api/io-mapping.rst index a0cfb15988df..7274204b0435 100644 --- a/Documentation/driver-api/io-mapping.rst +++ b/Documentation/driver-api/io-mapping.rst @@ -44,7 +44,7 @@ This _wc variant returns a write-combining map to the page and may only be used with mappings created by io_mapping_create_wc() Temporary mappings are only valid in the context of the caller. The mapping -is not guaranteed to be globaly visible. +is not guaranteed to be globally visible. io_mapping_map_local_wc() has a side effect on X86 32bit as it disables migration to make the mapping code work. No caller can rely on this side @@ -78,7 +78,7 @@ variant, although this may be significantly slower:: unsigned long offset) This works like io_mapping_map_atomic/local_wc() except it has no side -effects and the pointer is globaly visible. +effects and the pointer is globally visible. The mappings are released with:: diff --git a/Documentation/driver-api/md/md-cluster.rst b/Documentation/driver-api/md/md-cluster.rst index 96eb52cec7eb..e93f35e0e157 100644 --- a/Documentation/driver-api/md/md-cluster.rst +++ b/Documentation/driver-api/md/md-cluster.rst @@ -65,7 +65,7 @@ There are three groups of locks for managing the device: 2.3 new-device management ------------------------- - A single lock: "no-new-dev" is used to co-ordinate the addition of + A single lock: "no-new-dev" is used to coordinate the addition of new devices - this must be synchronized across the array. Normally all nodes hold a concurrent-read lock on this device. diff --git a/Documentation/driver-api/md/raid5-cache.rst b/Documentation/driver-api/md/raid5-cache.rst index d7a15f44a7c3..5f947cbc2e78 100644 --- a/Documentation/driver-api/md/raid5-cache.rst +++ b/Documentation/driver-api/md/raid5-cache.rst @@ -81,7 +81,7 @@ The write-through and write-back cache use the same disk format. The cache disk is organized as a simple write log. The log consists of 'meta data' and 'data' pairs. The meta data describes the data. It also includes checksum and sequence ID for recovery identification. Data can be IO data and parity data. Data is -checksumed too. The checksum is stored in the meta data ahead of the data. The +checksummed too. The checksum is stored in the meta data ahead of the data. The checksum is an optimization because MD can write meta and data freely without worry about the order. MD superblock has a field pointed to the valid meta data of log head. diff --git a/Documentation/driver-api/media/drivers/vidtv.rst b/Documentation/driver-api/media/drivers/vidtv.rst index 673bdff919ea..54f269f478d3 100644 --- a/Documentation/driver-api/media/drivers/vidtv.rst +++ b/Documentation/driver-api/media/drivers/vidtv.rst @@ -28,7 +28,7 @@ Currently, it consists of: takes parameters at initialization that will dictate how the simulation behaves. -- Code reponsible for encoding a valid MPEG Transport Stream, which is then +- Code responsible for encoding a valid MPEG Transport Stream, which is then passed to the bridge driver. This fake stream contains some hardcoded content. For now, we have a single, audio-only channel containing a single MPEG Elementary Stream, which in turn contains a SMPTE 302m encoded sine-wave. diff --git a/Documentation/driver-api/media/dtv-demux.rst b/Documentation/driver-api/media/dtv-demux.rst index c0ae5dec5328..144124142622 100644 --- a/Documentation/driver-api/media/dtv-demux.rst +++ b/Documentation/driver-api/media/dtv-demux.rst @@ -24,7 +24,7 @@ unless this is fixed in the HW platform. The demux kABI only controls front-ends regarding to their connections with demuxes; the kABI used to set the other front-end parameters, such as -tuning, are devined via the Digital TV Frontend kABI. +tuning, are defined via the Digital TV Frontend kABI. The functions that implement the abstract interface demux should be defined static or module private and registered to the Demux core for external diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst index 6f8d79926aa5..8797037c4e2e 100644 --- a/Documentation/driver-api/media/v4l2-subdev.rst +++ b/Documentation/driver-api/media/v4l2-subdev.rst @@ -321,7 +321,7 @@ response to video node operations. This hides the complexity of the underlying hardware from applications. For complex devices, finer-grained control of the device than what the video nodes offer may be required. In those cases, bridge drivers that implement :ref:`the media controller API <media_controller>` may -opt for making the subdevice operations directly accessible from userpace. +opt for making the subdevice operations directly accessible from userspace. Device nodes named ``v4l-subdev``\ *X* can be created in ``/dev`` to access sub-devices directly. If a sub-device supports direct userspace configuration @@ -574,7 +574,7 @@ issues with subdevice drivers that let the V4L2 core manage the active state, as they expect to receive the appropriate state as a parameter. To help the conversion of subdevice drivers to a managed active state without having to convert all callers at the same time, an additional wrapper layer has been -added to v4l2_subdev_call(), which handles the NULL case by geting and locking +added to v4l2_subdev_call(), which handles the NULL case by getting and locking the callee's active state with :c:func:`v4l2_subdev_lock_and_get_active_state()`, and unlocking the state after the call. diff --git a/Documentation/driver-api/mei/nfc.rst b/Documentation/driver-api/mei/nfc.rst index b5b6fc96f85e..8fe8664c28cc 100644 --- a/Documentation/driver-api/mei/nfc.rst +++ b/Documentation/driver-api/mei/nfc.rst @@ -3,7 +3,7 @@ MEI NFC ------- -Some Intel 8 and 9 Serieses chipsets supports NFC devices connected behind +Some Intel 8 and 9 Series chipsets support NFC devices connected behind the Intel Management Engine controller. MEI client bus exposes the NFC chips as NFC phy devices and enables binding with Microread and NXP PN544 NFC device driver from the Linux NFC diff --git a/Documentation/driver-api/nfc/nfc-hci.rst b/Documentation/driver-api/nfc/nfc-hci.rst index f10fe53aa9fe..486aa647c456 100644 --- a/Documentation/driver-api/nfc/nfc-hci.rst +++ b/Documentation/driver-api/nfc/nfc-hci.rst @@ -150,7 +150,7 @@ LLC Communication between the CPU and the chip often requires some link layer protocol. Those are isolated as modules managed by the HCI layer. There are -currently two modules : nop (raw transfert) and shdlc. +currently two modules : nop (raw transfer) and shdlc. A new llc must implement the following functions:: struct nfc_llc_ops { diff --git a/Documentation/driver-api/nvdimm/nvdimm.rst b/Documentation/driver-api/nvdimm/nvdimm.rst index be8587a558e1..ca16b5acbf30 100644 --- a/Documentation/driver-api/nvdimm/nvdimm.rst +++ b/Documentation/driver-api/nvdimm/nvdimm.rst @@ -82,7 +82,7 @@ LABEL: Metadata stored on a DIMM device that partitions and identifies (persistently names) capacity allocated to different PMEM namespaces. It also indicates whether an address abstraction like a BTT is applied to - the namepsace. Note that traditional partition tables, GPT/MBR, are + the namespace. Note that traditional partition tables, GPT/MBR, are layered on top of a PMEM namespace, or an address abstraction like BTT if present, but partition support is deprecated going forward. diff --git a/Documentation/driver-api/nvdimm/security.rst b/Documentation/driver-api/nvdimm/security.rst index 7aab71524116..eb3d35e6a95c 100644 --- a/Documentation/driver-api/nvdimm/security.rst +++ b/Documentation/driver-api/nvdimm/security.rst @@ -83,7 +83,7 @@ passed in. 6. Freeze --------- The freeze operation does not require any keys. The security config can be -frozen by a user with root privelege. +frozen by a user with root privilege. 7. Disable ---------- diff --git a/Documentation/driver-api/pin-control.rst b/Documentation/driver-api/pin-control.rst index bf5a78783861..4639912dc9cc 100644 --- a/Documentation/driver-api/pin-control.rst +++ b/Documentation/driver-api/pin-control.rst @@ -836,7 +836,7 @@ hardware and shall be put into different subsystems: Depending on the exact HW register design, some functions exposed by the GPIO subsystem may call into the pinctrl subsystem in order to -co-ordinate register settings across HW modules. In particular, this may +coordinate register settings across HW modules. In particular, this may be needed for HW with separate GPIO and pin controller HW modules, where e.g. GPIO direction is determined by a register in the pin controller HW module rather than the GPIO HW module. diff --git a/Documentation/driver-api/pldmfw/index.rst b/Documentation/driver-api/pldmfw/index.rst index ad2c33ece30f..fd871b83f34f 100644 --- a/Documentation/driver-api/pldmfw/index.rst +++ b/Documentation/driver-api/pldmfw/index.rst @@ -20,7 +20,7 @@ Overview of the ``pldmfw`` library The ``pldmfw`` library is intended to be used by device drivers for implementing device flash update based on firmware files following the PLDM -firwmare file format. +firmware file format. It is implemented using an ops table that allows device drivers to provide the underlying device specific functionality. diff --git a/Documentation/driver-api/serial/driver.rst b/Documentation/driver-api/serial/driver.rst index 98d268555dcc..84b43061c11b 100644 --- a/Documentation/driver-api/serial/driver.rst +++ b/Documentation/driver-api/serial/driver.rst @@ -24,7 +24,7 @@ console support. Console Support --------------- -The serial core provides a few helper functions. This includes identifing +The serial core provides a few helper functions. This includes identifying the correct port structure (via uart_get_console()) and decoding command line arguments (uart_parse_options()). diff --git a/Documentation/driver-api/surface_aggregator/ssh.rst b/Documentation/driver-api/surface_aggregator/ssh.rst index 18fd0f0aee84..b955b673838b 100644 --- a/Documentation/driver-api/surface_aggregator/ssh.rst +++ b/Documentation/driver-api/surface_aggregator/ssh.rst @@ -77,7 +77,7 @@ after the frame structure and before the payload. The payload is followed by its own CRC (over all payload bytes). If the payload is not present (i.e. the frame has ``LEN=0``), the CRC of the payload is still present and will evaluate to ``0xffff``. The |LEN| field does not include any of the CRCs, it -equals the number of bytes inbetween the CRC of the frame and the CRC of the +equals the number of bytes between the CRC of the frame and the CRC of the payload. Additionally, the following fixed two-byte sequences are used: diff --git a/Documentation/driver-api/usb/dwc3.rst b/Documentation/driver-api/usb/dwc3.rst index 8b36ff11cef9..e3d6a620997f 100644 --- a/Documentation/driver-api/usb/dwc3.rst +++ b/Documentation/driver-api/usb/dwc3.rst @@ -18,7 +18,7 @@ controller which can be configured in one of 4 ways: 4. Hub configuration Linux currently supports several versions of this controller. In all -likelyhood, the version in your SoC is already supported. At the time +likelihood, the version in your SoC is already supported. At the time of this writing, known tested versions range from 2.02a to 3.10a. As a rule of thumb, anything above 2.02a should work reliably well. diff --git a/Documentation/driver-api/usb/usb3-debug-port.rst b/Documentation/driver-api/usb/usb3-debug-port.rst index b9fd131f4723..d4610457b052 100644 --- a/Documentation/driver-api/usb/usb3-debug-port.rst +++ b/Documentation/driver-api/usb/usb3-debug-port.rst @@ -48,7 +48,7 @@ kernel boot parameter:: "earlyprintk=xdbc" If there are multiple xHCI controllers in your system, you can -append a host contoller index to this kernel parameter. This +append a host controller index to this kernel parameter. This index starts from 0. Current design doesn't support DbC runtime suspend/resume. As diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index e224b6d5b642..9d5fd9424e8b 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -1284,6 +1284,7 @@ support this. Table 1-9 lists the files and their meaning. rt_cache Routing cache snmp SNMP data sockstat Socket statistics + softnet_stat Per-CPU incoming packets queues statistics of online CPUs tcp TCP sockets udp UDP sockets unix UNIX domain sockets diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst index b99dede9a5b1..eee5996acf2c 100644 --- a/Documentation/gpu/index.rst +++ b/Documentation/gpu/index.rst @@ -1,6 +1,6 @@ -================================== -Linux GPU Driver Developer's Guide -================================== +============================ +GPU Driver Developer's Guide +============================ .. toctree:: diff --git a/Documentation/hid/intel-ish-hid.rst b/Documentation/hid/intel-ish-hid.rst index 91b5c52b3708..42dc77b7b10f 100644 --- a/Documentation/hid/intel-ish-hid.rst +++ b/Documentation/hid/intel-ish-hid.rst @@ -344,8 +344,8 @@ Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space. To debug ISH, event tracing mechanism is used. To enable debug logs:: - echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable - cat /sys/kernel/debug/tracing/trace + echo 1 > /sys/kernel/tracing/events/intel_ish/enable + cat /sys/kernel/tracing/trace 3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260 ----------------------------------------------------- diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst index 96ce91b7d9a8..f1fe75f596a5 100644 --- a/Documentation/hwmon/index.rst +++ b/Documentation/hwmon/index.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -========================= -Linux Hardware Monitoring -========================= +=================== +Hardware Monitoring +=================== .. toctree:: :maxdepth: 1 diff --git a/Documentation/input/index.rst b/Documentation/input/index.rst index 9888f5cbf6d5..35581cd18e91 100644 --- a/Documentation/input/index.rst +++ b/Documentation/input/index.rst @@ -1,6 +1,6 @@ -============================= -The Linux Input Documentation -============================= +=================== +Input Documentation +=================== Contents: diff --git a/Documentation/leds/index.rst b/Documentation/leds/index.rst index e5d63b940045..b9ca081fac71 100644 --- a/Documentation/leds/index.rst +++ b/Documentation/leds/index.rst @@ -26,3 +26,4 @@ LEDs leds-lp55xx leds-mlxcpld leds-sc27xx + leds-qcom-lpg diff --git a/Documentation/mm/active_mm.rst b/Documentation/mm/active_mm.rst index 6f8269c284ed..45d89f8fb3a8 100644 --- a/Documentation/mm/active_mm.rst +++ b/Documentation/mm/active_mm.rst @@ -1,5 +1,3 @@ -.. _active_mm: - ========= Active MM ========= diff --git a/Documentation/mm/arch_pgtable_helpers.rst b/Documentation/mm/arch_pgtable_helpers.rst index fd2a19df884e..30d9a09f01f4 100644 --- a/Documentation/mm/arch_pgtable_helpers.rst +++ b/Documentation/mm/arch_pgtable_helpers.rst @@ -1,7 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 -.. _arch_page_table_helpers: - =============================== Architecture Page Table Helpers =============================== diff --git a/Documentation/mm/balance.rst b/Documentation/mm/balance.rst index 6a1fadf3e173..6cd0127154ac 100644 --- a/Documentation/mm/balance.rst +++ b/Documentation/mm/balance.rst @@ -1,5 +1,3 @@ -.. _balance: - ================ Memory Balancing ================ diff --git a/Documentation/mm/free_page_reporting.rst b/Documentation/mm/free_page_reporting.rst index 8c05e62d8b2b..1468f71c261f 100644 --- a/Documentation/mm/free_page_reporting.rst +++ b/Documentation/mm/free_page_reporting.rst @@ -1,5 +1,3 @@ -.. _free_page_reporting: - ===================== Free Page Reporting ===================== diff --git a/Documentation/mm/frontswap.rst b/Documentation/mm/frontswap.rst index feecc5e24477..c892412988af 100644 --- a/Documentation/mm/frontswap.rst +++ b/Documentation/mm/frontswap.rst @@ -1,5 +1,3 @@ -.. _frontswap: - ========= Frontswap ========= diff --git a/Documentation/mm/highmem.rst b/Documentation/mm/highmem.rst index 0f731d9196b0..bb3f90e195fa 100644 --- a/Documentation/mm/highmem.rst +++ b/Documentation/mm/highmem.rst @@ -1,5 +1,3 @@ -.. _highmem: - ==================== High Memory Handling ==================== diff --git a/Documentation/mm/hmm.rst b/Documentation/mm/hmm.rst index f2a59ed82ed3..9aa512c3a12c 100644 --- a/Documentation/mm/hmm.rst +++ b/Documentation/mm/hmm.rst @@ -1,5 +1,3 @@ -.. _hmm: - ===================================== Heterogeneous Memory Management (HMM) ===================================== @@ -304,7 +302,7 @@ devm_memunmap_pages(), and devm_release_mem_region() when the resources can be tied to a ``struct device``. The overall migration steps are similar to migrating NUMA pages within system -memory (see :ref:`Page migration <page_migration>`) but the steps are split +memory (see Documentation/mm/page_migration.rst) but the steps are split between device driver specific code and shared common code: 1. ``mmap_read_lock()`` diff --git a/Documentation/mm/hugetlbfs_reserv.rst b/Documentation/mm/hugetlbfs_reserv.rst index f143954e0d05..05a44760da32 100644 --- a/Documentation/mm/hugetlbfs_reserv.rst +++ b/Documentation/mm/hugetlbfs_reserv.rst @@ -1,5 +1,3 @@ -.. _hugetlbfs_reserve: - ===================== Hugetlbfs Reservation ===================== @@ -7,7 +5,7 @@ Hugetlbfs Reservation Overview ======== -Huge pages as described at :ref:`hugetlbpage` are typically +Huge pages as described at Documentation/mm/hugetlbpage.rst are typically preallocated for application use. These huge pages are instantiated in a task's address space at page fault time if the VMA indicates huge pages are to be used. If no huge page exists at page fault time, the task is sent diff --git a/Documentation/mm/hwpoison.rst b/Documentation/mm/hwpoison.rst index b9d5253c1305..ba48a441feed 100644 --- a/Documentation/mm/hwpoison.rst +++ b/Documentation/mm/hwpoison.rst @@ -1,5 +1,3 @@ -.. hwpoison: - ======== hwpoison ======== diff --git a/Documentation/mm/index.rst b/Documentation/mm/index.rst index 4aa12b8be278..5a94a921ea40 100644 --- a/Documentation/mm/index.rst +++ b/Documentation/mm/index.rst @@ -1,6 +1,6 @@ -===================================== -Linux Memory Management Documentation -===================================== +=============================== +Memory Management Documentation +=============================== Memory Management Guide ======================= diff --git a/Documentation/mm/ksm.rst b/Documentation/mm/ksm.rst index f83cfbc12f4c..2806e3e4a10e 100644 --- a/Documentation/mm/ksm.rst +++ b/Documentation/mm/ksm.rst @@ -1,5 +1,3 @@ -.. _ksm: - ======================= Kernel Samepage Merging ======================= @@ -8,7 +6,7 @@ KSM is a memory-saving de-duplication feature, enabled by CONFIG_KSM=y, added to the Linux kernel in 2.6.32. See ``mm/ksm.c`` for its implementation, and http://lwn.net/Articles/306704/ and https://lwn.net/Articles/330589/ -The userspace interface of KSM is described in :ref:`Documentation/admin-guide/mm/ksm.rst <admin_guide_ksm>` +The userspace interface of KSM is described in Documentation/admin-guide/mm/ksm.rst Design ====== diff --git a/Documentation/mm/memory-model.rst b/Documentation/mm/memory-model.rst index 3779e562dc76..5f3eafbbc520 100644 --- a/Documentation/mm/memory-model.rst +++ b/Documentation/mm/memory-model.rst @@ -1,7 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 -.. _physical_memory_model: - ===================== Physical Memory Model ===================== diff --git a/Documentation/mm/mmu_notifier.rst b/Documentation/mm/mmu_notifier.rst index df5d7777fc6b..c687bea4922f 100644 --- a/Documentation/mm/mmu_notifier.rst +++ b/Documentation/mm/mmu_notifier.rst @@ -1,5 +1,3 @@ -.. _mmu_notifier: - When do you need to notify inside page table lock ? =================================================== diff --git a/Documentation/mm/numa.rst b/Documentation/mm/numa.rst index 99fdeca917ca..0f1b56809dca 100644 --- a/Documentation/mm/numa.rst +++ b/Documentation/mm/numa.rst @@ -1,5 +1,3 @@ -.. _numa: - Started Nov 1999 by Kanoj Sarcar <kanoj@sgi.com> ============= @@ -64,7 +62,7 @@ In addition, for some architectures, again x86 is an example, Linux supports the emulation of additional nodes. For NUMA emulation, linux will carve up the existing nodes--or the system memory for non-NUMA platforms--into multiple nodes. Each emulated node will manage a fraction of the underlying cells' -physical memory. NUMA emluation is useful for testing NUMA kernel and +physical memory. NUMA emulation is useful for testing NUMA kernel and application features on non-NUMA platforms, and as a sort of memory resource management mechanism when used together with cpusets. [see Documentation/admin-guide/cgroup-v1/cpusets.rst] @@ -110,7 +108,7 @@ to improve NUMA locality using various CPU affinity command line interfaces, such as taskset(1) and numactl(1), and program interfaces such as sched_setaffinity(2). Further, one can modify the kernel's default local allocation behavior using Linux NUMA memory policy. [see -:ref:`Documentation/admin-guide/mm/numa_memory_policy.rst <numa_memory_policy>`]. +Documentation/admin-guide/mm/numa_memory_policy.rst]. System administrators can restrict the CPUs and nodes' memories that a non- privileged user can specify in the scheduling or NUMA commands and functions diff --git a/Documentation/mm/page_frags.rst b/Documentation/mm/page_frags.rst index 7d6f9385d129..a81617e688a8 100644 --- a/Documentation/mm/page_frags.rst +++ b/Documentation/mm/page_frags.rst @@ -1,5 +1,3 @@ -.. _page_frags: - ============== Page fragments ============== diff --git a/Documentation/mm/page_migration.rst b/Documentation/mm/page_migration.rst index 11493bad7112..313dce18893e 100644 --- a/Documentation/mm/page_migration.rst +++ b/Documentation/mm/page_migration.rst @@ -1,5 +1,3 @@ -.. _page_migration: - ============== Page migration ============== @@ -9,8 +7,8 @@ nodes in a NUMA system while the process is running. This means that the virtual addresses that the process sees do not change. However, the system rearranges the physical location of those pages. -Also see :ref:`Heterogeneous Memory Management (HMM) <hmm>` -for migrating pages to or from device private memory. +Also see Documentation/mm/hmm.rst for migrating pages to or from device +private memory. The main intent of page migration is to reduce the latency of memory accesses by moving pages near to the processor where the process accessing that memory diff --git a/Documentation/mm/page_owner.rst b/Documentation/mm/page_owner.rst index 127514955a5e..e8d5090a9e6b 100644 --- a/Documentation/mm/page_owner.rst +++ b/Documentation/mm/page_owner.rst @@ -1,5 +1,3 @@ -.. _page_owner: - ================================================== page owner: Tracking about who allocated each page ================================================== @@ -52,7 +50,7 @@ pages are investigated and marked as allocated in initialization phase. Although it doesn't mean that they have the right owner information, at least, we can tell whether the page is allocated or not, more accurately. On 2GB memory x86-64 VM box, 13343 early allocated pages -are catched and marked, although they are mostly allocated from struct +are caught and marked, although they are mostly allocated from struct page extension feature. Anyway, after that, no page is left in un-tracking state. @@ -178,7 +176,7 @@ STANDARD FORMAT SPECIFIERS at alloc_ts timestamp of the page when it was allocated ator allocator memory allocator for pages - For --curl option: + For --cull option: KEY LONG DESCRIPTION p pid process ID diff --git a/Documentation/mm/page_table_check.rst b/Documentation/mm/page_table_check.rst index 1a09472f10a3..cfd8f4117cf3 100644 --- a/Documentation/mm/page_table_check.rst +++ b/Documentation/mm/page_table_check.rst @@ -1,7 +1,5 @@ .. SPDX-License-Identifier: GPL-2.0 -.. _page_table_check: - ================ Page Table Check ================ diff --git a/Documentation/mm/physical_memory.rst b/Documentation/mm/physical_memory.rst index 2ab7b8c1c863..f9d7ea4b9dca 100644 --- a/Documentation/mm/physical_memory.rst +++ b/Documentation/mm/physical_memory.rst @@ -3,3 +3,350 @@ =============== Physical Memory =============== + +Linux is available for a wide range of architectures so there is a need for an +architecture-independent abstraction to represent the physical memory. This +chapter describes the structures used to manage physical memory in a running +system. + +The first principal concept prevalent in the memory management is +`Non-Uniform Memory Access (NUMA) +<https://en.wikipedia.org/wiki/Non-uniform_memory_access>`_. +With multi-core and multi-socket machines, memory may be arranged into banks +that incur a different cost to access depending on the “distance” from the +processor. For example, there might be a bank of memory assigned to each CPU or +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 +for a particular node can be referenced by ``NODE_DATA(nid)`` macro where +``nid`` is the ID of that node. + +For NUMA architectures, the node structures are allocated by the architecture +specific code early during boot. Usually, these structures are allocated +locally on the memory bank they represent. For UMA architectures, only one +static ``pg_data_t`` structure called ``contig_page_data`` is used. Nodes will +be discussed further in Section :ref:`Nodes <nodes>` + +The entire physical address space is partitioned into one or more blocks +called zones which represent ranges within memory. These ranges are usually +determined by architectural constraints for accessing the physical memory. +The memory range within a node that corresponds to a particular zone is +described by a ``struct zone``, typedeffed to ``zone_t``. Each zone has +one of the types described below. + +* ``ZONE_DMA`` and ``ZONE_DMA32`` historically represented memory suitable for + DMA by peripheral devices that cannot access all of the addressable + memory. For many years there are better more and robust interfaces to get + memory with DMA specific requirements (Documentation/core-api/dma-api.rst), + but ``ZONE_DMA`` and ``ZONE_DMA32`` still represent memory ranges that have + restrictions on how they can be accessed. + Depending on the architecture, either of these zone types or even they both + can be disabled at build time using ``CONFIG_ZONE_DMA`` and + ``CONFIG_ZONE_DMA32`` configuration options. Some 64-bit platforms may need + both zones as they support peripherals with different DMA addressing + limitations. + +* ``ZONE_NORMAL`` is for normal memory that can be accessed by the kernel all + the time. DMA operations can be performed on pages in this zone if the DMA + devices support transfers to all addressable memory. ``ZONE_NORMAL`` is + always enabled. + +* ``ZONE_HIGHMEM`` is the part of the physical memory that is not covered by a + permanent mapping in the kernel page tables. The memory in this zone is only + accessible to the kernel using temporary mappings. This zone is available + only on some 32-bit architectures and is enabled with ``CONFIG_HIGHMEM``. + +* ``ZONE_MOVABLE`` is for normal accessible memory, just like ``ZONE_NORMAL``. + The difference is that the contents of most pages in ``ZONE_MOVABLE`` is + movable. That means that while virtual addresses of these pages do not + change, their content may move between different physical pages. Often + ``ZONE_MOVABLE`` is populated during memory hotplug, but it may be + also populated on boot using one of ``kernelcore``, ``movablecore`` and + ``movable_node`` kernel command line parameters. See + Documentation/mm/page_migration.rst and + Documentation/admin-guide/mm/memory_hotplug.rst for additional details. + +* ``ZONE_DEVICE`` represents memory residing on devices such as PMEM and GPU. + It has different characteristics than RAM zone types and it exists to provide + :ref:`struct page <Pages>` and memory map services for device driver + identified physical address ranges. ``ZONE_DEVICE`` is enabled with + configuration option ``CONFIG_ZONE_DEVICE``. + +It is important to note that many kernel operations can only take place using +``ZONE_NORMAL`` so it is the most performance critical zone. Zones are +discussed further in Section :ref:`Zones <zones>`. + +The relation between node and zone extents is determined by the physical memory +map reported by the firmware, architectural constraints for memory addressing +and certain parameters in the kernel command line. + +For example, with 32-bit kernel on an x86 UMA machine with 2 Gbytes of RAM the +entire memory will be on node 0 and there will be three zones: ``ZONE_DMA``, +``ZONE_NORMAL`` and ``ZONE_HIGHMEM``:: + + 0 2G + +-------------------------------------------------------------+ + | node 0 | + +-------------------------------------------------------------+ + + 0 16M 896M 2G + +----------+-----------------------+--------------------------+ + | ZONE_DMA | ZONE_NORMAL | ZONE_HIGHMEM | + +----------+-----------------------+--------------------------+ + + +With a kernel built with ``ZONE_DMA`` disabled and ``ZONE_DMA32`` enabled and +booted with ``movablecore=80%`` parameter on an arm64 machine with 16 Gbytes of +RAM equally split between two nodes, there will be ``ZONE_DMA32``, +``ZONE_NORMAL`` and ``ZONE_MOVABLE`` on node 0, and ``ZONE_NORMAL`` and +``ZONE_MOVABLE`` on node 1:: + + + 1G 9G 17G + +--------------------------------+ +--------------------------+ + | node 0 | | node 1 | + +--------------------------------+ +--------------------------+ + + 1G 4G 4200M 9G 9320M 17G + +---------+----------+-----------+ +------------+-------------+ + | DMA32 | NORMAL | MOVABLE | | NORMAL | MOVABLE | + +---------+----------+-----------+ +------------+-------------+ + +.. _nodes: + +Nodes +===== + +As we have mentioned, each node in memory is described by a ``pg_data_t`` which +is a typedef for a ``struct pglist_data``. When allocating a page, by default +Linux uses a node-local allocation policy to allocate memory from the node +closest to the running CPU. As processes tend to run on the same CPU, it is +likely the memory from the current node will be used. The allocation policy can +be controlled by users as described in +Documentation/admin-guide/mm/numa_memory_policy.rst. + +Most NUMA architectures maintain an array of pointers to the node +structures. The actual structures are allocated early during boot when +architecture specific code parses the physical memory map reported by the +firmware. The bulk of the node initialization happens slightly later in the +boot process by free_area_init() function, described later in Section +:ref:`Initialization <initialization>`. + + +Along with the node structures, kernel maintains an array of ``nodemask_t`` +bitmasks called ``node_states``. Each bitmask in this array represents a set of +nodes with particular properties as defined by ``enum node_states``: + +``N_POSSIBLE`` + The node could become online at some point. +``N_ONLINE`` + The node is online. +``N_NORMAL_MEMORY`` + The node has regular memory. +``N_HIGH_MEMORY`` + The node has regular or high memory. When ``CONFIG_HIGHMEM`` is disabled + aliased to ``N_NORMAL_MEMORY``. +``N_MEMORY`` + The node has memory(regular, high, movable) +``N_CPU`` + The node has one or more CPUs + +For each node that has a property described above, the bit corresponding to the +node ID in the ``node_states[<property>]`` bitmask is set. + +For example, for node 2 with normal memory and CPUs, bit 2 will be set in :: + + node_states[N_POSSIBLE] + node_states[N_ONLINE] + node_states[N_NORMAL_MEMORY] + node_states[N_HIGH_MEMORY] + node_states[N_MEMORY] + node_states[N_CPU] + +For various operations possible with nodemasks please refer to +``include/linux/nodemask.h``. + +Among other things, nodemasks are used to provide macros for node traversal, +namely ``for_each_node()`` and ``for_each_online_node()``. + +For instance, to call a function foo() for each online node:: + + for_each_online_node(nid) { + pg_data_t *pgdat = NODE_DATA(nid); + + foo(pgdat); + } + +Node structure +-------------- + +The nodes structure ``struct pglist_data`` is declared in +``include/linux/mmzone.h``. Here we briefly describe fields of this +structure: + +General +~~~~~~~ + +``node_zones`` + The zones for this node. Not all of the zones may be populated, but it is + the full list. It is referenced by this node's node_zonelists as well as + other node's node_zonelists. + +``node_zonelists`` + The list of all zones in all nodes. This list defines the order of zones + that allocations are preferred from. The ``node_zonelists`` is set up by + ``build_zonelists()`` in ``mm/page_alloc.c`` during the initialization of + core memory management structures. + +``nr_zones`` + Number of populated zones in this node. + +``node_mem_map`` + For UMA systems that use FLATMEM memory model the 0's node + ``node_mem_map`` is array of struct pages representing each physical frame. + +``node_page_ext`` + For UMA systems that use FLATMEM memory model the 0's node + ``node_page_ext`` is array of extensions of struct pages. Available only + in the kernels built with ``CONFIG_PAGE_EXTENSION`` enabled. + +``node_start_pfn`` + The page frame number of the starting page frame in this node. + +``node_present_pages`` + Total number of physical pages present in this node. + +``node_spanned_pages`` + Total size of physical page range, including holes. + +``node_size_lock`` + A lock that protects the fields defining the node extents. Only defined when + at least one of ``CONFIG_MEMORY_HOTPLUG`` or + ``CONFIG_DEFERRED_STRUCT_PAGE_INIT`` configuration options are enabled. + ``pgdat_resize_lock()`` and ``pgdat_resize_unlock()`` are provided to + manipulate ``node_size_lock`` without checking for ``CONFIG_MEMORY_HOTPLUG`` + or ``CONFIG_DEFERRED_STRUCT_PAGE_INIT``. + +``node_id`` + The Node ID (NID) of the node, starts at 0. + +``totalreserve_pages`` + This is a per-node reserve of pages that are not available to userspace + allocations. + +``first_deferred_pfn`` + If memory initialization on large machines is deferred then this is the first + PFN that needs to be initialized. Defined only when + ``CONFIG_DEFERRED_STRUCT_PAGE_INIT`` is enabled + +``deferred_split_queue`` + Per-node queue of huge pages that their split was deferred. Defined only when ``CONFIG_TRANSPARENT_HUGEPAGE`` is enabled. + +``__lruvec`` + Per-node lruvec holding LRU lists and related parameters. Used only when + memory cgroups are disabled. It should not be accessed directly, use + ``mem_cgroup_lruvec()`` to look up lruvecs instead. + +Reclaim control +~~~~~~~~~~~~~~~ + +See also Documentation/mm/page_reclaim.rst. + +``kswapd`` + Per-node instance of kswapd kernel thread. + +``kswapd_wait``, ``pfmemalloc_wait``, ``reclaim_wait`` + Workqueues used to synchronize memory reclaim tasks + +``nr_writeback_throttled`` + Number of tasks that are throttled waiting on dirty pages to clean. + +``nr_reclaim_start`` + Number of pages written while reclaim is throttled waiting for writeback. + +``kswapd_order`` + Controls the order kswapd tries to reclaim + +``kswapd_highest_zoneidx`` + The highest zone index to be reclaimed by kswapd + +``kswapd_failures`` + Number of runs kswapd was unable to reclaim any pages + +``min_unmapped_pages`` + Minimal number of unmapped file backed pages that cannot be reclaimed. + Determined by ``vm.min_unmapped_ratio`` sysctl. Only defined when + ``CONFIG_NUMA`` is enabled. + +``min_slab_pages`` + Minimal number of SLAB pages that cannot be reclaimed. Determined by + ``vm.min_slab_ratio sysctl``. Only defined when ``CONFIG_NUMA`` is enabled + +``flags`` + Flags controlling reclaim behavior. + +Compaction control +~~~~~~~~~~~~~~~~~~ + +``kcompactd_max_order`` + Page order that kcompactd should try to achieve. + +``kcompactd_highest_zoneidx`` + The highest zone index to be compacted by kcompactd. + +``kcompactd_wait`` + Workqueue used to synchronize memory compaction tasks. + +``kcompactd`` + Per-node instance of kcompactd kernel thread. + +``proactive_compact_trigger`` + Determines if proactive compaction is enabled. Controlled by + ``vm.compaction_proactiveness`` sysctl. + +Statistics +~~~~~~~~~~ + +``per_cpu_nodestats`` + Per-CPU VM statistics for the node + +``vm_stat`` + VM statistics for the node. + +.. _zones: + +Zones +===== + +.. admonition:: Stub + + This section is incomplete. Please list and describe the appropriate fields. + +.. _pages: + +Pages +===== + +.. admonition:: Stub + + This section is incomplete. Please list and describe the appropriate fields. + +.. _folios: + +Folios +====== + +.. admonition:: Stub + + This section is incomplete. Please list and describe the appropriate fields. + +.. _initialization: + +Initialization +============== + +.. admonition:: Stub + + This section is incomplete. Please list and describe the appropriate fields. diff --git a/Documentation/mm/remap_file_pages.rst b/Documentation/mm/remap_file_pages.rst index 7bef6718e3a9..297091ce257c 100644 --- a/Documentation/mm/remap_file_pages.rst +++ b/Documentation/mm/remap_file_pages.rst @@ -1,5 +1,3 @@ -.. _remap_file_pages: - ============================== remap_file_pages() system call ============================== diff --git a/Documentation/mm/slub.rst b/Documentation/mm/slub.rst index 7f652216dabe..fa01cdfd7d3a 100644 --- a/Documentation/mm/slub.rst +++ b/Documentation/mm/slub.rst @@ -1,5 +1,3 @@ -.. _slub: - ========================== Short users guide for SLUB ========================== diff --git a/Documentation/mm/split_page_table_lock.rst b/Documentation/mm/split_page_table_lock.rst index c08919662704..50ee0dfc95be 100644 --- a/Documentation/mm/split_page_table_lock.rst +++ b/Documentation/mm/split_page_table_lock.rst @@ -1,5 +1,3 @@ -.. _split_page_table_lock: - ===================== Split page table lock ===================== diff --git a/Documentation/mm/transhuge.rst b/Documentation/mm/transhuge.rst index ec3dc5b04226..9d924b651c61 100644 --- a/Documentation/mm/transhuge.rst +++ b/Documentation/mm/transhuge.rst @@ -1,5 +1,3 @@ -.. _transhuge: - ============================ Transparent Hugepage Support ============================ diff --git a/Documentation/mm/unevictable-lru.rst b/Documentation/mm/unevictable-lru.rst index 4a0e158aa9ce..b5dc98cd1ba8 100644 --- a/Documentation/mm/unevictable-lru.rst +++ b/Documentation/mm/unevictable-lru.rst @@ -1,5 +1,3 @@ -.. _unevictable_lru: - ============================== Unevictable LRU Infrastructure ============================== diff --git a/Documentation/mm/z3fold.rst b/Documentation/mm/z3fold.rst index 224e3c61d686..25b5935d06c7 100644 --- a/Documentation/mm/z3fold.rst +++ b/Documentation/mm/z3fold.rst @@ -1,5 +1,3 @@ -.. _z3fold: - ====== z3fold ====== diff --git a/Documentation/mm/zsmalloc.rst b/Documentation/mm/zsmalloc.rst index 6e79893d6132..24616a7c115a 100644 --- a/Documentation/mm/zsmalloc.rst +++ b/Documentation/mm/zsmalloc.rst @@ -1,5 +1,3 @@ -.. _zsmalloc: - ======== zsmalloc ======== diff --git a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/tracepoints.rst b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/tracepoints.rst index a9d3e123adc4..da8e53cebb6c 100644 --- a/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/tracepoints.rst +++ b/Documentation/networking/device_drivers/ethernet/mellanox/mlx5/tracepoints.rst @@ -10,42 +10,42 @@ Tracepoints mlx5 driver provides internal tracepoints for tracking and debugging using kernel tracepoints interfaces (refer to Documentation/trace/ftrace.rst). -For the list of support mlx5 events, check `/sys/kernel/debug/tracing/events/mlx5/`. +For the list of support mlx5 events, check /sys/kernel/tracing/events/mlx5/. tc and eswitch offloads tracepoints: - mlx5e_configure_flower: trace flower filter actions and cookies offloaded to mlx5:: - $ echo mlx5:mlx5e_configure_flower >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace + $ echo mlx5:mlx5e_configure_flower >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace ... tc-6535 [019] ...1 2672.404466: mlx5e_configure_flower: cookie=0000000067874a55 actions= REDIRECT - mlx5e_delete_flower: trace flower filter actions and cookies deleted from mlx5:: - $ echo mlx5:mlx5e_delete_flower >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace + $ echo mlx5:mlx5e_delete_flower >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace ... tc-6569 [010] .N.1 2686.379075: mlx5e_delete_flower: cookie=0000000067874a55 actions= NULL - mlx5e_stats_flower: trace flower stats request:: - $ echo mlx5:mlx5e_stats_flower >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace + $ echo mlx5:mlx5e_stats_flower >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace ... tc-6546 [010] ...1 2679.704889: mlx5e_stats_flower: cookie=0000000060eb3d6a bytes=0 packets=0 lastused=4295560217 - mlx5e_tc_update_neigh_used_value: trace tunnel rule neigh update value offloaded to mlx5:: - $ echo mlx5:mlx5e_tc_update_neigh_used_value >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace + $ echo mlx5:mlx5e_tc_update_neigh_used_value >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace ... kworker/u48:4-8806 [009] ...1 55117.882428: mlx5e_tc_update_neigh_used_value: netdev: ens1f0 IPv4: 1.1.1.10 IPv6: ::ffff:1.1.1.10 neigh_used=1 - mlx5e_rep_neigh_update: trace neigh update tasks scheduled due to neigh state change events:: - $ echo mlx5:mlx5e_rep_neigh_update >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace + $ echo mlx5:mlx5e_rep_neigh_update >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace ... kworker/u48:7-2221 [009] ...1 1475.387435: mlx5e_rep_neigh_update: netdev: ens1f0 MAC: 24:8a:07:9a:17:9a IPv4: 1.1.1.10 IPv6: ::ffff:1.1.1.10 neigh_connected=1 @@ -54,14 +54,14 @@ Bridge offloads tracepoints: - mlx5_esw_bridge_fdb_entry_init: trace bridge FDB entry offloaded to mlx5:: $ echo mlx5:mlx5_esw_bridge_fdb_entry_init >> set_event - $ cat /sys/kernel/debug/tracing/trace + $ cat /sys/kernel/tracing/trace ... kworker/u20:9-2217 [003] ...1 318.582243: mlx5_esw_bridge_fdb_entry_init: net_device=enp8s0f0_0 addr=e4:fd:05:08:00:02 vid=0 flags=0 used=0 - mlx5_esw_bridge_fdb_entry_cleanup: trace bridge FDB entry deleted from mlx5:: $ echo mlx5:mlx5_esw_bridge_fdb_entry_cleanup >> set_event - $ cat /sys/kernel/debug/tracing/trace + $ cat /sys/kernel/tracing/trace ... ip-2581 [005] ...1 318.629871: mlx5_esw_bridge_fdb_entry_cleanup: net_device=enp8s0f0_1 addr=e4:fd:05:08:00:03 vid=0 flags=0 used=16 @@ -69,7 +69,7 @@ Bridge offloads tracepoints: mlx5:: $ echo mlx5:mlx5_esw_bridge_fdb_entry_refresh >> set_event - $ cat /sys/kernel/debug/tracing/trace + $ cat /sys/kernel/tracing/trace ... kworker/u20:8-3849 [003] ...1 466716: mlx5_esw_bridge_fdb_entry_refresh: net_device=enp8s0f0_0 addr=e4:fd:05:08:00:02 vid=3 flags=0 used=0 @@ -77,7 +77,7 @@ Bridge offloads tracepoints: representor:: $ echo mlx5:mlx5_esw_bridge_vlan_create >> set_event - $ cat /sys/kernel/debug/tracing/trace + $ cat /sys/kernel/tracing/trace ... ip-2560 [007] ...1 318.460258: mlx5_esw_bridge_vlan_create: vid=1 flags=6 @@ -85,7 +85,7 @@ Bridge offloads tracepoints: representor:: $ echo mlx5:mlx5_esw_bridge_vlan_cleanup >> set_event - $ cat /sys/kernel/debug/tracing/trace + $ cat /sys/kernel/tracing/trace ... bridge-2582 [007] ...1 318.653496: mlx5_esw_bridge_vlan_cleanup: vid=2 flags=8 @@ -93,7 +93,7 @@ Bridge offloads tracepoints: device:: $ echo mlx5:mlx5_esw_bridge_vport_init >> set_event - $ cat /sys/kernel/debug/tracing/trace + $ cat /sys/kernel/tracing/trace ... ip-2560 [007] ...1 318.458915: mlx5_esw_bridge_vport_init: vport_num=1 @@ -101,7 +101,7 @@ Bridge offloads tracepoints: device:: $ echo mlx5:mlx5_esw_bridge_vport_cleanup >> set_event - $ cat /sys/kernel/debug/tracing/trace + $ cat /sys/kernel/tracing/trace ... ip-5387 [000] ...1 573713: mlx5_esw_bridge_vport_cleanup: vport_num=1 @@ -109,43 +109,43 @@ Eswitch QoS tracepoints: - mlx5_esw_vport_qos_create: trace creation of transmit scheduler arbiter for vport:: - $ echo mlx5:mlx5_esw_vport_qos_create >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace + $ echo mlx5:mlx5_esw_vport_qos_create >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace ... <...>-23496 [018] .... 73136.838831: mlx5_esw_vport_qos_create: (0000:82:00.0) vport=2 tsar_ix=4 bw_share=0, max_rate=0 group=000000007b576bb3 - mlx5_esw_vport_qos_config: trace configuration of transmit scheduler arbiter for vport:: - $ echo mlx5:mlx5_esw_vport_qos_config >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace + $ echo mlx5:mlx5_esw_vport_qos_config >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace ... <...>-26548 [023] .... 75754.223823: mlx5_esw_vport_qos_config: (0000:82:00.0) vport=1 tsar_ix=3 bw_share=34, max_rate=10000 group=000000007b576bb3 - mlx5_esw_vport_qos_destroy: trace deletion of transmit scheduler arbiter for vport:: - $ echo mlx5:mlx5_esw_vport_qos_destroy >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace + $ echo mlx5:mlx5_esw_vport_qos_destroy >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace ... <...>-27418 [004] .... 76546.680901: mlx5_esw_vport_qos_destroy: (0000:82:00.0) vport=1 tsar_ix=3 - mlx5_esw_group_qos_create: trace creation of transmit scheduler arbiter for rate group:: - $ echo mlx5:mlx5_esw_group_qos_create >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace + $ echo mlx5:mlx5_esw_group_qos_create >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace ... <...>-26578 [008] .... 75776.022112: mlx5_esw_group_qos_create: (0000:82:00.0) group=000000008dac63ea tsar_ix=5 - mlx5_esw_group_qos_config: trace configuration of transmit scheduler arbiter for rate group:: - $ echo mlx5:mlx5_esw_group_qos_config >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace + $ echo mlx5:mlx5_esw_group_qos_config >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace ... <...>-27303 [020] .... 76461.455356: mlx5_esw_group_qos_config: (0000:82:00.0) group=000000008dac63ea tsar_ix=5 bw_share=100 max_rate=20000 - mlx5_esw_group_qos_destroy: trace deletion of transmit scheduler arbiter for group:: - $ echo mlx5:mlx5_esw_group_qos_destroy >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace + $ echo mlx5:mlx5_esw_group_qos_destroy >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace ... <...>-27418 [006] .... 76547.187258: mlx5_esw_group_qos_destroy: (0000:82:00.0) group=000000007b576bb3 tsar_ix=1 @@ -153,77 +153,77 @@ SF tracepoints: - mlx5_sf_add: trace addition of the SF port:: - $ echo mlx5:mlx5_sf_add >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace + $ echo mlx5:mlx5_sf_add >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace ... devlink-9363 [031] ..... 24610.188722: mlx5_sf_add: (0000:06:00.0) port_index=32768 controller=0 hw_id=0x8000 sfnum=88 - mlx5_sf_free: trace freeing of the SF port:: - $ echo mlx5:mlx5_sf_free >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace + $ echo mlx5:mlx5_sf_free >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace ... devlink-9830 [038] ..... 26300.404749: mlx5_sf_free: (0000:06:00.0) port_index=32768 controller=0 hw_id=0x8000 - mlx5_sf_activate: trace activation of the SF port:: - $ echo mlx5:mlx5_sf_activate >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace + $ echo mlx5:mlx5_sf_activate >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace ... devlink-29841 [008] ..... 3669.635095: mlx5_sf_activate: (0000:08:00.0) port_index=32768 controller=0 hw_id=0x8000 - mlx5_sf_deactivate: trace deactivation of the SF port:: - $ echo mlx5:mlx5_sf_deactivate >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace + $ echo mlx5:mlx5_sf_deactivate >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace ... devlink-29994 [008] ..... 4015.969467: mlx5_sf_deactivate: (0000:08:00.0) port_index=32768 controller=0 hw_id=0x8000 - mlx5_sf_hwc_alloc: trace allocating of the hardware SF context:: - $ echo mlx5:mlx5_sf_hwc_alloc >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace + $ echo mlx5:mlx5_sf_hwc_alloc >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace ... devlink-9775 [031] ..... 26296.385259: mlx5_sf_hwc_alloc: (0000:06:00.0) controller=0 hw_id=0x8000 sfnum=88 - mlx5_sf_hwc_free: trace freeing of the hardware SF context:: - $ echo mlx5:mlx5_sf_hwc_free >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace + $ echo mlx5:mlx5_sf_hwc_free >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace ... kworker/u128:3-9093 [046] ..... 24625.365771: mlx5_sf_hwc_free: (0000:06:00.0) hw_id=0x8000 - mlx5_sf_hwc_deferred_free: trace deferred freeing of the hardware SF context:: - $ echo mlx5:mlx5_sf_hwc_deferred_free >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace + $ echo mlx5:mlx5_sf_hwc_deferred_free >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace ... devlink-9519 [046] ..... 24624.400271: mlx5_sf_hwc_deferred_free: (0000:06:00.0) hw_id=0x8000 - mlx5_sf_update_state: trace state updates for SF contexts:: - $ echo mlx5:mlx5_sf_update_state >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace + $ echo mlx5:mlx5_sf_update_state >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace ... kworker/u20:3-29490 [009] ..... 4141.453530: mlx5_sf_update_state: (0000:08:00.0) port_index=32768 controller=0 hw_id=0x8000 state=2 - mlx5_sf_vhca_event: trace SF vhca event and state:: - $ echo mlx5:mlx5_sf_vhca_event >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace + $ echo mlx5:mlx5_sf_vhca_event >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace ... kworker/u128:3-9093 [046] ..... 24625.365525: mlx5_sf_vhca_event: (0000:06:00.0) hw_id=0x8000 sfnum=88 vhca_state=1 - mlx5_sf_dev_add: trace SF device add event:: - $ echo mlx5:mlx5_sf_dev_add>> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace + $ echo mlx5:mlx5_sf_dev_add>> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace ... kworker/u128:3-9093 [000] ..... 24616.524495: mlx5_sf_dev_add: (0000:06:00.0) sfdev=00000000fc5d96fd aux_id=4 hw_id=0x8000 sfnum=88 - mlx5_sf_dev_del: trace SF device delete event:: - $ echo mlx5:mlx5_sf_dev_del >> /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace + $ echo mlx5:mlx5_sf_dev_del >> /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace ... kworker/u128:3-9093 [044] ..... 24624.400749: mlx5_sf_dev_del: (0000:06:00.0) sfdev=00000000fc5d96fd aux_id=4 hw_id=0x8000 sfnum=88 diff --git a/Documentation/peci/index.rst b/Documentation/peci/index.rst index 989de10416e7..930e75217c33 100644 --- a/Documentation/peci/index.rst +++ b/Documentation/peci/index.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0-only -==================== -Linux PECI Subsystem -==================== +============== +PECI Subsystem +============== .. toctree:: diff --git a/Documentation/process/botching-up-ioctls.rst b/Documentation/process/botching-up-ioctls.rst index ba4667ab396b..9739b88463a5 100644 --- a/Documentation/process/botching-up-ioctls.rst +++ b/Documentation/process/botching-up-ioctls.rst @@ -41,7 +41,7 @@ will need to add a 32-bit compat layer: structures to the kernel, or if the kernel checks the structure size, which e.g. the drm core does. - * Pointers are __u64, cast from/to a uintprt_t on the userspace side and + * Pointers are __u64, cast from/to a uintptr_t on the userspace side and from/to a void __user * in the kernel. Try really hard not to delay this conversion or worse, fiddle the raw __u64 through your code since that diminishes the checking tools like sparse can provide. The macro diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst index c8fd53a11a20..f91b8441f2ef 100644 --- a/Documentation/process/deprecated.rst +++ b/Documentation/process/deprecated.rst @@ -346,3 +346,29 @@ struct_size() and flex_array_size() helpers:: instance->count = count; memcpy(instance->items, source, flex_array_size(instance, items, instance->count)); + +There are two special cases of replacement where the DECLARE_FLEX_ARRAY() +helper needs to be used. (Note that it is named __DECLARE_FLEX_ARRAY() for +use in UAPI headers.) Those cases are when the flexible array is either +alone in a struct or is part of a union. These are disallowed by the C99 +specification, but for no technical reason (as can be seen by both the +existing use of such arrays in those places and the work-around that +DECLARE_FLEX_ARRAY() uses). For example, to convert this:: + + struct something { + ... + union { + struct type1 one[0]; + struct type2 two[0]; + }; + }; + +The helper must be used:: + + struct something { + ... + union { + DECLARE_FLEX_ARRAY(struct type1, one); + DECLARE_FLEX_ARRAY(struct type2, two); + }; + }; diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst index fc2c46f3f82d..471e1f93fa09 100644 --- a/Documentation/process/email-clients.rst +++ b/Documentation/process/email-clients.rst @@ -350,3 +350,23 @@ although tab2space problem can be solved with external editor. Another problem is that Gmail will base64-encode any message that has a non-ASCII character. That includes things like European names. + +Proton Mail +*********** + +Proton Mail has a "feature" where it looks up keys using Web Key Directory +(WKD) and encrypts mail to any recipients for which it finds a key. +Kernel.org publishes the WKD for all developers who have kernel.org accounts. +As a result, emails sent using Proton Mail to kernel.org addresses will be +encrypted. +Unfortunately, Proton Mail does not provide a mechanism to disable the +automatic encryption, viewing it as a privacy feature. +The automatic encryption feature is also enabled for mail sent via the Proton +Mail Bridge, so this affects all outgoing messages, including patches sent with +``git send-email``. +Encrypted mail adds unnecessary friction, as other developers may not have mail +clients, or tooling, configured for use with encrypted mail and some mail +clients may encrypt responses to encrypted mail for all recipients, including +the mailing lists. +Unless a way to disable this "feature" is introduced, Proton Mail is unsuited +to kernel development. diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst index 40bfbd3b7648..f5277993b195 100644 --- a/Documentation/process/maintainer-pgp-guide.rst +++ b/Documentation/process/maintainer-pgp-guide.rst @@ -60,36 +60,18 @@ establish the integrity of the Linux kernel itself. PGP tools ========= -Use GnuPG v2 ------------- +Use GnuPG 2.2 or later +---------------------- Your distro should already have GnuPG installed by default, you just -need to verify that you are using version 2.x and not the legacy 1.4 -release -- many distributions still package both, with the default -``gpg`` command invoking GnuPG v.1. To check, run:: +need to verify that you are using a reasonably recent version of it. +To check, run:: $ gpg --version | head -n1 -If you see ``gpg (GnuPG) 1.4.x``, then you are using GnuPG v.1. Try the -``gpg2`` command (if you don't have it, you may need to install the -gnupg2 package):: - - $ gpg2 --version | head -n1 - -If you see ``gpg (GnuPG) 2.x.x``, then you are good to go. This guide -will assume you have the version 2.2 of GnuPG (or later). If you are -using version 2.0 of GnuPG, then some of the commands in this guide will -not work, and you should consider installing the latest 2.2 version of -GnuPG. Versions of gnupg-2.1.11 and later should be compatible for the -purposes of this guide as well. - -If you have both ``gpg`` and ``gpg2`` commands, you should make sure you -are always using GnuPG v2, not the legacy version. You can enforce this -by setting the appropriate alias:: - - $ alias gpg=gpg2 - -You can put that in your ``.bashrc`` to make sure it's always the case. +If you have version 2.2 or above, then you are good to go. If you have a +version that is prior than 2.2, then some commands from this guide may +not work. Configure gpg-agent options ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -150,9 +132,9 @@ PGP defines four capabilities that a key can have: The key with the **[C]** capability is often called the "master" key, but this terminology is misleading because it implies that the Certify key can be used in place of any of other subkey on the same chain (like -a physical "master key" can be used to open the locks made for other -keys). Since this is not the case, this guide will refer to it as "the -Certify key" to avoid any ambiguity. +a physical "master key" can be used to open locks made for other keys). +Since this is not the case, this guide will refer to it as "the Certify +key" to avoid any ambiguity. It is critical to fully understand the following: @@ -186,10 +168,10 @@ If you used the default parameters when generating your key, then that is what you will have. You can verify by running ``gpg --list-secret-keys``, for example:: - 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] + ssb cv25519 2022-12-20 [E] [expires: 2024-12-19] The long line under the ``sec`` entry is your key fingerprint -- whenever you see ``[fpr]`` in the examples below, that 40-character @@ -219,18 +201,9 @@ separate signing subkey:: .. note:: ECC support in GnuPG - GnuPG 2.1 and later has full support for Elliptic Curve - Cryptography, with ability to combine ECC subkeys with traditional - RSA keys. The main upside of ECC cryptography is that it is much - faster computationally and creates much smaller signatures when - compared byte for byte with 2048+ bit RSA keys. Unless you plan on - using a smartcard device that does not support ECC operations, we - recommend that you create an ECC signing subkey for your kernel - work. - - Note, that if you plan to use a hardware device that does not + Note, that if you intend to use a hardware token that does not support ED25519 ECC keys, you should choose "nistp256" instead or - "ed25519." + "ed25519." See the section below on recommended hardware devices. Back up your Certify key for disaster recovery @@ -336,13 +309,13 @@ First, identify the keygrip of your Certify key:: The output will be something like this:: - 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 Find the keygrip entry that is beneath the ``pub`` line (right under the @@ -365,14 +338,14 @@ Now, if you issue the ``--list-secret-keys`` command, it will show that the Certify key is missing (the ``#`` indicates it is not available):: $ 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] You should also remove any ``secring.gpg`` files in the ``~/.gnupg`` -directory, which are left over from earlier versions of GnuPG. +directory, which may be left over from previous versions of GnuPG. If you don't have the "private-keys-v1.d" directory ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -437,8 +410,7 @@ functionality. There are several options available: U2F, among others, and now finally supports NISTP and ED25519 ECC keys. -`LWN has a good review`_ of some of the above models, as well as several -others. Your choice will depend on cost, shipping availability in your +Your choice will depend on cost, shipping availability in your geographical region, and open/proprietary hardware considerations. .. note:: @@ -451,7 +423,6 @@ geographical region, and open/proprietary hardware considerations. .. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nkpr2-nitrokey-pro-2-3 .. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/ .. _Gnuk: https://www.fsij.org/doc-gnuk/ -.. _`LWN has a good review`: https://lwn.net/Articles/736231/ .. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html Configure your smartcard device @@ -509,11 +480,11 @@ passphrase and the admin PIN of the card for most operations:: 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> @@ -577,11 +548,11 @@ If you perform ``--list-secret-keys`` now, you will see a subtle difference in the 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] The ``>`` in the ``ssb>`` output indicates that the subkey is only available on the smartcard. If you go back into your secret keys @@ -644,7 +615,7 @@ run:: You can also use a specific date if that is easier to remember (e.g. your birthday, January 1st, or Canada Day):: - $ gpg --quick-set-expire [fpr] 2020-07-01 + $ gpg --quick-set-expire [fpr] 2025-07-01 Remember to send the updated key back to keyservers:: @@ -707,12 +678,6 @@ should be used (``[fpr]`` is the fingerprint of your key):: $ git config --global user.signingKey [fpr] -**IMPORTANT**: If you have a distinct ``gpg2`` command, then you should -tell git to always use it instead of the legacy ``gpg`` from version 1:: - - $ git config --global gpg.program gpg2 - $ git config --global gpgv.program gpgv2 - How to work with signed tags ---------------------------- @@ -751,13 +716,6 @@ If you are verifying someone else's git tag, then you will need to import their PGP key. Please refer to the ":ref:`verify_identities`" section below. -.. note:: - - If you get "``gpg: Can't check signature: unknown pubkey - algorithm``" error, you need to tell git to use gpgv2 for - verification, so it properly processes signatures made by ECC keys. - See instructions at the start of this section. - Configure git to always sign annotated tags ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/scheduler/index.rst b/Documentation/scheduler/index.rst index f12d0d06de3a..3170747226f6 100644 --- a/Documentation/scheduler/index.rst +++ b/Documentation/scheduler/index.rst @@ -1,6 +1,6 @@ -=============== -Linux Scheduler -=============== +========= +Scheduler +========= .. toctree:: :maxdepth: 1 diff --git a/Documentation/scsi/index.rst b/Documentation/scsi/index.rst index 7c5f5f8f614e..919f3edfe1bf 100644 --- a/Documentation/scsi/index.rst +++ b/Documentation/scsi/index.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -==================== -Linux SCSI Subsystem -==================== +============== +SCSI Subsystem +============== .. toctree:: :maxdepth: 1 diff --git a/Documentation/sound/hd-audio/notes.rst b/Documentation/sound/hd-audio/notes.rst index 3432feb0fa33..a9e35b1f87bd 100644 --- a/Documentation/sound/hd-audio/notes.rst +++ b/Documentation/sound/hd-audio/notes.rst @@ -651,14 +651,14 @@ via power-saving behavior. Enabling all tracepoints can be done like :: - # echo 1 > /sys/kernel/debug/tracing/events/hda/enable + # echo 1 > /sys/kernel/tracing/events/hda/enable then after some commands, you can traces from -/sys/kernel/debug/tracing/trace file. For example, when you want to +/sys/kernel/tracing/trace file. For example, when you want to trace what codec command is sent, enable the tracepoint like: :: - # cat /sys/kernel/debug/tracing/trace + # cat /sys/kernel/tracing/trace # tracer: nop # # TASK-PID CPU# TIMESTAMP FUNCTION diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst index 4d7d42acf6df..7e67e12730d3 100644 --- a/Documentation/sound/index.rst +++ b/Documentation/sound/index.rst @@ -1,6 +1,8 @@ -=================================== -Linux Sound Subsystem Documentation -=================================== +.. SPDX-License-Identifier: GPL-2.0 + +============================= +Sound Subsystem Documentation +============================= .. toctree:: :maxdepth: 2 diff --git a/Documentation/sparc/adi.rst b/Documentation/sparc/adi.rst index 857ad30f9569..dbcd8b6e7bc3 100644 --- a/Documentation/sparc/adi.rst +++ b/Documentation/sparc/adi.rst @@ -38,7 +38,7 @@ virtual addresses that contain 0xa in bits 63-60. ADI is enabled on a set of pages using mprotect() with PROT_ADI flag. When ADI is enabled on a set of pages by a task for the first time, -kernel sets the PSTATE.mcde bit fot the task. Version tags for memory +kernel sets the PSTATE.mcde bit for the task. Version tags for memory addresses are set with an stxa instruction on the addresses using ASI_MCD_PRIMARY or ASI_MCD_ST_BLKINIT_PRIMARY. ADI block size is provided by the hypervisor to the kernel. Kernel returns the value of @@ -97,7 +97,7 @@ With ADI enabled, following new traps may occur: Disrupting memory corruption ---------------------------- - When a store accesses a memory localtion that has TTE.mcd=1, + When a store accesses a memory location that has TTE.mcd=1, the task is running with ADI enabled (PSTATE.mcde=1), and the ADI tag in the address used (bits 63:60) does not match the tag set on the corresponding cacheline, a memory corruption trap occurs. By diff --git a/Documentation/sparc/oradax/dax-hv-api.txt b/Documentation/sparc/oradax/dax-hv-api.txt index 73e8d506cf64..7ecd0bf4957b 100644 --- a/Documentation/sparc/oradax/dax-hv-api.txt +++ b/Documentation/sparc/oradax/dax-hv-api.txt @@ -22,7 +22,7 @@ Chapter 36. Coprocessor services functionality offered may vary by virtual machine implementation. The DAX is a virtual device to sun4v guests, with supported data operations indicated by the virtual device - compatibilty property. Functionality is accessed through the submission of Command Control Blocks + compatibility property. Functionality is accessed through the submission of Command Control Blocks (CCBs) via the ccb_submit API function. The operations are processed asynchronously, with the status of the submitted operations reported through a Completion Area linked to each CCB. Each CCB has a separate Completion Area and, unless execution order is specifically restricted through the use of serial- @@ -313,7 +313,7 @@ bits set, and terminate at a CCB that has the Conditional bit set, but not the P Secondary Input Description Format Code - 0 Element is stored as value minus 1 (0 evalutes to 1, 1 evalutes + 0 Element is stored as value minus 1 (0 evaluates to 1, 1 evaluates to 2, etc) 1 Element is stored as value @@ -659,7 +659,7 @@ Offset Size Field Description “Secondary Input Element Size” [13:10] Output Format (see Section 36.2.1.1.6, “Output Format”) [9:5] Operand size for first scan criteria value. In a scan value - operation, this is one of two potential extact match values. + operation, this is one of two potential exact match values. In a scan range operation, this is the size of the upper range @@ -673,7 +673,7 @@ Offset Size Field Description operand, minus 1. Values 0xF-0x1E are reserved. A value of 0x1F indicates this operand is not in use for this scan operation. [4:0] Operand size for second scan criteria value. In a scan value - operation, this is one of two potential extact match values. + operation, this is one of two potential exact match values. In a scan range operation, this is the size of the lower range boundary. The value of this field is the number of bytes in the operand, minus 1. Values 0xF-0x1E are reserved. A value of @@ -690,24 +690,24 @@ Offset Size Field Description 48 8 Output (same fields as Primary Input) 56 8 Symbol Table (if used by Primary Input). Same fields as Section 36.2.1.2, “Extract command” -64 4 Next 4 most significant bytes of first scan criteria operand occuring after the +64 4 Next 4 most significant bytes of first scan criteria operand occurring after the bytes specified at offset 40, if needed by the operand size. If first operand is less than 8 bytes, the valid bytes are left-aligned to the lowest address. -68 4 Next 4 most significant bytes of second scan criteria operand occuring after +68 4 Next 4 most significant bytes of second scan criteria operand occurring after the bytes specified at offset 44, if needed by the operand size. If second operand is less than 8 bytes, the valid bytes are left-aligned to the lowest address. -72 4 Next 4 most significant bytes of first scan criteria operand occuring after the +72 4 Next 4 most significant bytes of first scan criteria operand occurring after the bytes specified at offset 64, if needed by the operand size. If first operand is less than 12 bytes, the valid bytes are left-aligned to the lowest address. -76 4 Next 4 most significant bytes of second scan criteria operand occuring after +76 4 Next 4 most significant bytes of second scan criteria operand occurring after the bytes specified at offset 68, if needed by the operand size. If second operand is less than 12 bytes, the valid bytes are left-aligned to the lowest address. -80 4 Next 4 most significant bytes of first scan criteria operand occuring after the +80 4 Next 4 most significant bytes of first scan criteria operand occurring after the bytes specified at offset 72, if needed by the operand size. If first operand is less than 16 bytes, the valid bytes are left-aligned to the lowest address. -84 4 Next 4 most significant bytes of second scan criteria operand occuring after +84 4 Next 4 most significant bytes of second scan criteria operand occurring after the bytes specified at offset 76, if needed by the operand size. If second operand is less than 16 bytes, the valid bytes are left-aligned to the lowest address. @@ -721,10 +721,10 @@ Offset Size Field Description 36.2.1.4. Translate commands - The translate commands takes an input array of indicies, and a table of single bit values indexed by those - indicies, and outputs a bit vector or index array created by reading the tables bit value at each index in + The translate commands takes an input array of indices, and a table of single bit values indexed by those + indices, and outputs a bit vector or index array created by reading the tables bit value at each index in the input array. The output should therefore contain exactly one bit per index in the input data stream, - when outputing as a bit vector. When outputing as an index array, the number of elements depends on the + when outputting as a bit vector. When outputting as an index array, the number of elements depends on the values read in the bit table, but will always be less than, or equal to, the number of input elements. Only a restricted subset of the possible input format types are supported. No variable width or Huffman/OZIP encoded input streams are allowed. The primary input data element size must be 3 bytes or less. @@ -742,7 +742,7 @@ Offset Size Field Description code in the CCB header. There are two supported formats for the output stream: the bit vector and index array formats (codes 0x8, - 0xD, and 0xE). The index array format is an array of indicies of bits which would have been set if the + 0xD, and 0xE). The index array format is an array of indices of bits which would have been set if the output format was a bit array. The return value of the CCB completion area contains the number of bits set in the output bit vector, @@ -1254,7 +1254,7 @@ EUNAVAILABLE The requested CCB operation could not be performed at this time. submitted CCB, or may apply to a larger scope. The status should not be interpreted as permanent, and the guest should attempt to submit CCBs in the future which had previously been unable to be performed. The status - data provides additional information about scope of the retricted availability + data provides additional information about scope of the restricted availability as follows: Value Description 0 Processing for the exact CCB instance submitted was unavailable, @@ -1330,20 +1330,20 @@ EUNAVAILABLE The requested CCB operation could not be performed at this time. of other CCBs ahead of the requested CCB, to provide a relative estimate of when the CCB may execute. The dax return value is only valid when the state is ENQUEUED. The value returned is the DAX unit - instance indentifier for the DAX unit processing the queue where the requested CCB is located. The value + instance identifier for the DAX unit processing the queue where the requested CCB is located. The value matches the value that would have been, or was, returned by ccb_submit using the queue info flag. The queue return value is only valid when the state is ENQUEUED. The value returned is the DAX - queue instance indentifier for the DAX unit processing the queue where the requested CCB is located. The + queue instance identifier for the DAX unit processing the queue where the requested CCB is located. The value matches the value that would have been, or was, returned by ccb_submit using the queue info flag. 36.3.2.1. Errors - EOK The request was proccessed and the CCB state is valid. + EOK The request was processed and the CCB state is valid. EBADALIGN address is not on a 64-byte aligned. ENORADDR The real address provided for address is not valid. EINVAL The CCB completion area contents are not valid. - EWOULDBLOCK Internal resource contraints prevented the CCB state from being queried at this + EWOULDBLOCK Internal resource constraints prevented the CCB state from being queried at this time. The guest should retry the request. ENOACCESS The guest does not have permission to access the coprocessor virtual device functionality. @@ -1401,11 +1401,11 @@ EUNAVAILABLE The requested CCB operation could not be performed at this time. 36.3.3.2. Errors - EOK The request was proccessed and the result is valid. + EOK The request was processed and the result is valid. EBADALIGN address is not on a 64-byte aligned. ENORADDR The real address provided for address is not valid. EINVAL The CCB completion area contents are not valid. - EWOULDBLOCK Internal resource contraints prevented the CCB from being killed at this time. + EWOULDBLOCK Internal resource constraints prevented the CCB from being killed at this time. The guest should retry the request. ENOACCESS The guest does not have permission to access the coprocessor virtual device functionality. @@ -1423,7 +1423,7 @@ EUNAVAILABLE The requested CCB operation could not be performed at this time. 36.3.4.1. Errors - EOK The request was proccessed and the number of enabled/disabled DAX units + EOK The request was processed and the number of enabled/disabled DAX units are valid. diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css index 45a624fdcf2c..084a884f6fb7 100644 --- a/Documentation/sphinx-static/custom.css +++ b/Documentation/sphinx-static/custom.css @@ -11,7 +11,9 @@ div.body h3 { font-size: 130%; } /* Tighten up the layout slightly */ div.body { padding: 0 15px 0 10px; } div.sphinxsidebarwrapper { padding: 1em 0.4em; } -div.sphinxsidebar { font-size: inherit; } +div.sphinxsidebar { font-size: inherit; + max-height: 100%; + overflow-y: auto; } /* Tweak document margins and don't force width */ div.document { margin: 20px 10px 0 10px; @@ -27,3 +29,47 @@ dl.function, dl.struct, dl.enum { margin-top: 2em; background-color: #ecf0f3; } dl.function dt { margin-left: 10em; text-indent: -10em; } dt.sig-object { font-size: larger; } div.kernelindent { margin-left: 2em; margin-right: 4em; } + +/* + * Tweaks for our local TOC + */ +div.kerneltoc li.toctree-l1 { font-size: smaller; + text-indent: -1em; + margin-left: 1em; } +div.kerneltoc li.current > a {font-weight: bold; } +div.kerneltoc li.toctree-l2,li.toctree-l3 { font-size: small; + text-indent: -1em; + margin-left: 1em; + list-style-type: none; + } +div.kerneltoc li.current ul { margin-left: 0; } +div.kerneltoc { background-color: #eeeeee; } +div.kerneltoc li.current ul { background-color: white; } + +/* + * The CSS magic to toggle the contents on small screens. + */ +label.kernel-toc-title { display: none; } +label.kernel-toc-title:after { + content: "[Hide]"; +} +input[type=checkbox]:checked ~ label.kernel-toc-title:after { + content: "[Show]"; +} +/* Hide the toggle on large screens */ +input.kernel-toc-toggle { display: none; } + +/* + * Show and implement the toggle on small screens. + * The 875px width seems to be wired into alabaster. + */ +@media screen and (max-width: 875px) { + label.kernel-toc-title { display: inline; + font-weight: bold; + font-size: larger; } + input[type=checkbox]:checked ~ div.kerneltoc { + display: none; + } + h3.kernel-toc-contents { display: inline; } + div.kerneltoc a { color: black; } +} diff --git a/Documentation/sphinx/templates/kernel-toc.html b/Documentation/sphinx/templates/kernel-toc.html new file mode 100644 index 000000000000..b58efa99df52 --- /dev/null +++ b/Documentation/sphinx/templates/kernel-toc.html @@ -0,0 +1,16 @@ +<!-- SPDX-License-Identifier: GPL-2.0 --> +{# Create a local TOC the kernel way #} +<p> +<h3 class="kernel-toc-contents">Contents</h3> +<input type="checkbox" class="kernel-toc-toggle" id = "kernel-toc-toggle" checked> +<label class="kernel-toc-title" for="kernel-toc-toggle"></label> + +<div class="kerneltoc" id="kerneltoc"> +{{ toctree(maxdepth=3) }} +</div> +{# hacky script to try to position the left column #} +<script type="text/javascript"> <!-- + var sbar = document.getElementsByClassName("sphinxsidebar")[0]; + let currents = document.getElementsByClassName("current") + sbar.scrollTop = currents[currents.length - 1].offsetTop; + --> </script> diff --git a/Documentation/trace/events-msr.rst b/Documentation/trace/events-msr.rst index 810481e530b6..35d06dc66bc2 100644 --- a/Documentation/trace/events-msr.rst +++ b/Documentation/trace/events-msr.rst @@ -8,7 +8,7 @@ at https://www.intel.com/sdm (Volume 3) Available trace points: -/sys/kernel/debug/tracing/events/msr/ +/sys/kernel/tracing/events/msr/ Trace MSR reads: @@ -34,7 +34,7 @@ rdpmc The trace data can be post processed with the postprocess/decode_msr.py script:: - cat /sys/kernel/debug/tracing/trace | decode_msr.py /usr/src/linux/include/asm/msr-index.h + cat /sys/kernel/tracing/trace | decode_msr.py /usr/src/linux/include/asm/msr-index.h to add symbolic MSR names. diff --git a/Documentation/trace/events-nmi.rst b/Documentation/trace/events-nmi.rst index 9e0a7289d80a..22ac1be0ea6f 100644 --- a/Documentation/trace/events-nmi.rst +++ b/Documentation/trace/events-nmi.rst @@ -4,7 +4,7 @@ NMI Trace Events These events normally show up here: - /sys/kernel/debug/tracing/events/nmi + /sys/kernel/tracing/events/nmi nmi_handler @@ -31,13 +31,13 @@ really hogging a lot of CPU time, like a millisecond at a time. Note that the kernel's output is in milliseconds, but the input to the filter is in nanoseconds! You can filter on 'delta_ns':: - cd /sys/kernel/debug/tracing/events/nmi/nmi_handler + cd /sys/kernel/tracing/events/nmi/nmi_handler echo 'handler==0xffffffff81625600 && delta_ns>1000000' > filter echo 1 > enable Your output would then look like:: - $ cat /sys/kernel/debug/tracing/trace_pipe + $ cat /sys/kernel/tracing/trace_pipe <idle>-0 [000] d.h3 505.397558: nmi_handler: perf_event_nmi_handler() delta_ns: 3236765 handled: 1 <idle>-0 [000] d.h3 505.805893: nmi_handler: perf_event_nmi_handler() delta_ns: 3174234 handled: 1 <idle>-0 [000] d.h3 506.158206: nmi_handler: perf_event_nmi_handler() delta_ns: 3084642 handled: 1 diff --git a/Documentation/trace/events.rst b/Documentation/trace/events.rst index c47f381d0c00..8b33850b8bf9 100644 --- a/Documentation/trace/events.rst +++ b/Documentation/trace/events.rst @@ -24,27 +24,27 @@ tracing information should be printed. --------------------------------- The events which are available for tracing can be found in the file -/sys/kernel/debug/tracing/available_events. +/sys/kernel/tracing/available_events. To enable a particular event, such as 'sched_wakeup', simply echo it -to /sys/kernel/debug/tracing/set_event. For example:: +to /sys/kernel/tracing/set_event. For example:: - # echo sched_wakeup >> /sys/kernel/debug/tracing/set_event + # echo sched_wakeup >> /sys/kernel/tracing/set_event .. Note:: '>>' is necessary, otherwise it will firstly disable all the events. To disable an event, echo the event name to the set_event file prefixed with an exclamation point:: - # echo '!sched_wakeup' >> /sys/kernel/debug/tracing/set_event + # echo '!sched_wakeup' >> /sys/kernel/tracing/set_event To disable all events, echo an empty line to the set_event file:: - # echo > /sys/kernel/debug/tracing/set_event + # echo > /sys/kernel/tracing/set_event To enable all events, echo ``*:*`` or ``*:`` to the set_event file:: - # echo *:* > /sys/kernel/debug/tracing/set_event + # echo *:* > /sys/kernel/tracing/set_event The events are organized into subsystems, such as ext4, irq, sched, etc., and a full event name looks like this: <subsystem>:<event>. The @@ -53,29 +53,29 @@ file. All of the events in a subsystem can be specified via the syntax ``<subsystem>:*``; for example, to enable all irq events, you can use the command:: - # echo 'irq:*' > /sys/kernel/debug/tracing/set_event + # echo 'irq:*' > /sys/kernel/tracing/set_event 2.2 Via the 'enable' toggle --------------------------- -The events available are also listed in /sys/kernel/debug/tracing/events/ hierarchy +The events available are also listed in /sys/kernel/tracing/events/ hierarchy of directories. To enable event 'sched_wakeup':: - # echo 1 > /sys/kernel/debug/tracing/events/sched/sched_wakeup/enable + # echo 1 > /sys/kernel/tracing/events/sched/sched_wakeup/enable To disable it:: - # echo 0 > /sys/kernel/debug/tracing/events/sched/sched_wakeup/enable + # echo 0 > /sys/kernel/tracing/events/sched/sched_wakeup/enable To enable all events in sched subsystem:: - # echo 1 > /sys/kernel/debug/tracing/events/sched/enable + # echo 1 > /sys/kernel/tracing/events/sched/enable To enable all events:: - # echo 1 > /sys/kernel/debug/tracing/events/enable + # echo 1 > /sys/kernel/tracing/events/enable When reading one of these enable files, there are four results: @@ -126,7 +126,7 @@ is the size of the data item, in bytes. For example, here's the information displayed for the 'sched_wakeup' event:: - # cat /sys/kernel/debug/tracing/events/sched/sched_wakeup/format + # cat /sys/kernel/tracing/events/sched/sched_wakeup/format name: sched_wakeup ID: 60 @@ -215,19 +215,19 @@ to the 'filter' file for the given event. For example:: - # cd /sys/kernel/debug/tracing/events/sched/sched_wakeup + # cd /sys/kernel/tracing/events/sched/sched_wakeup # echo "common_preempt_count > 4" > filter A slightly more involved example:: - # cd /sys/kernel/debug/tracing/events/signal/signal_generate + # cd /sys/kernel/tracing/events/signal/signal_generate # echo "((sig >= 10 && sig < 15) || sig == 17) && comm != bash" > filter If there is an error in the expression, you'll get an 'Invalid argument' error when setting it, and the erroneous string along with an error message can be seen by looking at the filter e.g.:: - # cd /sys/kernel/debug/tracing/events/signal/signal_generate + # cd /sys/kernel/tracing/events/signal/signal_generate # echo "((sig >= 10 && sig < 15) || dsig == 17) && comm != bash" > filter -bash: echo: write error: Invalid argument # cat filter @@ -258,7 +258,7 @@ file. To clear the filters for all events in a subsystem, write a '0' to the subsystem's filter file. -5.3 Subsystem filters +5.4 Subsystem filters --------------------- For convenience, filters for every event in a subsystem can be set or @@ -277,7 +277,7 @@ above points: Clear the filters on all events in the sched subsystem:: - # cd /sys/kernel/debug/tracing/events/sched + # cd /sys/kernel/tracing/events/sched # echo 0 > filter # cat sched_switch/filter none @@ -287,7 +287,7 @@ Clear the filters on all events in the sched subsystem:: Set a filter using only common fields for all events in the sched subsystem (all events end up with the same filter):: - # cd /sys/kernel/debug/tracing/events/sched + # cd /sys/kernel/tracing/events/sched # echo common_pid == 0 > filter # cat sched_switch/filter common_pid == 0 @@ -298,14 +298,14 @@ Attempt to set a filter using a non-common field for all events in the sched subsystem (all events but those that have a prev_pid field retain their old filters):: - # cd /sys/kernel/debug/tracing/events/sched + # cd /sys/kernel/tracing/events/sched # echo prev_pid == 0 > filter # cat sched_switch/filter prev_pid == 0 # cat sched_wakeup/filter common_pid == 0 -5.4 PID filtering +5.5 PID filtering ----------------- The set_event_pid file in the same directory as the top events directory @@ -313,7 +313,7 @@ exists, will filter all events from tracing any task that does not have the PID listed in the set_event_pid file. :: - # cd /sys/kernel/debug/tracing + # cd /sys/kernel/tracing # echo $$ > set_event_pid # echo 1 > events/enable @@ -409,14 +409,14 @@ The following commands are supported: specifies that this enablement happens only once:: # echo 'enable_event:kmem:kmalloc:1' > \ - /sys/kernel/debug/tracing/events/syscalls/sys_enter_read/trigger + /sys/kernel/tracing/events/syscalls/sys_enter_read/trigger The following trigger causes kmalloc events to stop being traced when a read system call exits. This disablement happens on every read system call exit:: # echo 'disable_event:kmem:kmalloc' > \ - /sys/kernel/debug/tracing/events/syscalls/sys_exit_read/trigger + /sys/kernel/tracing/events/syscalls/sys_exit_read/trigger The format is:: @@ -426,10 +426,10 @@ The following commands are supported: To remove the above commands:: # echo '!enable_event:kmem:kmalloc:1' > \ - /sys/kernel/debug/tracing/events/syscalls/sys_enter_read/trigger + /sys/kernel/tracing/events/syscalls/sys_enter_read/trigger # echo '!disable_event:kmem:kmalloc' > \ - /sys/kernel/debug/tracing/events/syscalls/sys_exit_read/trigger + /sys/kernel/tracing/events/syscalls/sys_exit_read/trigger Note that there can be any number of enable/disable_event triggers per triggering event, but there can only be one trigger per @@ -448,13 +448,13 @@ The following commands are supported: kmalloc tracepoint is hit:: # echo 'stacktrace' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger The following trigger dumps a stacktrace the first 5 times a kmalloc request happens with a size >= 64K:: # echo 'stacktrace:5 if bytes_req >= 65536' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger The format is:: @@ -463,16 +463,16 @@ The following commands are supported: To remove the above commands:: # echo '!stacktrace' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger # echo '!stacktrace:5 if bytes_req >= 65536' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger The latter can also be removed more simply by the following (without the filter):: # echo '!stacktrace:5' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger Note that there can be only one stacktrace trigger per triggering event. @@ -488,20 +488,20 @@ The following commands are supported: capture those events when the trigger event occurred:: # echo 'snapshot if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger + /sys/kernel/tracing/events/block/block_unplug/trigger To only snapshot once:: # echo 'snapshot:1 if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger + /sys/kernel/tracing/events/block/block_unplug/trigger To remove the above commands:: # echo '!snapshot if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger + /sys/kernel/tracing/events/block/block_unplug/trigger # echo '!snapshot:1 if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger + /sys/kernel/tracing/events/block/block_unplug/trigger Note that there can be only one snapshot trigger per triggering event. @@ -519,20 +519,20 @@ The following commands are supported: trigger event:: # echo 'traceoff:1 if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger + /sys/kernel/tracing/events/block/block_unplug/trigger To always disable tracing when nr_rq > 1:: # echo 'traceoff if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger + /sys/kernel/tracing/events/block/block_unplug/trigger To remove the above commands:: # echo '!traceoff:1 if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger + /sys/kernel/tracing/events/block/block_unplug/trigger # echo '!traceoff if nr_rq > 1' > \ - /sys/kernel/debug/tracing/events/block/block_unplug/trigger + /sys/kernel/tracing/events/block/block_unplug/trigger Note that there can be only one traceon or traceoff trigger per triggering event. diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst index 21f01d32c959..b927fb2b94dc 100644 --- a/Documentation/trace/ftrace.rst +++ b/Documentation/trace/ftrace.rst @@ -830,10 +830,10 @@ Error conditions The extended error information and usage takes the form shown in this example:: - # echo xxx > /sys/kernel/debug/tracing/events/sched/sched_wakeup/trigger + # echo xxx > /sys/kernel/tracing/events/sched/sched_wakeup/trigger echo: write error: Invalid argument - # cat /sys/kernel/debug/tracing/error_log + # cat /sys/kernel/tracing/error_log [ 5348.887237] location: error: Couldn't yyy: zzz Command: xxx ^ @@ -843,7 +843,7 @@ Error conditions To clear the error log, echo the empty string into it:: - # echo > /sys/kernel/debug/tracing/error_log + # echo > /sys/kernel/tracing/error_log Examples of using the tracer ---------------------------- diff --git a/Documentation/trace/histogram-design.rst b/Documentation/trace/histogram-design.rst index 088c8cce738b..5765eb3e9efa 100644 --- a/Documentation/trace/histogram-design.rst +++ b/Documentation/trace/histogram-design.rst @@ -14,7 +14,7 @@ tracing_map.c. Note: All the ftrace histogram command examples assume the working directory is the ftrace /tracing directory. For example:: - # cd /sys/kernel/debug/tracing + # cd /sys/kernel/tracing Also, the histogram output displayed for those commands will be generally be truncated - only enough to make the point is displayed. @@ -905,7 +905,7 @@ means it will be automatically converted into a field variable:: # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0: \ onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,next_pid)' >> - /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + /sys/kernel/tracing/events/sched/sched_switch/trigger The diagram for the sched_switch event is similar to previous examples but shows the additional field_vars[] array for hist_data and shows @@ -1112,7 +1112,7 @@ sched_switch event fields, next_pid and next_comm, to generate a wakeup_latency trace event. The next_pid and next_comm event fields are automatically converted into field variables for this purpose:: - # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0:onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,next_pid,next_comm)' >> /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0:onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,next_pid,next_comm)' >> /sys/kernel/tracing/events/sched/sched_switch/trigger The sched_waking hist_debug output shows the same data as in the previous test example:: @@ -1305,7 +1305,7 @@ and event name for the onmatch() handler:: The commands below can be used to clean things up for the next test:: - # echo '!hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0:onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,next_pid,next_comm)' >> /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + # echo '!hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0:onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,next_pid,next_comm)' >> /sys/kernel/tracing/events/sched/sched_switch/trigger # echo '!hist:keys=pid:ts0=common_timestamp.usecs' >> events/sched/sched_waking/trigger @@ -1363,13 +1363,13 @@ with the save() and snapshot() actions. For example:: # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0: \ onmax($wakeup_lat).save(next_comm,prev_pid,prev_prio,prev_comm)' >> - /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + /sys/kernel/tracing/events/sched/sched_switch/trigger or:: # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0: \ onmax($wakeup_lat).snapshot()' >> - /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + /sys/kernel/tracing/events/sched/sched_switch/trigger save() action field variable test --------------------------------- diff --git a/Documentation/trace/histogram.rst b/Documentation/trace/histogram.rst index f95459aa984f..7b7e4893b8f6 100644 --- a/Documentation/trace/histogram.rst +++ b/Documentation/trace/histogram.rst @@ -102,12 +102,12 @@ Documentation written by Tom Zanussi trigger, read its current contents, and then turn it off:: # echo 'hist:keys=skbaddr.hex:vals=len' > \ - /sys/kernel/debug/tracing/events/net/netif_rx/trigger + /sys/kernel/tracing/events/net/netif_rx/trigger - # cat /sys/kernel/debug/tracing/events/net/netif_rx/hist + # cat /sys/kernel/tracing/events/net/netif_rx/hist # echo '!hist:keys=skbaddr.hex:vals=len' > \ - /sys/kernel/debug/tracing/events/net/netif_rx/trigger + /sys/kernel/tracing/events/net/netif_rx/trigger The trigger file itself can be read to show the details of the currently attached hist trigger. This information is also displayed @@ -169,13 +169,13 @@ Documentation written by Tom Zanussi aggregation on and off when conditions of interest are hit:: # echo 'hist:keys=skbaddr.hex:vals=len:pause' > \ - /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger + /sys/kernel/tracing/events/net/netif_receive_skb/trigger # echo 'enable_hist:net:netif_receive_skb if filename==/usr/bin/wget' > \ - /sys/kernel/debug/tracing/events/sched/sched_process_exec/trigger + /sys/kernel/tracing/events/sched/sched_process_exec/trigger # echo 'disable_hist:net:netif_receive_skb if comm==wget' > \ - /sys/kernel/debug/tracing/events/sched/sched_process_exit/trigger + /sys/kernel/tracing/events/sched/sched_process_exit/trigger The above sets up an initially paused hist trigger which is unpaused and starts aggregating events when a given program is executed, and @@ -218,7 +218,7 @@ Extended error information event. The fields that can be used for the hist trigger are listed in the kmalloc event's format file:: - # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/format + # cat /sys/kernel/tracing/events/kmem/kmalloc/format name: kmalloc ID: 374 format: @@ -238,7 +238,7 @@ Extended error information the kernel that made one or more calls to kmalloc:: # echo 'hist:key=call_site:val=bytes_req.buckets=32' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger This tells the tracing system to create a 'hist' trigger using the call_site field of the kmalloc event as the key for the table, which @@ -252,7 +252,7 @@ Extended error information file in the kmalloc event's subdirectory (for readability, a number of entries have been omitted):: - # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist + # cat /sys/kernel/tracing/events/kmem/kmalloc/hist # trigger info: hist:keys=call_site:vals=bytes_req:sort=hitcount:size=2048 [active] { call_site: 18446744072106379007 } hitcount: 1 bytes_req: 176 @@ -292,7 +292,7 @@ Extended error information the trigger info, which can also be displayed by reading the 'trigger' file:: - # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + # cat /sys/kernel/tracing/events/kmem/kmalloc/trigger hist:keys=call_site:vals=bytes_req:sort=hitcount:size=2048 [active] At the end of the output are a few lines that display the overall @@ -323,7 +323,7 @@ Extended error information command history and re-execute it with a '!' prepended:: # echo '!hist:key=call_site:val=bytes_req' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger Finally, notice that the call_site as displayed in the output above isn't really very useful. It's an address, but normally addresses @@ -331,9 +331,9 @@ Extended error information value, simply append '.hex' to the field name in the trigger:: # echo 'hist:key=call_site.hex:val=bytes_req' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger - # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist + # cat /sys/kernel/tracing/events/kmem/kmalloc/hist # trigger info: hist:keys=call_site.hex:vals=bytes_req:sort=hitcount:size=2048 [active] { call_site: ffffffffa026b291 } hitcount: 1 bytes_req: 433 @@ -376,9 +376,9 @@ Extended error information trigger:: # echo 'hist:key=call_site.sym:val=bytes_req' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger - # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist + # cat /sys/kernel/tracing/events/kmem/kmalloc/hist # trigger info: hist:keys=call_site.sym:vals=bytes_req:sort=hitcount:size=2048 [active] { call_site: [ffffffff810adcb9] syslog_print_all } hitcount: 1 bytes_req: 1024 @@ -426,9 +426,9 @@ Extended error information the 'sort' parameter, along with the 'descending' modifier:: # echo 'hist:key=call_site.sym:val=bytes_req:sort=bytes_req.descending' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger - # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist + # cat /sys/kernel/tracing/events/kmem/kmalloc/hist # trigger info: hist:keys=call_site.sym:vals=bytes_req:sort=bytes_req.descending:size=2048 [active] { call_site: [ffffffffa046041c] i915_gem_execbuffer2 [i915] } hitcount: 2186 bytes_req: 3397464 @@ -467,9 +467,9 @@ Extended error information name, just use 'sym-offset' instead:: # echo 'hist:key=call_site.sym-offset:val=bytes_req:sort=bytes_req.descending' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger - # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist + # cat /sys/kernel/tracing/events/kmem/kmalloc/hist # trigger info: hist:keys=call_site.sym-offset:vals=bytes_req:sort=bytes_req.descending:size=2048 [active] { call_site: [ffffffffa046041c] i915_gem_execbuffer2+0x6c/0x2c0 [i915] } hitcount: 4569 bytes_req: 3163720 @@ -506,9 +506,9 @@ Extended error information allocated in a descending order:: # echo 'hist:keys=call_site.sym:values=bytes_req,bytes_alloc:sort=bytes_alloc.descending' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger - # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist + # cat /sys/kernel/tracing/events/kmem/kmalloc/hist # trigger info: hist:keys=call_site.sym:vals=bytes_req,bytes_alloc:sort=bytes_alloc.descending:size=2048 [active] { call_site: [ffffffffa046041c] i915_gem_execbuffer2 [i915] } hitcount: 7403 bytes_req: 4084360 bytes_alloc: 5958016 @@ -549,7 +549,7 @@ Extended error information value 'stacktrace' for the key parameter:: # echo 'hist:keys=stacktrace:values=bytes_req,bytes_alloc:sort=bytes_alloc' > \ - /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger + /sys/kernel/tracing/events/kmem/kmalloc/trigger The above trigger will use the kernel stack trace in effect when an event is triggered as the key for the hash table. This allows the @@ -559,7 +559,7 @@ Extended error information every callpath in the system that led up to a kmalloc (in this case every callpath to a kmalloc for a kernel compile):: - # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist + # cat /sys/kernel/tracing/events/kmem/kmalloc/hist # trigger info: hist:keys=stacktrace:vals=bytes_req,bytes_alloc:sort=bytes_alloc:size=2048 [active] { stacktrace: @@ -658,9 +658,9 @@ Extended error information keeps a per-process sum of total bytes read:: # echo 'hist:key=common_pid.execname:val=count:sort=count.descending' > \ - /sys/kernel/debug/tracing/events/syscalls/sys_enter_read/trigger + /sys/kernel/tracing/events/syscalls/sys_enter_read/trigger - # cat /sys/kernel/debug/tracing/events/syscalls/sys_enter_read/hist + # cat /sys/kernel/tracing/events/syscalls/sys_enter_read/hist # trigger info: hist:keys=common_pid.execname:vals=count:sort=count.descending:size=2048 [active] { common_pid: gnome-terminal [ 3196] } hitcount: 280 count: 1093512 @@ -699,9 +699,9 @@ Extended error information counts for the system during the run:: # echo 'hist:key=id.syscall:val=hitcount' > \ - /sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/trigger + /sys/kernel/tracing/events/raw_syscalls/sys_enter/trigger - # cat /sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/hist + # cat /sys/kernel/tracing/events/raw_syscalls/sys_enter/hist # trigger info: hist:keys=id.syscall:vals=hitcount:sort=hitcount:size=2048 [active] { id: sys_fsync [ 74] } hitcount: 1 @@ -753,9 +753,9 @@ Extended error information hitcount sum as the secondary key:: # echo 'hist:key=id.syscall,common_pid.execname:val=hitcount:sort=id,hitcount' > \ - /sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/trigger + /sys/kernel/tracing/events/raw_syscalls/sys_enter/trigger - # cat /sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/hist + # cat /sys/kernel/tracing/events/raw_syscalls/sys_enter/hist # trigger info: hist:keys=id.syscall,common_pid.execname:vals=hitcount:sort=id.syscall,hitcount:size=2048 [active] { id: sys_read [ 0], common_pid: rtkit-daemon [ 1877] } hitcount: 1 @@ -803,9 +803,9 @@ Extended error information can use that to filter out all the other syscalls:: # echo 'hist:key=id.syscall,common_pid.execname:val=hitcount:sort=id,hitcount if id == 16' > \ - /sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/trigger + /sys/kernel/tracing/events/raw_syscalls/sys_enter/trigger - # cat /sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/hist + # cat /sys/kernel/tracing/events/raw_syscalls/sys_enter/hist # trigger info: hist:keys=id.syscall,common_pid.execname:vals=hitcount:sort=id.syscall,hitcount:size=2048 if id == 16 [active] { id: sys_ioctl [ 16], common_pid: gmain [ 2769] } hitcount: 1 @@ -846,9 +846,9 @@ Extended error information each process:: # echo 'hist:key=common_pid.execname,size:val=hitcount:sort=common_pid,size' > \ - /sys/kernel/debug/tracing/events/syscalls/sys_enter_recvfrom/trigger + /sys/kernel/tracing/events/syscalls/sys_enter_recvfrom/trigger - # cat /sys/kernel/debug/tracing/events/syscalls/sys_enter_recvfrom/hist + # cat /sys/kernel/tracing/events/syscalls/sys_enter_recvfrom/hist # trigger info: hist:keys=common_pid.execname,size:vals=hitcount:sort=common_pid.execname,size:size=2048 [active] { common_pid: smbd [ 784], size: 4 } hitcount: 1 @@ -899,9 +899,9 @@ Extended error information much smaller number, say 256:: # echo 'hist:key=child_comm:val=hitcount:size=256' > \ - /sys/kernel/debug/tracing/events/sched/sched_process_fork/trigger + /sys/kernel/tracing/events/sched/sched_process_fork/trigger - # cat /sys/kernel/debug/tracing/events/sched/sched_process_fork/hist + # cat /sys/kernel/tracing/events/sched/sched_process_fork/hist # trigger info: hist:keys=child_comm:vals=hitcount:sort=hitcount:size=256 [active] { child_comm: dconf worker } hitcount: 1 @@ -935,9 +935,9 @@ Extended error information displays as [paused]:: # echo 'hist:key=child_comm:val=hitcount:size=256:pause' >> \ - /sys/kernel/debug/tracing/events/sched/sched_process_fork/trigger + /sys/kernel/tracing/events/sched/sched_process_fork/trigger - # cat /sys/kernel/debug/tracing/events/sched/sched_process_fork/hist + # cat /sys/kernel/tracing/events/sched/sched_process_fork/hist # trigger info: hist:keys=child_comm:vals=hitcount:sort=hitcount:size=256 [paused] { child_comm: dconf worker } hitcount: 1 @@ -972,9 +972,9 @@ Extended error information again, and the data has changed:: # echo 'hist:key=child_comm:val=hitcount:size=256:cont' >> \ - /sys/kernel/debug/tracing/events/sched/sched_process_fork/trigger + /sys/kernel/tracing/events/sched/sched_process_fork/trigger - # cat /sys/kernel/debug/tracing/events/sched/sched_process_fork/hist + # cat /sys/kernel/tracing/events/sched/sched_process_fork/hist # trigger info: hist:keys=child_comm:vals=hitcount:sort=hitcount:size=256 [active] { child_comm: dconf worker } hitcount: 1 @@ -1026,7 +1026,7 @@ Extended error information netif_receive_skb event:: # echo 'hist:key=stacktrace:vals=len:pause' > \ - /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger + /sys/kernel/tracing/events/net/netif_receive_skb/trigger Next, we set up an 'enable_hist' trigger on the sched_process_exec event, with an 'if filename==/usr/bin/wget' filter. The effect of @@ -1037,7 +1037,7 @@ Extended error information hash table keyed on stacktrace:: # echo 'enable_hist:net:netif_receive_skb if filename==/usr/bin/wget' > \ - /sys/kernel/debug/tracing/events/sched/sched_process_exec/trigger + /sys/kernel/tracing/events/sched/sched_process_exec/trigger The aggregation continues until the netif_receive_skb is paused again, which is what the following disable_hist event does by @@ -1045,7 +1045,7 @@ Extended error information filter 'comm==wget':: # echo 'disable_hist:net:netif_receive_skb if comm==wget' > \ - /sys/kernel/debug/tracing/events/sched/sched_process_exit/trigger + /sys/kernel/tracing/events/sched/sched_process_exit/trigger Whenever a process exits and the comm field of the disable_hist trigger filter matches 'comm==wget', the netif_receive_skb hist @@ -1058,7 +1058,7 @@ Extended error information $ wget https://www.kernel.org/pub/linux/kernel/v3.x/patch-3.19.xz - # cat /sys/kernel/debug/tracing/events/net/netif_receive_skb/hist + # cat /sys/kernel/tracing/events/net/netif_receive_skb/hist # trigger info: hist:keys=stacktrace:vals=len:sort=hitcount:size=2048 [paused] { stacktrace: @@ -1142,12 +1142,12 @@ Extended error information again, we can just clear the histogram first:: # echo 'hist:key=stacktrace:vals=len:clear' >> \ - /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger + /sys/kernel/tracing/events/net/netif_receive_skb/trigger Just to verify that it is in fact cleared, here's what we now see in the hist file:: - # cat /sys/kernel/debug/tracing/events/net/netif_receive_skb/hist + # cat /sys/kernel/tracing/events/net/netif_receive_skb/hist # trigger info: hist:keys=stacktrace:vals=len:sort=hitcount:size=2048 [paused] Totals: @@ -1162,21 +1162,21 @@ Extended error information sched_process_exit events as such:: # echo 'enable_event:net:netif_receive_skb if filename==/usr/bin/wget' > \ - /sys/kernel/debug/tracing/events/sched/sched_process_exec/trigger + /sys/kernel/tracing/events/sched/sched_process_exec/trigger # echo 'disable_event:net:netif_receive_skb if comm==wget' > \ - /sys/kernel/debug/tracing/events/sched/sched_process_exit/trigger + /sys/kernel/tracing/events/sched/sched_process_exit/trigger If you read the trigger files for the sched_process_exec and sched_process_exit triggers, you should see two triggers for each: one enabling/disabling the hist aggregation and the other enabling/disabling the logging of events:: - # cat /sys/kernel/debug/tracing/events/sched/sched_process_exec/trigger + # cat /sys/kernel/tracing/events/sched/sched_process_exec/trigger enable_event:net:netif_receive_skb:unlimited if filename==/usr/bin/wget enable_hist:net:netif_receive_skb:unlimited if filename==/usr/bin/wget - # cat /sys/kernel/debug/tracing/events/sched/sched_process_exit/trigger + # cat /sys/kernel/tracing/events/sched/sched_process_exit/trigger enable_event:net:netif_receive_skb:unlimited if comm==wget disable_hist:net:netif_receive_skb:unlimited if comm==wget @@ -1192,7 +1192,7 @@ Extended error information saw in the last run, but this time you should also see the individual events in the trace file:: - # cat /sys/kernel/debug/tracing/trace + # cat /sys/kernel/tracing/trace # tracer: nop # @@ -1226,15 +1226,15 @@ Extended error information other things:: # echo 'hist:keys=skbaddr.hex:vals=len if len < 0' >> \ - /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger + /sys/kernel/tracing/events/net/netif_receive_skb/trigger # echo 'hist:keys=skbaddr.hex:vals=len if len > 4096' >> \ - /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger + /sys/kernel/tracing/events/net/netif_receive_skb/trigger # echo 'hist:keys=skbaddr.hex:vals=len if len == 256' >> \ - /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger + /sys/kernel/tracing/events/net/netif_receive_skb/trigger # echo 'hist:keys=skbaddr.hex:vals=len' >> \ - /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger + /sys/kernel/tracing/events/net/netif_receive_skb/trigger # echo 'hist:keys=len:vals=common_preempt_count' >> \ - /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger + /sys/kernel/tracing/events/net/netif_receive_skb/trigger The above set of commands create four triggers differing only in their filters, along with a completely different though fairly @@ -1246,7 +1246,7 @@ Extended error information Displaying the contents of the 'hist' file for the event shows the contents of all five histograms:: - # cat /sys/kernel/debug/tracing/events/net/netif_receive_skb/hist + # cat /sys/kernel/tracing/events/net/netif_receive_skb/hist # event histogram # @@ -1367,15 +1367,15 @@ Extended error information field in the shared 'foo' histogram data:: # echo 'hist:name=foo:keys=skbaddr.hex:vals=len' > \ - /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger + /sys/kernel/tracing/events/net/netif_receive_skb/trigger # echo 'hist:name=foo:keys=skbaddr.hex:vals=len' > \ - /sys/kernel/debug/tracing/events/net/netif_rx/trigger + /sys/kernel/tracing/events/net/netif_rx/trigger You can see that they're updating common histogram data by reading each event's hist files at the same time:: - # cat /sys/kernel/debug/tracing/events/net/netif_receive_skb/hist; - cat /sys/kernel/debug/tracing/events/net/netif_rx/hist + # cat /sys/kernel/tracing/events/net/netif_receive_skb/hist; + cat /sys/kernel/tracing/events/net/netif_rx/hist # event histogram # @@ -1488,15 +1488,15 @@ Extended error information couple of triggers named 'bar' using those fields:: # echo 'hist:name=bar:key=stacktrace:val=hitcount' > \ - /sys/kernel/debug/tracing/events/sched/sched_process_fork/trigger + /sys/kernel/tracing/events/sched/sched_process_fork/trigger # echo 'hist:name=bar:key=stacktrace:val=hitcount' > \ - /sys/kernel/debug/tracing/events/net/netif_rx/trigger + /sys/kernel/tracing/events/net/netif_rx/trigger And displaying the output of either shows some interesting if somewhat confusing output:: - # cat /sys/kernel/debug/tracing/events/sched/sched_process_fork/hist - # cat /sys/kernel/debug/tracing/events/net/netif_rx/hist + # cat /sys/kernel/tracing/events/sched/sched_process_fork/hist + # cat /sys/kernel/tracing/events/net/netif_rx/hist # event histogram # @@ -1826,19 +1826,19 @@ variable reference to a variable on another event:: u64 lat; \ pid_t pid; \ int prio' >> \ - /sys/kernel/debug/tracing/synthetic_events + /sys/kernel/tracing/synthetic_events Reading the tracing/synthetic_events file lists all the currently defined synthetic events, in this case the event defined above:: - # cat /sys/kernel/debug/tracing/synthetic_events + # cat /sys/kernel/tracing/synthetic_events wakeup_latency u64 lat; pid_t pid; int prio An existing synthetic event definition can be removed by prepending the command that defined it with a '!':: # echo '!wakeup_latency u64 lat pid_t pid int prio' >> \ - /sys/kernel/debug/tracing/synthetic_events + /sys/kernel/tracing/synthetic_events At this point, there isn't yet an actual 'wakeup_latency' event instantiated in the event subsystem - for this to happen, a 'hist @@ -1850,20 +1850,20 @@ done, the 'wakeup_latency' synthetic event instance is created. The new event is created under the tracing/events/synthetic/ directory and looks and behaves just like any other event:: - # ls /sys/kernel/debug/tracing/events/synthetic/wakeup_latency + # ls /sys/kernel/tracing/events/synthetic/wakeup_latency enable filter format hist id trigger A histogram can now be defined for the new synthetic event:: # echo 'hist:keys=pid,prio,lat.log2:sort=lat' >> \ - /sys/kernel/debug/tracing/events/synthetic/wakeup_latency/trigger + /sys/kernel/tracing/events/synthetic/wakeup_latency/trigger The above shows the latency "lat" in a power of 2 grouping. Like any other event, once a histogram is enabled for the event, the output can be displayed by reading the event's 'hist' file. - # cat /sys/kernel/debug/tracing/events/synthetic/wakeup_latency/hist + # cat /sys/kernel/tracing/events/synthetic/wakeup_latency/hist # event histogram # @@ -1911,7 +1911,7 @@ The latency values can also be grouped linearly by a given size with the ".buckets" modifier and specify a size (in this case groups of 10). # echo 'hist:keys=pid,prio,lat.buckets=10:sort=lat' >> \ - /sys/kernel/debug/tracing/events/synthetic/wakeup_latency/trigger + /sys/kernel/tracing/events/synthetic/wakeup_latency/trigger # event histogram # @@ -2039,9 +2039,9 @@ The following commonly-used handler.action pairs are available: event:: # echo 'wakeup_new_test pid_t pid' >> \ - /sys/kernel/debug/tracing/synthetic_events + /sys/kernel/tracing/synthetic_events - # cat /sys/kernel/debug/tracing/synthetic_events + # cat /sys/kernel/tracing/synthetic_events wakeup_new_test pid_t pid The following hist trigger both defines the missing testpid @@ -2052,26 +2052,26 @@ The following commonly-used handler.action pairs are available: # echo 'hist:keys=$testpid:testpid=pid:onmatch(sched.sched_wakeup_new).\ wakeup_new_test($testpid) if comm=="cyclictest"' >> \ - /sys/kernel/debug/tracing/events/sched/sched_wakeup_new/trigger + /sys/kernel/tracing/events/sched/sched_wakeup_new/trigger Or, equivalently, using the 'trace' keyword syntax: # echo 'hist:keys=$testpid:testpid=pid:onmatch(sched.sched_wakeup_new).\ trace(wakeup_new_test,$testpid) if comm=="cyclictest"' >> \ - /sys/kernel/debug/tracing/events/sched/sched_wakeup_new/trigger + /sys/kernel/tracing/events/sched/sched_wakeup_new/trigger Creating and displaying a histogram based on those events is now just a matter of using the fields and new synthetic event in the tracing/events/synthetic directory, as usual:: # echo 'hist:keys=pid:sort=pid' >> \ - /sys/kernel/debug/tracing/events/synthetic/wakeup_new_test/trigger + /sys/kernel/tracing/events/synthetic/wakeup_new_test/trigger Running 'cyclictest' should cause wakeup_new events to generate wakeup_new_test synthetic events which should result in histogram output in the wakeup_new_test event's hist file:: - # cat /sys/kernel/debug/tracing/events/synthetic/wakeup_new_test/hist + # cat /sys/kernel/tracing/events/synthetic/wakeup_new_test/hist A more typical usage would be to use two events to calculate a latency. The following example uses a set of hist triggers to @@ -2080,14 +2080,14 @@ The following commonly-used handler.action pairs are available: First, we define a 'wakeup_latency' synthetic event:: # echo 'wakeup_latency u64 lat; pid_t pid; int prio' >> \ - /sys/kernel/debug/tracing/synthetic_events + /sys/kernel/tracing/synthetic_events Next, we specify that whenever we see a sched_waking event for a cyclictest thread, save the timestamp in a 'ts0' variable:: # echo 'hist:keys=$saved_pid:saved_pid=pid:ts0=common_timestamp.usecs \ if comm=="cyclictest"' >> \ - /sys/kernel/debug/tracing/events/sched/sched_waking/trigger + /sys/kernel/tracing/events/sched/sched_waking/trigger Then, when the corresponding thread is actually scheduled onto the CPU by a sched_switch event (saved_pid matches next_pid), calculate @@ -2097,19 +2097,19 @@ The following commonly-used handler.action pairs are available: # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0:\ onmatch(sched.sched_waking).wakeup_latency($wakeup_lat,\ $saved_pid,next_prio) if next_comm=="cyclictest"' >> \ - /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + /sys/kernel/tracing/events/sched/sched_switch/trigger We also need to create a histogram on the wakeup_latency synthetic event in order to aggregate the generated synthetic event data:: # echo 'hist:keys=pid,prio,lat:sort=pid,lat' >> \ - /sys/kernel/debug/tracing/events/synthetic/wakeup_latency/trigger + /sys/kernel/tracing/events/synthetic/wakeup_latency/trigger Finally, once we've run cyclictest to actually generate some events, we can see the output by looking at the wakeup_latency synthetic event's hist file:: - # cat /sys/kernel/debug/tracing/events/synthetic/wakeup_latency/hist + # cat /sys/kernel/tracing/events/synthetic/wakeup_latency/hist - onmax(var).save(field,.. .) @@ -2135,19 +2135,19 @@ The following commonly-used handler.action pairs are available: # echo 'hist:keys=pid:ts0=common_timestamp.usecs \ if comm=="cyclictest"' >> \ - /sys/kernel/debug/tracing/events/sched/sched_waking/trigger + /sys/kernel/tracing/events/sched/sched_waking/trigger # echo 'hist:keys=next_pid:\ wakeup_lat=common_timestamp.usecs-$ts0:\ onmax($wakeup_lat).save(next_comm,prev_pid,prev_prio,prev_comm) \ if next_comm=="cyclictest"' >> \ - /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + /sys/kernel/tracing/events/sched/sched_switch/trigger When the histogram is displayed, the max value and the saved values corresponding to the max are displayed following the rest of the fields:: - # cat /sys/kernel/debug/tracing/events/sched/sched_switch/hist + # cat /sys/kernel/tracing/events/sched/sched_switch/hist { next_pid: 2255 } hitcount: 239 common_timestamp-ts0: 0 max: 27 @@ -2193,17 +2193,17 @@ The following commonly-used handler.action pairs are available: the scheduler events are also enabled, which are the events that will show up in the snapshot when it is taken at some point: - # echo 1 > /sys/kernel/debug/tracing/events/sched/enable + # echo 1 > /sys/kernel/tracing/events/sched/enable # echo 'hist:keys=pid:ts0=common_timestamp.usecs \ if comm=="cyclictest"' >> \ - /sys/kernel/debug/tracing/events/sched/sched_waking/trigger + /sys/kernel/tracing/events/sched/sched_waking/trigger # echo 'hist:keys=next_pid:wakeup_lat=common_timestamp.usecs-$ts0: \ onmax($wakeup_lat).save(next_prio,next_comm,prev_pid,prev_prio, \ prev_comm):onmax($wakeup_lat).snapshot() \ if next_comm=="cyclictest"' >> \ - /sys/kernel/debug/tracing/events/sched/sched_switch/trigger + /sys/kernel/tracing/events/sched/sched_switch/trigger When the histogram is displayed, for each bucket the max value and the saved values corresponding to the max are displayed @@ -2212,7 +2212,7 @@ The following commonly-used handler.action pairs are available: If a snapshot was taken, there is also a message indicating that, along with the value and event that triggered the global maximum: - # cat /sys/kernel/debug/tracing/events/sched/sched_switch/hist + # cat /sys/kernel/tracing/events/sched/sched_switch/hist { next_pid: 2101 } hitcount: 200 max: 52 next_prio: 120 next_comm: cyclictest \ prev_pid: 0 prev_prio: 120 prev_comm: swapper/6 @@ -2247,7 +2247,7 @@ The following commonly-used handler.action pairs are available: sched_switch events, which should match the time displayed in the global maximum):: - # cat /sys/kernel/debug/tracing/snapshot + # cat /sys/kernel/tracing/snapshot <...>-2103 [005] d..3 309.873125: sched_switch: prev_comm=cyclictest prev_pid=2103 prev_prio=19 prev_state=D ==> next_comm=swapper/5 next_pid=0 next_prio=120 <idle>-0 [005] d.h3 309.873611: sched_waking: comm=cyclictest pid=2102 prio=19 target_cpu=005 @@ -2312,13 +2312,13 @@ The following commonly-used handler.action pairs are available: enabled, which are the events that will show up in the snapshot when it is taken at some point: - # echo 1 > /sys/kernel/debug/tracing/events/sched/enable - # echo 1 > /sys/kernel/debug/tracing/events/tcp/enable + # echo 1 > /sys/kernel/tracing/events/sched/enable + # echo 1 > /sys/kernel/tracing/events/tcp/enable # echo 'hist:keys=dport:cwnd=snd_cwnd: \ onchange($cwnd).save(snd_wnd,srtt,rcv_wnd): \ onchange($cwnd).snapshot()' >> \ - /sys/kernel/debug/tracing/events/tcp/tcp_probe/trigger + /sys/kernel/tracing/events/tcp/tcp_probe/trigger When the histogram is displayed, for each bucket the tracked value and the saved values corresponding to that value are displayed @@ -2327,7 +2327,7 @@ The following commonly-used handler.action pairs are available: If a snapshot was taken, there is also a message indicating that, along with the value and event that triggered the snapshot:: - # cat /sys/kernel/debug/tracing/events/tcp/tcp_probe/hist + # cat /sys/kernel/tracing/events/tcp/tcp_probe/hist { dport: 1521 } hitcount: 8 changed: 10 snd_wnd: 35456 srtt: 154262 rcv_wnd: 42112 @@ -2361,7 +2361,7 @@ The following commonly-used handler.action pairs are available: And finally, looking at the snapshot data should show at or near the end the event that triggered the snapshot:: - # cat /sys/kernel/debug/tracing/snapshot + # cat /sys/kernel/tracing/snapshot gnome-shell-1261 [006] dN.3 49.823113: sched_stat_runtime: comm=gnome-shell pid=1261 runtime=49347 [ns] vruntime=1835730389 [ns] kworker/u16:4-773 [003] d..3 49.823114: sched_switch: prev_comm=kworker/u16:4 prev_pid=773 prev_prio=120 prev_state=R+ ==> next_comm=kworker/3:2 next_pid=135 next_prio=120 diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst index 08a2a6a3782f..0d103074d3d2 100644 --- a/Documentation/trace/kprobetrace.rst +++ b/Documentation/trace/kprobetrace.rst @@ -6,21 +6,21 @@ Kprobe-based Event Tracing Overview -------- -These events are similar to tracepoint based events. Instead of Tracepoint, +These events are similar to tracepoint-based events. Instead of tracepoints, this is based on kprobes (kprobe and kretprobe). So it can probe wherever kprobes can probe (this means, all functions except those with __kprobes/nokprobe_inline annotation and those marked NOKPROBE_SYMBOL). -Unlike the Tracepoint based event, this can be added and removed +Unlike the tracepoint-based event, this can be added and removed dynamically, on the fly. To enable this feature, build your kernel with CONFIG_KPROBE_EVENTS=y. -Similar to the events tracer, this doesn't need to be activated via +Similar to the event tracer, this doesn't need to be activated via current_tracer. Instead of that, add probe points via -/sys/kernel/debug/tracing/kprobe_events, and enable it via -/sys/kernel/debug/tracing/events/kprobes/<EVENT>/enable. +/sys/kernel/tracing/kprobe_events, and enable it via +/sys/kernel/tracing/events/kprobes/<EVENT>/enable. -You can also use /sys/kernel/debug/tracing/dynamic_events instead of +You can also use /sys/kernel/tracing/dynamic_events instead of kprobe_events. That interface will provide unified access to other dynamic events too. @@ -68,22 +68,25 @@ Synopsis of kprobe_events Types ----- -Several types are supported for fetch-args. Kprobe tracer will access memory +Several types are supported for fetchargs. Kprobe tracer will access memory by given type. Prefix 's' and 'u' means those types are signed and unsigned respectively. 'x' prefix implies it is unsigned. Traced arguments are shown in decimal ('s' and 'u') or hexadecimal ('x'). Without type casting, 'x32' or 'x64' is used depends on the architecture (e.g. x86-32 uses x32, and x86-64 uses x64). + These value types can be an array. To record array data, you can add '[N]' (where N is a fixed number, less than 64) to the base type. -E.g. 'x16[4]' means an array of x16 (2bytes hex) with 4 elements. +E.g. 'x16[4]' means an array of x16 (2-byte hex) with 4 elements. Note that the array can be applied to memory type fetchargs, you can not apply it to registers/stack-entries etc. (for example, '$stack1:x8[8]' is wrong, but '+8($stack):x8[8]' is OK.) + String type is a special type, which fetches a "null-terminated" string from kernel space. This means it will fail and store NULL if the string container has been paged out. "ustring" type is an alternative of string for user-space. -See :ref:`user_mem_access` for more info.. +See :ref:`user_mem_access` for more info. + The string array type is a bit different from other types. For other base types, <base-type>[1] is equal to <base-type> (e.g. +0(%di):x32[1] is same as +0(%di):x32.) But string[1] is not equal to string. The string type itself @@ -120,8 +123,8 @@ space. 'ustring' is a shortcut way of performing the same task. That is, Note that kprobe-event provides the user-memory access syntax but it doesn't use it transparently. This means if you use normal dereference or string type -for user memory, it might fail, and may always fail on some archs. The user -has to carefully check if the target data is in kernel or user space. +for user memory, it might fail, and may always fail on some architectures. The +user has to carefully check if the target data is in kernel or user space. Per-Probe Event Filtering ------------------------- @@ -150,7 +153,7 @@ trigger: Event Profiling --------------- You can check the total number of probe hits and probe miss-hits via -/sys/kernel/debug/tracing/kprobe_profile. +/sys/kernel/tracing/kprobe_profile. The first column is event name, the second is the number of probe hits, the third is the number of probe miss-hits. @@ -160,11 +163,11 @@ You can add and enable new kprobe events when booting up the kernel by "kprobe_event=" parameter. The parameter accepts a semicolon-delimited kprobe events, which format is similar to the kprobe_events. The difference is that the probe definition parameters are comma-delimited -instead of space. For example, adding myprobe event on do_sys_open like below +instead of space. For example, adding myprobe event on do_sys_open like below:: p:myprobe do_sys_open dfd=%ax filename=%dx flags=%cx mode=+4($stack) -should be below for kernel boot parameter (just replace spaces with comma) +should be below for kernel boot parameter (just replace spaces with comma):: p:myprobe,do_sys_open,dfd=%ax,filename=%dx,flags=%cx,mode=+4($stack) @@ -174,7 +177,7 @@ Usage examples To add a probe as a new event, write a new definition to kprobe_events as below:: - echo 'p:myprobe do_sys_open dfd=%ax filename=%dx flags=%cx mode=+4($stack)' > /sys/kernel/debug/tracing/kprobe_events + echo 'p:myprobe do_sys_open dfd=%ax filename=%dx flags=%cx mode=+4($stack)' > /sys/kernel/tracing/kprobe_events This sets a kprobe on the top of do_sys_open() function with recording 1st to 4th arguments as "myprobe" event. Note, which register/stack entry is @@ -184,15 +187,15 @@ under tools/perf/). As this example shows, users can choose more familiar names for each arguments. :: - echo 'r:myretprobe do_sys_open $retval' >> /sys/kernel/debug/tracing/kprobe_events + echo 'r:myretprobe do_sys_open $retval' >> /sys/kernel/tracing/kprobe_events This sets a kretprobe on the return point of do_sys_open() function with recording return value as "myretprobe" event. You can see the format of these events via -/sys/kernel/debug/tracing/events/kprobes/<EVENT>/format. +/sys/kernel/tracing/events/kprobes/<EVENT>/format. :: - cat /sys/kernel/debug/tracing/events/kprobes/myprobe/format + cat /sys/kernel/tracing/events/kprobes/myprobe/format name: myprobe ID: 780 format: @@ -215,7 +218,7 @@ You can see the format of these events via You can see that the event has 4 arguments as in the expressions you specified. :: - echo > /sys/kernel/debug/tracing/kprobe_events + echo > /sys/kernel/tracing/kprobe_events This clears all probe points. @@ -230,8 +233,8 @@ Right after definition, each event is disabled by default. For tracing these events, you need to enable it. :: - echo 1 > /sys/kernel/debug/tracing/events/kprobes/myprobe/enable - echo 1 > /sys/kernel/debug/tracing/events/kprobes/myretprobe/enable + echo 1 > /sys/kernel/tracing/events/kprobes/myprobe/enable + echo 1 > /sys/kernel/tracing/events/kprobes/myretprobe/enable Use the following command to start tracing in an interval. :: @@ -240,10 +243,10 @@ Use the following command to start tracing in an interval. Open something... # echo 0 > tracing_on -And you can see the traced information via /sys/kernel/debug/tracing/trace. +And you can see the traced information via /sys/kernel/tracing/trace. :: - cat /sys/kernel/debug/tracing/trace + cat /sys/kernel/tracing/trace # tracer: nop # # TASK-PID CPU# TIMESTAMP FUNCTION diff --git a/Documentation/trace/mmiotrace.rst b/Documentation/trace/mmiotrace.rst index fed13eaead89..95b750722a13 100644 --- a/Documentation/trace/mmiotrace.rst +++ b/Documentation/trace/mmiotrace.rst @@ -36,11 +36,11 @@ Usage Quick Reference :: $ mount -t debugfs debugfs /sys/kernel/debug - $ echo mmiotrace > /sys/kernel/debug/tracing/current_tracer - $ cat /sys/kernel/debug/tracing/trace_pipe > mydump.txt & + $ echo mmiotrace > /sys/kernel/tracing/current_tracer + $ cat /sys/kernel/tracing/trace_pipe > mydump.txt & Start X or whatever. - $ echo "X is up" > /sys/kernel/debug/tracing/trace_marker - $ echo nop > /sys/kernel/debug/tracing/current_tracer + $ echo "X is up" > /sys/kernel/tracing/trace_marker + $ echo nop > /sys/kernel/tracing/current_tracer Check for lost events. @@ -56,11 +56,11 @@ Check that the driver you are about to trace is not loaded. Activate mmiotrace (requires root privileges):: - $ echo mmiotrace > /sys/kernel/debug/tracing/current_tracer + $ echo mmiotrace > /sys/kernel/tracing/current_tracer Start storing the trace:: - $ cat /sys/kernel/debug/tracing/trace_pipe > mydump.txt & + $ cat /sys/kernel/tracing/trace_pipe > mydump.txt & The 'cat' process should stay running (sleeping) in the background. @@ -68,14 +68,14 @@ Load the driver you want to trace and use it. Mmiotrace will only catch MMIO accesses to areas that are ioremapped while mmiotrace is active. During tracing you can place comments (markers) into the trace by -$ echo "X is up" > /sys/kernel/debug/tracing/trace_marker +$ echo "X is up" > /sys/kernel/tracing/trace_marker This makes it easier to see which part of the (huge) trace corresponds to which action. It is recommended to place descriptive markers about what you do. Shut down mmiotrace (requires root privileges):: - $ echo nop > /sys/kernel/debug/tracing/current_tracer + $ echo nop > /sys/kernel/tracing/current_tracer The 'cat' process exits. If it does not, kill it by issuing 'fg' command and pressing ctrl+c. @@ -93,12 +93,12 @@ events were lost, the trace is incomplete. You should enlarge the buffers and try again. Buffers are enlarged by first seeing how large the current buffers are:: - $ cat /sys/kernel/debug/tracing/buffer_size_kb + $ cat /sys/kernel/tracing/buffer_size_kb gives you a number. Approximately double this number and write it back, for instance:: - $ echo 128000 > /sys/kernel/debug/tracing/buffer_size_kb + $ echo 128000 > /sys/kernel/tracing/buffer_size_kb Then start again from the top. diff --git a/Documentation/trace/postprocess/trace-pagealloc-postprocess.pl b/Documentation/trace/postprocess/trace-pagealloc-postprocess.pl index b9b7d80c2f9d..d16494c5e200 100644 --- a/Documentation/trace/postprocess/trace-pagealloc-postprocess.pl +++ b/Documentation/trace/postprocess/trace-pagealloc-postprocess.pl @@ -4,7 +4,7 @@ # to extract some high-level information on what is going on. The accuracy of the parser # may vary considerably # -# Example usage: trace-pagealloc-postprocess.pl < /sys/kernel/debug/tracing/trace_pipe +# Example usage: trace-pagealloc-postprocess.pl < /sys/kernel/tracing/trace_pipe # other options # --prepend-parent Report on the parent proc and PID # --read-procstat If the trace lacks process info, get it from /proc @@ -94,7 +94,7 @@ sub generate_traceevent_regex { my $regex; # Read the event format or use the default - if (!open (FORMAT, "/sys/kernel/debug/tracing/events/$event/format")) { + if (!open (FORMAT, "/sys/kernel/tracing/events/$event/format")) { $regex = $default; } else { my $line; diff --git a/Documentation/trace/postprocess/trace-vmscan-postprocess.pl b/Documentation/trace/postprocess/trace-vmscan-postprocess.pl index 2f4e39875fb3..e24c009789a0 100644 --- a/Documentation/trace/postprocess/trace-vmscan-postprocess.pl +++ b/Documentation/trace/postprocess/trace-vmscan-postprocess.pl @@ -3,7 +3,7 @@ # page reclaim. It makes an attempt to extract some high-level information on # what is going on. The accuracy of the parser may vary # -# Example usage: trace-vmscan-postprocess.pl < /sys/kernel/debug/tracing/trace_pipe +# Example usage: trace-vmscan-postprocess.pl < /sys/kernel/tracing/trace_pipe # other options # --read-procstat If the trace lacks process info, get it from /proc # --ignore-pid Aggregate processes of the same name together @@ -140,7 +140,7 @@ sub generate_traceevent_regex { my $regex; # Read the event format or use the default - if (!open (FORMAT, "/sys/kernel/debug/tracing/events/$event/format")) { + if (!open (FORMAT, "/sys/kernel/tracing/events/$event/format")) { print("WARNING: Event $event format string not found\n"); return $default; } else { diff --git a/Documentation/trace/tracepoint-analysis.rst b/Documentation/trace/tracepoint-analysis.rst index 716326b9f152..be01bf7b47e5 100644 --- a/Documentation/trace/tracepoint-analysis.rst +++ b/Documentation/trace/tracepoint-analysis.rst @@ -26,10 +26,10 @@ assumed that the PCL tool tools/perf has been installed and is in your path. 2.1 Standard Utilities ---------------------- -All possible events are visible from /sys/kernel/debug/tracing/events. Simply +All possible events are visible from /sys/kernel/tracing/events. Simply calling:: - $ find /sys/kernel/debug/tracing/events -type d + $ find /sys/kernel/tracing/events -type d will give a fair indication of the number of events available. @@ -59,7 +59,7 @@ See Documentation/trace/events.rst for a proper description on how events can be enabled system-wide. A short example of enabling all events related to page allocation would look something like:: - $ for i in `find /sys/kernel/debug/tracing/events -name "enable" | grep mm_`; do echo 1 > $i; done + $ for i in `find /sys/kernel/tracing/events -name "enable" | grep mm_`; do echo 1 > $i; done 3.2 System-Wide Event Enabling with SystemTap --------------------------------------------- @@ -189,7 +189,7 @@ time on a system-wide basis using -a and sleep. ============================================ When events are enabled the events that are triggering can be read from -/sys/kernel/debug/tracing/trace_pipe in human-readable format although binary +/sys/kernel/tracing/trace_pipe in human-readable format although binary options exist as well. By post-processing the output, further information can be gathered on-line as appropriate. Examples of post-processing might include diff --git a/Documentation/trace/uprobetracer.rst b/Documentation/trace/uprobetracer.rst index 3a1797d707f4..122d15572fd5 100644 --- a/Documentation/trace/uprobetracer.rst +++ b/Documentation/trace/uprobetracer.rst @@ -12,13 +12,13 @@ To enable this feature, build your kernel with CONFIG_UPROBE_EVENTS=y. Similar to the kprobe-event tracer, this doesn't need to be activated via current_tracer. Instead of that, add probe points via -/sys/kernel/debug/tracing/uprobe_events, and enable it via -/sys/kernel/debug/tracing/events/uprobes/<EVENT>/enable. +/sys/kernel/tracing/uprobe_events, and enable it via +/sys/kernel/tracing/events/uprobes/<EVENT>/enable. However unlike kprobe-event tracer, the uprobe event interface expects the user to calculate the offset of the probepoint in the object. -You can also use /sys/kernel/debug/tracing/dynamic_events instead of +You can also use /sys/kernel/tracing/dynamic_events instead of uprobe_events. That interface will provide unified access to other dynamic events too. @@ -79,7 +79,7 @@ For $comm, the default type is "string"; any other type is invalid. Event Profiling --------------- You can check the total number of probe hits per event via -/sys/kernel/debug/tracing/uprobe_profile. The first column is the filename, +/sys/kernel/tracing/uprobe_profile. The first column is the filename, the second is the event name, the third is the number of probe hits. Usage examples @@ -87,28 +87,28 @@ Usage examples * Add a probe as a new uprobe event, write a new definition to uprobe_events as below (sets a uprobe at an offset of 0x4245c0 in the executable /bin/bash):: - echo 'p /bin/bash:0x4245c0' > /sys/kernel/debug/tracing/uprobe_events + echo 'p /bin/bash:0x4245c0' > /sys/kernel/tracing/uprobe_events * Add a probe as a new uretprobe event:: - echo 'r /bin/bash:0x4245c0' > /sys/kernel/debug/tracing/uprobe_events + echo 'r /bin/bash:0x4245c0' > /sys/kernel/tracing/uprobe_events * Unset registered event:: - echo '-:p_bash_0x4245c0' >> /sys/kernel/debug/tracing/uprobe_events + echo '-:p_bash_0x4245c0' >> /sys/kernel/tracing/uprobe_events * Print out the events that are registered:: - cat /sys/kernel/debug/tracing/uprobe_events + cat /sys/kernel/tracing/uprobe_events * Clear all events:: - echo > /sys/kernel/debug/tracing/uprobe_events + echo > /sys/kernel/tracing/uprobe_events Following example shows how to dump the instruction pointer and %ax register at the probed text address. Probe zfree function in /bin/zsh:: - # cd /sys/kernel/debug/tracing/ + # cd /sys/kernel/tracing/ # cat /proc/`pgrep zsh`/maps | grep /bin/zsh | grep r-xp 00400000-0048a000 r-xp 00000000 08:03 130904 /bin/zsh # objdump -T /bin/zsh | grep -w zfree @@ -168,7 +168,7 @@ Also, you can disable the event by:: # echo 0 > events/uprobes/enable -And you can see the traced information via /sys/kernel/debug/tracing/trace. +And you can see the traced information via /sys/kernel/tracing/trace. :: # cat trace diff --git a/Documentation/trace/user_events.rst b/Documentation/trace/user_events.rst index 9f181f342a70..422802ef4025 100644 --- a/Documentation/trace/user_events.rst +++ b/Documentation/trace/user_events.rst @@ -11,10 +11,10 @@ that can be viewed via existing tools, such as ftrace and perf. To enable this feature, build your kernel with CONFIG_USER_EVENTS=y. Programs can view status of the events via -/sys/kernel/debug/tracing/user_events_status and can both register and write -data out via /sys/kernel/debug/tracing/user_events_data. +/sys/kernel/tracing/user_events_status and can both register and write +data out via /sys/kernel/tracing/user_events_data. -Programs can also use /sys/kernel/debug/tracing/dynamic_events to register and +Programs can also use /sys/kernel/tracing/dynamic_events to register and delete user based events via the u: prefix. The format of the command to dynamic_events is the same as the ioctl with the u: prefix applied. @@ -22,9 +22,9 @@ Typically programs will register a set of events that they wish to expose to tools that can read trace_events (such as ftrace and perf). The registration process gives back two ints to the program for each event. The first int is the status bit. This describes which bit in little-endian format in the -/sys/kernel/debug/tracing/user_events_status file represents this event. The +/sys/kernel/tracing/user_events_status file represents this event. The second int is the write index which describes the data when a write() or -writev() is called on the /sys/kernel/debug/tracing/user_events_data file. +writev() is called on the /sys/kernel/tracing/user_events_data file. The structures referenced in this document are contained within the /include/uapi/linux/user_events.h file in the source tree. @@ -35,7 +35,7 @@ filesystem and may be mounted at different paths than above.* Registering ----------- Registering within a user process is done via ioctl() out to the -/sys/kernel/debug/tracing/user_events_data file. The command to issue is +/sys/kernel/tracing/user_events_data file. The command to issue is DIAG_IOCSREG. This command takes a packed struct user_reg as an argument:: @@ -54,7 +54,7 @@ and the write index. User based events show up under tracefs like any other event under the subsystem named "user_events". This means tools that wish to attach to the -events need to use /sys/kernel/debug/tracing/events/user_events/[name]/enable +events need to use /sys/kernel/tracing/events/user_events/[name]/enable or perf record -e user_events:[name] when attaching/recording. **NOTE:** *The write_index returned is only valid for the FD that was used* @@ -96,7 +96,7 @@ Would be represented by the following field:: Deleting ----------- Deleting an event from within a user process is done via ioctl() out to the -/sys/kernel/debug/tracing/user_events_data file. The command to issue is +/sys/kernel/tracing/user_events_data file. The command to issue is DIAG_IOCSDEL. This command only requires a single string specifying the event to delete by @@ -110,7 +110,7 @@ When tools attach/record user based events the status of the event is updated in realtime. This allows user programs to only incur the cost of the write() or writev() calls when something is actively attached to the event. -User programs call mmap() on /sys/kernel/debug/tracing/user_events_status to +User programs call mmap() on /sys/kernel/tracing/user_events_status to check the status for each event that is registered. The bit to check in the file is given back after the register ioctl() via user_reg.status_bit. The bit is always in little-endian format. Programs can check if the bit is set either diff --git a/Documentation/translations/it_IT/admin-guide/README.rst b/Documentation/translations/it_IT/admin-guide/README.rst index b37166817842..c874586a9af9 100644 --- a/Documentation/translations/it_IT/admin-guide/README.rst +++ b/Documentation/translations/it_IT/admin-guide/README.rst @@ -4,7 +4,7 @@ .. _it_readme: -Rilascio del kernel Linux 5.x <http://kernel.org/> +Rilascio del kernel Linux 6.x <http://kernel.org/> =================================================== .. warning:: diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst index 78082281acf9..5cece223b46b 100644 --- a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst +++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst @@ -3,6 +3,8 @@ .. note:: Per leggere la documentazione originale in inglese: :ref:`Documentation/doc-guide/index.rst <doc_guide>` +.. title:: Commenti in kernel-doc + .. _it_kernel_doc: ================================= diff --git a/Documentation/translations/it_IT/doc-guide/sphinx.rst b/Documentation/translations/it_IT/doc-guide/sphinx.rst index 64528790dc34..1f513bc33618 100644 --- a/Documentation/translations/it_IT/doc-guide/sphinx.rst +++ b/Documentation/translations/it_IT/doc-guide/sphinx.rst @@ -151,7 +151,8 @@ Ovviamente, per generare la documentazione, Sphinx (``sphinx-build``) dev'essere installato. Se disponibile, il tema *Read the Docs* per Sphinx verrà utilizzato per ottenere una documentazione HTML più gradevole. Per la documentazione in formato PDF, invece, avrete bisogno di ``XeLaTeX` -e di ``convert(1)`` disponibile in ImageMagick (https://www.imagemagick.org). +e di ``convert(1)`` disponibile in ImageMagick +(https://www.imagemagick.org). \ [#ink]_ Tipicamente, tutti questi pacchetti sono disponibili e pacchettizzati nelle distribuzioni Linux. @@ -162,9 +163,20 @@ la generazione potete usare il seguente comando ``make SPHINXOPTS=-v htmldocs``. Potete anche personalizzare l'ouptut html passando un livello aggiuntivo DOCS_CSS usando la rispettiva variabile d'ambiente ``DOCS_CSS``. +La variable make ``SPHINXDIRS`` è utile quando si vuole generare solo una parte +della documentazione. Per esempio, si possono generare solo di documenti in +``Documentation/doc-guide`` eseguendo ``make SPHINXDIRS=doc-guide htmldocs``. La +sezione dedicata alla documentazione di ``make help`` vi mostrerà quali sotto +cartelle potete specificare. + Potete eliminare la documentazione generata tramite il comando ``make cleandocs``. +.. [#ink] Avere installato anche ``inkscape(1)`` dal progetto Inkscape () + potrebbe aumentare la qualità delle immagini che verranno integrate + nel documento PDF, specialmente per quando si usando rilasci del + kernel uguali o superiori a 5.18 + Scrivere la documentazione ========================== diff --git a/Documentation/translations/it_IT/index.rst b/Documentation/translations/it_IT/index.rst index e80a3097aa57..fc5f39814e83 100644 --- a/Documentation/translations/it_IT/index.rst +++ b/Documentation/translations/it_IT/index.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. _it_linux_doc: =================== @@ -67,75 +69,68 @@ I miglioramenti alla documentazione sono sempre i benvenuti; per cui, se vuoi aiutare, iscriviti alla lista di discussione linux-doc presso vger.kernel.org. -Documentazione sulla licenza dei sorgenti ------------------------------------------ - -I seguenti documenti descrivono la licenza usata nei sorgenti del kernel Linux -(GPLv2), come licenziare i singoli file; inoltre troverete i riferimenti al -testo integrale della licenza. +Lavorare con la comunità di sviluppo +------------------------------------ -* :ref:`it_kernel_licensing` +Le guide fondamentali per l'interazione con la comunità di sviluppo del kernel e +su come vedere il proprio lavoro integrato. -Documentazione per gli utenti ------------------------------ - -I seguenti manuali sono scritti per gli *utenti* del kernel - ovvero, -coloro che cercano di farlo funzionare in modo ottimale su un dato sistema - -.. warning:: +.. toctree:: + :maxdepth: 1 - TODO ancora da tradurre + process/development-process + process/submitting-patches + Code of conduct <process/code-of-conduct> + All development-process docs <process/index> -Documentazione per gli sviluppatori di applicazioni ---------------------------------------------------- -Il manuale delle API verso lo spazio utente è una collezione di documenti -che descrivono le interfacce del kernel viste dagli sviluppatori -di applicazioni. +Manuali sull'API interna +------------------------ -.. warning:: +Di seguito una serie di manuali per gli sviluppatori che hanno bisogno di +interfacciarsi con il resto del kernel. - TODO ancora da tradurre +.. toctree:: + :maxdepth: 1 + core-api/index -Introduzione allo sviluppo del kernel -------------------------------------- +Strumenti e processi per lo sviluppo +------------------------------------ -Questi manuali contengono informazioni su come contribuire allo sviluppo -del kernel. -Attorno al kernel Linux gira una comunità molto grande con migliaia di -sviluppatori che contribuiscono ogni anno. Come in ogni grande comunità, -sapere come le cose vengono fatte renderà il processo di integrazione delle -vostre modifiche molto più semplice +Di seguito una serie di manuali contenenti informazioni utili a tutti gli +sviluppatori del kernel. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - process/index + process/license-rules doc-guide/index kernel-hacking/index -Documentazione della API del kernel ------------------------------------ +Documentazione per gli utenti +----------------------------- -Questi manuali forniscono dettagli su come funzionano i sottosistemi del -kernel dal punto di vista degli sviluppatori del kernel. Molte delle -informazioni contenute in questi manuali sono prese direttamente dai -file sorgenti, informazioni aggiuntive vengono aggiunte solo se necessarie -(o almeno ci proviamo — probabilmente *non* tutto quello che è davvero -necessario). +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 +coloro che stanno sviluppando applicazioni che sfruttano l'API verso lo +spazio-utente. -.. toctree:: - :maxdepth: 2 +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. - core-api/index Documentazione specifica per architettura ----------------------------------------- -Questi manuali forniscono dettagli di programmazione per le diverse -implementazioni d'architettura. -.. warning:: +Documentazione varia +-------------------- - TODO ancora da tradurre +Ci sono documenti che sono difficili da inserire nell'attuale organizzazione +della documentazione; altri hanno bisogno di essere migliorati e/o convertiti +nel formato *ReStructured Text*; altri sono semplicamente troppo vecchi. diff --git a/Documentation/translations/it_IT/kernel-hacking/hacking.rst b/Documentation/translations/it_IT/kernel-hacking/hacking.rst index 560f1d0482d2..dd06bfc1a050 100644 --- a/Documentation/translations/it_IT/kernel-hacking/hacking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/hacking.rst @@ -137,7 +137,7 @@ macro :c:func:`in_softirq()` (``include/linux/preempt.h``). .. warning:: State attenti che questa macro ritornerà un falso positivo - se :ref:`botton half lock <it_local_bh_disable>` è bloccato. + se :ref:`bottom half lock <it_local_bh_disable>` è bloccato. Alcune regole basilari ====================== diff --git a/Documentation/translations/it_IT/process/2.Process.rst b/Documentation/translations/it_IT/process/2.Process.rst index 62826034e0b2..25cd00351c03 100644 --- a/Documentation/translations/it_IT/process/2.Process.rst +++ b/Documentation/translations/it_IT/process/2.Process.rst @@ -136,18 +136,11 @@ Quindi, per esempio, la storia del kernel 5.2 appare così (anno 2019): La 5.2.21 fu l'aggiornamento finale per la versione 5.2. Alcuni kernel sono destinati ad essere kernel a "lungo termine"; questi -riceveranno assistenza per un lungo periodo di tempo. Al momento in cui -scriviamo, i manutentori dei kernel stabili a lungo termine sono: - - ====== ================================ ========================================== - 3.16 Ben Hutchings (kernel stabile molto più a lungo termine) - 4.4 Greg Kroah-Hartman e Sasha Levin (kernel stabile molto più a lungo termine) - 4.9 Greg Kroah-Hartman e Sasha Levin - 4.14 Greg Kroah-Hartman e Sasha Levin - 4.19 Greg Kroah-Hartman e Sasha Levin - 5.4i Greg Kroah-Hartman e Sasha Levin - ====== ================================ ========================================== +riceveranno assistenza per un lungo periodo di tempo. Consultate il seguente +collegamento per avere la lista delle versioni attualmente supportate e i +relativi manutentori: + https://www.kernel.org/category/releases.html Questa selezione di kernel di lungo periodo sono puramente dovuti ai loro manutentori, alla loro necessità e al tempo per tenere aggiornate proprio diff --git a/Documentation/translations/it_IT/process/7.AdvancedTopics.rst b/Documentation/translations/it_IT/process/7.AdvancedTopics.rst index cc1cff5d23ae..dffd813a0910 100644 --- a/Documentation/translations/it_IT/process/7.AdvancedTopics.rst +++ b/Documentation/translations/it_IT/process/7.AdvancedTopics.rst @@ -35,9 +35,9 @@ git è parte del processo di sviluppo del kernel. Gli sviluppatori che desiderassero diventare agili con git troveranno più informazioni ai seguenti indirizzi: - http://git-scm.com/ + https://git-scm.com/ - http://www.kernel.org/pub/software/scm/git/docs/user-manual.html + https://www.kernel.org/pub/software/scm/git/docs/user-manual.html e su varie guide che potrete trovare su internet. @@ -63,7 +63,7 @@ eseguire git-daemon è relativamente semplice . Altrimenti, iniziano a svilupparsi piattaforme che offrono spazi pubblici, e gratuiti (Github, per esempio). Gli sviluppatori permanenti possono ottenere un account su kernel.org, ma non è proprio facile da ottenere; per maggiori informazioni -consultate la pagina web http://kernel.org/faq/. +consultate la pagina web https://kernel.org/faq/. In git è normale avere a che fare con tanti rami. Ogni linea di sviluppo può essere separata in "rami per argomenti" e gestiti indipendentemente. @@ -137,7 +137,7 @@ vostri rami. Citando Linus facendo, e ho bisogno di fidarmi *senza* dover passare tutte le modifiche manualmente una per una. -(http://lwn.net/Articles/224135/). +(https://lwn.net/Articles/224135/). Per evitare queste situazioni, assicuratevi che tutte le patch in un ramo siano strettamente correlate al tema delle modifiche; un ramo "driver fixes" diff --git a/Documentation/translations/it_IT/process/botching-up-ioctls.rst b/Documentation/translations/it_IT/process/botching-up-ioctls.rst new file mode 100644 index 000000000000..91732cdf808a --- /dev/null +++ b/Documentation/translations/it_IT/process/botching-up-ioctls.rst @@ -0,0 +1,249 @@ +.. include:: ../disclaimer-ita.rst + +:Original: Documentation/process/botching-up-ioctls.rst + +========================================== +(Come evitare di) Raffazzonare delle ioctl +========================================== + +Preso da: https://blog.ffwll.ch/2013/11/botching-up-ioctls.html + +Scritto da : Daniel Vetter, Copyright © 2013 Intel Corporation + +Una cosa che gli sviluppatori del sottosistema grafico del kernel Linux hanno +imparato negli ultimi anni è l'inutilità di cercare di creare un'interfaccia +unificata per gestire la memoria e le unità esecutive di diverse GPU. Dunque, +oggigiorno ogni driver ha il suo insieme di ioctl per allocare memoria ed +inviare dei programmi alla GPU. Il che è va bene dato che non c'è più un insano +sistema che finge di essere generico, ma al suo posto ci sono interfacce +dedicate. Ma al tempo stesso è più facile incasinare le cose. + +Per evitare di ripetere gli stessi errori ho preso nota delle lezioni imparate +mentre raffazzonavo il driver drm/i915. La maggior parte di queste lezioni si +focalizzano sui tecnicismi e non sulla visione d'insieme, come le discussioni +riguardo al modo migliore per implementare una ioctl per inviare compiti alla +GPU. Probabilmente, ogni sviluppatore di driver per GPU dovrebbe imparare queste +lezioni in autonomia. + + +Prerequisiti +------------ + +Prima i prerequisiti. Seguite i seguenti suggerimenti se non volete fallire in +partenza e ritrovarvi ad aggiungere un livello di compatibilità a 32-bit. + +* Usate solamente interi a lunghezza fissa. Per evitare i conflitti coi tipi + definiti nello spazio utente, il kernel definisce alcuni tipi speciali, come: + ``__u32``, ``__s64``. Usateli. + +* Allineate tutto alla lunghezza naturale delle piattaforma in uso e riempite + esplicitamente i vuoti. Non necessariamente le piattaforme a 32-bit allineano + i valori a 64-bit rispettandone l'allineamento, ma le piattaforme a 64-bit lo + fanno. Dunque, per farlo correttamente in entrambe i casi dobbiamo sempre + riempire i vuoti. + +* Se una struttura dati contiene valori a 64-bit, allora fate si che la sua + dimensione sia allineata a 64-bit, altrimenti la sua dimensione varierà su + sistemi a 32-bit e 64-bit. Avere una dimensione differente causa problemi + quando si passano vettori di strutture dati al kernel, o quando il kernel + effettua verifiche sulla dimensione (per esempio il sistema drm lo fa). + +* I puntatori sono di tipo ``__u64``, con un *cast* da/a ``uintptr_t`` da lato + spazio utente e da/a ``void __user *`` nello spazio kernel. Sforzatevi il più + possibile per non ritardare la conversione, o peggio maneggiare ``__u64`` nel + vostro codice perché questo riduce le verifiche che strumenti come sparse + possono effettuare. La macro u64_to_user_ptr() può essere usata nel kernel + per evitare avvisi riguardo interi e puntatori di dimensioni differenti. + + +Le Basi +------- + +Con la gioia d'aver evitato un livello di compatibilità, possiamo ora dare uno +sguardo alle basi. Trascurare questi punti renderà difficile la gestione della +compatibilità all'indietro ed in avanti. E dato che sbagliare al primo colpo è +garantito, dovrete rivisitare il codice o estenderlo per ogni interfaccia. + +* Abbiate un modo chiaro per capire dallo spazio utente se una nuova ioctl, o + l'estensione di una esistente, sia supportata dal kernel in esecuzione. Se non + potete fidarvi del fatto che un vecchio kernel possa rifiutare correttamente + un nuovo *flag*, modalità, o ioctl, (probabilmente perché avevate raffazzonato + qualcosa nel passato) allora dovrete implementare nel driver un meccanismo per + notificare quali funzionalità sono supportate, o in alternativa un numero di + versione. + +* Abbiate un piano per estendere le ioctl con nuovi *flag* o campi alla fine di + una struttura dati. Il sistema drm verifica la dimensione di ogni ioctl in + arrivo, ed estende con zeri ogni incongruenza fra kernel e spazio utente. + Questo aiuta, ma non è una soluzione completa dato che uno spazio utente nuovo + su un kernel vecchio non noterebbe che i campi nuovi alla fine della struttura + vengono ignorati. Dunque, anche questo avrà bisogno di essere notificato dal + driver allo spazio utente. + +* Verificate tutti i campi e *flag* inutilizzati ed i riempimenti siano a 0, + altrimenti rifiutare la ioctl. Se non lo fate il vostro bel piano per + estendere le ioctl andrà a rotoli dato che qualcuno userà delle ioctl con + strutture dati con valori casuali dallo stack nei campi inutilizzati. Il che + si traduce nell'avere questi campi nell'ABI, e la cui unica utilità sarà + quella di contenere spazzatura. Per questo dovrete esplicitamente riempire i + vuoti di tutte le vostre strutture dati, anche se non le userete in un + vettore. Il riempimento fatto dal compilatore potrebbe contenere valori + casuali. + +* Abbiate un semplice codice di test per ognuno dei casi sopracitati. + + +Divertirsi coi percorsi d'errore +-------------------------------- + +Oggigiorno non ci sono più scuse rimaste per permettere ai driver drm di essere +sfruttati per diventare root. Questo significa che dobbiamo avere una completa +validazione degli input e gestire in modo robusto i percorsi - tanto le GPU +moriranno comunque nel più strano dei casi particolari: + + * Le ioctl devono verificare l'overflow dei vettori. Inoltre, per i valori + interi si devono verificare *overflow*, *underflow*, e *clamping*. Il + classico esempio è l'inserimento direttamente nell'hardware di valori di + posizionamento di un'immagine *sprite* quando l'hardware supporta giusto 12 + bit, o qualcosa del genere. Tutto funzionerà finché qualche strano *display + server* non decide di preoccuparsi lui stesso del *clamping* e il cursore + farà il giro dello schermo. + + * Avere un test semplice per ogni possibile fallimento della vostra ioctl. + Verificate che il codice di errore rispetti le aspettative. Ed infine, + assicuratevi che verifichiate un solo percorso sbagliato per ogni sotto-test + inviando comunque dati corretti. Senza questo, verifiche precedenti + potrebbero rigettare la ioctl troppo presto, impedendo l'esecuzione del + codice che si voleva effettivamente verificare, rischiando quindi di + mascherare bachi e regressioni. + + * Fate si che tutte le vostre ioctl siano rieseguibili. Prima di tutto X adora + i segnali; secondo questo vi permetterà di verificare il 90% dei percorsi + d'errore interrompendo i vostri test con dei segnali. Grazie all'amore di X + per i segnali, otterrete gratuitamente un eccellente copertura di base per + tutti i vostri percorsi d'errore. Inoltre, siate consistenti sul modo di + gestire la riesecuzione delle ioctl - per esempio, drm ha una piccola + funzione di supporto `drmIoctl` nella sua librerie in spazio utente. Il + driver i915 l'abbozza con l'ioctl `set_tiling`, ed ora siamo inchiodati per + sempre con una semantica arcana sia nel kernel che nello spazio utente. + + + * Se non potete rendere un pezzo di codice rieseguibile, almeno rendete + possibile la sua interruzione. Le GPU moriranno e i vostri utenti non vi + apprezzeranno affatto se tenete in ostaggio il loro scatolotto (mediante un + processo X insopprimibile). Se anche recuperare lo stato è troppo complicato, + allora implementate una scadenza oppure come ultima spiaggia una rete di + sicurezza per rilevare situazioni di stallo quando l'hardware da di matto. + + * Preparate dei test riguardo ai casi particolarmente estremi nel codice di + recupero del sistema - è troppo facile create uno stallo fra il vostro codice + anti-stallo e un processo scrittore. + + +Tempi, attese e mancate scadenze +-------------------------------- + +Le GPU fanno quasi tutto in modo asincrono, dunque dobbiamo regolare le +operazioni ed attendere quelle in sospeso. Questo è davvero difficile; al +momento nessuna delle ioctl supportante dal driver drm/i915 riesce a farlo +perfettamente, il che significa che qui ci sono ancora una valanga di lezioni da +apprendere. + + * Per fare riferimento al tempo usate sempre ``CLOCK_MONOTONIC``. Oggigiorno + questo è quello che viene usato di base da alsa, drm, e v4l. Tuttavia, + lasciate allo spazio utente la possibilità di capire quali *timestamp* + derivano da domini temporali diversi come il vostro orologio di sistema + (fornito dal kernel) oppure un contatore hardware indipendente da qualche + parte. Gli orologi divergeranno, ma con questa informazione gli strumenti di + analisi delle prestazioni possono compensare il problema. Se il vostro spazio + utente può ottenere i valori grezzi degli orologi, allora considerate di + esporre anch'essi. + + * Per descrivere il tempo, usate ``__s64`` per i secondi e ``__u64`` per i + nanosecondi. Non è il modo migliore per specificare il tempo, ma è + praticamente uno standard. + + * Verificate che gli input di valori temporali siano normalizzati, e se non lo + sono scartateli. Fate attenzione perché la struttura dati ``struct ktime`` + del kernel usa interi con segni sia per i secondi che per i nanosecondi. + + * Per le scadenze (*timeout*) usate valori temporali assoluti. Se siete dei + bravi ragazzi e avete reso la vostra ioctl rieseguibile, allora i tempi + relativi tendono ad essere troppo grossolani e a causa degli arrotondamenti + potrebbero estendere in modo indefinito i tempi di attesa ad ogni + riesecuzione. Particolarmente vero se il vostro orologio di riferimento è + qualcosa di molto lento come il contatore di *frame*. Con la giacca da + avvocato delle specifiche diremmo che questo non è un baco perché tutte le + scadenze potrebbero essere estese - ma sicuramente gli utenti vi odieranno + quando le animazioni singhiozzano. + + * Considerate l'idea di eliminare tutte le ioctl sincrone con scadenze, e di + sostituirle con una versione asincrona il cui stato può essere consultato + attraverso il descrittore di file mediante ``poll``. Questo approccio si + sposa meglio in un applicazione guidata dagli eventi. + + * Sviluppate dei test per i casi estremi, specialmente verificate che i valori + di ritorno per gli eventi già completati, le attese terminate con successo, e + le attese scadute abbiano senso e servano ai vostri scopi. + + +Non perdere risorse +------------------- +Nel suo piccolo il driver drm implementa un sistema operativo specializzato per +certe GPU. Questo significa che il driver deve esporre verso lo spazio +utente tonnellate di agganci per accedere ad oggetti e altre risorse. Farlo +correttamente porterà con se alcune insidie: + + * Collegate sempre la vita di una risorsa creata dinamicamente, a quella del + descrittore di file. Considerate una mappatura 1:1 se la vostra risorsa + dev'essere condivisa fra processi - passarsi descrittori di file sul socket + unix semplifica la gestione anche per lo spazio utente. + + * Dev'esserci sempre Il supporto ``O_CLOEXEC``. + + * Assicuratevi di avere abbastanza isolamento fra utenti diversi. Di base + impostate uno spazio dei nomi riservato per ogni descrittore di file, il che + forzerà ogni condivisione ad essere esplicita. Usate uno spazio più globale + per dispositivo solo se gli oggetti sono effettivamente unici per quel + dispositivo. Un controesempio viene dall'interfaccia drm modeset, dove + oggetti specifici di dispositivo, come i connettori, condividono uno spazio + dei nomi con oggetti per il *framebuffer*, ma questi non sono per niente + condivisi. Uno spazio separato, privato di base, per i *framebuffer* sarebbe + stato meglio. + + * Pensate all'identificazione univoca degli agganci verso lo spazio utente. Per + esempio, per la maggior parte dei driver drm, si considera fallace la doppia + sottomissione di un oggetto allo stesso comando ioctl. Ma per evitarlo, se + gli oggetti sono condivisibili, lo spazio utente ha bisogno di sapere se il + driver ha importato un oggetto da un altro processo. Non l'ho ancora provato, + ma considerate l'idea di usare il numero di inode come identificatore per i + descrittori di file condivisi - che poi è come si distinguono i veri file. + Sfortunatamente, questo richiederebbe lo sviluppo di un vero e proprio + filesystem virtuale nel kernel. + + +Ultimo, ma non meno importante +------------------------------ + +Non tutti i problemi si risolvono con una nuova ioctl: + +* Pensateci su due o tre volte prima di implementare un'interfaccia privata per + un driver. Ovviamente è molto più veloce seguire questa via piuttosto che + buttarsi in lunghe discussioni alla ricerca di una soluzione più generica. Ed + a volte un'interfaccia privata è quello che serve per sviluppare un nuovo + concetto. Ma alla fine, una volta che c'è un'interfaccia generica a + disposizione finirete per mantenere due interfacce. Per sempre. + +* Considerate interfacce alternative alle ioctl. Gli attributi sysfs sono molto + meglio per impostazioni che sono specifiche di un dispositivo, o per + sotto-oggetti con una vita piuttosto statica (come le uscite dei connettori in + drm con tutti gli attributi per la sovrascrittura delle rilevazioni). O magari + solo il vostro sistema di test ha bisogno di una certa interfaccia, e allora + debugfs (che non ha un'interfaccia stabile) sarà la soluzione migliore. + +Per concludere. Questo gioco consiste nel fare le cose giuste fin da subito, +dato che se il vostro driver diventa popolare e la piattaforma hardware longeva +finirete per mantenere le vostre ioctl per sempre. Potrete tentare di deprecare +alcune orribili ioctl, ma ci vorranno anni per riuscirci effettivamente. E +ancora, altri anni prima che sparisca l'ultimo utente capace di lamentarsi per +una regressione. diff --git a/Documentation/translations/it_IT/process/changes.rst b/Documentation/translations/it_IT/process/changes.rst index 10e0ef9c34b7..473ec2cc558e 100644 --- a/Documentation/translations/it_IT/process/changes.rst +++ b/Documentation/translations/it_IT/process/changes.rst @@ -35,6 +35,7 @@ PC Card, per esempio, probabilmente non dovreste preoccuparvi di pcmciautils. 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 flex 2.5.35 flex --version bison 2.0 bison --version @@ -88,6 +89,11 @@ Make Per compilare il kernel vi servirà GNU make 3.81 o successivo. +Bash +---- +Per generare il kernel vengono usati alcuni script per bash. +Questo richiede bash 4.2 o successivo. + Binutils -------- @@ -370,6 +376,11 @@ Make - <ftp://ftp.gnu.org/gnu/make/> +Bash +---- + +- <ftp://ftp.gnu.org/gnu/bash/> + Binutils -------- diff --git a/Documentation/translations/it_IT/process/email-clients.rst b/Documentation/translations/it_IT/process/email-clients.rst index de7d32f78246..970671cd91af 100644 --- a/Documentation/translations/it_IT/process/email-clients.rst +++ b/Documentation/translations/it_IT/process/email-clients.rst @@ -106,7 +106,7 @@ Funziona. Alcune persone riescono ad usarlo con successo per inviare le patch. Per inserire una patch usate :menuselection:`Messaggio-->Inserisci file` (:kbd:`CTRL-I`) oppure un editor esterno. -Se la patch che avete inserito dev'essere modificata usato la finestra di +Se la patch che avete inserito dev'essere modificata usando la finestra di scrittura di Claws, allora assicuratevi che l'"auto-interruzione" sia disabilitata :menuselection:`Configurazione-->Preferenze-->Composizione-->Interruzione riga`. @@ -288,37 +288,62 @@ Thunderbird (GUI) Thunderbird è un clone di Outlook a cui piace maciullare il testo, ma esistono modi per impedirglielo. +Dopo la configurazione, inclusa l'installazione delle estenzioni, dovrete +riavviare Thunderbird. + - permettere l'uso di editor esterni: + La cosa più semplice da fare con Thunderbird e le patch è quello di usare - l'estensione "external editor" e di usare il vostro ``$EDITOR`` preferito per - leggere/includere patch nel vostro messaggio. Per farlo, scaricate ed - installate l'estensione e aggiungete un bottone per chiamarla rapidamente - usando :menuselection:`Visualizza-->Barra degli strumenti-->Personalizza...`; - una volta fatto potrete richiamarlo premendo sul bottone mentre siete nella - finestra :menuselection:`Scrivi` - - Tenete presente che "external editor" richiede che il vostro editor non - faccia alcun fork, in altre parole, l'editor non deve ritornare prima di - essere stato chiuso. Potreste dover passare dei parametri aggiuntivi al - vostro editor oppure cambiargli la configurazione. Per esempio, usando - gvim dovrete aggiungere l'opzione -f ``/usr/bin/gvim -f`` (Se il binario - si trova in ``/usr/bin``) nell'apposito campo nell'interfaccia di - configurazione di :menuselection:`external editor`. Se usate altri editor - consultate il loro manuale per sapere come configurarli. + estensioni che permettano di aprire il vostro editor preferito. + + Di seguito alcune estensioni che possono essere utili al caso. + + - "External Editor Revived" + + https://github.com/Frederick888/external-editor-revived + + https://addons.thunderbird.net/en-GB/thunderbird/addon/external-editor-revived/ + + L'estensione richiede l'installazione di "native messaging host". Date + un'occhiata alla seguente wiki: + https://github.com/Frederick888/external-editor-revived/wiki + + - "External Editor" + + https://github.com/exteditor/exteditor + + Per usarlo, scaricate ed installate l'applicazione. Poi aprite la finestra + :menuselection:`Scrivi` e a seguire aggiungete un bottone per eseguirlo + `Visualizza-->Barra degli strumenti-->Personalizza...`. Infine, premente + questo nuovo bottone tutte le volte che volete usare l'editor esterno. + + Tenete presente che "external editor" richiede che il vostro editor non + faccia alcun fork, in altre parole, l'editor non deve ritornare prima di + essere stato chiuso. Potreste dover passare dei parametri aggiuntivi al + vostro editor oppure cambiargli la configurazione. Per esempio, usando + gvim dovrete aggiungere l'opzione -f ``/usr/bin/gvim -f`` (Se il binario + si trova in ``/usr/bin``) nell'apposito campo nell'interfaccia di + configurazione di :menuselection:`external editor`. Se usate altri editor + consultate il loro manuale per sapere come configurarli.``)`` Per rendere l'editor interno un po' più sensato, fate così: -- Modificate le impostazioni di Thunderbird per far si che non usi - ``format=flowed``. Andate in :menuselection:`Modifica-->Preferenze-->Avanzate-->Editor di configurazione` +- Modificate le impostazioni di Thunderbird per far si che non usi ``format=flowed``! + Andate sulla finestra principale e cercate il bottone per il menu a tendina principale. + Poi :menuselection:`Modifica-->Preferenze-->Avanzate-->Editor di configurazione` per invocare il registro delle impostazioni. -- impostate ``mailnews.send_plaintext_flowed`` a ``false`` + - impostate ``mailnews.send_plaintext_flowed`` a ``false`` -- impostate ``mailnews.wraplength`` da ``72`` a ``0`` + - impostate ``mailnews.wraplength`` da ``72`` a ``0`` -- :menuselection:`Visualizza-->Corpo del messaggio come-->Testo semplice` +- Non scrivete messaggi HTML! Andate sulla finestra principale ed aprite la + schermata :menuselection:`Menu principale-->Impostazioni account-->nome@unserver.ovunque-->Composizioni e indirizzi`. + Qui potrete disabilitare l'opzione "Componi i messaggi in HTML" -- :menuselection:`Visualizza-->Codifica del testo-->Unicode` +- Aprite i messaggi solo in formato testo! Andate sulla finestra principale e + selezionate + :menuselection:`Menu principale-->Visualizza-->Copro del messaggio come-->Testo semplice` TkRat (GUI) diff --git a/Documentation/translations/it_IT/process/index.rst b/Documentation/translations/it_IT/process/index.rst index 8d4e36a07ff4..25602c1a97d1 100644 --- a/Documentation/translations/it_IT/process/index.rst +++ b/Documentation/translations/it_IT/process/index.rst @@ -58,6 +58,7 @@ perché non si è trovato un posto migliore. adding-syscalls magic-number volatile-considered-harmful + botching-up-ioctls clang-format ../riscv/patch-acceptance diff --git a/Documentation/translations/it_IT/process/kernel-docs.rst b/Documentation/translations/it_IT/process/kernel-docs.rst index 38e0a955121a..eadcbf50a1b5 100644 --- a/Documentation/translations/it_IT/process/kernel-docs.rst +++ b/Documentation/translations/it_IT/process/kernel-docs.rst @@ -6,8 +6,8 @@ .. _it_kernel_docs: -Indice di documenti per le persone interessate a capire e/o scrivere per il kernel Linux -======================================================================================== +Ulteriore Documentazione Del Kernel Linux +========================================= .. note:: Questo documento contiene riferimenti a documenti in lingua inglese; inoltre diff --git a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst index a1e98ec9532e..5526bcabeb0a 100644 --- a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst +++ b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst @@ -163,7 +163,7 @@ 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 fesa di creazione, assegniamo limitazioni funzionali ad ogni chiave +2. In fase di creazione, assegniamo limitazioni funzionali ad ogni chiave assegnando capacità specifiche. 3. Una chiave PGP può avere 4 capacità: @@ -286,9 +286,7 @@ magari in una cassetta di sicurezza in banca. Probabilmente la vostra stampante non è più quello stupido dispositivo connesso alla porta parallela, ma dato che il suo output è comunque criptato con la passphrase, eseguire la stampa in un sistema "cloud" - moderno dovrebbe essere comunque relativamente sicuro. Un'opzione potrebbe - essere quella di cambiare la passphrase della vostra chiave primaria - subito dopo aver finito con paperkey. + moderno dovrebbe essere comunque relativamente sicuro. Copia di riserva di tutta la cartella GnuPG ------------------------------------------- diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst index a3bb0008837a..c2cfa0948b2b 100644 --- a/Documentation/translations/it_IT/process/submitting-patches.rst +++ b/Documentation/translations/it_IT/process/submitting-patches.rst @@ -340,7 +340,7 @@ Assicuratevi di dire ai revisori quali cambiamenti state facendo e di ringraziarli per il loro tempo. Revisionare codice è un lavoro faticoso e che richiede molto tempo, e a volte i revisori diventano burberi. Tuttavia, anche in questo caso, rispondete con educazione e concentratevi sul problema che hanno -evidenziato. Quando inviate una version successiva ricordatevi di aggiungere un +evidenziato. Quando inviate una versione successiva ricordatevi di aggiungere un ``patch changelog`` alla email di intestazione o ad ogni singola patch spiegando le differenze rispetto a sottomissioni precedenti (vedere :ref:`it_the_canonical_patch_format`). diff --git a/Documentation/translations/sp_SP/process/code-of-conduct.rst b/Documentation/translations/sp_SP/process/code-of-conduct.rst new file mode 100644 index 000000000000..adc6c770cc37 --- /dev/null +++ b/Documentation/translations/sp_SP/process/code-of-conduct.rst @@ -0,0 +1,97 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/code-of-conduct.rst <code_of_conduct>` +:Translator: Contributor Covenant and Carlos Bilbao <carlos.bilbao@amd.com> + +.. _sp_code_of_conduct: + +Código de Conducta para Contribuyentes ++++++++++++++++++++++++++++++++++++++++ + +Nuestro Compromiso +================== + +Nosotros, como miembros, contribuyentes y administradores nos comprometemos +a hacer de la participación en nuestra comunidad una experiencia libre de +acoso para todo el mundo, independientemente de la edad, dimensión corporal, +minusvalía visible o invisible, etnicidad, características sexuales, +identidad y expresión de género, nivel de experiencia, educación, nivel +socio-económico, nacionalidad, apariencia personal, raza, religión, o +identidad u orientación sexual. Nos comprometemos a actuar e interactuar de +maneras que contribuyan a una comunidad abierta, acogedora, diversa, +inclusiva y sana. + +Nuestros Estándares +=================== + +Ejemplos de comportamiento que contribuyen a crear un ambiente positivo +para nuestra comunidad: + +* Demostrar empatía y amabilidad ante otras personas +* Respeto a diferentes opiniones, puntos de vista y experiencias +* Dar y aceptar adecuadamente retroalimentación constructiva +* Aceptar la responsabilidad y disculparse ante quienes se vean afectados + por nuestros errores, aprendiendo de la experiencia +* Centrarse en lo que sea mejor no sólo para nosotros como individuos, sino + para la comunidad en general + + +Ejemplos de comportamiento inaceptable: + +* El uso de lenguaje o imágenes sexualizadas, y aproximaciones o + atenciones sexuales de cualquier tipo +* Comentarios despectivos (trolling), insultantes o derogatorios, y ataques + personales o políticos +* El acoso en público o privado +* Publicar información privada de otras personas, tales como direcciones + físicas o de correo + electrónico, sin su permiso explícito +* Otras conductas que puedan ser razonablemente consideradas como + inapropiadas en un entorno profesional + + +Aplicación de las responsabilidades +=================================== + +Los administradores de la comunidad son responsables de aclarar y hacer +cumplir nuestros estándares de comportamiento aceptable y tomarán acciones +apropiadas y correctivas de forma justa en respuesta a cualquier +comportamiento que consideren inapropiado, amenazante, ofensivo o dañino. + +Los administradores de la comunidad tendrán el derecho y la responsabilidad +de eliminar, editar o rechazar comentarios, commits, código, ediciones de +páginas de wiki, issues y otras contribuciones que no se alineen con este +Código de Conducta, y comunicarán las razones para sus decisiones de +moderación cuando sea apropiado. + +Alcance +======= + +Este código de conducta aplica tanto a espacios del proyecto como a +espacios públicos donde un individuo esté en representación del proyecto o +comunidad. Ejemplos de esto incluyen el uso de la cuenta oficial de correo +electrónico, publicaciones a través de las redes sociales oficiales, o +presentaciones con personas designadas en eventos en línea o no. + +Aplicación +========== + +Instancias de comportamiento abusivo, acosador o inaceptable de otro modo +podrán ser reportadas contactando el Code of Conduct Commitee a través de +<conduct@kernel.org>. Todas las quejas serán evaluadas e investigadas de +una manera puntual y justa. El Code of Condut Commitee está obligados a +respetar la privacidad y la seguridad de quienes reporten incidentes. +Detalles de políticas y aplicación en particular, serán incluidos por +separado. + +Atribución +========== + +Este Código de Conducta es una adaptación del Contributor Covenant, versión +1.4, disponible en https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +Interpretación +============== + +Consulte el documento :ref:`code_of_conduct_interpretation` para ver cómo +interpretará la comunidad del kernel Linux este documento. diff --git a/Documentation/translations/sp_SP/process/email-clients.rst b/Documentation/translations/sp_SP/process/email-clients.rst new file mode 100644 index 000000000000..fdf1e51b84e4 --- /dev/null +++ b/Documentation/translations/sp_SP/process/email-clients.rst @@ -0,0 +1,374 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/email-clients.rst <email_clients>` +:Translator: Carlos Bilbao <carlos.bilbao@amd.com> + +.. _sp_email_clients: + +Información de clientes de correo electrónico para Linux +======================================================== + +Git +--- + +A día de hoy, la mayoría de los desarrolladores usan ``git send-email`` en +lugar de los clientes de correo electrónico normales. La página de manual +para esto es bastante buena. En la recepción del correo, los maintainers +usan ``git am`` para aplicar los parches. + +Si es usted nuevo en ``git`` entonces envíese su primer parche. Guárdelo +como texto sin formato, incluidos todos los encabezados. Ejecute ``git am raw_email.txt`` +y luego revise el registro de cambios con ``git log``. Cuando eso funcione, +envíe el parche a la(s) lista(s) de correo apropiada(s). + +Preferencias Generales +---------------------- + +Los parches para el kernel de Linux se envían por correo electrónico, +preferiblemente como texto en línea en el cuerpo del correo electrónico. +Algunos maintainers aceptan archivos adjuntos, pero entonces los archivos +adjuntos deben tener tipo de contenido ``text/plain``. Sin embargo, los +archivos adjuntos generalmente están mal vistos porque hacen que citar +partes del parche sea más difícil durante el proceso de revisión del +parche. + +También se recomienda encarecidamente que utilice texto sin formato en el +cuerpo del correo electrónico, para parches y otros correos electrónicos +por igual. https://useplaintext.email puede ser útil para obtener +información sobre cómo configurar su cliente de correo electrónico +preferido, así como una lista de clientes de correo electrónico +recomendados si aún no tiene una preferencia. + +Los clientes de correo electrónico que se utilizan para los parches del +kernel Linux deben enviar el texto del parche intacto. Por ejemplo, no +deben modificar ni eliminar pestañas o espacios, incluso al principio o al +final de las líneas. + +No envíe parches con ``format=flowed``. Esto puede causar saltos de línea +no deseados e inesperados. + +No deje que su cliente de correo electrónico ajuste automáticamente las +palabras por usted. Esto también puede corromper su parche. + +Los clientes de correo electrónico no deben modificar la codificación del +de caracteres del texto. Los parches enviados por correo electrónico deben +estar en codificación ASCII o UTF-8 únicamente. Si configura su cliente de +correo electrónico para enviar correos electrónicos con codificación UTF-8, +evite algunos posibles problemas con los caracteres. + +Los clientes de correo electrónico deben generar y mantener los +encabezados "References:" o "In-Reply-To:" para que el hilo de correo no +se rompa. + +Copiar y pegar (o cortar y pegar) generalmente no funciona para los +parches, porque las tabulaciones se convierten en espacios. Utilizar +xclipboard, xclip y/o xcutsel puede funcionar, pero es mejor probarlo usted +mismo o simplemente evitar copiar y pegar. + +No utilice firmas PGP/GPG en el correo que contiene parches. +Esto rompe muchos scripts que leen y aplican los parches. +(Esto debería ser reparable.) + +Es una buena idea enviarse un parche a sí mismo, guardar el mensaje +recibido, y aplicarlo con éxito con 'patch' antes de enviar el parche a las +listas de correo de Linux. + +Algunas sugerencias para el cliente de correo electrónico (MUA) +--------------------------------------------------------------- + +Aquí hay algunos consejos específicos de configuración de MUA para editar y +enviar parches para el kernel de Linux. Estos no pretenden cubrir todo +detalle de configuración de los paquetes de software. + +Leyenda: + +- TUI = text-based user interface (interfaz de usuario basada en texto) +- GUI = graphical user interface (interfaz de usuario gráfica) + +Alpine (TUI) +************ + +Opciones de configuración: + +En la sección :menuselection:`Sending Preferences`: + +- :menuselection: `Do Not Send Flowed Text` debe estar ``enabled`` +- :menuselection:`Strip Whitespace Before Sending` debe estar ``disabled`` + +Al redactar el mensaje, el cursor debe colocarse donde el parche debería +aparecer, y luego presionando :kbd:`CTRL-R` se le permite especificar e +archivo de parche a insertar en el mensaje. + +Claws Mail (GUI) +**************** + +Funciona. Algunos usan esto con éxito para los parches. + +Para insertar un parche haga :menuselection:`Message-->Insert File` (:kbd:`CTRL-I`) +o use un editor externo. + +Si el parche insertado debe editarse en la ventana de composición de Claws +"Auto wrapping" en +:menuselection:`Configuration-->Preferences-->Compose-->Wrapping` debe +permanecer deshabilitado. + +Evolution (GUI) +*************** + +Algunos usan esto con éxito para sus parches. + +Cuando escriba un correo seleccione: Preformat + desde :menuselection:`Format-->Paragraph Style-->Preformatted` (:kbd:`CTRL-7`) + o en la barra de herramientas + +Luego haga: +:menuselection:`Insert-->Text File...` (:kbd:`ALT-N x`) +para insertar el parche. + +También puede hacer ``diff -Nru old.c new.c | xclip``, seleccione +:menuselection:`Preformat`, luego pege con el boton del medio. + +Kmail (GUI) +*********** + +Algunos usan Kmail con éxito para los parches. + +La configuración predeterminada de no redactar en HTML es adecuada; no haga +cambios en esto. + +Al redactar un correo electrónico, en las opciones, desmarque "word wrap". +La única desventaja es que cualquier texto que escriba en el correo +electrónico no se ajustará a cada palabra, por lo que tendrá que ajustar +manualmente el texto antes del parche. La forma más fácil de evitar esto es +redactar su correo electrónico con Word Wrap habilitado, luego guardar +como borrador. Una vez que lo vuelva a sacar de sus borradores, estará +envuelto por palabras y puede desmarcar "word wrap" sin perder el existente +texto. + +En la parte inferior de su correo electrónico, coloque el delimitador de +parche de uso común antes de insertar su parche: tres guiones (``---``). + +Luego desde la opción de menu :menuselection:`Message` seleccione +:menuselection:`insert file` y busque su parche. +De forma adicional, puede personalizar el menú de la barra de herramientas +de creación de mensajes y poner el icono :menuselection:`insert file`. + +Haga que la ventana del editor sea lo suficientemente ancha para que no se +envuelva ninguna línea. A partir de KMail 1.13.5 (KDE 4.5.4), KMail +aplicará ajuste de texto al enviar el correo electrónico si las líneas se +ajustan en la ventana del redactor. Tener ajuste de palabras deshabilitado +en el menú Opciones no es suficiente. Por lo tanto, si su parche tiene +líneas muy largas, debe hacer que la ventana del redactor sea muy amplia +antes de enviar el correo electrónico. Consulte: https://bugs.kde.org/show_bug.cgi?id=174034 + +You can safely GPG sign attachments, but inlined text is preferred for +patches so do not GPG sign them. Signing patches that have been inserted +as inlined text will make them tricky to extract from their 7-bit encoding. + +Puede firmar archivos adjuntos con GPG de forma segura, pero se prefiere el +texto en línea para parches, así que no los firme con GPG. Firmar parches +que se han insertado como texto en línea hará que sea difícil extraerlos de +su codificación de 7 bits. + +Si es absolutamente necesario enviar parches como archivos adjuntos en +lugar de como texto en línea, haga clic con el botón derecho en el archivo +adjunto y seleccione :menuselection:`properties`, y luego +:menuselection:`Suggest automatic display` para hacer que el archivo +adjunto esté en línea para que sea más visible. + +Al guardar parches que se envían como texto en línea, seleccione el correo +electrónico que contiene el parche del panel de la lista de mensajes, haga +clic con el botón derecho y seleccione :menuselection:`save as`. Puede usar +todo el correo electrónico sin modificar como un parche de estar bien +compuesto. Los correos electrónicos se guardan como lectura y escritura +solo para el usuario, por lo que tendrá que cambiarlos para que sean +legibles en grupo y en todo el mundo si copia estos en otro lugar. + +Notas de Lotus (GUI) +******************** + +Huya de este. + +IBM Verse (Web GUI) +******************* + +Vea notas sobre Lotus. + +Mutt (TUI) +********** + +Muchos desarrolladores de Linux usan ``mutt``, por lo que debe funcionar +bastante bien. + +Mutt no viene con un editor, por lo que cualquier editor que use debe ser +utilizado de forma que no haya saltos de línea automáticos. La mayoría de +los editores tienen una opción :menuselection:`insert file` que inserta el +contenido de un archivo inalterado. + +Para usar ``vim`` con mutt:: + + set editor="vi" + +Si utiliza xclip, escriba el comando:: + + :set paste + +antes del boton del medio o shift-insert o use:: + + :r filename + +si desea incluir el parche en línea. +(a)ttach (adjuntar) funciona bien sin ``set paste``. + +También puedes generar parches con ``git format-patch`` y luego usar Mutt +para enviarlos:: + + $ mutt -H 0001-some-bug-fix.patch + +Opciones de configuración: + +Debería funcionar con la configuración predeterminada. +Sin embargo, es una buena idea establecer ``send_charset`` en: + + set send_charset="us-ascii:utf-8" + +Mutt es altamente personalizable. Aquí tiene una configuración mínima para +empezar a usar Mutt para enviar parches a través de Gmail:: + + # .muttrc + # ================ IMAP ==================== + set imap_user = 'suusuario@gmail.com' + set imap_pass = 'sucontraseña' + set spoolfile = imaps://imap.gmail.com/INBOX + set folder = imaps://imap.gmail.com/ + set record="imaps://imap.gmail.com/[Gmail]/Sent Mail" + set postponed="imaps://imap.gmail.com/[Gmail]/Drafts" + set mbox="imaps://imap.gmail.com/[Gmail]/All Mail" + + # ================ SMTP ==================== + set smtp_url = "smtp://username@smtp.gmail.com:587/" + set smtp_pass = $imap_pass + set ssl_force_tls = yes # Requerir conexión encriptada + + # ================ Composición ==================== + set editor = `echo \$EDITOR` + set edit_headers = yes # Ver los encabezados al editar + set charset = UTF-8 # valor de $LANG; also fallback for send_charset + # El remitente, la dirección de correo electrónico y la línea de firma deben coincidir + unset use_domain # Porque joe@localhost es simplemente vergonzoso + set realname = "SU NOMBRE" + set from = "username@gmail.com" + set use_from = yes + +Los documentos Mutt tienen mucha más información: + + https://gitlab.com/muttmua/mutt/-/wikis/UseCases/Gmail + + http://www.mutt.org/doc/manual/ + +Pine (TUI) +********** + +Pine ha tenido algunos problemas de truncamiento de espacios en blanco en +el pasado, pero estos todo debería estar arreglados ahora. + +Use alpine (sucesor de pino) si puede. + +Opciones de configuración: + +- ``quell-flowed-text`` necesitado para versiones actuales +- la opción ``no-strip-whitespace-before-send`` es necesaria + + +Sylpheed (GUI) +************** + +- Funciona bien para insertar texto (o usar archivos adjuntos). +- Permite el uso de un editor externo. +- Es lento en carpetas grandes. +- No realizará la autenticación TLS SMTP en una conexión que no sea SSL. +- Tiene una útil barra de reglas en la ventana de redacción. +- Agregar direcciones a la libreta de direcciones no las muestra + adecuadamente. + +Thunderbird (GUI) +***************** + +Thunderbird es un clon de Outlook al que le gusta alterar el texto, pero +hay formas para obligarlo a comportarse. + +Después de hacer las modificaciones, que incluye instalar las extensiones, +necesita reiniciar Thunderbird. + +- Permitir el uso de un editor externo: + + Lo más fácil de hacer con Thunderbird y los parches es usar extensiones + que abran su editor externo favorito. + + Aquí hay algunas extensiones de ejemplo que son capaces de hacer esto. + + - "External Editor Revived" + + https://github.com/Frederick888/external-editor-revived + + https://addons.thunderbird.net/en-GB/thunderbird/addon/external-editor-revived/ + + Requiere instalar un "native messaging host". + Por favor, lea la wiki que se puede encontrar aquí: + https://github.com/Frederick888/external-editor-revived/wiki + + - "External Editor" + + https://github.com/exteditor/exteditor + + Para hacer esto, descargue e instale la extensión, luego abra la ventana + :menuselection:`compose`, agregue un botón para ello usando + :menuselection:`View-->Toolbars-->Customize...` + luego simplemente haga clic en el botón nuevo cuando desee usar el editor + externo. + + Tenga en cuenta que "External Editor" requiere que su editor no haga + fork, o en otras palabras, el editor no debe regresar antes de cerrar. + Es posible que deba pasar flags adicionales o cambiar la configuración + de su editor. En particular, si está utilizando gvim, debe pasar la + opción -f a gvim poniendo ``/usr/bin/gvim --nofork"`` (si el binario + está en ``/usr/bin``) al campo del editor de texto en los ajustes + :menuselection:`external editor`. Si está utilizando algún otro editor, + lea su manual para saber cómo hacer esto. + +Para sacarle algo de sentido al editor interno, haga esto: + +- Edite sus ajustes de configuración de Thunderbird para que no utilice ``format=flowed``! + Vaya a su ventana principal y busque el botón de su menú desplegable principal. + :menuselection:`Main Menu-->Preferences-->General-->Config Editor...` + para abrir el editor de registro de Thunderbird. + + - Seleccione ``mailnews.send_plaintext_flowed`` como ``false`` + + - Seleccione ``mailnews.wraplength`` de ``72`` a ``0`` + +- ¡No escriba mensajes HTML! Acuda a la ventana principal + :menuselection:`Main Menu-->Account Settings-->youracc@server.something-->Composition & Addressing`! + Ahí puede deshabilitar la opción "Compose messages in HTML format". + +- ¡Abra mensajes solo como texto sin formato! Acuda a la ventana principal + :menuselection:`Main Menu-->View-->Message Body As-->Plain Text`! + +TkRat (GUI) +*********** + +Funciona. Utilice "Insert file..." o un editor externo. + +Gmail (Web GUI) +*************** + +No funciona para enviar parches. + +El cliente web de Gmail convierte las tabulaciones en espacios automáticamente. + +Al mismo tiempo, envuelve líneas cada 78 caracteres con saltos de línea de +estilo CRLF aunque el problema de tab2space se puede resolver con un editor +externo. + +Otro problema es que Gmail codificará en base64 cualquier mensaje que tenga +un carácter no ASCII. Eso incluye cosas como nombres europeos. diff --git a/Documentation/translations/sp_SP/process/index.rst b/Documentation/translations/sp_SP/process/index.rst index 49a05f6a5544..c978a8132ce1 100644 --- a/Documentation/translations/sp_SP/process/index.rst +++ b/Documentation/translations/sp_SP/process/index.rst @@ -13,3 +13,7 @@ submitting-patches kernel-docs coding-style + code-of-conduct + kernel-enforcement-statement + email-clients + magic-number diff --git a/Documentation/translations/sp_SP/process/kernel-enforcement-statement.rst b/Documentation/translations/sp_SP/process/kernel-enforcement-statement.rst new file mode 100644 index 000000000000..d66902694089 --- /dev/null +++ b/Documentation/translations/sp_SP/process/kernel-enforcement-statement.rst @@ -0,0 +1,174 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/kernel-enforcement-statement.rst <process_statement_kernel>` +:Translator: Carlos Bilbao <carlos.bilbao@amd.com> + +.. _sp_process_statement_kernel: + +Aplicación de la licencia en el kernel Linux +============================================ + +Como desarrolladores del kernel Linux, tenemos un gran interés en cómo se +se utiliza nuestro software y cómo se aplica la licencia de nuestro software. +El cumplimiento de las obligaciones de intercambio recíproco de GPL-2.0 son +fundamentales en el largo plazo para la sostenibilidad de nuestro software +y comunidad. + +Aunque existe el derecho de hacer valer un copyright distinto en las +contribuciones hechas a nuestra comunidad, compartimos el interés de +asegurar que las acciones individuales para proteger estos se lleven a cabo +de una manera que beneficia a nuestra comunidad y no tenga un indeseado +impacto negativo en la salud y crecimiento de nuestro ecosistema de software. +Con el fin de disuadir la aplicación inútil de acciones, estamos de acuerdo +en que es en el mejor interés de nuestro desarrollo como comunidad asumir +el siguiente compromiso con los usuarios del kernel Linux, en nombre +nuestro y de cualquier sucesor de nuestros derechos de autor (copyright): + + Sin perjuicio de las disposiciones de terminación de GPL-2.0, aceptamos + que es en el mejor interés de nuestra comunidad de desarrollo adoptar + las siguientes disposiciones de GPL-3.0 como permisos adicionales bajo + nuestra licencia, con respecto a cualquier interposición de alegación + de infringimiento (en inglés, "non-defensive assertion") de los + derechos bajo la licencia. + + Sin embargo, si deja de violar esta Licencia, entonces su licencia + de copyright como particular se restablece (a) provisionalmente, + a menos que y hasta que el titular de los derechos de autor explícita + y finalmente rescinda su licencia, y (b) de forma permanente, si el + titular de los derechos de autor no le notifica la violación por algún + medio razonable antes de 60 días después del cese. + + Además, su licencia de un titular de derechos de autor en particular es + restablecida permanentemente si el titular de los derechos de autor le + notifica de la violación por algún medio razonable, esta es la primera + vez que ha recibido notificación de violación de esta Licencia (para + cualquier trabajo) de ese titular de los derechos de autor, y subsana + la infracción antes de los 30 días posteriores de recibir el aviso. + +Nuestra intención al proporcionar estas garantías es fomentar un mayor uso +del software. Queremos que empresas y particulares utilicen, modifiquen y +distribuyan este software. Queremos trabajar con los usuarios de forma +abierta y transparente para eliminar cualquier incertidumbre sobre nuestras +expectativas con respecto al cumplimiento que podría limitar la adopción de +nuestro software. Entendemos la acción legal como último recurso, que se +iniciará solo cuando otros esfuerzos de la comunidad no hayan podido +resolver el problema. + +Finalmente, una vez que se resuelva un problema de incumplimiento, +esperamos que el usuario se sienta bienvenido a unirse a nosotros en +nuestros esfuerzos con este proyecto. Trabajando juntos, somos más fuertes. + +Excepto donde se indica a continuación, hablamos solo por nosotros mismos y +no por ninguna compañía donde puede que trabajemos hoy, o hayamos trabajado +en el pasado, o trabajaremos en el futuro. + +- Laura Abbott +- Bjorn Andersson (Linaro) +- Andrea Arcangeli +- Neil Armstrong +- Jens Axboe +- Pablo Neira Ayuso +- Khalid Aziz +- Ralf Baechle +- Felipe Balbi +- Arnd Bergmann +- Ard Biesheuvel +- Tim Bird +- Paolo Bonzini +- Christian Borntraeger +- Mark Brown (Linaro) +- Paul Burton +- Javier Martinez Canillas +- Rob Clark +- Kees Cook (Google) +- Jonathan Corbet +- Dennis Dalessandro +- Vivien Didelot (Savoir-faire Linux) +- Hans de Goede +- Mel Gorman (SUSE) +- Sven Eckelmann +- Alex Elder (Linaro) +- Fabio Estevam +- Larry Finger +- Bhumika Goyal +- Andy Gross +- Juergen Gross +- Shawn Guo +- Ulf Hansson +- Stephen Hemminger (Microsoft) +- Tejun Heo +- Rob Herring +- Masami Hiramatsu +- Michal Hocko +- Simon Horman +- Johan Hovold (Hovold Consulting AB) +- Christophe JAILLET +- Olof Johansson +- Lee Jones (Linaro) +- Heiner Kallweit +- Srinivas Kandagatla +- Jan Kara +- Shuah Khan (Samsung) +- David Kershner +- Jaegeuk Kim +- Namhyung Kim +- Colin Ian King +- Jeff Kirsher +- Greg Kroah-Hartman (Linux Foundation) +- Christian König +- Vinod Koul +- Krzysztof Kozlowski +- Viresh Kumar +- Aneesh Kumar K.V +- Julia Lawall +- Doug Ledford +- Chuck Lever (Oracle) +- Daniel Lezcano +- Shaohua Li +- Xin Long +- Tony Luck +- Catalin Marinas (Arm Ltd) +- Mike Marshall +- Chris Mason +- Paul E. McKenney +- Arnaldo Carvalho de Melo +- David S. Miller +- Ingo Molnar +- Kuninori Morimoto +- Trond Myklebust +- Martin K. Petersen (Oracle) +- Borislav Petkov +- Jiri Pirko +- Josh Poimboeuf +- Sebastian Reichel (Collabora) +- Guenter Roeck +- Joerg Roedel +- Leon Romanovsky +- Steven Rostedt (VMware) +- Frank Rowand +- Ivan Safonov +- Anna Schumaker +- Jes Sorensen +- K.Y. Srinivasan +- David Sterba (SUSE) +- Heiko Stuebner +- Jiri Kosina (SUSE) +- Willy Tarreau +- Dmitry Torokhov +- Linus Torvalds +- Thierry Reding +- Rik van Riel +- Luis R. Rodriguez +- Geert Uytterhoeven (Glider bvba) +- Eduardo Valentin (Amazon.com) +- Daniel Vetter +- Linus Walleij +- Richard Weinberger +- Dan Williams +- Rafael J. Wysocki +- Arvind Yadav +- Masahiro Yamada +- Wei Yongjun +- Lv Zheng +- Marc Zyngier (Arm Ltd) + diff --git a/Documentation/translations/sp_SP/process/magic-number.rst b/Documentation/translations/sp_SP/process/magic-number.rst new file mode 100644 index 000000000000..2b62cec34e8e --- /dev/null +++ b/Documentation/translations/sp_SP/process/magic-number.rst @@ -0,0 +1,90 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/magic-number.rst <magicnumbers>` +:Translator: Carlos Bilbao <carlos.bilbao@amd.com> + +.. _sp_magicnumbers: + +Números mágicos de Linux +======================== + +Este archivo es un registro de los números mágicos que están en uso. Cuando +usted incluya un número mágico a una estructura, también debe agregarlo a +este documento, ya que es mejor si los números mágicos utilizados por +varias estructuras son únicos. + +Es una muy buena idea proteger las estructuras de datos del kernel con +números mágicos. Esto le permite verificar en tiempo de ejecución si (a) +una estructura ha sido manipulada, o (b) ha pasado la estructura incorrecta +a una rutina. Esto último es especialmente útil --- particularmente cuando +pasa punteros a estructuras a través de un puntero void \*. El código tty, +por ejemplo, hace esto con frecuencia para pasar información específica del +driver y líneas de estructuras específicas de protocolo de un lado al +otro. + +La forma de usar números mágicos es declararlos al principio de la +estructura, así:: + + struct tty_ldisc { + int magic; + ... + }; + +Por favor, siga este método cuando agregue futuras mejoras al kernel! Me ha +ahorrado innumerables horas de depuración, especialmente en los casos +complicados donde una matriz ha sido invadida y las estructuras que siguen +a la matriz se han sobrescrito. Usando este método, estos casos se detectan +de forma rápida y segura. + +Changelog:: + + Theodore Ts'o + 31 Mar 94 + + La tabla mágica ha sido actualizada para Linux 2.1.55. + + Michael Chastain + <mailto:mec@shout.net> + 22 Sep 1997 + + Ahora debería estar actualizada con Linux 2.1.112. Porque + estamos en fase de "feature freeze", es muy poco probable que + algo cambiará antes de 2.2.x. Las entradas son + ordenados por campo numérico. + + Krzysztof G. Baranowski + <mailto: kgb@knm.org.pl> + 29 Jul 1998 + + Se actualizó la tabla mágica a Linux 2.5.45. Justo sobre el feature + freeze, pero es posible que algunos nuevos números mágicos se cuelen en + el kernel antes de 2.6.x todavía. + + Petr Baudis + <pasky@ucw.cz> + 03 Nov 2002 + + La tabla mágica ha sido actualizada para Linux 2.5.74. + + Fabian Frederick + <ffrederick@users.sourceforge.net> + 09 Jul 2003 + +===================== ================ ======================== ========================================== +Magic Name Number Structure File +===================== ================ ======================== ========================================== +PG_MAGIC 'P' pg_{read,write}_hdr ``include/linux/pg.h`` +APM_BIOS_MAGIC 0x4101 apm_user ``arch/x86/kernel/apm_32.c`` +FASYNC_MAGIC 0x4601 fasync_struct ``include/linux/fs.h`` +SLIP_MAGIC 0x5302 slip ``drivers/net/slip.h`` +MGSLPC_MAGIC 0x5402 mgslpc_info ``drivers/char/pcmcia/synclink_cs.c`` +BAYCOM_MAGIC 0x19730510 baycom_state ``drivers/net/baycom_epp.c`` +HDLCDRV_MAGIC 0x5ac6e778 hdlcdrv_state ``include/linux/hdlcdrv.h`` +KV_MAGIC 0x5f4b565f kernel_vars_s ``arch/mips/include/asm/sn/klkernvars.h`` +CODA_MAGIC 0xC0DAC0DA coda_file_info ``fs/coda/coda_fs_i.h`` +YAM_MAGIC 0xF10A7654 yam_port ``drivers/net/hamradio/yam.c`` +CCB_MAGIC 0xf2691ad2 ccb ``drivers/scsi/ncr53c8xx.c`` +QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry ``drivers/scsi/arm/queue.c`` +QUEUE_MAGIC_USED 0xf7e1cc33 queue_entry ``drivers/scsi/arm/queue.c`` +NMI_MAGIC 0x48414d4d455201 nmi_s ``arch/mips/include/asm/sn/nmi.h`` +===================== ================ ======================== ========================================== diff --git a/Documentation/translations/zh_CN/PCI/msi-howto.rst b/Documentation/translations/zh_CN/PCI/msi-howto.rst index 7ea4d50cdad2..1b9b5ea790d8 100644 --- a/Documentation/translations/zh_CN/PCI/msi-howto.rst +++ b/Documentation/translations/zh_CN/PCI/msi-howto.rst @@ -231,3 +231,14 @@ ACPI FADT表中指明了它。在这种情况下，Linux会自动禁用MSI。有 也需要检查设备驱动程序，看它是否支持MSI。例如，它可能包含对带有PCI_IRQ_MSI或 PCI_IRQ_MSIX标志的pci_alloc_irq_vectors（）的调用。 + + +MSI(-X) APIs设备驱动程序列表 +============================ + +PCI/MSI子系统有一个专门的C文件，用于其导出的设备驱动程序APIs - `drivers/pci/msi/api.c` 。 +以下是导出的函数: + +该API在以下内核代码中: + +drivers/pci/msi/api.c diff --git a/Documentation/translations/zh_CN/accounting/delay-accounting.rst b/Documentation/translations/zh_CN/accounting/delay-accounting.rst index f1849411018e..a01dc3d5b0db 100644 --- a/Documentation/translations/zh_CN/accounting/delay-accounting.rst +++ b/Documentation/translations/zh_CN/accounting/delay-accounting.rst @@ -17,8 +17,9 @@ a) 等待一个CPU（任务为可运行） b) 完成由该任务发起的块I/O同步请求 c) 页面交换 d) 内存回收 -e) 页缓存抖动 +e) 抖动 f) 直接规整 +g) 写保护复制 并将这些统计信息通过taskstats接口提供给用户空间。 @@ -42,7 +43,7 @@ f) 直接规整 include/uapi/linux/taskstats.h 其描述了延时计数相关字段。系统通常以计数器形式返回 CPU、同步块 I/O、交换、内存 -回收、页缓存抖动、直接规整等的累积延时。 +回收、页缓存抖动、直接规整、写保护复制等的累积延时。 取任务某计数器两个连续读数的差值，将得到任务在该时间间隔内等待对应资源的总延时。 @@ -100,6 +101,8 @@ getdelays命令的一般格式:: 0 0 0ms COMPACT count delay total delay average 0 0 0ms + WPCOPY count delay total delay average + 0 0 0ms 获取pid为1的IO计数，它只和-p一起使用:: # ./getdelays -i -p 1 diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst index 30c69e1f44fe..6f8676a50b38 100644 --- a/Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst @@ -22,6 +22,7 @@ start usage reclaim + lru_sort diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/lru_sort.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/lru_sort.rst new file mode 100644 index 000000000000..812ef315c8f6 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/lru_sort.rst @@ -0,0 +1,263 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/mm/damon/lru_sort.rst + +:翻译: + + 臧雷刚 Leigang Zang <zangleigang@hisilicon.com> + +:校译: + +================== +基于DAMON的LRU排序 +================== + +基于DAMON的LRU排序是一个静态的内核模块，旨在用于以主动的、轻量级的数据访问模型 +为基础的页面优先级处理的LRU链表上，以使得LRU上的数据访问模型更为可信。 + +哪里需要主动的LRU排序 +===================== + +在一个大型系统中，以页为粒度的访问检测会有比较显著的开销，LRU通常不会主动去排序， +而是对部分特殊事件进行部分的、响应式的排序，例如：特殊的用户请求，系统调用或者 +内存压力。这导致，在有些场景下，LRU不能够完美的作为一个可信的数据访问模型，比如 +在内存压力下对目标内存进行回收。 + +因为DAMON能够尽可能准确的识别数据访问模型，同时只引起用户指定范围的开销，主动的 +执行DAMON_LRU_SORT让LRU变得更为可信是有益的，而且这只需要较少和可控的开销。 + +这是如何工作的 +============== + +DAMON_LRU_SORT使用DAMON寻找热页（范围内的页面访问频率高于用户指定的阈值）和冷页 +（范围内的页面在超过用户指定的时间无访问），并提高热页和降低冷页在LRU中的优先级。 +为了避免在排序过程占用更多的CPU计算资源，可以设置一个CPU占用时间的约束值。在约 +束下，分别提升或者降低更多的热页和冷页。系统管理员也可以配置三个内存水位以控制 +在何种条件下自动激活或者停止这种机制。 + +冷热阈值和CPU约束的默认值是比较保守的。这意味着，在默认参数下，模块可以广泛且无 +负作用的使用在常见环境中，同时在只消耗一小部分CPU时间的情况下，给有内存压力的系 +统提供一定水平的冷热识别。 + +接口：模块参数 +============== + +使用此特性，你首先需要确认你的系统中运行的内核在编译时启用了 +``CONFIG_DAMON_LRU_SORT=y``. + +为了让系统管理员打开或者关闭并且调节指定的系统，DAMON_LRU_SORT设计了模块参数。 +这意味着，你可以添加 ``damon_lru_sort.<parameter>=<value>`` 到内核的启动命令行 +参数，或者在 ``/sys/modules/damon_lru_sort/parameters/<parameter>`` 写入正确的 +值。 + +下边是每个参数的描述 + +enabled +------- + +打开或者关闭DAMON_LRU_SORT. + +你可以通过设置这个参数为 ``Y`` 来打开DAMON_LRU_SORT。设置为 ``N`` 关闭 +DAMON_LRU_SORT。注意，在基于水位的激活的情况下，DAMON_LRU_SORT有可能不会真正去 +监测或者做LRU排序。对这种情况，参考下方关于水位的描述。 + +commit_inputs +------------- + +让DAMON_LRU_SORT再次读取输入参数，除了 ``enabled`` 。 + +在DAMON_LRU_SORT运行时，新的输入参数默认不会被应用。一旦这个参数被设置为 ``Y`` +，DAMON_LRU_SORT会再次读取除了 ``enabled`` 之外的参数。读取完成后，这个参数会被 +设置为 ``N`` 。如果在读取时发现有无效参数，DAMON_LRU_SORT会被关闭。 + +hot_thres_access_freq +--------------------- + +热点内存区域的访问频率阈值，千分比。 + +如果一个内存区域的访问频率大于等于这个值，DAMON_LRU_SORT把这个区域看作热区，并 +在LRU上把这个区域标记为已访问，因些在内存压力下这部分内存不会被回收。默认为50%。 + +cold_min_age +------------ + +用于识别冷内存区域的时间阈值，单位是微秒。 + +如果一个内存区域在这个时间内未被访问过，DAMON_LRU_SORT把这个区域看作冷区，并在 +LRU上把这个区域标记为未访问，因此在内存压力下这些内存会首先被回收。默认值为120 +秒。 + +quota_ms +-------- + +尝试LRU链表排序的时间限制，单位是毫秒。 + +DAMON_LRU_SORT在一个时间窗口内（quota_reset_interval_ms）内最多尝试这么长时间来 +对LRU进行排序。这个可以用来作为CPU计算资源的约束。如果值为0，则表示无限制。 + +默认10毫秒。 + +quota_reset_interval_ms +----------------------- + +配额计时重置周期，毫秒。 + +配额计时重置周期。即，在quota_reset_interval_ms毫秒内，DAMON_LRU_SORT对LRU进行 +排序不会超过quota_ms或者quota_sz。 + +默认1秒。 + +wmarks_interval +--------------- + +水位的检查周期，单位是微秒。 + +当DAMON_LRU_SORT使能但是由于水位而不活跃时检查水位前最小的等待时间。默认值5秒。 + +wmarks_high +----------- + +空闲内存高水位，千分比。 + +如果空闲内存水位高于这个值，DAMON_LRU_SORT停止工作，不做任何事，除了周期性的检 +查水位。默认200(20%)。 + +wmarks_mid +---------- + +空闲内存中间水位，千分比。 + +如果空闲内存水位在这个值与低水位之间，DAMON_LRU_SORT开始工作，开始检测并对LRU链 +表进行排序。默认150(15%)。 + +wmarks_low +---------- + +空闲内存低水位，千分比。 + +如果空闲内存小于这个值，DAMON_LRU_SORT不再工作，不做任何事，除了周期性的检查水 +线。默认50(5%)。 + +sample_interval +--------------- + +监测的采样周期，微秒。 + +DAMON对冷内存监测的采样周期。更多细节请参考DAMON文档 (:doc:`usage`) 。默认5 +毫秒。 + +aggr_interval +------------- + +监测的收集周期，微秒。 + +DAMON对冷内存进行收集的时间周期。更多细节请参考DAMON文档 (:doc:`usage`) 。默认 +100毫秒。 + +min_nr_regions +-------------- + +最小监测区域数量。 + +对冷内存区域监测的最小数量。这个值可以作为监测质量的下限。不过，这个值设置的过 +大会增加开销。更多细节请参考DAMON文档 (:doc:`usage`) 。默认值为10。 + +max_nr_regions +-------------- + +最大监测区域数量。 + +对冷内存区域监测的最大数量。这个值可以作为监测质量的上限。然而，这个值设置的过 +低会导致监测结果变差。更多细节请参考DAMON文档 (:doc:`usage`) 。默认值为1000。 + +monitor_region_start +-------------------- + +目标内存区域的起始物理地址。 + +DAMON_LRU_SORT要处理的目标内存区域的起始物理地址。默认，使用系统最大内存。 + +monitor_region_end +------------------ + +目标内存区域的结束物理地址。 + +DAMON_LRU_SORT要处理的目标内存区域的结束物理地址。默认，使用系统最大内存。 + +kdamond_pid +----------- + +DAMON线程的PID。 + +如果DAMON_LRU_SORT是使能的，这个表示任务线程的PID。其它情况为-1。 + +nr_lru_sort_tried_hot_regions +----------------------------- + +被尝试进行LRU排序的热内存区域的数量。 + +bytes_lru_sort_tried_hot_regions +-------------------------------- + +被尝试进行LRU排序的热内存区域的大小（字节）。 + +nr_lru_sorted_hot_regions +------------------------- + +成功进行LRU排序的热内存区域的数量。 + +bytes_lru_sorted_hot_regions +---------------------------- + +成功进行LRU排序的热内存区域的大小（字节）。 + +nr_hot_quota_exceeds +-------------------- + +热区域时间约束超过限制的次数。 + +nr_lru_sort_tried_cold_regions +------------------------------ + +被尝试进行LRU排序的冷内存区域的数量。 + +bytes_lru_sort_tried_cold_regions +--------------------------------- + +被尝试进行LRU排序的冷内存区域的大小（字节）。 + +nr_lru_sorted_cold_regions +-------------------------- + +成功进行LRU排序的冷内存区域的数量。 + +bytes_lru_sorted_cold_regions +----------------------------- + +成功进行LRU排序的冷内存区域的大小（字节）。 + +nr_cold_quota_exceeds +--------------------- + +冷区域时间约束超过限制的次数。 + +Example +======= + +如下是一个运行时的命令示例，使DAMON_LRU_SORT查找访问频率超过50%的区域并对其进行 +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 + # echo 120000000 > cold_min_age + # echo 10 > quota_ms + # echo 1000 > quota_reset_interval_ms + # echo 500 > wmarks_high + # echo 400 > wmarks_mid + # echo 200 > wmarks_low + # echo Y > enabled diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst index c976f3e33ffd..d14ba32f7788 100644 --- a/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst @@ -45,11 +45,7 @@ DAMON_RECLAIM找到在特定时间内没有被访问的内存区域并分页。 为了让系统管理员启用或禁用它，并为给定的系统进行调整，DAMON_RECLAIM利用了模块参数。也就 是说，你可以把 ``damon_reclaim.<parameter>=<value>`` 放在内核启动命令行上，或者把 -适当的值写入 ``/sys/modules/damon_reclaim/parameters/<parameter>`` 文件。 - -注意，除 ``启用`` 外的参数值只在DAMON_RECLAIM启动时应用。因此，如果你想在运行时应用新 -的参数值，而DAMON_RECLAIM已经被启用，你应该通过 ``启用`` 的参数文件禁用和重新启用它。 -在重新启用之前，应将新的参数值写入适当的参数值中。 +适当的值写入 ``/sys/module/damon_reclaim/parameters/<parameter>`` 文件。 下面是每个参数的描述。 @@ -218,7 +214,7 @@ nr_quota_exceeds 就开始真正的工作。如果DAMON_RECLAIM没有取得进展，因此空闲内存率低于20%，它会要求 DAMON_RECLAIM再次什么都不做，这样我们就可以退回到基于LRU列表的页面粒度回收了:: - # cd /sys/modules/damon_reclaim/parameters + # cd /sys/module/damon_reclaim/parameters # echo 30000000 > min_age # echo $((1 * 1024 * 1024 * 1024)) > quota_sz # echo 1000 > quota_reset_interval_ms diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst index 67d1b49481dc..bf21ff84f396 100644 --- a/Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst @@ -34,16 +34,8 @@ https://github.com/awslabs/damo找到。下面的例子假设DAMO在你的$PATH上。当然，但 这并不是强制性的。 -因为DAMO使用的是DAMON的debugfs接口(详情请参考 :doc:`usage` 中的使用方法) 你应该 -确保debugfs被挂载。手动挂载它，如下所示:: - - # mount -t debugfs none /sys/kernel/debug/ - -或者在你的 ``/etc/fstab`` 文件中添加以下一行，这样你的系统就可以在启动时自动挂载 -debugfs了:: - - debugfs /sys/kernel/debug debugfs defaults 0 0 - +因为DAMO使用了DAMON的sysfs接口（详情请参考:doc:`usage`），你应该确保 +:doc:`sysfs </filesystems/sysfs>` 被挂载。 记录数据访问模式 ================ diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst index aeae2ab65dd8..17b9949d9b43 100644 --- a/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst @@ -46,10 +46,10 @@ DAMON的sysfs接口是在定义 ``CONFIG_DAMON_SYSFS`` 时建立的。它在其s 对于一个简短的例子，用户可以监测一个给定工作负载的虚拟地址空间，如下所示:: # cd /sys/kernel/mm/damon/admin/ - # echo 1 > kdamonds/nr && echo 1 > kdamonds/0/contexts/nr + # echo 1 > kdamonds/nr_kdamonds && echo 1 > kdamonds/0/contexts/nr_contexts # echo vaddr > kdamonds/0/contexts/0/operations - # echo 1 > kdamonds/0/contexts/0/targets/nr - # echo $(pidof <workload>) > kdamonds/0/contexts/0/targets/0/pid + # echo 1 > kdamonds/0/contexts/0/targets/nr_targets + # echo $(pidof <workload>) > kdamonds/0/contexts/0/targets/0/pid_target # echo on > kdamonds/0/state 文件层次结构 @@ -82,6 +82,9 @@ DAMON sysfs接口的文件层次结构如下图所示。在下图中，父子关 │ │ │ │ │ │ │ │ weights/sz_permil,nr_accesses_permil,age_permil │ │ │ │ │ │ │ watermarks/metric,interval_us,high,mid,low │ │ │ │ │ │ │ stats/nr_tried,sz_tried,nr_applied,sz_applied,qt_exceeds + │ │ │ │ │ │ │ tried_regions/ + │ │ │ │ │ │ │ │ 0/start,end,nr_accesses,age + │ │ │ │ │ │ │ │ ... │ │ │ │ │ │ ... │ │ │ │ ... │ │ ... @@ -111,7 +114,11 @@ kdamonds/<N>/ 读取 ``state`` 时，如果kdamond当前正在运行，则返回 ``on`` ，如果没有运行则返回 ``off`` 。 写入 ``on`` 或 ``off`` 使kdamond处于状态。向 ``state`` 文件写 ``update_schemes_stats`` ， 更新kdamond的每个基于DAMON的操作方案的统计文件的内容。关于统计信息的细节，请参考 -:ref:`stats section <sysfs_schemes_stats>`. +:ref:`stats section <sysfs_schemes_stats>`. 将 ``update_schemes_tried_regions`` 写到 +``state`` 文件，为kdamond的每个基于DAMON的操作方案，更新基于DAMON的操作方案动作的尝试区域目录。 +将`clear_schemes_tried_regions`写入`state`文件，清除kdamond的每个基于DAMON的操作方案的动作 +尝试区域目录。 关于基于DAMON的操作方案动作尝试区域目录的细节，请参考:ref:tried_regions 部分 +<sysfs_schemes_tried_regions>`。 如果状态为 ``on``，读取 ``pid`` 显示kdamond线程的pid。 @@ -186,6 +193,8 @@ regions/<N>/ 在每个区域目录中，你会发现两个文件（ ``start`` 和 ``end`` ）。你可以通过向文件写入 和从文件中读出，分别设置和获得初始监测目标区域的起始和结束地址。 +每个区域不应该与其他区域重叠。 目录“N”的“结束”应等于或小于目录“N+1”的“开始”。 + contexts/<N>/schemes/ --------------------- @@ -199,8 +208,8 @@ contexts/<N>/schemes/ schemes/<N>/ ------------ -在每个方案目录中，存在四个目录(``access_pattern``, ``quotas``,``watermarks``, -和 ``stats``)和一个文件(``action``)。 +在每个方案目录中，存在五个目录(``access_pattern``、``quotas``、``watermarks``、 +``stats`` 和 ``tried_regions``)和一个文件(``action``)。 ``action`` 文件用于设置和获取你想应用于具有特定访问模式的内存区域的动作。可以写入文件 和从文件中读取的关键词及其含义如下。 @@ -229,8 +238,8 @@ schemes/<N>/quotas/ 每个 ``动作`` 的最佳 ``目标访问模式`` 取决于工作负载，所以不容易找到。更糟糕的是，将某些动作 的方案设置得过于激进会造成严重的开销。为了避免这种开销，用户可以为每个方案限制时间和大小配额。 -具体来说，用户可以要求DAMON尽量只使用特定的时间（``时间配额``）来应用行动，并且在给定的时间间 -隔（``重置间隔``）内，只对具有目标访问模式的内存区域应用行动，而不使用特定数量（``大小配额``）。 +具体来说，用户可以要求DAMON尽量只使用特定的时间（``时间配额``）来应用动作，并且在给定的时间间 +隔（``重置间隔``）内，只对具有目标访问模式的内存区域应用动作，而不使用特定数量（``大小配额``）。 当预计超过配额限制时，DAMON会根据 ``目标访问模式`` 的大小、访问频率和年龄，对找到的内存区域 进行优先排序。为了进行个性化的优先排序，用户可以为这三个属性设置权重。 @@ -272,6 +281,24 @@ DAMON统计每个方案被尝试应用的区域的总数量和字节数，每个 你应该要求DAMON sysfs接口通过在相关的 ``kdamonds/<N>/state`` 文件中写入一个特殊的关键字 ``update_schemes_stats`` 来更新统计信息的文件内容。 +schemes/<N>/tried_regions/ +-------------------------- + +当一个特殊的关键字 ``update_schemes_tried_regions`` 被写入相关的 ``kdamonds/<N>/state`` +文件时，DAMON会在这个目录下创建从 ``0`` 开始命名的整数目录。每个目录包含的文件暴露了关于每个 +内存区域的详细信息，在下一个 :ref:`聚集区间 <sysfs_monitoring_attrs>`，相应的方案的 ``动作`` +已经尝试在这个目录下应用。这些信息包括地址范围、``nr_accesses`` 以及区域的 ``年龄`` 。 + +当另一个特殊的关键字 ``clear_schemes_tried_regions`` 被写入相关的 ``kdamonds/<N>/state`` +文件时，这些目录将被删除。 + +tried_regions/<N>/ +------------------ + +在每个区域目录中，你会发现四个文件(``start``, ``end``, ``nr_accesses``, and ``age``)。 +读取这些文件将显示相应的基于DAMON的操作方案 ``动作`` 试图应用的区域的开始和结束地址、``nr_accesses`` +和 ``年龄`` 。 + 用例 ~~~~ @@ -287,12 +314,12 @@ DAMON统计每个方案被尝试应用的区域的总数量和字节数，每个 # echo 1 > kdamonds/0/contexts/0/schemes/nr_schemes # cd kdamonds/0/contexts/0/schemes/0 # # set the basic access pattern and the action - # echo 4096 > access_patterns/sz/min - # echo 8192 > access_patterns/sz/max - # echo 0 > access_patterns/nr_accesses/min - # echo 5 > access_patterns/nr_accesses/max - # echo 10 > access_patterns/age/min - # echo 20 > access_patterns/age/max + # echo 4096 > access_pattern/sz/min + # echo 8192 > access_pattern/sz/max + # echo 0 > access_pattern/nr_accesses/min + # echo 5 > access_pattern/nr_accesses/max + # echo 10 > access_pattern/age/min + # echo 20 > access_pattern/age/max # echo pageout > action # # set quotas # echo 10 > quotas/ms @@ -311,6 +338,11 @@ DAMON统计每个方案被尝试应用的区域的总数量和字节数，每个 debugfs接口 =========== +.. note:: + + DAMON debugfs接口将在下一个LTS内核发布后被移除，所以用户应该转移到 + :ref:`sysfs接口<sysfs_interface>`。 + DAMON导出了八个文件, ``attrs``, ``target_ids``, ``init_regions``, ``schemes``, ``monitor_on``, ``kdamond_pid``, ``mk_contexts`` 和 ``rm_contexts`` under its debugfs directory, ``<debugfs>/damon/``. @@ -364,7 +396,7 @@ DAMON导出了八个文件, ``attrs``, ``target_ids``, ``init_regions``, 监测目标区域。 在这种情况下，用户可以通过在 ``init_regions`` 文件中写入适当的值，明确地设置他们想要的初 -始监测目标区域。输入的每一行应代表一个区域，形式如下:: +始监测目标区域。输入应该是一个由三个整数组成的队列，用空格隔开，代表一个区域的形式如下:: <target idx> <start address> <end address> @@ -376,9 +408,9 @@ DAMON导出了八个文件, ``attrs``, ``target_ids``, ``init_regions``, # cd <debugfs>/damon # cat target_ids 42 4242 - # echo "0 1 100 - 0 100 200 - 1 20 40 + # echo "0 1 100 \ + 0 100 200 \ + 1 20 40 \ 1 50 100" > init_regions 请注意，这只是设置了初始的监测目标区域。在虚拟内存监测的情况下，DAMON会在一个 ``更新间隔`` diff --git a/Documentation/translations/zh_CN/admin-guide/mm/index.rst b/Documentation/translations/zh_CN/admin-guide/mm/index.rst index 702271c5b683..a8fd2c4a8796 100644 --- a/Documentation/translations/zh_CN/admin-guide/mm/index.rst +++ b/Documentation/translations/zh_CN/admin-guide/mm/index.rst @@ -22,7 +22,7 @@ Linux内存管理是一个具有许多可配置设置的复杂系统, 且这些 .. _man 5 proc: http://man7.org/linux/man-pages/man5/proc.5.html Linux内存管理有它自己的术语，如果你还不熟悉它，请考虑阅读下面参考： -:ref:`Documentation/admin-guide/mm/concepts.rst <mm_concepts>`. +Documentation/admin-guide/mm/concepts.rst. 在此目录下，我们详细描述了如何与Linux内存管理中的各种机制交互。 diff --git a/Documentation/translations/zh_CN/admin-guide/mm/ksm.rst b/Documentation/translations/zh_CN/admin-guide/mm/ksm.rst index 4829156ef1ae..0029c4fd2201 100644 --- a/Documentation/translations/zh_CN/admin-guide/mm/ksm.rst +++ b/Documentation/translations/zh_CN/admin-guide/mm/ksm.rst @@ -146,3 +146,53 @@ stable_node_dups 比值 ``pages_sharing/pages_shared`` 的最大值受限制于 ``max_page_sharing`` 的设定。要想增加该比值，则相应地要增加 ``max_page_sharing`` 的值。 + +监测KSM的收益 +============= + +KSM可以通过合并相同的页面来节省内存，但也会消耗额外的内存，因为它需要生成一些rmap_items +来保存每个扫描页面的简要rmap信息。其中有些页面可能会被合并，但有些页面在被检查几次 +后可能无法被合并，这些都是无益的内存消耗。 + +1) 如何确定KSM在全系统范围内是节省内存还是消耗内存？这里有一个简单的近似计算方法供参考:: + + general_profit =~ pages_sharing * sizeof(page) - (all_rmap_items) * + sizeof(rmap_item); + + 其中all_rmap_items可以通过对 ``pages_sharing`` 、 ``pages_shared`` 、 ``pages_unshared`` + 和 ``pages_volatile`` 的求和而轻松获得。 + +2) 单一进程中KSM的收益也可以通过以下近似的计算得到:: + + process_profit =~ ksm_merging_pages * sizeof(page) - + ksm_rmap_items * sizeof(rmap_item). + + 其中ksm_merging_pages显示在 ``/proc/<pid>/`` 目录下，而ksm_rmap_items + 显示在 ``/proc/<pid>/ksm_stat`` 。 + +从应用的角度来看， ``ksm_rmap_items`` 和 ``ksm_merging_pages`` 的高比例意 +味着不好的madvise-applied策略，所以开发者或管理员必须重新考虑如何改变madvis策 +略。举个例子供参考，一个页面的大小通常是4K，而rmap_item的大小在32位CPU架构上分 +别是32B，在64位CPU架构上是64B。所以如果 ``ksm_rmap_items/ksm_merging_pages`` +的比例在64位CPU上超过64，或者在32位CPU上超过128，那么应用程序的madvise策略应 +该被放弃，因为ksm收益大约为零或负值。 + +监控KSM事件 +=========== + +在/proc/vmstat中有一些计数器，可以用来监控KSM事件。KSM可能有助于节省内存，这是 +一种权衡，因为它可能会在KSM COW或复制中的交换上遭受延迟。这些事件可以帮助用户评估 +是否或如何使用KSM。例如，如果cow_ksm增加得太快，用户可以减少madvise(, , MADV_MERGEABLE) +的范围。 + +cow_ksm + 在每次KSM页面触发写时拷贝（COW）时都会被递增，当用户试图写入KSM页面时， + 我们必须做一个拷贝。 + +ksm_swpin_copy + 在换入时，每次KSM页被复制时都会被递增。请注意，KSM页在换入时可能会被复 + 制，因为do_swap_page()不能做所有的锁，而需要重组一个跨anon_vma的KSM页。 + +-- +Izik Eidus, +Hugh Dickins, 2009年11月17日。 diff --git a/Documentation/translations/zh_CN/core-api/kernel-api.rst b/Documentation/translations/zh_CN/core-api/kernel-api.rst index c22662679065..a4b373c48c0c 100644 --- a/Documentation/translations/zh_CN/core-api/kernel-api.rst +++ b/Documentation/translations/zh_CN/core-api/kernel-api.rst @@ -48,6 +48,8 @@ lib/string_helpers.c 该API在以下内核代码中: +include/linux/fortify-string.h + lib/string.c include/linux/string.h @@ -119,6 +121,12 @@ include/linux/textsearch.h Linux中的CRC和数学函数 ====================== +算术溢出检查 +------------ + +该API在以下内核代码中: + +include/linux/overflow.h CRC函数 ------- @@ -166,8 +174,6 @@ include/asm-generic/div64.h include/linux/math64.h -lib/math/div64.c - lib/math/gcd.c UUID/GUID diff --git a/Documentation/translations/zh_CN/core-api/mm-api.rst b/Documentation/translations/zh_CN/core-api/mm-api.rst index a732b0eebf16..113359bdb7be 100644 --- a/Documentation/translations/zh_CN/core-api/mm-api.rst +++ b/Documentation/translations/zh_CN/core-api/mm-api.rst @@ -37,7 +37,7 @@ mm/gup.c 该API在以下内核代码中: -include/linux/gfp.h +include/linux/gfp_types.h Slab缓存 ======== diff --git a/Documentation/translations/zh_CN/core-api/workqueue.rst b/Documentation/translations/zh_CN/core-api/workqueue.rst index f6567cf9d3fb..6c1b5ec31d75 100644 --- a/Documentation/translations/zh_CN/core-api/workqueue.rst +++ b/Documentation/translations/zh_CN/core-api/workqueue.rst @@ -313,8 +313,8 @@ And with cmwq with ``@max_active`` >= 3, :: 第一个可以用追踪的方式进行跟踪: :: - $ echo workqueue:workqueue_queue_work > /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace_pipe > out.txt + $ echo workqueue:workqueue_queue_work > /sys/kernel/tracing/set_event + $ cat /sys/kernel/tracing/trace_pipe > out.txt (wait a few secs) 如果有什么东西在工作队列上忙着做循环，它就会主导输出，可以用工作项函数确定违规者。 diff --git a/Documentation/translations/zh_CN/dev-tools/kasan.rst b/Documentation/translations/zh_CN/dev-tools/kasan.rst index fe76cbe77ad6..05ef904dbcfb 100644 --- a/Documentation/translations/zh_CN/dev-tools/kasan.rst +++ b/Documentation/translations/zh_CN/dev-tools/kasan.rst @@ -90,6 +90,47 @@ KASAN只支持SLUB。 ``CONFIG_STACKTRACE`` 。要包括受影响物理页面的分配和释放堆栈跟踪的话， 请启用 ``CONFIG_PAGE_OWNER`` 并使用 ``page_owner=on`` 进行引导。 +启动参数 +~~~~~~~~ + +KASAN受到通用 ``panic_on_warn`` 命令行参数的影响。当它被启用时，KASAN +在打印出错误报告后会使内核恐慌。 + +默认情况下，KASAN只对第一个无效的内存访问打印错误报告。使用 +``kasan_multi_shot``，KASAN对每一个无效的访问都打印一份报告。这会禁用 +了KASAN报告的 ``panic_on_warn``。 + +另外，独立于 ``panic_on_warn`` 、 ``kasan.fault=`` boot参数可以用 +来控制恐慌和报告行为。 + +- ``kasan.fault=report`` 或 ``=panic`` 控制是否只打印KASAN report或 + 同时使内核恐慌（默认： ``report`` ）。即使 ``kasan_multi_shot`` 被 + 启用，恐慌也会发生。 + +基于软件和硬件标签的KASAN模式（见下面关于各种模式的部分）支持改变堆栈跟 +踪收集行为： + +- ``kasan.stacktrace=off`` 或 ``=on`` 禁用或启用分配和释放堆栈痕 + 迹的收集（默认： ``on`` ）。 + +- ``kasan.stack_ring_size=<number of entries>`` 指定堆栈环的条 + 目数（默认： ``32768`` ）。 + +基于硬件标签的KASAN模式是为了在生产中作为一种安全缓解措施使用。因此，它 +支持额外的启动参数，允许完全禁用KASAN或控制其功能。 + +- ``kasan=off`` 或 ``=on`` 控制KASAN是否被启用（默认： ``on`` ）。 + +- ``kasan.mode=sync``, ``=async`` or ``=asymm`` 控制KASAN是否 + 被配置为同步、异步或非对称的执行模式（默认： ``同步`` ）。 + 同步模式：当标签检查异常发生时，会立即检测到不良访问。 + 异步模式：不良访问的检测是延迟的。当标签检查异常发生时，信息被存储在硬 + 件中（对于arm64来说是在TFSR_EL1寄存器中）。内核周期性地检查硬件，并\ + 且只在这些检查中报告标签异常。 + 非对称模式：读取时同步检测不良访问，写入时异步检测。 + +- ``kasan.vmalloc=off`` or ``=on`` 禁用或启用vmalloc分配的标记（默认： ``on`` ）。 + 错误报告 ~~~~~~~~ @@ -194,39 +235,6 @@ slab对象的描述以及关于访问的内存页的信息。 通用KASAN还报告两个辅助调用堆栈跟踪。这些堆栈跟踪指向代码中与对象交互但不直接 出现在错误访问堆栈跟踪中的位置。目前，这包括 call_rcu() 和排队的工作队列。 -启动参数 -~~~~~~~~ - -KASAN受通用 ``panic_on_warn`` 命令行参数的影响。启用该功能后，KASAN在打印错误 -报告后会引起内核恐慌。 - -默认情况下，KASAN只为第一次无效内存访问打印错误报告。使用 ``kasan_multi_shot`` ， -KASAN会针对每个无效访问打印报告。这有效地禁用了KASAN报告的 ``panic_on_warn`` 。 - -另外，独立于 ``panic_on_warn`` , ``kasan.fault=`` 引导参数可以用来控制恐慌和报 -告行为: - -- ``kasan.fault=report`` 或 ``=panic`` 控制是只打印KASAN报告还是同时使内核恐慌 - (默认: ``report`` )。即使启用了 ``kasan_multi_shot`` ，也会发生内核恐慌。 - -基于硬件标签的KASAN模式（请参阅下面有关各种模式的部分）旨在在生产中用作安全缓解 -措施。因此，它支持允许禁用KASAN或控制其功能的附加引导参数。 - -- ``kasan=off`` 或 ``=on`` 控制KASAN是否启用 (默认: ``on`` )。 - -- ``kasan.mode=sync`` 、 ``=async`` 或 ``=asymm`` 控制KASAN是否配置 - 为同步或异步执行模式(默认:``sync`` )。 - 同步模式：当标签检查错误发生时，立即检测到错误访问。 - 异步模式：延迟错误访问检测。当标签检查错误发生时，信息存储在硬件中（在arm64的 - TFSR_EL1寄存器中）。内核会定期检查硬件，并且仅在这些检查期间报告标签错误。 - 非对称模式：读取时同步检测不良访问，写入时异步检测。 - -- ``kasan.vmalloc=off`` 或 ``=on`` 禁用或启用vmalloc分配的标记（默认：``on`` ）。 - -- ``kasan.stacktrace=off`` 或 ``=on`` 禁用或启用alloc和free堆栈跟踪收集 - (默认: ``on`` )。 - - 实施细则 -------- diff --git a/Documentation/translations/zh_CN/dev-tools/testing-overview.rst b/Documentation/translations/zh_CN/dev-tools/testing-overview.rst index d6f2c65ed511..af65e7e93c02 100644 --- a/Documentation/translations/zh_CN/dev-tools/testing-overview.rst +++ b/Documentation/translations/zh_CN/dev-tools/testing-overview.rst @@ -132,3 +132,30 @@ Documentation/dev-tools/kcov.rst 是能够构建在内核之中，用于在每 不过要注意的是，静态分析工具存在**假阳性**的问题。在试图修复错误和警 告之前，需要仔细评估它们。 + +何时使用Sparse和Smatch +---------------------- + +Sparse做类型检查，例如验证注释的变量不会导致无符号的错误，检测 +``__user`` 指针使用不当的地方，以及分析符号初始化器的兼容性。 + +Smatch进行流程分析，如果允许建立函数数据库，它还会进行跨函数分析。 +Smatch试图回答一些问题，比如这个缓冲区是在哪里分配的？它有多大？这 +个索引可以由用户控制吗？这个变量比那个变量大吗？ + +一般来说，在Smatch中写检查比在Sparse中写检查要容易。尽管如此， +Sparse和Smatch的检查还是有一些重叠的地方。 + +Smatch和Coccinelle的强项 +------------------------ + +Coccinelle可能是最容易写检查的。它在预处理器之前工作，所以用Coccinelle +检查宏中的错误更容易。Coccinelle还能为你创建补丁，这是其他工具无法做到的。 + +例如，用Coccinelle你可以从 ``kmalloc_array(x, size, GFP_KERNEL)`` +到 ``kmalloc_array(x, size, GFP_KERNEL)`` 进行大规模转换，这真的很 +有用。如果你只是创建一个Smatch警告，并试图把转换的工作推给维护者，他们会很 +恼火。你将不得不为每个警告争论是否真的可以溢出。 + +Coccinelle不对变量值进行分析，而这正是Smatch的强项。另一方面，Coccinelle +允许你用简单的方法做简单的事情。 diff --git a/Documentation/translations/zh_CN/glossary.rst b/Documentation/translations/zh_CN/glossary.rst new file mode 100644 index 000000000000..24f094df97cd --- /dev/null +++ b/Documentation/translations/zh_CN/glossary.rst @@ -0,0 +1,36 @@ +.. SPDX-License-Identifier: GPL-2.0 + +术语表 +====== + +这不是一个完善的术语表，我们只是将有争议的和陌生的翻译词汇记录于此， +它的篇幅应该根据内核文档翻译的需求而增加。新词条最好随翻译补丁一起 +提交，且仅在以下情况下收录新词条： + + - 在翻译过程中遇到陌生词汇，且尚无翻译先例的； + - 在审阅过程中，针对某词条出现了不同的翻译意见； + - 使用频率不高的词条和首字母缩写类型的词条； + - 已经存在且有歧义的词条翻译。 + + +* atomic: 原子的，一般指不可中断的极小的临界区操作。 +* DVFS: 动态电压频率升降。（Dynamic Voltage and Frequency Scaling） +* EAS: 能耗感知调度。（Energy Aware Scheduling） +* flush: 刷新，一般指对cache的冲洗操作。 +* fork: 创建, 通常指父进程创建子进程。 +* futex: 快速用户互斥锁。（fast user mutex） +* guest halt polling: 客户机停机轮询机制。 +* HugePage: 巨页。 +* hypervisor: 虚拟机超级管理器。 +* memory barriers: 内存屏障。 +* MIPS: 每秒百万指令。（Millions of Instructions Per Second）,注意与mips指令集区分开。 +* mutex: 互斥锁。 +* NUMA: 非统一内存访问。 +* OpenCAPI: 开放相干加速器处理器接口。（Open Coherent Accelerator Processor Interface） +* OPP: 操作性能值。 +* overhead: 开销，一般指需要消耗的计算机资源。 +* PELT: 实体负载跟踪。（Per-Entity Load Tracking） +* sched domain: 调度域。 +* semaphores: 信号量。 +* spinlock: 自旋锁。 +* watermark: 水位，一般指页表的消耗水平。 diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst index 3660a3451c86..7c3216845b71 100644 --- a/Documentation/translations/zh_CN/index.rst +++ b/Documentation/translations/zh_CN/index.rst @@ -133,6 +133,15 @@ TODOList: staging/index +术语表 +------ + +.. toctree:: + :maxdepth: 1 + + glossary + + 索引和表格 ---------- diff --git a/Documentation/translations/zh_CN/mm/highmem.rst b/Documentation/translations/zh_CN/mm/highmem.rst index f74800a6d9a7..2c0ee0cbf5c4 100644 --- a/Documentation/translations/zh_CN/mm/highmem.rst +++ b/Documentation/translations/zh_CN/mm/highmem.rst @@ -57,15 +57,29 @@ 在可行的情况下，这个函数应该比其他所有的函数优先使用。 - 这些映射是线程本地和CPU本地的，这意味着映射只能从这个线程中访问，并且当映射处于活动状 - 态时，该线程与CPU绑定。即使线程被抢占了（因为抢占永远不会被函数禁用），CPU也不能通过 - CPU-hotplug从系统中拔出，直到映射被处理掉。 + 这些映射是线程本地和CPU本地的，这意味着映射只能从这个线程中访问，并且当映射处于活跃状 + 态时，线程被绑定到CPU上。尽管这个函数从来没有禁用过抢占，但在映射被处理之前，CPU不能 + 通过CPU-hotplug从系统中拔出。 在本地的kmap区域中采取pagefaults是有效的，除非获取本地映射的上下文由于其他原因不允许 这样做。 + 如前所述，缺页异常和抢占从未被禁用。没有必要禁用抢占，因为当上下文切换到一个不同的任务 + 时，离开的任务的映射被保存，而进入的任务的映射被恢复。 + kmap_local_page()总是返回一个有效的虚拟地址，并且假定kunmap_local()不会失败。 + 在CONFIG_HIGHMEM=n的内核中，对于低内存页，它返回直接映射的虚拟地址。只有真正的高内 + 存页面才会被临时映射。因此，用户可以为那些已知不是来自ZONE_HIGHMEM的页面调用普通的 + page_address()。然而，使用kmap_local_page() / kunmap_local()总是安全的。 + + 虽然它比kmap()快得多，但在高内存的情况下，它对指针的有效性有限制。与kmap()映射相反， + 本地映射只在调用者的上下文中有效，不能传递给其他上下文。这意味着用户必须绝对保证返回 + 地址的使用只限于映射它的线程。 + + 大多数代码可以被设计成使用线程本地映射。因此，用户在设计他们的代码时，应该尽量避免使用 + kmap()，将页面映射到将被使用的同一线程中，并优先使用kmap_local_page()。 + 嵌套kmap_local_page()和kmap_atomic()映射在一定程度上是允许的（最多到KMAP_TYPE_NR）， 但是它们的调用必须严格排序，因为映射的实现是基于堆栈的。关于如何管理嵌套映射的细节， 请参见kmap_local_page() kdocs（包含在 "函数 "部分）。 diff --git a/Documentation/translations/zh_CN/mm/hmm.rst b/Documentation/translations/zh_CN/mm/hmm.rst index 5024a8a15516..babbbe756c0f 100644 --- a/Documentation/translations/zh_CN/mm/hmm.rst +++ b/Documentation/translations/zh_CN/mm/hmm.rst @@ -248,7 +248,7 @@ migrate_vma_finalize() 函数旨在使驱动程序更易于编写并集中跨驱 还有devm_request_free_mem_region(), devm_memremap_pages(), devm_memunmap_pages() 和 devm_release_mem_region() 当资源可以绑定到 ``struct device``. -整体迁移步骤类似于在系统内存中迁移 NUMA 页面(see :ref:`Page migration <page_migration>`) ， +整体迁移步骤类似于在系统内存中迁移 NUMA 页面(see Documentation/mm/page_migration.rst) ， 但这些步骤分为设备驱动程序特定代码和共享公共代码: 1. ``mmap_read_lock()`` diff --git a/Documentation/translations/zh_CN/mm/hugetlbfs_reserv.rst b/Documentation/translations/zh_CN/mm/hugetlbfs_reserv.rst index 752e5696cd47..80787af29222 100644 --- a/Documentation/translations/zh_CN/mm/hugetlbfs_reserv.rst +++ b/Documentation/translations/zh_CN/mm/hugetlbfs_reserv.rst @@ -15,7 +15,7 @@ Hugetlbfs 预留 概述 ==== -:ref:`hugetlbpage` 中描述的巨页通常是预先分配给应用程序使用的。如果VMA指 +Documentation/mm/hugetlbpage.rst 中描述的巨页通常是预先分配给应用程序使用的。如果VMA指 示要使用巨页，这些巨页会在缺页异常时被实例化到任务的地址空间。如果在缺页异常 时没有巨页存在，任务就会被发送一个SIGBUS，并经常不高兴地死去。在加入巨页支 持后不久，人们决定，在mmap()时检测巨页的短缺情况会更好。这个想法是，如果 diff --git a/Documentation/translations/zh_CN/mm/numa.rst b/Documentation/translations/zh_CN/mm/numa.rst index b15cfeeb6dfb..61fad89272fa 100644 --- a/Documentation/translations/zh_CN/mm/numa.rst +++ b/Documentation/translations/zh_CN/mm/numa.rst @@ -76,7 +76,7 @@ Linux将系统的硬件资源划分为多个软件抽象，称为“节点”。 系统管理员和应用程序设计者可以使用各种CPU亲和命令行接口，如taskset(1)和numactl(1)，以及程 序接口，如sched_setaffinity(2)，来限制任务的迁移，以改善NUMA定位。此外，人们可以使用 Linux NUMA内存策略修改内核的默认本地分配行为。 [见 -:ref:`Documentation/admin-guide/mm/numa_memory_policy.rst <numa_memory_policy>`]. +Documentation/admin-guide/mm/numa_memory_policy.rst]. 系统管理员可以使用控制组和CPUsets限制非特权用户在调度或NUMA命令和功能中可以指定的CPU和节点 的内存。 [见 Documentation/admin-guide/cgroup-v1/cpusets.rst] diff --git a/Documentation/translations/zh_CN/mm/page_owner.rst b/Documentation/translations/zh_CN/mm/page_owner.rst index 21a6a0837d42..dba511fafef2 100644 --- a/Documentation/translations/zh_CN/mm/page_owner.rst +++ b/Documentation/translations/zh_CN/mm/page_owner.rst @@ -34,20 +34,9 @@ page owner在默认情况下是禁用的。所以，如果你想使用它，你 一样进行。这两个不可能的分支应该不会影响到分配的性能，特别是在静态键跳转标签修补 功能可用的情况下。以下是由于这个功能而导致的内核代码大小的变化。 -- 没有page owner:: - - text data bss dec hex filename - 48392 2333 644 51369 c8a9 mm/page_alloc.o - -- 有page owner:: - - text data bss dec hex filename - 48800 2445 644 51889 cab1 mm/page_alloc.o - 6662 108 29 6799 1a8f mm/page_owner.o - 1025 8 8 1041 411 mm/page_ext.o - -虽然总共增加了8KB的代码，但page_alloc.o增加了520字节，其中不到一半是在hotpath -中。构建带有page owner的内核，并在需要时打开它，将是调试内核内存问题的最佳选择。 +尽管启用page owner会使内核的大小增加几千字节，但这些代码大部分都在页面分配器和 +热路径之外。构建带有page owner的内核，并在需要时打开它，将是调试内核内存问题的 +最佳选择。 有一个问题是由实现细节引起的。页所有者将信息存储到struct page扩展的内存中。这 个内存的初始化时间比稀疏内存系统中的页面分配器启动的时间要晚一些，所以，在初始化 diff --git a/Documentation/translations/zh_CN/power/energy-model.rst b/Documentation/translations/zh_CN/power/energy-model.rst index c7da1b6aefee..48849919d8aa 100644 --- a/Documentation/translations/zh_CN/power/energy-model.rst +++ b/Documentation/translations/zh_CN/power/energy-model.rst @@ -23,15 +23,15 @@ 实现支持，EM框架作为一个抽象层介入，它在内核中对功率成本表的格式进行标准化， 因此能够避免多余的工作。 -功率值可以用毫瓦或“抽象刻度”表示。多个子系统可能使用EM，由系统集成商来检查 +功率值可以用微瓦或“抽象刻度”表示。多个子系统可能使用EM，由系统集成商来检查 功率值刻度类型的要求是否满足。可以在能量感知调度器的文档中找到一个例子 Documentation/scheduler/sched-energy.rst。对于一些子系统，比如热能或 powercap，用“抽象刻度”描述功率值可能会导致问题。这些子系统对过去使用的功率的 -估算值更感兴趣，因此可能需要真实的毫瓦。这些要求的一个例子可以在智能功率分配 +估算值更感兴趣，因此可能需要真实的微瓦。这些要求的一个例子可以在智能功率分配 Documentation/driver-api/thermal/power_allocator.rst文档中找到。 内核子系统可能（基于EM内部标志位）实现了对EM注册设备是否具有不一致刻度的自动 -检查。要记住的重要事情是，当功率值以“抽象刻度”表示时，从中推导以毫焦耳为单位 +检查。要记住的重要事情是，当功率值以“抽象刻度”表示时，从中推导以微焦耳为单位 的真实能量消耗是不可能的。 下图描述了一个驱动的例子（这里是针对Arm的，但该方法适用于任何体系结构），它 @@ -89,20 +89,40 @@ Documentation/driver-api/thermal/power_allocator.rst文档中找到。 驱动程序应通过以下API将性能域注册到EM框架中:: int em_dev_register_perf_domain(struct device *dev, unsigned int nr_states, - struct em_data_callback *cb, cpumask_t *cpus, bool milliwatts); + struct em_data_callback *cb, cpumask_t *cpus, bool microwatts); 驱动程序必须提供一个回调函数，为每个性能状态返回<频率,功率>元组。驱动程序 提供的回调函数可以自由地从任何相关位置（DT、固件......）以及以任何被认为是 必要的方式获取数据。只有对于CPU设备，驱动程序必须使用cpumask指定性能域的CPU。 对于CPU以外的其他设备，最后一个参数必须被设置为NULL。 -最后一个参数“milliwatts”（毫瓦）设置成正确的值是很重要的，使用EM的内核 +最后一个参数“microwatts”（微瓦）设置成正确的值是很重要的，使用EM的内核 子系统可能会依赖这个标志来检查所有的EM设备是否使用相同的刻度。如果有不同的 -刻度，这些子系统可能决定：返回警告/错误，停止工作或崩溃（panic）。 +刻度，这些子系统可能决定返回警告/错误，停止工作或崩溃（panic）。 关于实现这个回调函数的驱动程序的例子，参见第3节。或者在第2.4节阅读这个API 的更多文档。 +使用DT的EM注册 +============== + +EM也可以使用OPP框架和DT "操作点-v2 "中的信息注册。DT中的每个OPP条目都可 +以用一个包含微瓦特功率值的属性 "op-microwatt "来扩展。这个OPP DT属性允 +许平台注册反映总功率（静态+动态）的EM功率值。这些功率值可能直接来自实验和 +测量。 + +“人工”EM的注册 +============== + +有一个选项可以为缺少关于每个性能状态的功率值的详细知识的驱动程序提供一个自 +定义回调。回调.get_cost()是可选的，它提供EAS使用的“成本”值。这对那些只提 +供CPU类型之间相对效率信息的平台很有用，人们可以利用这些信息来创建一个抽象的 +功率模型。但是，考虑到输入功率值的大小限制，即使是抽象的功率模型有时也很难装 +进去。.get_cost()允许提供反映CPU效率的“成本”值。这将允许提供EAS信息，它 +与EM内部计算'成本'值的公式有不同的关系。要为这样的平台注册EM，驱动程序必须 +将标志“microwatts”设置为0，提供.get_power()回调和.get_cost()回调。EM +框架会在注册过程中正确处理这样的平台。这种平台会被设置EM_PERF_DOMAIN_ARTIFICIAL +标志。其他使用EM的框架应该特别注意测试和正确对待这个标志。 “简单”EM的注册 ~~~~~~~~~~~~~~~~ @@ -147,8 +167,8 @@ cpufreq_driver::register_em()。这个回调必须为每个特定的驱动程序 -> drivers/cpufreq/foo_cpufreq.c - 01 static int est_power(unsigned long *mW, unsigned long *KHz, - 02 struct device *dev) + 01 static int est_power(struct device *dev, unsigned long *mW, + 02 unsigned long *KHz) 03 { 04 long freq, power; 05 diff --git a/Documentation/translations/zh_CN/process/howto.rst b/Documentation/translations/zh_CN/process/howto.rst index 888978a62db3..10254751df6a 100644 --- a/Documentation/translations/zh_CN/process/howto.rst +++ b/Documentation/translations/zh_CN/process/howto.rst @@ -254,7 +254,7 @@ Linux-next 集成测试树 https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git 通过这种方式，Linux-next 对下一个合并阶段将进入主线内核的内容给出了一个概要 -展望。非常欢冒险的测试者运行测试Linux-next。 +展望。非常欢迎冒险的测试者运行测试Linux-next。 多个主要版本的稳定版内核树 ----------------------------------- diff --git a/Documentation/userspace-api/iommufd.rst b/Documentation/userspace-api/iommufd.rst index 79dd9eb51587..aa004faed5fd 100644 --- a/Documentation/userspace-api/iommufd.rst +++ b/Documentation/userspace-api/iommufd.rst @@ -165,7 +165,7 @@ Multiple io_pagetable-s, through their iopt_area-s, can share a single iopt_pages which avoids multi-pinning and double accounting of page consumption. -iommufd_ioas is sharable between subsystems, e.g. VFIO and VDPA, as long as +iommufd_ioas is shareable between subsystems, e.g. VFIO and VDPA, as long as devices managed by different subsystems are bound to a same iommufd. IOMMUFD User API diff --git a/Documentation/userspace-api/media/drivers/st-vgxy61.rst b/Documentation/userspace-api/media/drivers/st-vgxy61.rst index d9e3b80e3a96..17ac15afa77c 100644 --- a/Documentation/userspace-api/media/drivers/st-vgxy61.rst +++ b/Documentation/userspace-api/media/drivers/st-vgxy61.rst @@ -18,7 +18,7 @@ The ST VGXY61 driver implements the following controls: * - HDR linearize - The merger outputs a long exposure capture as long as it is not saturated. - * - HDR substraction + * - HDR subtraction - This involves subtracting the short exposure frame from the long exposure frame. * - No HDR diff --git a/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst index c9d578e291b8..5ae8fac8ed4f 100644 --- a/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst +++ b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst @@ -43,7 +43,7 @@ reduced range of reception. .. note:: - Wide band receiver might be implictly enabled if you enable + Wide band receiver might be implicitly enabled if you enable carrier reports. In that case it will be disabled as soon as you disable carrier reports. Trying to disable wide band receiver while carrier reports are active will do nothing. diff --git a/Documentation/userspace-api/media/rc/rc-protos.rst b/Documentation/userspace-api/media/rc/rc-protos.rst index a2eab3b45647..2a888ff5829f 100644 --- a/Documentation/userspace-api/media/rc/rc-protos.rst +++ b/Documentation/userspace-api/media/rc/rc-protos.rst @@ -75,7 +75,7 @@ protocol, or the manchester BPF decoder. - Command There is a variant of rc5 called either rc5x or extended rc5 -where there the second stop bit is the 6th commmand bit, but inverted. +where there the second stop bit is the 6th command bit, but inverted. This is done so it the scancodes and encoding is compatible with existing schemes. This bit is stored in bit 6 of the scancode, inverted. This is done to keep it compatible with plain rc-5 where there are two start bits. diff --git a/Documentation/userspace-api/media/rc/rc-tables.rst b/Documentation/userspace-api/media/rc/rc-tables.rst index 28ed94088015..aab99260fef5 100644 --- a/Documentation/userspace-api/media/rc/rc-tables.rst +++ b/Documentation/userspace-api/media/rc/rc-tables.rst @@ -628,7 +628,7 @@ the remote via /dev/input/event devices. - Put device into zoom/full screen mode - - ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH + - ZOOM / FULL SCREEN / ZOOM+ / HIDE PANEL / SWITCH - .. row 80 diff --git a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst index 44415822c7c5..42cdb0a9f786 100644 --- a/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst +++ b/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst @@ -490,7 +490,7 @@ struct v4l2_mpeg_vbi_fmt_ivtv - An alternate form of the sliced VBI data payload used when 36 lines of sliced VBI data are present. No line masks are provided in this form of the payload; all valid line mask bits are - implcitly set. + implicitly set. * - } - diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst index cd33857d947d..3d8411acd5b8 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst @@ -1213,7 +1213,7 @@ FWHT Flags - Luma AC coefficient table index. * - __s8 - ``y_dc_delta`` - - Luma DC delta vaue. + - Luma DC delta value. * - __s8 - ``y2_dc_delta`` - Y2 block DC delta value. diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst index 60f9a09422d6..522095c08469 100644 --- a/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst @@ -8,7 +8,7 @@ JPEG Control Reference The JPEG class includes controls for common features of JPEG encoders and decoders. Currently it includes features for codecs implementing -progressive baseline DCT compression process with Huffman entrophy +progressive baseline DCT compression process with Huffman entropy coding. diff --git a/Documentation/userspace-api/media/v4l/hist-v4l2.rst b/Documentation/userspace-api/media/v4l/hist-v4l2.rst index dbc04374dc22..cdc11e9a0f32 100644 --- a/Documentation/userspace-api/media/v4l/hist-v4l2.rst +++ b/Documentation/userspace-api/media/v4l/hist-v4l2.rst @@ -47,7 +47,7 @@ Codec API was released. 1998-11-08: Many minor changes. Most symbols have been renamed. Some material changes to struct v4l2_capability. -1998-11-12: The read/write directon of some ioctls was misdefined. +1998-11-12: The read/write direction of some ioctls was misdefined. 1998-11-14: ``V4L2_PIX_FMT_RGB24`` changed to ``V4L2_PIX_FMT_BGR24``, and ``V4L2_PIX_FMT_RGB32`` changed to ``V4L2_PIX_FMT_BGR32``. Audio @@ -145,7 +145,7 @@ common Linux driver API conventions. ``VIDIOC_G_INFMT``, ``VIDIOC_S_OUTFMT``, ``VIDIOC_G_OUTFMT``, ``VIDIOC_S_VBIFMT`` and ``VIDIOC_G_VBIFMT``. The image format struct v4l2_format was renamed to struct v4l2_pix_format, while - struct v4l2_format is now the envelopping structure + struct v4l2_format is now the enveloping structure for all format negotiations. 5. Similar to the changes above, the ``VIDIOC_G_PARM`` and diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst index 6a387f9df3ba..62078a01de76 100644 --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst @@ -14,7 +14,7 @@ are often referred to as greyscale formats. - In all the tables that follow, bit 7 is the most significant bit in a byte. - Formats are described with the minimum number of pixels needed to create a byte-aligned repeating pattern. `...` indicates repetition of the pattern. - - Y'\ :sub:`x`\ [9:2] denotes bits 9 to 2 of the Y' value for pixel at colum + - Y'\ :sub:`x`\ [9:2] denotes bits 9 to 2 of the Y' value for pixel at column `x`. - `0` denotes padding bits set to 0. diff --git a/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst b/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst index 551ac9d3c6ef..7f10f0bbcfd3 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-cropcap.rst @@ -71,7 +71,7 @@ overlay devices. - Default cropping rectangle, it shall cover the "whole picture". Assuming pixel aspect 1/1 this could be for example a 640 × 480 rectangle for NTSC, a 768 × 576 rectangle for PAL and SECAM - centered over the active picture area. The same co-ordinate system + centered over the active picture area. The same coordinate system as for ``bounds`` is used. * - struct :c:type:`v4l2_fract` - ``pixelaspect`` diff --git a/Documentation/userspace-api/seccomp_filter.rst b/Documentation/userspace-api/seccomp_filter.rst index d1e2b9193f09..cff0fa7f3175 100644 --- a/Documentation/userspace-api/seccomp_filter.rst +++ b/Documentation/userspace-api/seccomp_filter.rst @@ -274,7 +274,7 @@ value will be the injected file descriptor number. The notifying process can be preempted, resulting in the notification being aborted. This can be problematic when trying to take actions on behalf of the notifying process that are long-running and typically retryable (mounting a -filesytem). Alternatively, at filter installation time, the +filesystem). Alternatively, at filter installation time, the ``SECCOMP_FILTER_FLAG_WAIT_KILLABLE_RECV`` flag can be set. This flag makes it such that when a user notification is received by the supervisor, the notifying process will ignore non-fatal signals until the response is sent. Signals that diff --git a/Documentation/userspace-api/sysfs-platform_profile.rst b/Documentation/userspace-api/sysfs-platform_profile.rst index c33a71263d9e..4fccde2e4563 100644 --- a/Documentation/userspace-api/sysfs-platform_profile.rst +++ b/Documentation/userspace-api/sysfs-platform_profile.rst @@ -37,6 +37,6 @@ representation onto this fixed set. If there is no good match when mapping then a new profile name may be added. Drivers which wish to introduce new profile names must: - 1. Explain why the existing profile names canot be used. + 1. Explain why the existing profile names cannot be used. 2. Add the new profile name, along with a clear description of the expected behaviour, to the sysfs-platform_profile ABI documentation. diff --git a/Documentation/virt/index.rst b/Documentation/virt/index.rst index 56e003ff28ff..7fb55ae08598 100644 --- a/Documentation/virt/index.rst +++ b/Documentation/virt/index.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -============================ -Linux Virtualization Support -============================ +====================== +Virtualization Support +====================== .. toctree:: :maxdepth: 2 diff --git a/Documentation/virt/kvm/x86/amd-memory-encryption.rst b/Documentation/virt/kvm/x86/amd-memory-encryption.rst index 935aaeb97fe6..487b6328b3e7 100644 --- a/Documentation/virt/kvm/x86/amd-memory-encryption.rst +++ b/Documentation/virt/kvm/x86/amd-memory-encryption.rst @@ -440,7 +440,7 @@ References See [white-paper]_, [api-spec]_, [amd-apm]_ and [kvm-forum]_ for more info. -.. [white-paper] http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf +.. [white-paper] https://developer.amd.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf .. [api-spec] https://support.amd.com/TechDocs/55766_SEV-KM_API_Specification.pdf .. [amd-apm] https://support.amd.com/TechDocs/24593.pdf (section 15.34) .. [kvm-forum] https://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf diff --git a/Documentation/virt/kvm/x86/running-nested-guests.rst b/Documentation/virt/kvm/x86/running-nested-guests.rst index a27e6768d900..71136fe1723b 100644 --- a/Documentation/virt/kvm/x86/running-nested-guests.rst +++ b/Documentation/virt/kvm/x86/running-nested-guests.rst @@ -150,7 +150,7 @@ able to start an L1 guest with:: $ qemu-kvm -cpu host [...] The above will pass through the host CPU's capabilities as-is to the -gues); or for better live migration compatibility, use a named CPU +guest, or for better live migration compatibility, use a named CPU model supported by QEMU. e.g.:: $ qemu-kvm -cpu Haswell-noTSX-IBRS,vmx=on diff --git a/Documentation/watchdog/hpwdt.rst b/Documentation/watchdog/hpwdt.rst index c824cd7f6e32..5eab5dfec042 100644 --- a/Documentation/watchdog/hpwdt.rst +++ b/Documentation/watchdog/hpwdt.rst @@ -48,7 +48,7 @@ Last reviewed: 08/20/2018 NOTE: More information about watchdog drivers in general, including the ioctl interface to /dev/watchdog can be found in - Documentation/watchdog/watchdog-api.rst and Documentation/IPMI.txt. + Documentation/watchdog/watchdog-api.rst and Documentation/driver-api/ipmi.rst Due to limitations in the iLO hardware, the NMI pretimeout if enabled, can only be set to 9 seconds. Attempts to set pretimeout to other @@ -63,9 +63,9 @@ Last reviewed: 08/20/2018 and loop forever. This is generally not what a watchdog user wants. For those wishing to learn more please see: - Documentation/admin-guide/kdump/kdump.rst - Documentation/admin-guide/kernel-parameters.txt (panic=) - Your Linux Distribution specific documentation. + - Documentation/admin-guide/kdump/kdump.rst + - Documentation/admin-guide/kernel-parameters.txt (panic=) + - Your Linux Distribution specific documentation. If the hpwdt does not receive the NMI associated with an expiring timer, the iLO will proceed to reset the system at timeout if the timer hasn't diff --git a/Documentation/watchdog/index.rst b/Documentation/watchdog/index.rst index c177645081d8..4603f2511f58 100644 --- a/Documentation/watchdog/index.rst +++ b/Documentation/watchdog/index.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -====================== -Linux Watchdog Support -====================== +================ +Watchdog Support +================ .. toctree:: :maxdepth: 1 diff --git a/Documentation/x86/resctrl.rst b/Documentation/x86/resctrl.rst index 058257dc56c8..387ccbcb558f 100644 --- a/Documentation/x86/resctrl.rst +++ b/Documentation/x86/resctrl.rst @@ -751,12 +751,12 @@ how we can measure the latency in cycles of reading from this region and visualize this data with a histogram that is available if CONFIG_HIST_TRIGGERS is set:: - # :> /sys/kernel/debug/tracing/trace - # echo 'hist:keys=latency' > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/trigger - # echo 1 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/enable + # :> /sys/kernel/tracing/trace + # echo 'hist:keys=latency' > /sys/kernel/tracing/events/resctrl/pseudo_lock_mem_latency/trigger + # echo 1 > /sys/kernel/tracing/events/resctrl/pseudo_lock_mem_latency/enable # echo 1 > /sys/kernel/debug/resctrl/newlock/pseudo_lock_measure - # echo 0 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/enable - # cat /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_mem_latency/hist + # echo 0 > /sys/kernel/tracing/events/resctrl/pseudo_lock_mem_latency/enable + # cat /sys/kernel/tracing/events/resctrl/pseudo_lock_mem_latency/hist # event histogram # @@ -785,11 +785,11 @@ cache of a platform. Here is how we can obtain details of the cache hits and misses using the platform's precision counters. :: - # :> /sys/kernel/debug/tracing/trace - # echo 1 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_l2/enable + # :> /sys/kernel/tracing/trace + # echo 1 > /sys/kernel/tracing/events/resctrl/pseudo_lock_l2/enable # echo 2 > /sys/kernel/debug/resctrl/newlock/pseudo_lock_measure - # echo 0 > /sys/kernel/debug/tracing/events/resctrl/pseudo_lock_l2/enable - # cat /sys/kernel/debug/tracing/trace + # echo 0 > /sys/kernel/tracing/events/resctrl/pseudo_lock_l2/enable + # cat /sys/kernel/tracing/trace # tracer: nop # diff --git a/Documentation/x86/x86_64/mm.rst b/Documentation/x86/x86_64/mm.rst index 9798676bb0bf..35e5e18c83d0 100644 --- a/Documentation/x86/x86_64/mm.rst +++ b/Documentation/x86/x86_64/mm.rst @@ -140,7 +140,7 @@ The direct mapping covers all memory in the system up to the highest memory address (this means in some cases it can also include PCI memory holes). -We map EFI runtime services in the 'efi_pgd' PGD in a 64Gb large virtual +We map EFI runtime services in the 'efi_pgd' PGD in a 64GB large virtual memory window (this size is arbitrary, it can be raised later if needed). The mappings are not part of any other kernel PGD and are only available during EFI runtime calls. diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug index 3509115a0e85..cecae75d7519 100644 --- a/lib/Kconfig.debug +++ b/lib/Kconfig.debug @@ -2891,6 +2891,4 @@ config RUST_BUILD_ASSERT_ALLOW endmenu # "Rust" -source "Documentation/Kconfig" - endmenu # Kernel hacking diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 54b0893cae66..5cf38abdaf9d 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2079,17 +2079,6 @@ sub process_name($$) { sub process_body($$) { my $file = shift; - # Until all named variable macro parameters are - # documented using the bare name (`x`) rather than with - # dots (`x...`), strip the dots: - if ($section =~ /\w\.\.\.$/) { - $section =~ s/\.\.\.$//; - - if ($verbose) { - emit_warning("${file}:$.", "Variable macro arguments should be documented without dots\n"); - } - } - if ($state == STATE_BODY_WITH_BLANK_LINE && /^\s*\*\s?\S/) { dump_section($file, $section, $contents); $section = $section_default; |