Commit 3868772b authored by Linus Torvalds's avatar Linus Torvalds

Merge tag 'docs-5.0' of git://git.lwn.net/linux

Pull documentation update from Jonathan Corbet:
 "A fairly normal cycle for documentation stuff. We have a new document
  on perf security, more Italian translations, more improvements to the
  memory-management docs, improvements to the pathname lookup
  documentation, and the usual array of smaller fixes.

  As is often the case, there are a few reaches outside of
  Documentation/ to adjust kerneldoc comments"

* tag 'docs-5.0' of git://git.lwn.net/linux: (38 commits)
  docs: improve pathname-lookup document structure
  configfs: fix wrong name of struct in documentation
  docs/mm-api: link slab_common.c to "The Slab Cache" section
  slab: make kmem_cache_create{_usercopy} description proper kernel-doc
  doc:process: add links where missing
  docs/core-api: make mm-api.rst more structured
  x86, boot: documentation whitespace fixup
  Documentation: devres: note checking needs when converting
  doc:it: add some process/* translations
  doc:it: fixes in process/1.Intro
  Documentation: convert path-lookup from markdown to resturctured text
  Documentation/admin-guide: update admin-guide index.rst
  Documentation/admin-guide: introduce perf-security.rst file
  scripts/kernel-doc: Fix struct and struct field attribute processing
  Documentation: dev-tools: Fix typos in index.rst
  Correct gen_init_cpio tool's documentation
  Document /proc/pid PID reuse behavior
  Documentation: update path-lookup.md for parallel lookups
  Documentation: Use "while" instead of "whilst"
  dmaengine: Add mailing list address to the documentation
  ...
parents 6f9d71c9 942104a2
......@@ -31,14 +31,13 @@
#define YBLANK 38
#define XOFFSET 8
#define XPULSE 144
#define YOFFSET (63+3)
#define YPULSE (63+6)
#define YOFFSET 3
#define YPULSE 6
#define DPI 72
#define VFREQ 60 /* Hz */
#define TIMING_NAME "Linux XGA"
#define ESTABLISHED_TIMING2_BITS 0x08 /* Bit 3 -> 1024x768 @60 Hz */
#define HSYNC_POL 0
#define VSYNC_POL 0
#define CRC 0x55
#include "edid.S"
......@@ -31,14 +31,13 @@
#define YBLANK 42
#define XOFFSET 48
#define XPULSE 112
#define YOFFSET (63+1)
#define YPULSE (63+3)
#define YOFFSET 1
#define YPULSE 3
#define DPI 72
#define VFREQ 60 /* Hz */
#define TIMING_NAME "Linux SXGA"
/* No ESTABLISHED_TIMINGx_BITS */
#define HSYNC_POL 1
#define VSYNC_POL 1
#define CRC 0xa0
#include "edid.S"
......@@ -31,14 +31,13 @@
#define YBLANK 50
#define XOFFSET 64
#define XPULSE 192
#define YOFFSET (63+1)
#define YPULSE (63+3)
#define YOFFSET 1
#define YPULSE 3
#define DPI 72
#define VFREQ 60 /* Hz */
#define TIMING_NAME "Linux UXGA"
/* No ESTABLISHED_TIMINGx_BITS */
#define HSYNC_POL 1
#define VSYNC_POL 1
#define CRC 0x9d
#include "edid.S"
......@@ -31,14 +31,13 @@
#define YBLANK 39
#define XOFFSET 104
#define XPULSE 176
#define YOFFSET (63+3)
#define YPULSE (63+6)
#define YOFFSET 3
#define YPULSE 6
#define DPI 96
#define VFREQ 60 /* Hz */
#define TIMING_NAME "Linux WSXGA"
/* No ESTABLISHED_TIMINGx_BITS */
#define HSYNC_POL 1
#define VSYNC_POL 1
#define CRC 0x26
#include "edid.S"
......@@ -31,14 +31,13 @@
#define YBLANK 45
#define XOFFSET 88
#define XPULSE 44
#define YOFFSET (63+4)
#define YPULSE (63+5)
#define YOFFSET 4
#define YPULSE 5
#define DPI 96
#define VFREQ 60 /* Hz */
#define TIMING_NAME "Linux FHD"
/* No ESTABLISHED_TIMINGx_BITS */
#define HSYNC_POL 1
#define VSYNC_POL 1
#define CRC 0x05
#include "edid.S"
......@@ -28,14 +28,13 @@
#define YBLANK 28
#define XOFFSET 40
#define XPULSE 128
#define YOFFSET (63+1)
#define YPULSE (63+4)
#define YOFFSET 1
#define YPULSE 4
#define DPI 72
#define VFREQ 60 /* Hz */
#define TIMING_NAME "Linux SVGA"
#define ESTABLISHED_TIMING1_BITS 0x01 /* Bit 0: 800x600 @ 60Hz */
#define HSYNC_POL 1
#define VSYNC_POL 1
#define CRC 0xc2
#include "edid.S"
......@@ -45,14 +45,5 @@ EDID:
#define YPIX vdisp
#define YBLANK vtotal-vdisp
#define YOFFSET (63+(vsyncstart-vdisp))
#define YPULSE (63+(vsyncend-vsyncstart))
The CRC value in the last line
#define CRC 0x55
also is a bit tricky. After a first version of the binary data set is
created, it must be checked with the "edid-decode" utility which will
most probably complain about a wrong CRC. Fortunately, the utility also
displays the correct CRC which must then be inserted into the source
file. After the make procedure is repeated, the EDID data set is ready
to be used.
#define YOFFSET vsyncstart-vdisp
#define YPULSE vsyncend-vsyncstart
......@@ -15,10 +15,21 @@ clean:
%.o: %.S
@cc -c $^
%.bin: %.o
%.bin.nocrc: %.o
@objcopy -Obinary $^ $@
%.bin.ihex: %.o
%.crc: %.bin.nocrc
@list=$$(for i in `seq 1 127`; do head -c$$i $^ | tail -c1 \
| hexdump -v -e '/1 "%02X+"'; done); \
echo "ibase=16;100-($${list%?})%100" | bc >$@
%.p: %.crc %.S
@cc -c -DCRC="$$(cat $*.crc)" -o $@ $*.S
%.bin: %.p
@objcopy -Obinary $^ $@
%.bin.ihex: %.p
@objcopy -Oihex $^ $@
@dos2unix $@ 2>/dev/null
......
......@@ -47,9 +47,11 @@
#define mfgname2id(v1,v2,v3) \
((((v1-'@')&0x1f)<<10)+(((v2-'@')&0x1f)<<5)+((v3-'@')&0x1f))
#define swap16(v1) ((v1>>8)+((v1&0xff)<<8))
#define lsbs2(v1,v2) (((v1&0x0f)<<4)+(v2&0x0f))
#define msbs2(v1,v2) ((((v1>>8)&0x0f)<<4)+((v2>>8)&0x0f))
#define msbs4(v1,v2,v3,v4) \
(((v1&0x03)>>2)+((v2&0x03)>>4)+((v3&0x03)>>6)+((v4&0x03)>>8))
((((v1>>8)&0x03)<<6)+(((v2>>8)&0x03)<<4)+\
(((v3>>4)&0x03)<<2)+((v4>>4)&0x03))
#define pixdpi2mm(pix,dpi) ((pix*25)/dpi)
#define xsize pixdpi2mm(XPIX,DPI)
#define ysize pixdpi2mm(YPIX,DPI)
......@@ -200,9 +202,9 @@ y_msbs: .byte msbs2(YPIX,YBLANK)
x_snc_off_lsb: .byte XOFFSET&0xff
/* Horizontal sync pulse width pixels 8 lsbits (0-1023) */
x_snc_pls_lsb: .byte XPULSE&0xff
/* Bits 7-4 Vertical sync offset lines 4 lsbits -63)
Bits 3-0 Vertical sync pulse width lines 4 lsbits -63) */
y_snc_lsb: .byte ((YOFFSET-63)<<4)+(YPULSE-63)
/* Bits 7-4 Vertical sync offset lines 4 lsbits (0-63)
Bits 3-0 Vertical sync pulse width lines 4 lsbits (0-63) */
y_snc_lsb: .byte lsbs2(YOFFSET, YPULSE)
/* Bits 7-6 Horizontal sync offset pixels 2 msbits
Bits 5-4 Horizontal sync pulse width pixels 2 msbits
Bits 3-2 Vertical sync offset lines 2 msbits
......
.. _admin_devices:
Linux allocated devices (4.x+ version)
======================================
......
......@@ -110,8 +110,8 @@ If your query set is big, you can batch them too::
~# cat query-batch-file > <debugfs>/dynamic_debug/control
A another way is to use wildcard. The match rule support ``*`` (matches
zero or more characters) and ``?`` (matches exactly one character).For
Another way is to use wildcards. The match rule supports ``*`` (matches
zero or more characters) and ``?`` (matches exactly one character). For
example, you can match all usb drivers::
~# echo "file drivers/usb/* +p" > <debugfs>/dynamic_debug/control
......@@ -258,7 +258,7 @@ this boot parameter for debugging purposes.
If ``foo`` module is not built-in, ``foo.dyndbg`` will still be processed at
boot time, without effect, but will be reprocessed when module is
loaded later. ``dyndbg_query=`` and bare ``dyndbg=`` are only processed at
loaded later. ``ddebug_query=`` and bare ``dyndbg=`` are only processed at
boot.
......@@ -301,7 +301,7 @@ The ``dyndbg`` option is a "fake" module parameter, which means:
For ``CONFIG_DYNAMIC_DEBUG`` kernels, any settings given at boot-time (or
enabled by ``-DDEBUG`` flag during compilation) can be disabled later via
the sysfs interface if the debug messages are no longer needed::
the debugfs interface if the debug messages are no longer needed::
echo "module module_name -p" > <debugfs>/dynamic_debug/control
......
......@@ -76,6 +76,7 @@ configure specific aspects of kernel behavior to your liking.
thunderbolt
LSM/index
mm/index
perf-security
.. only:: subproject and html
......
......@@ -331,7 +331,7 @@
APC and your system crashes randomly.
apic= [APIC,X86] Advanced Programmable Interrupt Controller
Change the output verbosity whilst booting
Change the output verbosity while booting
Format: { quiet (default) | verbose | debug }
Change the amount of debugging information output
when initialising the APIC and IO-APIC components.
......
......@@ -4,13 +4,13 @@
Concepts overview
=================
The memory management in Linux is complex system that evolved over the
years and included more and more functionality to support variety of
The memory management in Linux is a complex system that evolved over the
years and included more and more functionality to support a variety of
systems from MMU-less microcontrollers to supercomputers. The memory
management for systems without MMU is called ``nommu`` and it
management for systems without an MMU is called ``nommu`` and it
definitely deserves a dedicated document, which hopefully will be
eventually written. Yet, although some of the concepts are the same,
here we assume that MMU is available and CPU can translate a virtual
here we assume that an MMU is available and a CPU can translate a virtual
address to a physical address.
.. contents:: :local:
......@@ -21,10 +21,10 @@ Virtual Memory Primer
The physical memory in a computer system is a limited resource and
even for systems that support memory hotplug there is a hard limit on
the amount of memory that can be installed. The physical memory is not
necessary contiguous, it might be accessible as a set of distinct
necessarily contiguous; it might be accessible as a set of distinct
address ranges. Besides, different CPU architectures, and even
different implementations of the same architecture have different view
how these address ranges defined.
different implementations of the same architecture have different views
of how these address ranges are defined.
All this makes dealing directly with physical memory quite complex and
to avoid this complexity a concept of virtual memory was developed.
......@@ -48,8 +48,8 @@ appropriate kernel configuration option.
Each physical memory page can be mapped as one or more virtual
pages. These mappings are described by page tables that allow
translation from virtual address used by programs to real address in
the physical memory. The page tables organized hierarchically.
translation from a virtual address used by programs to the physical
memory address. The page tables are organized hierarchically.
The tables at the lowest level of the hierarchy contain physical
addresses of actual pages used by the software. The tables at higher
......@@ -121,8 +121,8 @@ Nodes
Many multi-processor machines are NUMA - Non-Uniform Memory Access -
systems. In such systems the memory is arranged into banks that have
different access latency depending on the "distance" from the
processor. Each bank is referred as `node` and for each node Linux
constructs an independent memory management subsystem. A node has it's
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/vm/numa.rst <numa>` and in
......@@ -149,9 +149,9 @@ for program's stack and heap or by explicit calls to mmap(2) system
call. Usually, the anonymous mappings only define virtual memory areas
that the program is allowed to access. The read accesses will result
in creation of a page table entry that references a special physical
page filled with zeroes. When the program performs a write, regular
page filled with zeroes. When the program performs a write, a regular
physical page will be allocated to hold the written data. The page
will be marked dirty and if the kernel will decide to repurpose it,
will be marked dirty and if the kernel decides to repurpose it,
the dirty page will be swapped out.
Reclaim
......@@ -181,8 +181,8 @@ pressure.
The process of freeing the reclaimable physical memory pages and
repurposing them is called (surprise!) `reclaim`. Linux can reclaim
pages either asynchronously or synchronously, depending on the state
of the system. When system is not loaded, most of the memory is free
and allocation request will be satisfied immediately from the free
of the system. When the system is not loaded, most of the memory is free
and allocation requests will be satisfied immediately from the free
pages supply. As the load increases, the amount of the free pages goes
down and when it reaches a certain threshold (high watermark), an
allocation request will awaken the ``kswapd`` daemon. It will
......@@ -190,7 +190,7 @@ asynchronously scan memory pages and either just free them if the data
they contain is available elsewhere, or evict to the backing storage
device (remember those dirty pages?). As memory usage increases even
more and reaches another threshold - min watermark - an allocation
will trigger the `direct reclaim`. In this case allocation is stalled
will trigger `direct reclaim`. In this case allocation is stalled
until enough memory pages are reclaimed to satisfy the request.
Compaction
......@@ -200,7 +200,7 @@ As the system runs, tasks allocate and free the memory and it becomes
fragmented. Although with virtual memory it is possible to present
scattered physical pages as virtually contiguous range, sometimes it is
necessary to allocate large physically contiguous memory areas. Such
need may arise, for instance, when a device driver requires large
need may arise, for instance, when a device driver requires a large
buffer for DMA, or when THP allocates a huge page. Memory `compaction`
addresses the fragmentation issue. This mechanism moves occupied pages
from the lower part of a memory zone to free pages in the upper part
......@@ -208,15 +208,16 @@ of the zone. When a compaction scan is finished free pages are grouped
together at the beginning of the zone and allocations of large
physically contiguous areas become possible.
Like reclaim, the compaction may happen asynchronously in ``kcompactd``
daemon or synchronously as a result of memory allocation request.
Like reclaim, the compaction may happen asynchronously in the ``kcompactd``
daemon or synchronously as a result of a memory allocation request.
OOM killer
==========
It may happen, that on a loaded machine memory will be exhausted. When
the kernel detects that the system runs out of memory (OOM) it invokes
`OOM killer`. Its mission is simple: all it has to do is to select a
task to sacrifice for the sake of the overall system health. The
selected task is killed in a hope that after it exits enough memory
will be freed to continue normal operation.
It is possible that on a loaded machine memory will be exhausted and the
kernel will be unable to reclaim enough memory to continue to operate. In
order to save the rest of the system, it invokes the `OOM killer`.
The `OOM killer` selects a task to sacrifice for the sake of the overall
system health. The selected task is killed in a hope that after it exits
enough memory will be freed to continue normal operation.
.. _perf_security:
Perf Events and tool security
=============================
Overview
--------
Usage of Performance Counters for Linux (perf_events) [1]_ , [2]_ , [3]_ can
impose a considerable risk of leaking sensitive data accessed by monitored
processes. The data leakage is possible both in scenarios of direct usage of
perf_events system call API [2]_ and over data files generated by Perf tool user
mode utility (Perf) [3]_ , [4]_ . The risk depends on the nature of data that
perf_events performance monitoring units (PMU) [2]_ collect and expose for
performance analysis. Having that said perf_events/Perf performance monitoring
is the subject for security access control management [5]_ .
perf_events/Perf access control
-------------------------------
To perform security checks, the Linux implementation splits processes into two
categories [6]_ : a) privileged processes (whose effective user ID is 0, referred
to as superuser or root), and b) unprivileged processes (whose effective UID is
nonzero). Privileged processes bypass all kernel security permission checks so
perf_events performance monitoring is fully available to privileged processes
without access, scope and resource restrictions.
Unprivileged processes are subject to a full security permission check based on
the process's credentials [5]_ (usually: effective UID, effective GID, and
supplementary group list).
Linux divides the privileges traditionally associated with superuser into
distinct units, known as capabilities [6]_ , which can be independently enabled
and disabled on per-thread basis for processes and files of unprivileged users.
Unprivileged processes with enabled CAP_SYS_ADMIN capability are treated as
privileged processes with respect to perf_events performance monitoring and
bypass *scope* permissions checks in the kernel.
Unprivileged processes using perf_events system call API is also subject for
PTRACE_MODE_READ_REALCREDS ptrace access mode check [7]_ , whose outcome
determines whether monitoring is permitted. So unprivileged processes provided
with CAP_SYS_PTRACE capability are effectively permitted to pass the check.
Other capabilities being granted to unprivileged processes can effectively
enable capturing of additional data required for later performance analysis of
monitored processes or a system. For example, CAP_SYSLOG capability permits
reading kernel space memory addresses from /proc/kallsyms file.
perf_events/Perf unprivileged users
-----------------------------------
perf_events/Perf *scope* and *access* control for unprivileged processes is
governed by perf_event_paranoid [2]_ setting:
-1:
Impose no *scope* and *access* restrictions on using perf_events performance
monitoring. Per-user per-cpu perf_event_mlock_kb [2]_ locking limit is
ignored when allocating memory buffers for storing performance data.
This is the least secure mode since allowed monitored *scope* is
maximized and no perf_events specific limits are imposed on *resources*
allocated for performance monitoring.
>=0:
*scope* includes per-process and system wide performance monitoring
but excludes raw tracepoints and ftrace function tracepoints monitoring.
CPU and system events happened when executing either in user or
in kernel space can be monitored and captured for later analysis.
Per-user per-cpu perf_event_mlock_kb locking limit is imposed but
ignored for unprivileged processes with CAP_IPC_LOCK [6]_ capability.
>=1:
*scope* includes per-process performance monitoring only and excludes
system wide performance monitoring. CPU and system events happened when
executing either in user or in kernel space can be monitored and
captured for later analysis. Per-user per-cpu perf_event_mlock_kb
locking limit is imposed but ignored for unprivileged processes with
CAP_IPC_LOCK capability.
>=2:
*scope* includes per-process performance monitoring only. CPU and system
events happened when executing in user space only can be monitored and
captured for later analysis. Per-user per-cpu perf_event_mlock_kb
locking limit is imposed but ignored for unprivileged processes with
CAP_IPC_LOCK capability.
Bibliography
------------
.. [1] `<https://lwn.net/Articles/337493/>`_
.. [2] `<http://man7.org/linux/man-pages/man2/perf_event_open.2.html>`_
.. [3] `<http://web.eece.maine.edu/~vweaver/projects/perf_events/>`_
.. [4] `<https://perf.wiki.kernel.org/index.php/Main_Page>`_
.. [5] `<https://www.kernel.org/doc/html/latest/security/credentials.html>`_
.. [6] `<http://man7.org/linux/man-pages/man7/capabilities.7.html>`_
.. [7] `<http://man7.org/linux/man-pages/man2/ptrace.2.html>`_
......@@ -54,7 +54,7 @@ those errors are correctable.
Types of errors
---------------
Most mechanisms used on modern systems use use technologies like Hamming
Most mechanisms used on modern systems use technologies like Hamming
Codes that allow error correction when the number of errors on a bit packet
is below a threshold. If the number of errors is above, those mechanisms
can indicate with a high degree of confidence that an error happened, but
......
......@@ -44,7 +44,7 @@ only valid reason for deferring the publication of a fix is to accommodate
the logistics of QA and large scale rollouts which require release
coordination.
Whilst embargoed information may be shared with trusted individuals in
While embargoed information may be shared with trusted individuals in
order to develop a fix, such information will not be published alongside
the fix or on any other disclosure channel without the permission of the
reporter. This includes but is not limited to the original bug report
......
......@@ -126,7 +126,7 @@ tagged list.
The boot loader must pass at a minimum the size and location of the
system memory, and the root filesystem location. The dtb must be
placed in a region of memory where the kernel decompressor will not
overwrite it, whilst remaining within the region which will be covered
overwrite it, while remaining within the region which will be covered
by the kernel's low-memory mapping.
A safe location is just above the 128MiB boundary from start of RAM.
......
......@@ -55,7 +55,7 @@ out s3c2410 API, then here are some notes on the process.
as they have the same arguments, and can either take the pin specific
values, or the more generic special-function-number arguments.
3) s3c2410_gpio_pullup() changes have the problem that whilst the
3) s3c2410_gpio_pullup() changes have the problem that while the
s3c2410_gpio_pullup(x, 1) can be easily translated to the
s3c_gpio_setpull(x, S3C_GPIO_PULL_NONE), the s3c2410_gpio_pullup(x, 0)
are not so easy.
......
......@@ -17,7 +17,7 @@ Introduction
versions.
The S3C2416 and S3C2450 devices are very similar and S3C2450 support is
included under the arch/arm/mach-s3c2416 directory. Note, whilst core
included under the arch/arm/mach-s3c2416 directory. Note, while core
support for these SoCs is in, work on some of the extra peripherals
and extra interrupts is still ongoing.
......
......@@ -87,7 +87,7 @@ Debugging
suspending, which means that use of printascii() or similar direct
access to the UARTs will cause the debug to stop.
2) Whilst the pm code itself will attempt to re-enable the UART clocks,
2) While the pm code itself will attempt to re-enable the UART clocks,
care should be taken that any external clock sources that the UARTs
rely on are still enabled at that point.
......
......@@ -34,7 +34,7 @@ properties:
8. The array can iterated over. The objects will not necessarily come out in
key order.
9. The array can be iterated over whilst it is being modified, provided the
9. The array can be iterated over while it is being modified, provided the
RCU readlock is being held by the iterator. Note, however, under these
circumstances, some objects may be seen more than once. If this is a
problem, the iterator should lock against modification. Objects will not
......@@ -42,7 +42,7 @@ properties:
10. Objects in the array can be looked up by means of their index key.
11. Objects can be looked up whilst the array is being modified, provided the
11. Objects can be looked up while the array is being modified, provided the
RCU readlock is being held by the thread doing the look up.
The implementation uses a tree of 16-pointer nodes internally that are indexed
......@@ -273,7 +273,7 @@ The function will return ``0`` if successful and ``-ENOMEM`` if there wasn't
enough memory.
It is possible for other threads to iterate over or search the array under
the RCU read lock whilst this function is in progress. The caller should
the RCU read lock while this function is in progress. The caller should
lock exclusively against other modifiers of the array.
......
.. _memory-allocation:
=======================
Memory Allocation Guide
=======================
......
......@@ -46,11 +46,20 @@ The Slab Cache
.. kernel-doc:: mm/slab.c
:export:
.. kernel-doc:: mm/slab_common.c
:export:
.. kernel-doc:: mm/util.c
:functions: kfree_const kvmalloc_node kvfree
More Memory Management Functions
================================
Virtually Contiguous Mappings
=============================
.. kernel-doc:: mm/vmalloc.c
:export:
File Mapping and Page Cache
===========================
.. kernel-doc:: mm/readahead.c
:export:
......@@ -58,23 +67,28 @@ More Memory Management Functions
.. kernel-doc:: mm/filemap.c
:export:
.. kernel-doc:: mm/memory.c
.. kernel-doc:: mm/page-writeback.c
:export:
.. kernel-doc:: mm/vmalloc.c
.. kernel-doc:: mm/truncate.c
:export:
.. kernel-doc:: mm/page_alloc.c
:internal:
Memory pools
============
.. kernel-doc:: mm/mempool.c
:export:
DMA pools
=========
.. kernel-doc:: mm/dmapool.c
:export:
.. kernel-doc:: mm/page-writeback.c
:export:
More Memory Management Functions
================================
.. kernel-doc:: mm/truncate.c
.. kernel-doc:: mm/memory.c
:export:
.. kernel-doc:: mm/page_alloc.c
......@@ -4,6 +4,8 @@
.. highlight:: none
.. _devtools_coccinelle:
Coccinelle
==========
......
......@@ -3,8 +3,8 @@ Development tools for the kernel
================================
This document is a collection of documents about development tools that can
be used to work on the kernel. For now, the documents have been pulled
together without any significant effot to integrate them into a coherent
be used to work on the kernel. For now, the documents have been pulled
together without any significant effort to integrate them into a coherent
whole; patches welcome!
.. class:: toc-title
......
......@@ -9,7 +9,7 @@ and booting a kernel.
On some systems, hot-plug tests could hang forever waiting for cpu and
memory to be ready to be offlined. A special hot-plug target is created
to run full range of hot-plug tests. In default mode, hot-plug tests run
to run the full range of hot-plug tests. In default mode, hot-plug tests run
in safe mode with a limited scope. In limited mode, cpu-hotplug test is
run on a single cpu as opposed to all hotplug capable cpus, and memory
hotplug test is run on 2% of hotplug capable memory instead of 10%.
......@@ -89,9 +89,9 @@ Note that some tests will require root privileges.
Install selftests
=================
You can use kselftest_install.sh tool installs selftests in default
location which is tools/testing/selftests/kselftest or a user specified
location.
You can use the kselftest_install.sh tool to install selftests in the
default location, which is tools/testing/selftests/kselftest, or in a
user specified location.
To install selftests in default location::
......@@ -109,7 +109,7 @@ Running installed selftests
Kselftest install as well as the Kselftest tarball provide a script
named "run_kselftest.sh" to run the tests.
You can simply do the following to run the installed Kselftests. Please
You can simply do the following to run the installed Kselftests. Please
note some tests will require root privileges::
$ cd kselftest
......@@ -139,7 +139,7 @@ Contributing new tests (details)
default.
TEST_CUSTOM_PROGS should be used by tests that require custom build
rule and prevent common build rule use.
rules and prevent common build rule use.
TEST_PROGS are for test shell scripts. Please ensure shell script has
its exec bit set. Otherwise, lib.mk run_tests will generate a warning.
......
......@@ -146,7 +146,7 @@ The target is named "raid" and it accepts the following parameters:
[data_offset <sectors>]
This option value defines the offset into each data device
where the data starts. This is used to provide out-of-place
reshaping space to avoid writing over data whilst
reshaping space to avoid writing over data while
changing the layout of stripes, hence an interruption/crash
may happen at any time without the risk of losing data.
E.g. when adding devices to an existing raid set during
......
......@@ -142,7 +142,7 @@ characterised by the following graph:
The graph is split in two parts delimited by time 1ms on the X-axis.
The graph curve with X-axis values = { x | 0 < x < 1ms } has a steep slope
and denotes the energy costs incurred whilst entering and leaving the idle
and denotes the energy costs incurred while entering and leaving the idle
state.
The graph curve in the area delimited by X-axis values = {x | x > 1ms } has
shallower slope and essentially represents the energy consumption of the idle
......
......@@ -56,7 +56,7 @@ For CAM, this 24-bit offset is:
cfg_offset(bus, device, function, register) =
bus << 16 | device << 11 | function << 8 | register
Whilst ECAM extends this by 4 bits to accommodate 4k of function space:
While ECAM extends this by 4 bits to accommodate 4k of function space:
cfg_offset(bus, device, function, register) =
bus << 20 | device << 15 | function << 12 | register
......
......@@ -16,7 +16,7 @@ Optional properties:
- linux,rs485-enabled-at-boot-time: empty property telling to enable the rs485
feature at boot time. It can be disabled later with proper ioctl.
- rs485-rx-during-tx: empty property that enables the receiving of data even
whilst sending data.
while sending data.
RS485 example for Atmel USART:
usart0: serial@fff8c000 {
......
......@@ -77,7 +77,7 @@ The general format of a function and function-like macro kernel-doc comment is::
* Context: Describes whether the function can sleep, what locks it takes,
* releases, or expects to be held. It can extend over multiple
* lines.
* Return: Describe the return value of foobar.
* Return: Describe the return value of function_name.
*
* The return value description can also have multiple paragraphs, and should
* be placed at the end of the comment block.
......
.. _sphinxdoc:
Introduction
============
......
......@@ -11,6 +11,10 @@ This small document introduces how to test DMA drivers using dmatest module.
capability of the following: DMA_MEMCPY (memory-to-memory), DMA_MEMSET
(const-to-memory or memory-to-memory, when emulated), DMA_XOR, DMA_PQ.
.. note::
In case of any related questions use the official mailing list
dmaengine@vger.kernel.org.
Part 1 - How to build the test module
=====================================
......
......@@ -6,6 +6,8 @@
.. |struct wakeup_source| replace:: :c:type:`struct wakeup_source <wakeup_source>`
.. |struct device| replace:: :c:type:`struct device <device>`
.. _driverapi_pm_devices:
==============================
Device Power Management Basics
==============================
......
......@@ -132,6 +132,13 @@ devres. Complexity is shifted from less maintained low level drivers
to better maintained higher layer. Also, as init failure path is
shared with exit path, both can get more testing.
Note though that when converting current calls or assignments to
managed devm_* versions it is up to you to check if internal operations
like allocating memory, have failed. Managed resources pertains to the
freeing of these resources *only* - all other checks needed are still
on you. In some cases this may mean introducing checks that were not
necessary before moving to the managed devm_* calls.
3. Devres group
---------------
......
......@@ -52,7 +52,7 @@ user root (0). INITRAMFS_ROOT_GID can be set to a group ID that needs
to be mapped to group root (0).
A source file must be directives in the format required by the
usr/gen_init_cpio utility (run 'usr/gen_init_cpio --help' to get the
usr/gen_init_cpio utility (run 'usr/gen_init_cpio -h' to get the
file format). The directives in the file will be passed directly to
usr/gen_init_cpio.
......
......@@ -704,7 +704,7 @@ FS-Cache provides some utilities that a cache backend may make use of:
void fscache_get_retrieval(struct fscache_retrieval *op);
void fscache_put_retrieval(struct fscache_retrieval *op);
These two functions are used to retain a retrieval record whilst doing
These two functions are used to retain a retrieval record while doing
asynchronous data retrieval and block allocation.
......
......@@ -45,7 +45,7 @@ filesystems are very specific in nature.
CacheFiles creates a misc character device - "/dev/cachefiles" - that is used
to communication with the daemon. Only one thing may have this open at once,
and whilst it is open, a cache is at least partially in existence. The daemon
and while it is open, a cache is at least partially in existence. The daemon
opens this and sends commands down it to control the cache.
CacheFiles is currently limited to a single cache.
......@@ -163,7 +163,7 @@ Do not mount other things within the cache as this will cause problems. The
kernel module contains its own very cut-down path walking facility that ignores
mountpoints, but the daemon can't avoid them.
Do not create, rename or unlink files and directories in the cache whilst the
Do not create, rename or unlink files and directories in the cache while the
cache is active, as this may cause the state to become uncertain.
Renaming files in the cache might make objects appear to be other objects (the
......
......@@ -382,7 +382,7 @@ MISCELLANEOUS OBJECT REGISTRATION
An optional step is to request an object of miscellaneous type be created in
the cache. This is almost identical to index cookie acquisition. The only
difference is that the type in the object definition should be something other
than index type. Whilst the parent object could be an index, it's more likely
than index type. While the parent object could be an index, it's more likely
it would be some other type of object such as a data file.
xattr->cache =
......
......@@ -171,7 +171,7 @@ Operations are used through the following procedure:
(3) If the submitting thread wants to do the work itself, and has marked the
operation with FSCACHE_OP_MYTHREAD, then it should monitor
FSCACHE_OP_WAITING as described above and check the state of the object if
necessary (the object might have died whilst the thread was waiting).
necessary (the object might have died while the thread was waiting).
When it has finished doing its processing, it should call
fscache_op_complete() and fscache_put_operation() on it.
......
......@@ -216,7 +216,7 @@ be called whenever userspace asks for a write(2) on the attribute.
[struct configfs_bin_attribute]
struct configfs_attribute {
struct configfs_bin_attribute {
struct configfs_attribute cb_attr;
void *cb_private;
size_t cb_max_size;
......
......@@ -359,3 +359,24 @@ encryption of files and directories.
:maxdepth: 2
fscrypt
Pathname lookup
===============
This write-up is based on three articles published at lwn.net:
- <https://lwn.net/Articles/649115/> Pathname lookup in Linux
- <https://lwn.net/Articles/649729/> RCU-walk: faster pathname lookup in Linux
- <https://lwn.net/Articles/650786/> A walk among the symlinks
Written by Neil Brown with help from Al Viro and Jon Corbet.
It has subsequently been updated to reflect changes in the kernel
including:
- per-directory parallel name lookup.
.. toctree::
:maxdepth: 2
path-lookup.rst
......@@ -125,6 +125,13 @@ process running on the system, which is named after the process ID (PID).
The link self points to the process reading the file system. Each process
subdirectory has the entries listed in Table 1-1.
Note that an open a file descriptor to /proc/<pid> or to any of its
contained files or subdirectories does not prevent <pid> being reused
for some other process in the event that <pid> exits. Operations on
open /proc/<pid> file descriptors corresponding to dead processes
never act on any new process that the kernel may, through chance, have
also assigned the process ID <pid>. Instead, operations on these FDs
usually fail with ESRCH.
Table 1-1: Process specific entries in /proc
..............................................................................
......@@ -194,8 +201,10 @@ read the file /proc/PID/status:
CapPrm: 0000000000000000
CapEff: 0000000000000000
CapBnd: ffffffffffffffff
CapAmb: 0000000000000000
NoNewPrivs: 0
Seccomp: 0
Speculation_Store_Bypass: thread vulnerable
voluntary_ctxt_switches: 0
nonvoluntary_ctxt_switches: 1
......@@ -215,7 +224,7 @@ asynchronous manner and the value may not be very precise. To see a precise
snapshot of a moment, you can see /proc/<pid>/smaps file and scan page table.
It's slow but very precise.
Table 1-2: Contents of the status files (as of 4.8)
Table 1-2: Contents of the status files (as of 4.19)
..............................................................................
Field Content
Name filename of the executable
......@@ -270,8 +279,10 @@ Table 1-2: Contents of the status files (as of 4.8)
CapPrm bitmap of permitted capabilities
CapEff bitmap of effective capabilities
CapBnd bitmap of capabilities bounding set
CapAmb bitmap of ambient capabilities
NoNewPrivs no_new_privs, like prctl(PR_GET_NO_NEW_PRIV, ...)
Seccomp seccomp mode, like prctl(PR_GET_SECCOMP, ...)
Speculation_Store_Bypass speculative store bypass mitigation status
Cpus_allowed mask of CPUs on which this process may run
Cpus_allowed_list Same as previous, but in "list format"
Mems_allowed mask of memory nodes allowed to this process
......
......@@ -87,7 +87,7 @@ addressed with 16 direct blocks.
For more than 16 blocks an indirect addressing in form of another tree is
used. (scheme is the same as the one used for the superblock root nodes)
The filesize is stored 64bit. Inode counting starts with 1. (whilst long
The filesize is stored 64bit. Inode counting starts with 1. (while long
filename inodes start with 0)
Directories
......@@ -155,7 +155,7 @@ Then userspace.
The requirement for a static, fixed preallocated system area comes from how
qnx6fs deals with writes.
Each superblock got it's own half of the system area. So superblock #1
always uses blocks from the lower half whilst superblock #2 just writes to
always uses blocks from the lower half while superblock #2 just writes to
blocks represented by the upper half bitmap system area bits.
Bitmap blocks, Inode blocks and indirect addressing blocks for those two
......
......@@ -452,7 +452,7 @@ RETURN VALUE
ERRORS
EACCESS
EACCES
The current user does not have write access on the spufs mount
point.
......
......@@ -1131,7 +1131,7 @@ struct dentry_operations {
d_manage: called to allow the filesystem to manage the transition from a
dentry (optional). This allows autofs, for example, to hold up clients
waiting to explore behind a 'mountpoint' whilst letting the daemon go
waiting to explore behind a 'mountpoint' while letting the daemon go
past and construct the subtree there. 0 should be returned to let the
calling process continue. -EISDIR can be returned to tell pathwalk to
use this directory as an ordinary directory and to ignore anything
......
......@@ -110,7 +110,7 @@ owner field in the metadata object, we can immediately do top down validation to
determine the scope of the problem.
Different types of metadata have different owner identifiers. For example,
directory, attribute and extent tree blocks are all owned by an inode, whilst
directory, attribute and extent tree blocks are all owned by an inode, while
freespace btree blocks are owned by an allocation group. Hence the size and
contents of the owner field are determined by the type of metadata object we are
looking at. The owner information can also identify misplaced writes (e.g.
......
......@@ -417,7 +417,7 @@ level directory:
filesystem from ever unmounting fully in the case of "retry forever"
handler configurations.
Note: there is no guarantee that fail_at_unmount can be set whilst an
Note: there is no guarantee that fail_at_unmount can be set while an
unmount is in progress. It is possible that the sysfs entries are
removed by the unmounting filesystem before a "retry forever" error
handler configuration causes unmount to hang, and hence the filesystem
......
......@@ -190,11 +190,11 @@ ENOSPC:
Simply running out of kernel/system memory is signalled through ENOMEM.
EPERM/EACCESS:
EPERM/EACCES:
Returned for an operation that is valid, but needs more privileges.
E.g. root-only or much more common, DRM master-only operations return
this when when called by unpriviledged clients. There's no clear
difference between EACCESS and EPERM.
difference between EACCES and EPERM.
ENODEV:
The device is not (yet) present or fully initialized.
......
......@@ -15,7 +15,7 @@ existing subsystems with minimal additional code. Examples are the disk-activity
nand-disk and sharpsl-charge triggers. With led triggers disabled, the code
optimises away.
Complex triggers whilst available to all LEDs have LED specific
Complex triggers while available to all LEDs have LED specific
parameters and work on a per LED basis. The timer trigger is an example.
The timer trigger will periodically change the LED brightness between
LED_OFF and the current brightness setting. The "on" and "off" time can
......
......@@ -4003,7 +4003,7 @@ demodulator. It receives radio frequency (RF) from the antenna and
converts that received signal to lower intermediate frequency (IF) or
baseband frequency (BB). Tuners that could do baseband output are often
called Zero-IF tuners. Older tuners were typically simple PLL tuners
inside a metal box, whilst newer ones are highly integrated chips
inside a metal box, while newer ones are highly integrated chips
without a metal box "silicon tuners". These controls are mostly
applicable for new feature rich silicon tuners, just because older
tuners does not have much adjustable features.
......
......@@ -587,7 +587,7 @@ leading to the following situation:
(Q == &B) and (D == 2) ????
Whilst this may seem like a failure of coherency or causality maintenance, it
While this may seem like a failure of coherency or causality maintenance, it
isn't, and this behaviour can be observed on certain real CPUs (such as the DEC
Alpha).
......@@ -2008,7 +2008,7 @@ for each construct. These operations all imply certain barriers:
Certain locking variants of the ACQUIRE operation may fail, either due to
being unable to get the lock immediately, or due to receiving an unblocked
signal whilst asleep waiting for the lock to become available. Failed
signal while asleep waiting for the lock to become available. Failed
locks do not imply any sort of barrier.
[!] Note: one of the consequences of lock ACQUIREs and RELEASEs being only
......@@ -2508,7 +2508,7 @@ CPU, that CPU's dependency ordering logic will take care of everything else.
ATOMIC OPERATIONS
-----------------
Whilst they are technically interprocessor interaction considerations, atomic
While they are technically interprocessor interaction considerations, atomic
operations are noted specially as some of them imply full memory barriers and
some don't, but they're very heavily relied on as a group throughout the
kernel.
......@@ -2531,7 +2531,7 @@ the device to malfunction.
Inside of the Linux kernel, I/O should be done through the appropriate accessor
routines - such as inb() or writel() - which know how to make such accesses
appropriately sequential. Whilst this, for the most part, renders the explicit
appropriately sequential. While this, for the most part, renders the explicit
use of memory barriers unnecessary, there are a couple of situations where they
might be needed:
......@@ -2555,7 +2555,7 @@ access the device.
This may be alleviated - at least in part - by disabling local interrupts (a
form of locking), such that the critical operations are all contained within
the interrupt-disabled section in the driver. Whilst the driver's interrupt
the interrupt-disabled section in the driver. While the driver's interrupt
routine is executing, the driver's core may not run on the same CPU, and its
interrupt is not permitted to happen again until the current interrupt has been
handled, thus the interrupt handler does not need to lock against that.
......@@ -2763,7 +2763,7 @@ CACHE COHERENCY
Life isn't quite as simple as it may appear above, however: for while the
caches are expected to be coherent, there's no guarantee that that coherency
will be ordered. This means that whilst changes made on one CPU will
will be ordered. This means that while changes made on one CPU will
eventually become visible on all CPUs, there's no guarantee that they will
become apparent in the same order on those other CPUs.
......@@ -2799,7 +2799,7 @@ Imagine the system has the following properties:
(*) an even-numbered cache line may be in cache B, cache D or it may still be
resident in memory;
(*) whilst the CPU core is interrogating one cache, the other cache may be
(*) while the CPU core is interrogating one cache, the other cache may be
making use of the bus to access the rest of the system - perhaps to
displace a dirty cacheline or to do a speculative load;
......@@ -2835,7 +2835,7 @@ now imagine that the second CPU wants to read those values:
x = *q;
The above pair of reads may then fail to happen in the expected order, as the
cacheline holding p may get updated in one of the second CPU's caches whilst
cacheline holding p may get updated in one of the second CPU's caches while
the update to the cacheline holding v is delayed in the other of the second
CPU's caches by some other cache event:
......@@ -2855,7 +2855,7 @@ CPU's caches by some other cache event:
<C:unbusy>
<C:commit v=2>
Basically, whilst both cachelines will be updated on CPU 2 eventually, there's
Basically, while both cachelines will be updated on CPU 2 eventually, there's
no guarantee that, without intervention, the order of update will be the same
as that committed on CPU 1.
......@@ -2885,7 +2885,7 @@ coherency queue before processing any further requests:
This sort of problem can be encountered on DEC Alpha processors as they have a
split cache that improves performance by making better use of the data bus.
Whilst most CPUs do imply a data dependency barrier on the read when a memory
While most CPUs do imply a data dependency barrier on the read when a memory
access depends on a read, not all do, so it may not be relied on.
Other CPUs may also have split caches, but must coordinate between the various
......@@ -2974,7 +2974,7 @@ assumption doesn't hold because:
thus cutting down on transaction setup costs (memory and PCI devices may
both be able to do this); and
(*) the CPU's data cache may affect the ordering, and whilst cache-coherency
(*) the CPU's data cache may affect the ordering, and while cache-coherency
mechanisms may alleviate this - once the store has actually hit the cache
- there's no guarantee that the coherency management will be propagated in
order to other CPUs.
......
......@@ -84,7 +84,7 @@
Automedia detection is included so that in principle you can disconnect
from, e.g. TP, reconnect to BNC and things will still work (after a
pause whilst the driver figures out where its media went). My tests
pause while the driver figures out where its media went). My tests
using ping showed that it appears to work....
By default, the driver will now autodetect any DECchip based card.
......
......@@ -661,7 +661,7 @@ A server would be set up to accept operations in the following manner:
setsockopt(server, SOL_RXRPC, RXRPC_SECURITY_KEYRING, "AFSkeys", 7);
The keyring can be manipulated after it has been given to the socket. This
permits the server to add more keys, replace keys, etc. whilst it is live.
permits the server to add more keys, replace keys, etc. while it is live.
(3) A local address must then be bound:
......@@ -1032,7 +1032,7 @@ The kernel interface functions are as follows:
struct sockaddr_rxrpc *srx,
struct key *key);
This attempts to partially reinitialise a call and submit it again whilst
This attempts to partially reinitialise a call and submit it again while
reusing the original call's Tx queue to avoid the need to repackage and
re-encrypt the data to be sent. call indicates the call to retry, srx the
new address to send it to and key the encryption key to use for signing or
......@@ -1066,7 +1066,7 @@ The kernel interface functions are as follows:
alive after waiting for a suitable interval.
This allows the caller to work out if the server is still contactable and
if the call is still alive on the server whilst waiting for the server to
if the call is still alive on the server while waiting for the server to
process a client operation.
The second function causes a ping ACK to be transmitted to try to provoke
......@@ -1149,14 +1149,14 @@ adjusted through sysctls in /proc/net/rxrpc/:
(*) connection_expiry
The amount of time in seconds after a connection was last used before we
remove it from the connection list. Whilst a connection is in existence,
remove it from the connection list. While a connection is in existence,
it serves as a placeholder for negotiated security; when it is deleted,
the security must be renegotiated.
(*) transport_expiry
The amount of time in seconds after a transport was last used before we
remove it from the transport list. Whilst a transport is in existence, it
remove it from the transport list. While a transport is in existence, it
serves to anchor the peer data and keeps the connection ID counter.
(*) rxrpc_rx_window_size
......
......@@ -22,7 +22,7 @@ Nomenclature
Some terms used in this document:-
o Regulator - Electronic device that supplies power to other devices.
Most regulators can enable and disable their output whilst
Most regulators can enable and disable their output while
some can control their output voltage and or current.
Input Voltage -> Regulator -> Output Voltage
......
.. _development_process_intro:
Introduction
============
......
......@@ -315,7 +315,8 @@ variety of potential coding problems; it can also propose fixes for those
problems. Quite a few "semantic patches" for the kernel have been packaged
under the scripts/coccinelle directory; running "make coccicheck" will run
through those semantic patches and report on any problems found. See
Documentation/dev-tools/coccinelle.rst for more information.
:ref:`Documentation/dev-tools/coccinelle.rst <devtools_coccinelle>`
for more information.
Other kinds of portability errors are best found by compiling your code for
other architectures. If you do not happen to have an S/390 system or a
......
......@@ -9,9 +9,10 @@ kernel. Unsurprisingly, the kernel development community has evolved a set
of conventions and procedures which are used in the posting of patches;
following them will make life much easier for everybody involved. This
document will attempt to cover these expectations in reasonable detail;
more information can also be found in the files process/submitting-patches.rst,
process/submitting-drivers.rst, and process/submit-checklist.rst in the kernel
documentation directory.
more information can also be found in the files
:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`,
:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`
and :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`.
When to post
......@@ -198,8 +199,10 @@ pass it to diff with the "-X" option.
The tags mentioned above are used to describe how various developers have
been associated with the development of this patch. They are described in
detail in the process/submitting-patches.rst document; what follows here is a
brief summary. Each of these lines has the format:
detail in
the :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
document; what follows here is a brief summary. Each of these lines has
the format:
::
......@@ -210,8 +213,8 @@ The tags in common use are:
- Signed-off-by: this is a developer's certification that he or she has
the right to submit the patch for inclusion into the kernel. It is an
agreement to the Developer's Certificate of Origin, the full text of
which can be found in Documentation/process/submitting-patches.rst. Code
without a proper signoff cannot be merged into the mainline.
which can be found in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
Code without a proper signoff cannot be merged into the mainline.
- Co-developed-by: states that the patch was also created by another developer
along with the original author. This is useful at times when multiple
......@@ -226,7 +229,7 @@ The tags in common use are:
it to work.
- Reviewed-by: the named developer has reviewed the patch for correctness;
see the reviewer's statement in Documentation/process/submitting-patches.rst
see the reviewer's statement in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
for more detail.
- Reported-by: names a user who reported a problem which is fixed by this
......@@ -253,8 +256,8 @@ take care of:
be examined in any detail. If there is any doubt at all, mail the patch
to yourself and convince yourself that it shows up intact.
Documentation/process/email-clients.rst has some helpful hints on making
specific mail clients work for sending patches.
:ref:`Documentation/process/email-clients.rst <email_clients>` has some
helpful hints on making specific mail clients work for sending patches.
- Are you sure your patch is free of silly mistakes? You should always
run patches through scripts/checkpatch.pl and address the complaints it
......
......@@ -5,9 +5,10 @@ For more information
There are numerous sources of information on Linux kernel development and
related topics. First among those will always be the Documentation
directory found in the kernel source distribution. The top-level process/howto.rst
file is an important starting point; process/submitting-patches.rst and
process/submitting-drivers.rst are also something which all kernel developers should
directory found in the kernel source distribution. The top-level :ref:`process/howto.rst <process_howto>`
file is an important starting point; :ref:`process/submitting-patches.rst <submittingpatches>`
and :ref:`process/submitting-drivers.rst <submittingdrivers>`
are also something which all kernel developers should
read. Many internal kernel APIs are documented using the kerneldoc
mechanism; "make htmldocs" or "make pdfdocs" can be used to generate those
documents in HTML or PDF format (though the version of TeX shipped by some
......
.. _addsyscalls:
Adding a New System Call
========================
......
......@@ -326,7 +326,7 @@ Kernel documentation
Sphinx
------
Please see :ref:`sphinx_install` in ``Documentation/doc-guide/sphinx.rst``
Please see :ref:`sphinx_install` in :ref:`Documentation/doc-guide/sphinx.rst <sphinxdoc>`
for details about Sphinx requirements.
Getting updated software
......
......@@ -1075,5 +1075,5 @@ gcc internals and indent, all available from http://www.gnu.org/manual/
WG14 is the international standardization working group for the programming
language C, URL: http://www.open-std.org/JTC1/SC22/WG14/
Kernel process/coding-style.rst, by greg@kroah.com at OLS 2002:
Kernel :ref:`process/coding-style.rst <codingstyle>`, by greg@kroah.com at OLS 2002:
http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
.. _process_howto:
HOWTO do Linux kernel development
=================================
......@@ -296,9 +298,9 @@ two weeks, but it can be longer if there are no pressing problems. A
security-related problem, instead, can cause a release to happen almost
instantly.
The file Documentation/process/stable-kernel-rules.rst in the kernel tree
documents what kinds of changes are acceptable for the -stable tree, and
how the release process works.
The file :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`
in the kernel tree documents what kinds of changes are acceptable for
the -stable tree, and how the release process works.
4.x -git patches
~~~~~~~~~~~~~~~~
......@@ -358,7 +360,8 @@ tool. For details on how to use the kernel bugzilla, please see:
https://bugzilla.kernel.org/page.cgi?id=faq.html
The file admin-guide/reporting-bugs.rst in the main kernel source directory has a good
The file :ref:`admin-guide/reporting-bugs.rst <reportingbugs>`
in the main kernel source directory has a good
template for how to report a possible kernel bug, and details what kind
of information is needed by the kernel developers to help track down the
problem.
......@@ -424,7 +427,7 @@ add your statements between the individual quoted sections instead of
writing at the top of the mail.
If you add patches to your mail, make sure they are plain readable text
as stated in Documentation/process/submitting-patches.rst.
as stated in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
Kernel developers don't want to deal with
attachments or compressed patches; they may want to comment on
individual lines of your patch, which works only that way. Make sure you
......
.. _process_statement_driver:
Kernel Driver Statement
-----------------------
......
Linux Kernel Enforcement Statement
.. _process_statement_kernel:
Linux Kernel Enforcement Statement
----------------------------------
As developers of the Linux kernel, we have a keen interest in how our software
......
.. _magicnumbers:
Linux magic numbers
===================
......
......@@ -5,8 +5,9 @@ Linux kernel management style
This is a short document describing the preferred (or made up, depending
on who you ask) management style for the linux kernel. It's meant to
mirror the process/coding-style.rst document to some degree, and mainly written to
avoid answering [#f1]_ the same (or similar) questions over and over again.
mirror the :ref:`process/coding-style.rst <codingstyle>` document to some
degree, and mainly written to avoid answering [#f1]_ the same (or similar)
questions over and over again.
Management style is very personal and much harder to quantify than
simple coding style rules, so this document may or may not have anything
......
......@@ -16,7 +16,8 @@ you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org
Oh, and we don't really recommend submitting changes to XFree86 :)
Also read the Documentation/process/submitting-patches.rst document.
Also read the :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
document.
Allocating Device Numbers
......@@ -27,7 +28,8 @@ by the Linux assigned name and number authority (currently this is
Torben Mathiasen). The site is http://www.lanana.org/. This
also deals with allocating numbers for devices that are not going to
be submitted to the mainstream kernel.
See Documentation/admin-guide/devices.rst for more information on this.
See :ref:`Documentation/admin-guide/devices.rst <admin_devices>`
for more information on this.
If you don't use assigned numbers then when your device is submitted it will
be given an assigned number even if that is different from values you may
......@@ -117,7 +119,7 @@ PM support:
anything. For the driver testing instructions see
Documentation/power/drivers-testing.txt and for a relatively
complete overview of the power management issues related to
drivers see Documentation/driver-api/pm/devices.rst.
drivers see :ref:`Documentation/driver-api/pm/devices.rst <driverapi_pm_devices>`.
Control:
In general if there is active maintenance of a driver by
......
......@@ -16,7 +16,7 @@ Sep 2002: Dynamically get 3270 input buffer
Sep 2002: Fix tubfs kmalloc()s
* Do read and write lengths correctly in fs3270_read()
and fs3270_write(), whilst never asking kmalloc()
and fs3270_write(), while never asking kmalloc()
for more than 0x800 bytes. Affects tubfs.c and tubio.h.
Sep 2002: Recognize 3270 control unit type 3174
......
......@@ -291,7 +291,7 @@ for example), it must be considered immutable, barring two exceptions:
1. The reference count may be altered.
2. Whilst the keyring subscriptions of a set of credentials may not be
2. While the keyring subscriptions of a set of credentials may not be
changed, the keyrings subscribed to may have their contents altered.
To catch accidental credential alteration at compile time, struct task_struct
......@@ -358,7 +358,7 @@ Once a reference has been obtained, it must be released with ``put_cred()``,
Accessing Another Task's Credentials
------------------------------------
Whilst a task may access its own credentials without the need for locking, the
While a task may access its own credentials without the need for locking, the
same is not true of a task wanting to access another task's credentials. It
must use the RCU read lock and ``rcu_dereference()``.
......@@ -382,7 +382,7 @@ This should be used inside the RCU read lock, as in the following example::
}
Should it be necessary to hold another task's credentials for a long period of
time, and possibly to sleep whilst doing so, then the caller should get a
time, and possibly to sleep while doing so, then the caller should get a
reference on them using::
const struct cred *get_task_cred(struct task_struct *task);
......@@ -442,7 +442,7 @@ duplicate of the current process's credentials, returning with the mutex still
held if successful. It returns NULL if not successful (out of memory).
The mutex prevents ``ptrace()`` from altering the ptrace state of a process
whilst security checks on credentials construction and changing is taking place
while security checks on credentials construction and changing is taking place
as the ptrace state may alter the outcome, particularly in the case of
``execve()``.
......
......@@ -132,7 +132,7 @@ Negative Instantiation And Rejection
Rather than instantiating a key, it is possible for the possessor of an
authorisation key to negatively instantiate a key that's under construction.
This is a short duration placeholder that causes any attempt at re-requesting
the key whilst it exists to fail with error ENOKEY if negated or the specified
the key while it exists to fail with error ENOKEY if negated or the specified
error if rejected.
This is provided to prevent excessive repeated spawning of /sbin/request-key
......
......@@ -75,7 +75,7 @@
/* Set rts delay after send, if needed: */
rs485conf.delay_rts_after_send = ...;
/* Set this flag if you want to receive data even whilst sending data */
/* Set this flag if you want to receive data even while sending data */
rs485conf.flags |= SER_RS485_RX_DURING_TX;
if (ioctl (fd, TIOCSRS485, &rs485conf) < 0) {
......
......@@ -24,7 +24,7 @@ I2S
===
I2S is a common 4 wire DAI used in HiFi, STB and portable devices. The Tx and
Rx lines are used for audio transmission, whilst the bit clock (BCLK) and
Rx lines are used for audio transmission, while the bit clock (BCLK) and
left/right clock (LRC) synchronise the link. I2S is flexible in that either the
controller or CODEC can drive (master) the BCLK and LRC clock lines. Bit clock
usually varies depending on the sample rate and the master system clock
......@@ -49,9 +49,9 @@ PCM
PCM is another 4 wire interface, very similar to I2S, which can support a more
flexible protocol. It has bit clock (BCLK) and sync (SYNC) lines that are used
to synchronise the link whilst the Tx and Rx lines are used to transmit and
to synchronise the link while the Tx and Rx lines are used to transmit and
receive the audio data. Bit clock usually varies depending on sample rate
whilst sync runs at the sample rate. PCM also supports Time Division
while sync runs at the sample rate. PCM also supports Time Division
Multiplexing (TDM) in that several devices can use the bus simultaneously (this
is sometimes referred to as network mode).
......
......@@ -218,7 +218,7 @@ like a BT phone call :-
* * <----DAI5-----> FM
*************
This allows the host CPU to sleep whilst the DSP, MODEM DAI and the BT DAI are
This allows the host CPU to sleep while the DSP, MODEM DAI and the BT DAI are
still in operation.
A BE DAI link can also set the codec to a dummy device if the code is a device
......
......@@ -156,7 +156,7 @@ or increment/decrement function.
Note that switching branches results in some locks being taken,
particularly the CPU hotplug lock (in order to avoid races against
CPUs being brought in the kernel whilst the kernel is getting
CPUs being brought in the kernel while the kernel is getting
patched). Calling the static key API from within a hotplug notifier is
thus a sure deadlock recipe. In order to still allow use of the
functionnality, the following functions are provided:
......
......@@ -110,7 +110,7 @@ the permitted thermal "ramp" of the system. For instance, a lower
`k_pu` value will provide a slower ramp, at the cost of capping
available capacity at a low temperature. On the other hand, a high
value of `k_pu` will result in the governor granting very high power
whilst temperature is low, and may lead to temperature overshooting.
while temperature is low, and may lead to temperature overshooting.
The default value for `k_pu` is:
......
......@@ -24,13 +24,13 @@ It can be used for debugging or analyzing latencies and
performance issues that take place outside of user-space.
Although ftrace is typically considered the function tracer, it
is really a frame work of several assorted tracing utilities.
is really a framework of several assorted tracing utilities.
There's latency tracing to examine what occurs between interrupts
disabled and enabled, as well as for preemption and from a time
a task is woken to the task is actually scheduled in.
One of the most common uses of ftrace is the event tracing.
Through out the kernel is hundreds of static event points that
Throughout the kernel is hundreds of static event points that
can be enabled via the tracefs file system to see what is
going on in certain parts of the kernel.
......@@ -462,7 +462,7 @@ of ftrace. Here is a list of some of the key files:
mono_raw:
This is the raw monotonic clock (CLOCK_MONOTONIC_RAW)
which is montonic but is not subject to any rate adjustments
which is monotonic but is not subject to any rate adjustments
and ticks at the same rate as the hardware clocksource.
boot:
......@@ -914,8 +914,8 @@ The above is mostly meaningful for kernel developers.
current trace and the next trace.
- '$' - greater than 1 second
- '@' - greater than 100 milisecond
- '*' - greater than 10 milisecond
- '@' - greater than 100 millisecond
- '*' - greater than 10 millisecond
- '#' - greater than 1000 microsecond
- '!' - greater than 100 microsecond
- '+' - greater than 10 microsecond
......@@ -2541,7 +2541,7 @@ At compile time every C file object is run through the
recordmcount program (located in the scripts directory). This
program will parse the ELF headers in the C object to find all
the locations in the .text section that call mcount. Starting
with gcc verson 4.6, the -mfentry has been added for x86, which
with gcc version 4.6, the -mfentry has been added for x86, which
calls "__fentry__" instead of "mcount". Which is called before
the creation of the stack frame.
......@@ -2978,7 +2978,7 @@ The following commands are supported:
When the function is hit, it will dump the contents of the ftrace
ring buffer to the console. This is useful if you need to debug
something, and want to dump the trace when a certain function
is hit. Perhaps its a function that is called before a tripple
is hit. Perhaps it's a function that is called before a triple
fault happens and does not allow you to get a regular dump.
- cpudump:
......
.. include:: ../disclaimer-ita.rst
:Original: :ref:`Documentation/admin-guide/README.rst <readme>`
.. _it_readme:
Rilascio del kernel Linux 4.x <http://kernel.org/>
===================================================
.. warning::
TODO ancora da tradurre
.. include:: ../disclaimer-ita.rst
:Original: :ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>`
.. _it_securitybugs:
Bachi di sicurezza
==================
.. warning::
TODO ancora da tradurre
......@@ -107,7 +107,7 @@ macro simil-funzioni è il seguente::
* Context: Describes whether the function can sleep, what locks it takes,
* releases, or expects to be held. It can extend over multiple
* lines.
* Return: Describe the return value of foobar.
* Return: Describe the return value of function_name.
*
* The return value description can also have multiple paragraphs, and should
* be placed at the end of the comment block.
......
......@@ -86,6 +86,7 @@ vostre modifiche molto più semplice
.. toctree::
:maxdepth: 2
process/index
doc-guide/index
kernel-hacking/index
......
......@@ -593,8 +593,8 @@ l'opzione ``GFP_KERNEL`` che è permessa solo in contesto utente. Ho supposto
che :c:func:`cache_add()` venga chiamata dal contesto utente, altrimenti
questa opzione deve diventare un parametro di :c:func:`cache_add()`.
Exposing Objects Outside This File
----------------------------------
Esporre gli oggetti al di fuori del file
----------------------------------------
Se i vostri oggetti contengono più informazioni, potrebbe non essere
sufficiente copiare i dati avanti e indietro: per esempio, altre parti del
......
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
.. include:: ../disclaimer-ita.rst
:Original: :ref:`Documentation/process/8.Conclusion.rst <development_conclusion>`
:Translator: Alessia Mantegazza <amantegazza@vaga.pv.it>
.. _it_development_conclusion:
Per maggiori informazioni
=========================
Esistono numerose fonti di informazioni sullo sviluppo del kernel Linux
e argomenti correlati. Primo tra questi sarà sempre la cartella Documentation
che si trova nei sorgenti kernel.
Il file :ref:`process/howto.rst <it_process_howto>` è un punto di partenza
importante; :ref:`process/submitting-patches.rst <it_submittingpatches>` e
:ref:`process/submitting-drivers.rst <it_submittingdrivers>` sono
anch'essi qualcosa che tutti gli sviluppatori del kernel dovrebbero leggere.
Molte API interne al kernel sono documentate utilizzando il meccanismo
kerneldoc; "make htmldocs" o "make pdfdocs" possono essere usati per generare
quei documenti in HTML o PDF (sebbene le versioni di TeX di alcune
distribuzioni hanno dei limiti interni e fallisce nel processare
appropriatamente i documenti).
Diversi siti web approfondiscono lo sviluppo del kernel ad ogni livello
di dettaglio. Il vostro autore vorrebbe umilmente suggerirvi
http://lwn.net/ come fonte; usando l'indice 'kernel' su LWN troverete
molti argomenti specifici sul kernel:
http://lwn.net/Kernel/Index/
Oltre a ciò, una risorsa valida per gli sviluppatori kernel è:
http://kernelnewbies.org/
E, ovviamente, una fonte da non dimenticare è http://kernel.org/, il luogo
definitivo per le informazioni sui rilasci del kernel.
Ci sono numerosi libri sullo sviluppo del kernel:
Linux Device Drivers, 3rd Edition (Jonathan Corbet, Alessandro
Rubini, and Greg Kroah-Hartman). In linea all'indirizzo
http://lwn.net/Kernel/LDD3/.
Linux Kernel Development (Robert Love).
Understanding the Linux Kernel (Daniel Bovet and Marco Cesati).
Tutti questi libri soffrono di un errore comune: tendono a risultare in un
certo senso obsoleti dal momento che si trovano in libreria da diverso
tempo. Comunque contengono informazioni abbastanza buone.
La documentazione per git la troverete su:
http://www.kernel.org/pub/software/scm/git/docs/
http://www.kernel.org/pub/software/scm/git/docs/user-manual.html
Conclusioni
===========
Congratulazioni a chiunque ce l'abbia fatta a terminare questo documento di
lungo-respiro. Si spera che abbia fornito un'utile comprensione d'insieme
di come il kernel Linux viene sviluppato e di come potete partecipare a
tale processo.
Infine, quello che conta è partecipare. Qualsiasi progetto software
open-source non è altro che la somma di quello che i suoi contributori
mettono al suo interno. Il kernel Linux è cresciuto velocemente e bene
perché ha ricevuto il supporto di un impressionante gruppo di sviluppatori,
ognuno dei quali sta lavorando per renderlo migliore. Il kernel è un esempio
importante di cosa può essere fatto quando migliaia di persone lavorano
insieme verso un obiettivo comune.
Il kernel può sempre beneficiare di una larga base di sviluppatori, tuttavia,
c'è sempre molto lavoro da fare. Ma, cosa non meno importante, molti degli
altri partecipanti all'ecosistema Linux possono trarre beneficio attraverso
il contributo al kernel. Inserire codice nel ramo principale è la chiave
per arrivare ad una qualità del codice più alta, bassa manutenzione e
bassi prezzi di distribuzione, alti livelli d'influenza sulla direzione
dello sviluppo del kernel, e molto altro. È una situazione nella quale
tutti coloro che sono coinvolti vincono. Mollate il vostro editor e
raggiungeteci; sarete più che benvenuti.
This diff is collapsed.
.. include:: ../disclaimer-ita.rst
:Original: :ref:`Documentation/process/applying-patches.rst <applying_patches>`
.. _it_applying_patches:
Applicare modifiche al kernel Linux
===================================
.. warning::
TODO ancora da tradurre
.. include:: ../disclaimer-ita.rst
:Original: :ref:`Documentation/process/changes.rst <changes>`
.. _it_changes:
Requisiti minimi per compilare il kernel
++++++++++++++++++++++++++++++++++++++++
.. warning::
TODO ancora da tradurre
This diff is collapsed.
.. include:: ../disclaimer-ita.rst
:Original: :ref:`Documentation/process/code-of-conduct.rst <code_of_conduct>`
.. _it_code_of_conduct:
Accordo dei contributori sul codice di condotta
+++++++++++++++++++++++++++++++++++++++++++++++
.. warning::
TODO ancora da tradurre
This diff is collapsed.
.. include:: ../disclaimer-ita.rst
:Original: :ref:`Documentation/process/development-process.rst <development_process_main>`
:Translator: Alessia Mantegazza <amantegazza@vaga.pv.it>
.. _it_development_process_main:
Una guida al processo di sviluppo del Kernel
============================================
Contenuti:
.. toctree::
:numbered:
:maxdepth: 2
1.Intro
2.Process
3.Early-stage
4.Coding
5.Posting
6.Followthrough
7.AdvancedTopics
8.Conclusion
Lo scopo di questo documento è quello di aiutare gli sviluppatori (ed i loro
supervisori) a lavorare con la communità di sviluppo con il minimo sforzo. È
un tentativo di documentare il funzionamento di questa communità in modo che
sia accessibile anche a coloro che non hanno famigliarità con lo sviluppo del
Kernel Linux (o, anzi, con lo sviluppo di software libero in generale). Benchè
qui sia presente del materiale tecnico, questa è una discussione rivolta in
particolare al procedimento, e quindi per essere compreso non richiede una
conoscenza approfondità sullo sviluppo del kernel.
.. include:: ../disclaimer-ita.rst
:Original: :ref:`Documentation/process/email-clients.rst <email_clients>`
.. _it_email_clients:
Informazioni sui programmi di posta elettronica per Linux
=========================================================
.. warning::
TODO ancora da tradurre
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment