mirrors/linux
2
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2026-07-16 17:57:38 -04:00
Code Issues Packages Projects Releases Wiki Activity

Merge tag 'docs-7.2' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux

Browse Source 
Pull documentation updates from Jonathan Corbet:
 "Things have calmed down a bit on the docs front, with no earthshaking
  changes this time around:

   - Ongoing work on the Japanese and Portuguese translations

   - Better integration of the MAINTAINERS file into the rendered
     documents, including a search interface

   - A seemingly infinite supply of fixes for typos, minor grammatical
     issues, and related problems that LLMs find with abandon"

* tag 'docs-7.2' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux: (93 commits)
  docs: pt_BR: Translate 3.Early-stage.rst into Portuguese
  docs: pt_BR: update "Purpose of Defconfigs" section in maintainer-soc.rst
  Documentation: bug-hunting.rst: fix grammar
  docs/ja_JP: translate submitting-patches.rst (interleaved-replies)
  docs: Fix minor grammatical error
  docs/{it_it,sp_SP,zh_CN,zh_TW}: update references to removed CONFIG_DEBUG_SLAB
  Documentation: process: fix brackets
  Documentation: arch: fix brackets
  docs/dyndbg: explain flags parse 1st
  docs/dyndbg: update examples \012 to \n
  docs: kernel-parameters: Fix stale sticore file paths
  docs: real-time: Fix duplicated sched(7) text
  docs: kgdb: Fix stale source file paths
  docs: sonypi: Fix stale header file path
  docs: kernel-parameters: Remove sa1100ir IrDA parameter
  iommu: Documentation: rearrange, update kernel-parameters
  docs: md: fix grammar in speed_limit description
  docs: changes.rst: restore pahole 1.26 minimum (regressed by sort)
  Documentation: Fix syntax of kmalloc_objs example in coding style doc
  docs: pt_BR: update maintainer-handbooks
  ...
This commit is contained in:
Linus Torvalds
2026-06-16 08:35:59 +05:30
parent bd77e50c9a fa34b01aa0
commit a87bbc4578
91 changed files with 2669 additions and 558 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
Documentation/RCU/Design/Requirements/Requirements.rst
View File

@@ -206,7 +206,7 @@ non-\ ``NULL``, locklessly accessing the ``->a`` and ``->b`` fields.
1 bool add_gp_buggy(int a, int b)
2 {
3 p = kmalloc(sizeof(*p), GFP_KERNEL);
3 p = kmalloc_obj(*p);
4 if (!p)
5 return -ENOMEM;
6 spin_lock(&gp_lock);
@@ -228,7 +228,7 @@ their rights to reorder this code as follows:
1 bool add_gp_buggy_optimized(int a, int b)
2 {
3 p = kmalloc(sizeof(*p), GFP_KERNEL);
3 p = kmalloc_obj(*p);
4 if (!p)
5 return -ENOMEM;
6 spin_lock(&gp_lock);
@@ -264,7 +264,7 @@ shows an example of insertion:
1 bool add_gp(int a, int b)
2 {
3 p = kmalloc(sizeof(*p), GFP_KERNEL);
3 p = kmalloc_obj(*p);
4 if (!p)
5 return -ENOMEM;
6 spin_lock(&gp_lock);

2
Documentation/RCU/listRCU.rst
View File

@@ -276,7 +276,7 @@ The RCU version of audit_upd_rule() is as follows::
list_for_each_entry(e, list, list) {
if (!audit_compare_rule(rule, &e->rule)) {
ne = kmalloc(sizeof(*entry), GFP_ATOMIC);
ne = kmalloc_obj(*entry, GFP_ATOMIC);
if (ne == NULL)
return -ENOMEM;
audit_copy_rule(&ne->rule, &e->rule);

4
Documentation/RCU/whatisRCU.rst
View File

@@ -468,7 +468,7 @@ uses of RCU may be found in listRCU.rst and NMI-RCU.rst.
struct foo *new_fp;
struct foo *old_fp;
new_fp = kmalloc(sizeof(*new_fp), GFP_KERNEL);
new_fp = kmalloc_obj(*new_fp);
spin_lock(&foo_mutex);
old_fp = rcu_dereference_protected(gbl_foo, lockdep_is_held(&foo_mutex));
*new_fp = *old_fp;
@@ -570,7 +570,7 @@ The foo_update_a() function might then be written as follows::
struct foo *new_fp;
struct foo *old_fp;
new_fp = kmalloc(sizeof(*new_fp), GFP_KERNEL);
new_fp = kmalloc_obj(*new_fp);
spin_lock(&foo_mutex);
old_fp = rcu_dereference_protected(gbl_foo, lockdep_is_held(&foo_mutex));
*new_fp = *old_fp;

8
Documentation/admin-guide/binfmt-misc.rst
View File

@@ -68,10 +68,10 @@ Here is what the fields mean:
Legacy behavior of binfmt_misc is to pass the full path
of the binary to the interpreter as an argument. When this flag is
included, binfmt_misc will open the file for reading and pass its
descriptor as an argument, instead of the full path, thus allowing
the interpreter to execute non-readable binaries. This feature
should be used with care - the interpreter has to be trusted not to
emit the contents of the non-readable binary.
descriptor into the auxilary vector with the key "AT_EXECFD", thus
allowing the interpreter to execute non-readable binaries. This
feature should be used with care - the interpreter has to be trusted
not to emit the contents of the non-readable binary.
``C`` - credentials
Currently, the behavior of binfmt_misc is to calculate
the credentials and security token of the new process according to

4
Documentation/admin-guide/bug-hunting.rst
View File

@@ -63,8 +63,8 @@ Documentation/admin-guide/tainted-kernels.rst, "being loaded" is
annotated with "+", and "being unloaded" is annotated with "-".
Where is the Oops message is located?
-------------------------------------
Where is the Oops message located?
----------------------------------
Normally the Oops text is read from the kernel buffers by klogd and
handed to ``syslogd`` which writes it to a syslog file, typically

35
Documentation/admin-guide/dynamic-debug-howto.rst
View File

@@ -38,12 +38,12 @@ You can view the currently configured behaviour in the *prdbg* catalog::
:#> head -n7 /proc/dynamic_debug/control
# filename:lineno [module]function flags format
init/main.c:1179 [main]initcall_blacklist =_ "blacklisting initcall %s\012
init/main.c:1218 [main]initcall_blacklisted =_ "initcall %s blacklisted\012"
init/main.c:1424 [main]run_init_process =_ " with arguments:\012"
init/main.c:1426 [main]run_init_process =_ " %s\012"
init/main.c:1427 [main]run_init_process =_ " with environment:\012"
init/main.c:1429 [main]run_init_process =_ " %s\012"
init/main.c:1179 [main]initcall_blacklist =_ "blacklisting initcall %s\n"
init/main.c:1218 [main]initcall_blacklisted =_ "initcall %s blacklisted\n"
init/main.c:1424 [main]run_init_process =_ " with arguments:\n"
init/main.c:1426 [main]run_init_process =_ " %s\n"
init/main.c:1427 [main]run_init_process =_ " with environment:\n"
init/main.c:1429 [main]run_init_process =_ " %s\n"
The 3rd space-delimited column shows the current flags, preceded by
a ``=`` for easy use with grep/cut. ``=p`` shows enabled callsites.
@@ -59,10 +59,10 @@ query/commands to the control file. Example::
:#> ddcmd '-p; module main func run* +p'
:#> grep =p /proc/dynamic_debug/control
init/main.c:1424 [main]run_init_process =p " with arguments:\012"
init/main.c:1426 [main]run_init_process =p " %s\012"
init/main.c:1427 [main]run_init_process =p " with environment:\012"
init/main.c:1429 [main]run_init_process =p " %s\012"
init/main.c:1424 [main]run_init_process =p " with arguments:\n"
init/main.c:1426 [main]run_init_process =p " %s\n"
init/main.c:1427 [main]run_init_process =p " with environment:\n"
init/main.c:1429 [main]run_init_process =p " %s\n"
Error messages go to console/syslog::
@@ -109,10 +109,19 @@ The match-spec's select *prdbgs* from the catalog, upon which to apply
the flags-spec, all constraints are ANDed together. An absent keyword
is the same as keyword "*".
Note that since the match-spec can be empty, the flags are checked 1st,
then the pairs of keyword and value. Flag errs will hide keyword errs::
A match specification is a keyword, which selects the attribute of
the callsite to be compared, and a value to compare against. Possible
keywords are:::
bash-5.2# ddcmd mod bar +foo
dyndbg: read 13 bytes from userspace
dyndbg: query 0: "mod bar +foo" mod:*
dyndbg: unknown flag 'o'
dyndbg: flags parse failed
dyndbg: processed 1 queries, with 0 matches, 1 errs
So a match-spec is a keyword, which selects the attribute of the
callsite to be compared, and a value to compare against. Possible
keywords are::
match-spec ::= 'func' string |
'file' string |

74
Documentation/admin-guide/kernel-parameters.txt
View File

@@ -24,7 +24,6 @@
IP_PNP IP DHCP, BOOTP, or RARP is enabled.
IPV6 IPv6 support is enabled.
ISAPNP ISA PnP code is enabled.
ISDN Appropriate ISDN support is enabled.
ISOL CPU Isolation is enabled.
JOY Appropriate joystick support is enabled.
KGDB Kernel debugger support is enabled.
@@ -2223,9 +2222,6 @@ Kernel parameters
syscalls, essentially overriding IA32_EMULATION_DEFAULT_DISABLED at
boot time. When false, unconditionally disables IA32 emulation.
icn= [HW,ISDN]
Format: <io>[,<membase>[,<icn_id>[,<icn_id2>]]]
idle= [X86,EARLY]
Format: idle=poll, idle=halt, idle=nomwait
@@ -2562,23 +2558,41 @@ Kernel parameters
Don't force hardware IOMMU usage when it is not
needed. (default).
biomerge
panic
nopanic
merge
Do scatter-gather (SG) merging. Implies "force"
(experimental).
nomerge
Don't do scatter-gather (SG) merging.
biomerge
Do scatter-gather (SG) merging. Implies "force"
(experimental). [same as "merge"]
panic
Always panic when IOMMU overflows.
nopanic
Don't panic on IOMMU overflows.
pt
Use passththrough mode by default
(Equivalent to iommu.passthrough=1)
nopt
Use translated mode for DMA by default
(Equivalent to iommu.passthrough=0)
soft
Use software bounce buffering (SWIOTLB) (default for
Intel machines). This can be used to prevent the usage
of an available hardware IOMMU.
pt
nopt
nobypass [PPC/POWERNV]
Disable IOMMU bypass, using IOMMU for PCI devices.
usedac
Use the DAC on VIA PCI bridge
(default: disable the VIA PCI bridge DAC)
AMD Gart HW IOMMU-specific options:
AMD Gart HW IOMMU-specific options: (CONFIG_GART_IOMMU)
<size>
Set the size of the remapping area in bytes.
@@ -2586,6 +2600,9 @@ Kernel parameters
allowed
Overwrite iommu off workarounds for specific chipsets
force
Overwrite iommu off workarounds for specific chipsets
fullflush
Flush IOMMU on each allocation (default).
@@ -2596,21 +2613,16 @@ Kernel parameters
Allocate an own aperture over RAM with size
32MB<<order. (default: order=1, i.e. 64MB)
merge
Do scatter-gather (SG) merging. Implies "force"
(experimental).
nomerge
Don't do scatter-gather (SG) merging.
noaperture
Ask the IOMMU not to touch the aperture for AGP.
noagp
Don't initialize the AGP driver and use full aperture.
panic
Always panic when IOMMU overflows.
iommu= [PPC/POWERNV]
nobypass
Disable IOMMU bypass, using IOMMU for PCI devices.
iommu.forcedac= [ARM64,X86,EARLY] Control IOVA allocation for PCI devices.
Format: { "0" | "1" }
@@ -2733,7 +2745,6 @@ Kernel parameters
Format: <RDP>,<reset>,<pci_scan>,<verbosity>
isolcpus= [KNL,SMP,ISOL] Isolate a given set of CPUs from disturbance.
[Deprecated - use cpusets instead]
Format: [flag-list,]<cpu-list>
Specify one or more CPUs to isolate from disturbances
@@ -2758,11 +2769,10 @@ Kernel parameters
Isolate from the general SMP balancing and scheduling
algorithms. Note that performing domain isolation this way
is irreversible: it's not possible to bring back a CPU to
the domains once isolated through isolcpus. It's strongly
advised to use cpusets instead to disable scheduler load
balancing through the "cpuset.sched_load_balance" file.
It offers a much more flexible interface where CPUs can
move in and out of an isolated set anytime.
the domains once isolated through this boot time
configuration. Use cpusets for a dynamic configuration
which can be altered at runtime. For details see
Documentation/admin-guide/cpu-isolation.rst.
You can move a process onto or off an "isolated" CPU via
the CPU affinity syscalls or cpuset.
@@ -4614,7 +4624,7 @@ Kernel parameters
nosmt [KNL,MIPS,PPC,EARLY] Disable symmetric multithreading (SMT).
Equivalent to smt=1.
[KNL,LOONGARCH,X86,PPC,S390] Disable symmetric multithreading (SMT).
[KNL,LOONGARCH,X86,ARM64,PPC,S390] Disable symmetric multithreading (SMT).
nosmt=force: Force disable SMT, cannot be undone
via the sysfs control file.
@@ -5007,8 +5017,6 @@ Kernel parameters
the specified number of seconds. This is to be used if
your oopses keep scrolling off the screen.
pcbit= [HW,ISDN]
pci=option[,option...] [PCI,EARLY] various PCI subsystem options.
Some options herein operate on a specific device
@@ -6748,8 +6756,6 @@ Kernel parameters
restrictions other than those given by hardware at the
cost of significant additional memory use for tables.
sa1100ir [NET]
See drivers/net/irda/sa1100_ir.c.
sched_proxy_exec= [KNL]
Enables or disables "proxy execution" style
@@ -7396,10 +7402,10 @@ Kernel parameters
Set the STI (builtin display/keyboard on the HP-PARISC
machines) console (graphic card) which should be used
as the initial boot-console.
See also comment in drivers/video/console/sticore.c.
See also comment in drivers/video/sticore.c.
sti_font= [HW]
See comment in drivers/video/console/sticore.c.
See comment in drivers/video/sticore.c.
stifb= [HW]
Format: bpp:<bpp1>[:<bpp2>[:<bpp3>...]]

2
Documentation/admin-guide/laptops/sonypi.rst
View File

@@ -89,7 +89,7 @@ statically linked into the kernel). Those options are:
set to 0xffffffff, meaning that all possible events
will be tried. You can use the following bits to
construct your own event mask (from
drivers/char/sonypi.h)::
include/linux/sonypi.h)::
SONYPI_JOGGER_MASK 0x0001
SONYPI_CAPTURE_MASK 0x0002

2
Documentation/admin-guide/md.rst
View File

@@ -734,7 +734,7 @@ also have
They should be scaled by the bitmap_chunksize.
sync_speed_min, sync_speed_max
This are similar to ``/proc/sys/dev/raid/speed_limit_{min,max}``
These are similar to ``/proc/sys/dev/raid/speed_limit_{min,max}``
however they only apply to the particular array.
If no value has been written to these, or if the word ``system``

2
Documentation/admin-guide/quickly-build-trimmed-linux.rst
View File

@@ -217,7 +217,7 @@ again.
There is a catch: 'localmodconfig' is likely to disable kernel features you
did not use since you booted your Linux -- like drivers for currently
disconnected peripherals or a virtualization software not haven't used yet.
disconnected peripherals or virtualization software not currently in use.
You can reduce or nearly eliminate that risk with tricks the reference
section outlines; but when building a kernel just for quick testing purposes
it is often negligible if such features are missing. But you should keep that

4
Documentation/admin-guide/reporting-issues.rst
View File

@@ -129,7 +129,7 @@ After these preparations you'll now enter the main part:
situations; during the merge window that actually might be even the best
approach, but in that development phase it can be an even better idea to
suspend your efforts for a few days anyway. Whatever version you choose,
ideally use a 'vanilla' build. Ignoring these advices will dramatically
ideally use a 'vanilla' build. Ignoring all of this advice will dramatically
increase the risk your report will be rejected or ignored.
* Ensure the kernel you just installed does not 'taint' itself when
@@ -795,7 +795,7 @@ Install a fresh kernel for testing
situations; during the merge window that actually might be even the best
approach, but in that development phase it can be an even better idea to
suspend your efforts for a few days anyway. Whatever version you choose,
ideally use a 'vanilla' built. Ignoring these advices will dramatically
ideally use a 'vanilla' built. Ignoring all of this advice will dramatically
increase the risk your report will be rejected or ignored.*
As mentioned in the detailed explanation for the first step already: Like most

11
Documentation/admin-guide/sysctl/net.rst
View File

@@ -36,12 +36,11 @@ Table : Subdirectories in /proc/sys/net
========= =================== = ========== ===================
802 E802 protocol mptcp Multipath TCP
appletalk Appletalk protocol netfilter Network Filter
ax25 AX25 netrom NET/ROM
bridge Bridging rose X.25 PLP layer
core General parameter tipc TIPC
ethernet Ethernet protocol unix Unix domain sockets
ipv4 IP version 4 vsock VSOCK sockets
ipv6 IP version 6 x25 X.25 protocol
bridge Bridging tipc TIPC
core General parameter unix Unix domain sockets
ethernet Ethernet protocol vsock VSOCK sockets
ipv4 IP version 4 x25 X.25 protocol
ipv6 IP version 6
========= =================== = ========== ===================
1. /proc/sys/net/core - Network core options

41
Documentation/admin-guide/workload-tracing.rst
View File

@@ -202,6 +202,15 @@ 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.
Alternatively, the kernel build system can generate the cscope database::
make cscope
To exclude directories from the generated database, pass IGNORE_DIRS to
the cscope target. For example, to exclude Documentation/, run::
make IGNORE_DIRS="Documentation" cscope
What is perf and how do we use it?
==================================
@@ -243,13 +252,21 @@ 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:
"perf bench all" runs all available benchmarks in the perf bench
framework. The exact set of benchmarks depends on the perf version and on
the features enabled when perf was built.
* sched/messaging
* sched/pipe
* syscall/basic
* mem/memcpy
* mem/memset
To list the benchmark collections available on the current system, run::
perf bench
To list benchmarks in a collection, run::
perf bench <collection>
For example, to list the benchmarks in the mem collection, run::
perf bench mem
What is stress-ng and how do we use it?
=======================================
@@ -271,17 +288,17 @@ exercised:
The following command runs the stressor::
stress-ng --netdev 1 -t 60 --metrics command.
stress-ng --netdev 1 -t 60 --metrics
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::
netdev stressor, view the generated report perf.data and annotate the output
to view the statistics of each instruction of the program::
perf record stress-ng --netdev 1 -t 60 --metrics command.
perf record -- stress-ng --netdev 1 -t 60 --metrics
perf report
perf annotate
@@ -349,13 +366,13 @@ times each system call is invoked, and the corresponding Linux subsystem.
+-------------------+-----------+-----------------+-------------------------+
| geteuid | 1 | Process Mgmt. | sys_geteuid() |
+-------------------+-----------+-----------------+-------------------------+
| getegid | 1 | Process Mgmt. | sys_getegid |
| getegid | 1 | Process Mgmt. | sys_getegid() |
+-------------------+-----------+-----------------+-------------------------+
| close | 49951 | Filesystem | sys_close() |
+-------------------+-----------+-----------------+-------------------------+
| pipe | 604 | Filesystem | sys_pipe() |
+-------------------+-----------+-----------------+-------------------------+
| openat | 48560 | Filesystem | sys_opennat() |
| openat | 48560 | Filesystem | sys_openat() |
+-------------------+-----------+-----------------+-------------------------+
| fstat | 8338 | Filesystem | sys_fstat() |
+-------------------+-----------+-----------------+-------------------------+

2
Documentation/arch/arc/arc.rst
View File

@@ -36,7 +36,7 @@ Important note on ARC processors configurability
ARC processors are highly configurable and several configurable options
are supported in Linux. Some options are transparent to software
(i.e cache geometries, some can be detected at runtime and configured
(e.g., cache geometries), some can be detected at runtime and configured
and used accordingly, while some need to be explicitly selected or configured
in the kernel's configuration utility (AKA "make menuconfig").

2
Documentation/arch/arm/samsung/clksrc-change-registers.awk
View File

@@ -163,4 +163,4 @@ BEGIN {
}
}
// && ! /clksrc_clk.*=.*{/ { print $0 }
// && ! /clksrc_clk.*=.*{/ { print $0 }}

4
Documentation/arch/arm/vlocks.rst
View File

@@ -102,10 +102,10 @@ Features and limitations
if (I_won) {
/* we won the town election, let's go for the state */
my_state = states[(this_cpu >> 8) & 0xf];
I_won = vlock_lock(my_state, this_cpu & 0xf));
I_won = vlock_lock(my_state, this_cpu & 0xf);
if (I_won) {
/* and so on */
I_won = vlock_lock(the_whole_country, this_cpu & 0xf];
I_won = vlock_lock(the_whole_country, this_cpu & 0xf);
if (I_won) {
/* ... */
}

2
Documentation/arch/arm64/memory-tagging-extension.rst
View File

@@ -222,7 +222,7 @@ programs should not retry in case of a non-zero system call return.
address ABI control and MTE configuration of a process as per the
``prctl()`` options described in
Documentation/arch/arm64/tagged-address-abi.rst and above. The corresponding
``regset`` is 1 element of 8 bytes (``sizeof(long))``).
``regset`` is 1 element of 8 bytes (``sizeof(long)``).
Core dump support
-----------------

2
Documentation/arch/powerpc/vas-api.rst
View File

@@ -293,7 +293,7 @@ Simple example
//Format CRB request with compression or
//uncompression
// Refer tests for vas_copy/vas_paste
vas_copy((&crb, 0, 1);
vas_copy(&crb, 0, 1);
vas_paste(addr, 0, 1);
// Poll on csb.flags with timeout
// csb address is listed in CRB

18
Documentation/arch/sparc/oradax/dax-hv-api.txt
View File

@@ -457,7 +457,7 @@ bits set, and terminate at a CCB that has the Conditional bit set, but not the P
Offset Size Field Description
Bits Field Description
[15:14] Secondary Input Element Size (see Section 36.2.1.1.4,
“Secondary Input Element Size”
“Secondary Input Element Size”)
[13:10] Output Format (see Section 36.2.1.1.6, “Output Format”)
[9] Padding Direction selector: A value of 1 causes padding bytes
to be added to the left side of output elements. A value of 0
@@ -656,7 +656,7 @@ Offset Size Field Description
[18:16] Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input
Element Offsets”)
[15:14] Secondary Input Element Size (see Section 36.2.1.1.4,
“Secondary Input Element Size”
“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 exact match values.
@@ -793,13 +793,13 @@ Offset Size Field Description
[18:16] Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input
Element Offsets”)
[15:14] Secondary Input Element Size (see Section 36.2.1.1.4,
“Secondary Input Element Size”
“Secondary Input Element Size”)
[13:10] Output Format (see Section 36.2.1.1.6, “Output Format”)
[9] Reserved
[8:0] Test value used for comparison against the most significant bits
in the input values, when using 2 or 3 byte input elements.
8 8 Completion (same fields as Section 36.2.1.2, “Extract command”
16 8 Primary Input (same fields as Section 36.2.1.2, “Extract command”
8 8 Completion (same fields as Section 36.2.1.2, “Extract command”)
16 8 Primary Input (same fields as Section 36.2.1.2, “Extract command”)
24 8 Data Access Control (same fields as Section 36.2.1.2, “Extract command”,
except Primary Input Length Format may not use the 0x0 value)
32 8 Secondary Input, if used by Primary Input Format. Same fields as Primary
@@ -880,7 +880,7 @@ Offset Size Field Description
[18:16] Secondary Input Starting Offset (see Section 36.2.1.1.5, “Input
Element Offsets”)
[15:14] Secondary Input Element Size (see Section 36.2.1.1.4,
“Secondary Input Element Size”
“Secondary Input Element Size”)
524
@@ -895,8 +895,8 @@ Offset Size Field Description
causes padding bytes to be added to the right side of output
elements.
[8:0] Reserved
8 8 Completion (same fields as Section 36.2.1.2, “Extract command”
16 8 Primary Input (same fields as Section 36.2.1.2, “Extract command”
8 8 Completion (same fields as Section 36.2.1.2, “Extract command”)
16 8 Primary Input (same fields as Section 36.2.1.2, “Extract command”)
24 8 Data Access Control (same fields as Section 36.2.1.2, “Extract command”)
32 8 Secondary Bit Vector Input. Same fields as Primary Input.
40 8 Reserved
@@ -949,7 +949,7 @@ Offset Size Field Description
[31] If set, this CCB functions as a Sync command. If clear, this
CCB functions as a No-op command.
[30:0] Reserved
8 8 Completion (same fields as Section 36.2.1.2, “Extract command”
8 8 Completion (same fields as Section 36.2.1.2, “Extract command”)
16 46 Reserved
36.2.2. CCB Completion Area

2
Documentation/arch/sparc/oradax/oracle-dax.rst
View File

@@ -438,7 +438,7 @@ that in user land::
The output bitmap is ready for consumption immediately after the
completion status indicates success.
Excer[t from UltraSPARC Virtual Machine Specification
Excerpt from UltraSPARC Virtual Machine Specification
=====================================================
.. include:: dax-hv-api.txt

4
Documentation/arch/x86/x86_64/fsgs.rst
View File

@@ -182,8 +182,8 @@ address spaces via an attribute based mechanism in Clang 2.6 and newer
versions:
==================================== =====================================
__attribute__((address_space(256)) Variable is addressed relative to GS
__attribute__((address_space(257)) Variable is addressed relative to FS
__attribute__(address_space(256)) Variable is addressed relative to GS
__attribute__(address_space(257)) Variable is addressed relative to FS
==================================== =====================================
FS/GS based addressing with inline assembly

2
Documentation/block/data-integrity.rst
View File

@@ -154,7 +154,7 @@ bio_free() will automatically free the bip.
----------------
Block devices can set up the integrity information in the integrity
sub-struture of the queue_limits structure.
sub-structure of the queue_limits structure.
Layered block devices will need to pick a profile that's appropriate
for all subdevices. queue_limits_stack_integrity() can help with that. DM

2
Documentation/core-api/housekeeping.rst
View File

@@ -99,7 +99,7 @@ the same RCU read side critical section.
A typical layout example would look like this on the update side
(``housekeeping_update()``)::
rcu_assign_pointer(housekeeping_cpumasks[type], trial);
rcu_assign_pointer(housekeeping.cpumasks[type], trial);
synchronize_rcu();
flush_workqueue(example_workqueue);

4
Documentation/core-api/kref.rst
View File

@@ -40,7 +40,7 @@ kref_init as so::
struct my_data *data;
data = kmalloc(sizeof(*data), GFP_KERNEL);
data = kmalloc_obj(*data);
if (!data)
return -ENOMEM;
kref_init(&data->refcount);
@@ -100,7 +100,7 @@ thread to process::
int rv = 0;
struct my_data *data;
struct task_struct *task;
data = kmalloc(sizeof(*data), GFP_KERNEL);
data = kmalloc_obj(*data);
if (!data)
return -ENOMEM;
kref_init(&data->refcount);

6
Documentation/core-api/list.rst
View File

@@ -112,7 +112,7 @@ list:
/* State 1 */
grock = kzalloc(sizeof(*grock), GFP_KERNEL);
grock = kzalloc_obj(*grock);
if (!grock)
return -ENOMEM;
grock->name = "Grock";
@@ -123,7 +123,7 @@ list:
/* State 2 */
dimitri = kzalloc(sizeof(*dimitri), GFP_KERNEL);
dimitri = kzalloc_obj(*dimitri);
if (!dimitri)
return -ENOMEM;
dimitri->name = "Dimitri";
@@ -752,7 +752,7 @@ This is because list_splice() did not reinitialize the list_head it took
entries from, leaving its pointer pointing into what is now a different list.
If we want to avoid this situation, list_splice_init() can be used. It does the
same thing as list_splice(), except reinitalizes the donor list_head after the
same thing as list_splice(), except reinitializes the donor list_head after the
transplant.
Concurrency considerations

2
Documentation/core-api/real-time/theory.rst
View File

@@ -25,7 +25,7 @@ Scheduling
==========
The core principles of Linux scheduling and the associated user-space API are
documented in the man page sched(7)
documented in the man page
`sched(7) <https://man7.org/linux/man-pages/man7/sched.7.html>`_.
By default, the Linux kernel uses the SCHED_OTHER scheduling policy. Under
this policy, a task is preempted when the scheduler determines that it has

2
Documentation/driver-api/eisa.rst
View File

@@ -1,3 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0
================
EISA bus support
================

4
Documentation/driver-api/mailbox.rst
View File

@@ -87,8 +87,8 @@ a message and a callback function to the API and return immediately).
struct async_pkt ap;
struct sync_pkt sp;
dc_sync = kzalloc(sizeof(*dc_sync), GFP_KERNEL);
dc_async = kzalloc(sizeof(*dc_async), GFP_KERNEL);
dc_sync = kzalloc_obj(*dc_sync);
dc_async = kzalloc_obj(*dc_async);
/* Populate non-blocking mode client */
dc_async->cl.dev = &pdev->dev;

2
Documentation/driver-api/media/v4l2-fh.rst
View File

@@ -42,7 +42,7 @@ Example:
...
my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);
my_fh = kzalloc_obj(*my_fh);
...

22
Documentation/filesystems/cramfs.rst
View File

@@ -28,8 +28,10 @@ Only the low 8 bits of gid are stored. The current version of
mkcramfs simply truncates to 8 bits, which is a potential security
issue.
Hard links are supported, but hard linked files
will still have a link count of 1 in the cramfs image.
Hard links are not preserved. mkcramfs deduplicates files with
identical content, but two names for the same on-disk inode in the
source tree become two separate (content-shared) entries in the
image, and cramfs always reports a link count of 1.
Cramfs directories have no ``.`` or ``..`` entries. Directories (like
every other file on cramfs) always have a link count of 1. (There's
@@ -40,12 +42,16 @@ No timestamps are stored in a cramfs, so these default to the epoch
the update lasts only as long as the inode is cached in memory, after
which the timestamp reverts to 1970, i.e. moves backwards in time.
Currently, cramfs must be written and read with architectures of the
same endianness, and can be read only by kernels with PAGE_SIZE
== 4096. At least the latter of these is a bug, but it hasn't been
decided what the best fix is. For the moment if you have larger pages
you can just change the #define in mkcramfs.c, so long as you don't
mind the filesystem becoming unreadable to future kernels.
The on-disk layout is host-endian: the kernel does not swab, and
refuses to mount an image whose endianness does not match the CPU.
For cross-builds, mkcramfs -B / -L forces the output endianness so
that a host of one endianness can produce an image for a target of
the other.
The on-disk block size is fixed at 4096 bytes. On systems with a
larger PAGE_SIZE you can change the #define in mkcramfs.c, with the
caveat that the resulting image will only be readable on kernels
configured for the same PAGE_SIZE.
Memory Mapped cramfs image

2
Documentation/filesystems/locking.rst
View File

@@ -570,7 +570,7 @@ write_info: yes dqonoff_sem
FS recursion means calling ->quota_read() and ->quota_write() from superblock
operations.
More details about quota locking can be found in fs/dquot.c.
More details about quota locking can be found in fs/quota/dquot.c.
vm_operations_struct
====================

18
Documentation/filesystems/proc.rst
View File

@@ -23,13 +23,13 @@ fixes/update part 1.1 Stefani Seibold <stefani@seibold.net> June 9 2009
1 Collecting System Information
1.1 Process-Specific Subdirectories
1.2 Kernel data
1.3 IDE devices in /proc/ide
1.4 Networking info in /proc/net
1.5 SCSI info
1.6 Parallel port info in /proc/parport
1.7 TTY info in /proc/tty
1.8 Miscellaneous kernel statistics in /proc/stat
1.9 Ext4 file system parameters
1.3 Networking info in /proc/net
1.4 SCSI info
1.5 Parallel port info in /proc/parport
1.6 TTY info in /proc/tty
1.7 Miscellaneous kernel statistics in /proc/stat
1.8 Ext4 file system parameters
1.9 /proc/consoles - Shows registered system consoles
2 Modifying System Parameters
@@ -119,7 +119,7 @@ PTRACE_MODE_ATTACH permissions; CAP_PERFMON capability does not grant access
to /proc/PID/mem for other processes.
Note that an open file descriptor to /proc/<pid> or to any of its
contained files or subdirectories does not prevent <pid> being reused
contained files or subdirectories does not prevent <pid> from 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
@@ -2212,7 +2212,7 @@ the process is maintaining. Example output::
| lr-------- 1 root root 64 Jan 27 11:24 400000-41a000 -> /usr/bin/ls
The name of a link represents the virtual memory bounds of a mapping, i.e.
vm_area_struct::vm_start-vm_area_struct::vm_end.
vm_area_struct::vm_start - vm_area_struct::vm_end.
The main purpose of the map_files is to retrieve a set of memory mapped
files in a fast way instead of parsing /proc/<pid>/maps or

2
Documentation/gpu/drm-uapi.rst
View File

@@ -568,7 +568,7 @@ ENOSPC:
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 called by unpriviledged clients. There's no clear
this when called by unprivileged clients. There's no clear
difference between EACCES and EPERM.
ENODEV:

4
Documentation/kernel-hacking/locking.rst
View File

@@ -442,7 +442,7 @@ to protect the cache and all the objects within it. Here's the code::
{
struct object *obj;
if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
if ((obj = kmalloc_obj(*obj)) == NULL)
return -ENOMEM;
strscpy(obj->name, name, sizeof(obj->name));
@@ -517,7 +517,7 @@ which are taken away, and the ``+`` are lines which are added.
struct object *obj;
+ unsigned long flags;
if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
if ((obj = kmalloc_obj(*obj)) == NULL)
return -ENOMEM;
@@ -63,30 +64,33 @@
obj->id = id;

2
Documentation/leds/leds-lp55xx.rst
View File

@@ -18,7 +18,7 @@ The LP55xx common driver provides these features using exported functions.
lp55xx_init_device() / lp55xx_deinit_device()
lp55xx_register_leds() / lp55xx_unregister_leds()
lp55xx_regsister_sysfs() / lp55xx_unregister_sysfs()
lp55xx_register_sysfs() / lp55xx_unregister_sysfs()
( Driver Structure Data )

4
Documentation/locking/locktypes.rst
View File

@@ -498,7 +498,7 @@ allocating memory. Thus, on a non-PREEMPT_RT kernel the following code
works perfectly::
raw_spin_lock(&lock);
p = kmalloc(sizeof(*p), GFP_ATOMIC);
p = kmalloc_obj(*p, GFP_ATOMIC);
But this code fails on PREEMPT_RT kernels because the memory allocator is
fully preemptible and therefore cannot be invoked from truly atomic
@@ -507,7 +507,7 @@ while holding normal non-raw spinlocks because they do not disable
preemption on PREEMPT_RT kernels::
spin_lock(&lock);
p = kmalloc(sizeof(*p), GFP_ATOMIC);
p = kmalloc_obj(*p, GFP_ATOMIC);
bit spinlocks

24
Documentation/maintainer/maintainer-entry-profile.rst
View File

@@ -92,24 +92,8 @@ full series, or privately send a reminder email. This section might also
list how review works for this code area and methods to get feedback
that are not directly from the maintainer.
Existing profiles
-----------------
Maintainer Handbooks
--------------------
For now, existing maintainer profiles are listed here; we will likely want
to do something different in the near future.
.. toctree::
:maxdepth: 1
../doc-guide/maintainer-profile
../nvdimm/maintainer-entry-profile
../arch/riscv/patch-acceptance
../process/maintainer-soc
../process/maintainer-soc-clean-dts
../driver-api/media/maintainer-entry-profile
../process/maintainer-netdev
../driver-api/vfio-pci-device-specific-driver-acceptance
../nvme/feature-and-quirk-policy
../filesystems/nfs/nfsd-maintainer-entry-profile
../filesystems/xfs/xfs-maintainer-entry-profile
../mm/damon/maintainer-profile
For examples of other subsystem handbooks see
Documentation/process/maintainer-handbooks.rst.

7
Documentation/process/changes.rst
View File

@@ -53,7 +53,7 @@ mcelog 0.6 mcelog --version
mkimage (optional) 2017.01 mkimage --version
nfs-utils 1.0.5 showmount --version
openssl & libcrypto 1.0.0 openssl version
pahole 1.22 pahole --version
pahole 1.26 pahole --version
pcmciautils 004 pccardctl -V
PPP 2.4.0 pppd --version
procps 3.2.0 ps --version
@@ -147,6 +147,11 @@ Since Linux 5.2, if CONFIG_DEBUG_INFO_BTF is selected, the build system
generates BTF (BPF Type Format) from DWARF in vmlinux, a bit later from kernel
modules as well. This requires pahole v1.22 or later.
Since Linux 7.0, kfuncs annotated with KF_IMPLICIT_ARGS require pahole v1.26
or later. Without it, such kfuncs will have incorrect BTF prototypes in
vmlinux, causing BPF programs to fail to load with a "func_proto incompatible
with vmlinux" error. Many sched_ext kfuncs are affected.
It is found in the 'dwarves' or 'pahole' distro packages or from
https://fedorapeople.org/~acme/dwarves/.

8
Documentation/process/coding-style.rst
View File

@@ -936,7 +936,7 @@ used.
---------------------
The kernel provides the following general purpose memory allocators:
kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
kmalloc(), kzalloc(), kmalloc_objs(), kzalloc_objs(), vmalloc(), and
vzalloc(). Please refer to the API documentation for further information
about them. :ref:`Documentation/core-api/memory-allocation.rst
<memory_allocation>`
@@ -945,7 +945,7 @@ The preferred form for passing a size of a struct is the following:
.. code-block:: c
p = kmalloc(sizeof(*p), ...);
p = kmalloc_obj(*p, ...);
The alternative form where struct name is spelled out hurts readability and
introduces an opportunity for a bug when the pointer variable type is changed
@@ -959,13 +959,13 @@ The preferred form for allocating an array is the following:
.. code-block:: c
p = kmalloc_array(n, sizeof(...), ...);
p = kmalloc_objs(*p, n, ...);
The preferred form for allocating a zeroed array is the following:
.. code-block:: c
p = kcalloc(n, sizeof(...), ...);
p = kzalloc_objs(*p, n, ...);
Both forms check for overflow on the allocation size n * sizeof(...),
and return NULL if that occurred.

4
Documentation/process/debugging/kgdb.rst
View File

@@ -696,7 +696,7 @@ The kernel debugger is organized into a number of components:
1. The debug core
The debug core is found in ``kernel/debugger/debug_core.c``. It
The debug core is found in ``kernel/debug/debug_core.c``. It
contains:
- A generic OS exception handler which includes sync'ing the
@@ -877,7 +877,7 @@ attached keyboard. The keyboard infrastructure is only compiled into the
kernel when ``CONFIG_KDB_KEYBOARD=y`` is set in the kernel configuration.
The core polled keyboard driver for PS/2 type keyboards is in
``drivers/char/kdb_keyboard.c``. This driver is hooked into the debug core
``kernel/debug/kdb/kdb_keyboard.c``. This driver is hooked into the debug core
when kgdboc populates the callback in the array called
:c:expr:`kdb_poll_funcs[]`. The kdb_get_kbd_char() is the top-level
function which polls hardware for single character input.

15
Documentation/process/deprecated.rst
View File

@@ -388,17 +388,18 @@ allocations. For example, these open coded assignments::
ptr = kmalloc_array(count, sizeof(*ptr), gfp);
ptr = kcalloc(count, sizeof(*ptr), gfp);
ptr = kmalloc(struct_size(ptr, flex_member, count), gfp);
ptr = kmalloc(sizeof(struct foo, gfp);
ptr = kmalloc(sizeof(struct foo), gfp);
become, respectively::
ptr = kmalloc_obj(*ptr, gfp);
ptr = kzalloc_obj(*ptr, gfp);
ptr = kmalloc_objs(*ptr, count, gfp);
ptr = kzalloc_objs(*ptr, count, gfp);
ptr = kmalloc_flex(*ptr, flex_member, count, gfp);
__auto_type ptr = kmalloc_obj(struct foo, gfp);
ptr = kmalloc_obj(*ptr [, gfp] );
ptr = kzalloc_obj(*ptr [, gfp] );
ptr = kmalloc_objs(*ptr, count [, gfp] );
ptr = kzalloc_objs(*ptr, count [, gfp] );
ptr = kmalloc_flex(*ptr, flex_member, count [, gfp] );
__auto_type ptr = kmalloc_obj(struct foo [, gfp] );
The argument gfp is optional, the default value is GFP_KERNEL.
If `ptr->flex_member` is annotated with __counted_by(), the allocation
will automatically fail if `count` is larger than the maximum
representable value that can be stored in the counter member associated

17
Documentation/process/maintainer-handbooks.rst
View File

@@ -7,14 +7,13 @@ The purpose of this document is to provide subsystem specific information
which is supplementary to the general development process handbook
:ref:`Documentation/process <development_process_main>`.
Contents:
For developers, see below for all the known subsystem specific guides.
If the subsystem you are contributing to does not have a guide listed
here, it is fair to seek clarification of questions raised in
Documentation/maintainer/maintainer-entry-profile.rst.
.. toctree::
:numbered:
:maxdepth: 2
For maintainers, consider documenting additional requirements and
expectations if submissions routinely overlook specific submission
criteria. See Documentation/maintainer/maintainer-entry-profile.rst.
maintainer-netdev
maintainer-soc
maintainer-soc-clean-dts
maintainer-tip
maintainer-kvm-x86
.. maintainers-profile-toc::

2
Documentation/process/maintainer-soc.rst
View File

@@ -60,7 +60,7 @@ All typical platform related patches should be sent via SoC submaintainers
shared defconfigs. Note that scripts/get_maintainer.pl might not provide
correct addresses for the shared defconfig, so ignore its output and manually
create CC-list based on MAINTAINERS file or use something like
``scripts/get_maintainer.pl -f drivers/soc/FOO/``).
``scripts/get_maintainer.pl -f drivers/soc/FOO/``.
Submitting Patches to the Main SoC Maintainers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

2
Documentation/process/maintainers.rst
View File

@@ -1 +1,3 @@
.. SPDX-License-Identifier: GPL-2.0
.. maintainers-include::

12
Documentation/process/submitting-patches.rst
View File

@@ -581,12 +581,12 @@ By offering my Reviewed-by: tag, I state that:
A Reviewed-by tag is a statement of opinion that the patch is an
appropriate modification of the kernel without any remaining serious
technical issues. Any interested reviewer (who has done the work) can
offer a Reviewed-by tag for a patch. This tag serves to give credit to
reviewers and to inform maintainers of the degree of review which has been
done on the patch. Reviewed-by: tags, when supplied by reviewers known to
understand the subject area and to perform thorough reviews, will normally
increase the likelihood of your patch getting into the kernel.
technical issues. Any interested reviewer (who has done the work and is a
person with known identity) can offer a Reviewed-by tag for a patch. This tag
serves to give credit to reviewers and to inform maintainers of the degree of
review which has been done on the patch. Reviewed-by: tags, when supplied by
reviewers known to understand the subject area and to perform thorough reviews,
will normally increase the likelihood of your patch getting into the kernel.
Both Tested-by and Reviewed-by tags, once received on mailing list from tester
or reviewer, should be added by author to the applicable patches when sending

2
Documentation/process/threat-model.rst
View File

@@ -176,7 +176,7 @@ regular bug:
* problems seen only under development simulators, emulators, or combinations
that do not exist on real systems at the time of reporting (issues
involving tens of millions of threads, tens of thousands of CPUs,
unrealistic CPU frequencies, RAM sizes or disk capacities, network speeds.
unrealistic CPU frequencies, RAM sizes or disk capacities, network speeds).
* issues whose reproduction requires hardware modification or emulation,
including fake USB devices that pretend to be another one.

2
Documentation/scheduler/sched-deadline.rst
View File

@@ -685,7 +685,7 @@ Deadline Task Scheduling
Deadline tasks cannot have a cpu affinity mask smaller than the root domain they
are created on. So, using ``sched_setaffinity(2)`` won't work. Instead, the
the deadline task should be created in a restricted root domain. This can be
deadline task should be created in a restricted root domain. This can be
done using the cpuset controller of either cgroup v1 (deprecated) or cgroup v2.
See :ref:`Documentation/admin-guide/cgroup-v1/cpusets.rst <cpusets>` and
:ref:`Documentation/admin-guide/cgroup-v2.rst <cgroup-v2>` for more information.

6
Documentation/security/credentials.rst
View File

@@ -189,9 +189,9 @@ The Linux kernel supports the following types of credentials:
be searched for the desired key. Each process may subscribe to a number
of keyrings:
Per-thread keying
Per-process keyring
Per-session keyring
- Per-thread keyring
- Per-process keyring
- Per-session keyring
When a process accesses a key, if not already present, it will normally be
cached on one of these keyrings for future accesses to find.

12
Documentation/sound/kernel-api/writing-an-alsa-driver.rst
View File

@@ -266,7 +266,7 @@ to details explained in the following section.
....
/* allocate a chip-specific data with zero filled */
chip = kzalloc(sizeof(*chip), GFP_KERNEL);
chip = kzalloc_obj(*chip);
if (chip == NULL)
return -ENOMEM;
@@ -628,7 +628,7 @@ After allocating a card instance via :c:func:`snd_card_new()`
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
0, &card);
.....
chip = kzalloc(sizeof(*chip), GFP_KERNEL);
chip = kzalloc_obj(*chip);
The chip record should have the field to hold the card pointer at least,
@@ -747,7 +747,7 @@ destructor and PCI entries. Example code is shown first, below::
return -ENXIO;
}
chip = kzalloc(sizeof(*chip), GFP_KERNEL);
chip = kzalloc_obj(*chip);
if (chip == NULL) {
pci_disable_device(pci);
return -ENOMEM;
@@ -1737,7 +1737,7 @@ callback::
{
struct my_pcm_data *data;
....
data = kmalloc(sizeof(*data), GFP_KERNEL);
data = kmalloc_obj(*data);
substream->runtime->private_data = data;
....
}
@@ -3301,7 +3301,7 @@ You can then pass any pointer value to the ``private_data``. If you
assign private data, you should define a destructor, too. The
destructor function is set in the ``private_free`` field::
struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
struct mydata *p = kmalloc_obj(*p);
hw->private_data = p;
hw->private_free = mydata_free;
@@ -3833,7 +3833,7 @@ chip data individually::
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
0, &card);
....
chip = kzalloc(sizeof(*chip), GFP_KERNEL);
chip = kzalloc_obj(*chip);
....
card->private_data = chip;
....

2
Documentation/sphinx-static/custom.css
View File

@@ -30,7 +30,7 @@ img.logo {
margin-bottom: 20px;
}
/* The default is to use -1em, wich makes it override text */
/* The default is to use -1em, which makes it override text */
li { text-indent: 0em; }
/*

524
Documentation/sphinx/maintainers_include.py
View File

@@ -1,197 +1,415 @@
#!/usr/bin/env python
# SPDX-License-Identifier: GPL-2.0
# -*- coding: utf-8; mode: python -*-
# pylint: disable=R0903, C0330, R0914, R0912, E0401
# pylint: disable=C0209, C0301, E0401, R0022, R0902, R0903, R0912, R0914
"""
maintainers-include
~~~~~~~~~~~~~~~~~~~
Implementation of the ``maintainers-include`` reST-directive.
Implementation of the ``maintainers-include`` reST-directive.
:copyright: Copyright (C) 2019 Kees Cook <keescook@chromium.org>
:license: GPL Version 2, June 1991 see linux/COPYING for details.
:copyright: Copyright (C) 2019 Kees Cook <keescook@chromium.org>
:license: GPL Version 2, June 1991 see linux/COPYING for details.
The ``maintainers-include`` reST-directive performs extensive parsing
specific to the Linux kernel's standard "MAINTAINERS" file, in an
effort to avoid needing to heavily mark up the original plain text.
The ``maintainers-include`` reST-directive performs extensive parsing
specific to the Linux kernel's standard "MAINTAINERS" file, in an
effort to avoid needing to heavily mark up the original plain text.
"""
import sys
import re
import os.path
import re
from glob import glob
from docutils import statemachine
from docutils.parsers.rst import Directive
from docutils.parsers.rst.directives.misc import Include
def ErrorString(exc): # Shamelessly stolen from docutils
return f'{exc.__class__.__name}: {exc}'
#
# Base URL for intersphinx-like links to maintainer profiles
#
KERNELDOC_URL = "https://docs.kernel.org/"
__version__ = '1.0'
__version__ = "1.0"
maint_parser = None # pylint: disable=C0103
JS_FILTER = """
(function() {
function filterTable(table) {
const filter = document.getElementById("filter-table").value.trim();
const rows = table.querySelectorAll("tbody tr");
for (let i = 0; i < rows.length; i++) {
const tds = rows[i].getElementsByTagName("td");
let match = false;
for (let j = 0; j < tds.length; j++) {
const cellText = (tds[j].textContent || tds[j].innerText);
if (cellText.includes(filter)) {
match = true;
break;
}
}
rows[i].style.display = match ? "table-row" : "none";
}
}
function addInput() {
const table = document.getElementById("maintainers-table");
if (!table) return;
let input = document.getElementById("filter-table");
if (!input) {
const filt_div = document.createElement('div');
filt_div.innerHTML = `
<p>Filter:
<input type="search" id="filter-table" placeholder="search string"/>
subsystem or property (case-sensitive)
</p>
`;
table.parentNode.insertBefore(filt_div, table);
const input = document.getElementById("filter-table")
input.addEventListener('input', () => filterTable(table));
}
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', addInput);
} else {
addInput();
}
})();
"""
# Shamelessly stolen from docutils
def ErrorString(exc): # pylint: disable=C0103, C0116
return f"{exc.__class__.__name}: {exc}" # pylint: disable=W0212
class MaintainersParser:
"""Parse MAINTAINERS file(s) content"""
def __init__(self, base_dir, app_dir, path):
self.path = path
# Poor man's state machine.
self.descriptions = False
self.maintainers = False
self.subsystems = False
self.subsystem_name = None
self.base_dir = base_dir
self.app_dir = app_dir
self.re_doc = re.compile(r'(Documentation/(\S*)\.rst)')
#
# Output variables with maintainers content to be stored
#
self.profile_toc = set()
self.profile_entries = {}
self.header = ""
self.maint_entries = {}
self.fields = {}
prev = None
with open(path, "r", encoding="utf-8") as fp:
for line in fp:
if self.descriptions:
self.parse_descriptions(line)
elif self.maintainers and not self.subsystems:
if re.search('^[A-Z0-9]', line):
self.subsystems = True
self.parse_subsystems(line)
else:
self.header += line
elif self.subsystems:
self.parse_subsystems(line)
else:
self.header += line
# Update the state machine when we find heading separators.
if line.startswith("----------"):
if prev.startswith("Descriptions"):
self.descriptions = True
if prev.startswith("Maintainers"):
self.maintainers = True
# Retain previous line for state machine transitions.
prev = line
def get_entries(self, text):
"""Generate refs to ReST files in Documentation/"""
if "Documentation/" not in text:
return None
if "*" in text or "?" in text:
m = self.re_doc.search(text)
if not m:
return None
doc_list = glob(os.path.join(self.base_dir, m.group(1)))
else:
doc_list = [text]
entries = {}
for doc in doc_list:
m = self.re_doc.search(doc)
if m:
fname = m.group(1)
ename = m.group(2)
entry = os.path.relpath(self.base_dir + fname, self.app_dir)
entry = entry.removesuffix(".rst")
if entry.startswith("../"):
html = KERNELDOC_URL + ename + ".html"
entries[entry] = f'`{ename} <{html}>`_'
else:
entries[entry] = f':doc:`{ename} </{entry}>`'
return entries
def linkify(self, text):
"""Return a list of doc files converted to cross-references"""
entries = self.get_entries(text)
if not entries:
return text
return self.re_doc.sub(", ".join(entries.values()), text)
def parse_descriptions(self, line):
"""Handle contents of the descriptions section."""
# Have we reached the end of the preformatted Descriptions text?
if line.startswith("Maintainers"):
self.descriptions = False
self.header += "\n" + line
return
# Look for and record field letter to field name mappings:
# R: Designated *reviewer*: FullName <address@domain>
m = re.match(r"\s+(\S):\s+(\S+)", line)
if m:
field = m.group(1)
details = m.group(2)
if field not in self.fields:
m = re.search(r"\*([^\*]+)\*", line)
if m:
self.fields[field] = m.group(1)
elif field in ['F', 'N', 'X', 'K']:
line = line.replace(details, f'``{details}``')
self.header += "| " + self.linkify(line)
def parse_subsystems(self, line):
"""Handle contents of the per-subsystem sections."""
# Drop needless input whitespace.
line = line.rstrip()
# Skip empty lines: subsystem parser adds them as needed.
if not line:
return
if line[1] != ':':
self.subsystem_name = re.sub(r"\s+", " ", self.linkify(line))
return
# Render a subsystem field as:
# :Field: entry
# entry...
field, details = line.split(":", 1)
details = details.strip()
#
# Handle profile entries - either as files or as https refs
#
if field == "P":
entries = self.get_entries(details)
if entries:
for e, link in entries.items():
if "html" not in link:
self.profile_toc.add(e)
self.profile_entries[self.subsystem_name] = link
details = ", ".join(entries.values())
else:
match = re.match(r"(https?://.*)", details)
if match:
entry = match.group(1).strip()
self.profile_entries[self.subsystem_name] = entry
else:
self.profile_entries[self.subsystem_name] = f"``{details}``"
details = self.linkify(details)
else:
details = self.linkify(details)
#
# Mark paths (and regexes) as literal text for improved
# readability and to escape any escapes.
#
if field in ['F', 'N', 'X', 'K']:
# But only if not already marked :)
if ':doc:' not in details and "http" not in details:
details = '``%s``' % (details)
if self.subsystem_name not in self.maint_entries:
self.maint_entries[self.subsystem_name] = {}
if field not in self.maint_entries[self.subsystem_name]:
self.maint_entries[self.subsystem_name][field] = []
self.maint_entries[self.subsystem_name][field].append(details)
self.field_prev = field
def setup(app):
app.add_directive("maintainers-include", MaintainersInclude)
return dict(
version = __version__,
parallel_read_safe = True,
parallel_write_safe = True
)
class MaintainersInclude(Include):
"""MaintainersInclude (``maintainers-include``) directive"""
required_arguments = 0
def parse_maintainers(self, path):
def emit(self):
"""Parse all the MAINTAINERS lines into ReST for human-readability"""
path = maint_parser.path
output = ".. _maintainers:\n\n"
output += maint_parser.header
result = list()
result.append(".. _maintainers:")
result.append("")
output += ".. _maintainers_table:\n\n"
output += ".. flat-table::\n"
output += " :header-rows: 1\n\n"
output += " * - Subsystem\n"
output += " - Properties\n\n"
# Poor man's state machine.
descriptions = False
maintainers = False
subsystems = False
self.state.document['maintainers_included'] = True
# Field letter to field name mapping.
field_letter = None
fields = dict()
# Keep the last entry ("THE REST") in the end
entries = list(maint_parser.maint_entries.keys())
entries = sorted(entries[:-1], key=str.casefold) + [entries[-1]]
prev = None
field_prev = ""
field_content = ""
for name in entries:
fields = maint_parser.maint_entries[name]
output += f" * - {name}\n"
tag = "-"
for field, lines in fields.items():
field_name = maint_parser.fields.get(field, field)
for line in open(path):
# Have we reached the end of the preformatted Descriptions text?
if descriptions and line.startswith('Maintainers'):
descriptions = False
# Ensure a blank line following the last "|"-prefixed line.
result.append("")
output += f" {tag} :{field_name}:\n "
output += ",\n ".join(lines) + "\n"
tag = " "
# Start subsystem processing? This is to skip processing the text
# between the Maintainers heading and the first subsystem name.
if maintainers and not subsystems:
if re.search('^[A-Z0-9]', line):
subsystems = True
output += "\n"
# Drop needless input whitespace.
line = line.rstrip()
# Linkify all non-wildcard refs to ReST files in Documentation/.
pat = r'(Documentation/([^\s\?\*]*)\.rst)'
m = re.search(pat, line)
if m:
# maintainers.rst is in a subdirectory, so include "../".
line = re.sub(pat, ':doc:`%s <../%s>`' % (m.group(2), m.group(2)), line)
# Check state machine for output rendering behavior.
output = None
if descriptions:
# Escape the escapes in preformatted text.
output = "| %s" % (line.replace("\\", "\\\\"))
# Look for and record field letter to field name mappings:
# R: Designated *reviewer*: FullName <address@domain>
m = re.search(r"\s(\S):\s", line)
if m:
field_letter = m.group(1)
if field_letter and not field_letter in fields:
m = re.search(r"\*([^\*]+)\*", line)
if m:
fields[field_letter] = m.group(1)
elif subsystems:
# Skip empty lines: subsystem parser adds them as needed.
if len(line) == 0:
continue
# Subsystem fields are batched into "field_content"
if line[1] != ':':
# Render a subsystem entry as:
# SUBSYSTEM NAME
# ~~~~~~~~~~~~~~
# Flush pending field content.
output = field_content + "\n\n"
field_content = ""
# Collapse whitespace in subsystem name.
heading = re.sub(r"\s+", " ", line)
output = output + "%s\n%s" % (heading, "~" * len(heading))
field_prev = ""
else:
# Render a subsystem field as:
# :Field: entry
# entry...
field, details = line.split(':', 1)
details = details.strip()
# Mark paths (and regexes) as literal text for improved
# readability and to escape any escapes.
if field in ['F', 'N', 'X', 'K']:
# But only if not already marked :)
if not ':doc:' in details:
details = '``%s``' % (details)
# Comma separate email field continuations.
if field == field_prev and field_prev in ['M', 'R', 'L']:
field_content = field_content + ","
# Do not repeat field names, so that field entries
# will be collapsed together.
if field != field_prev:
output = field_content + "\n"
field_content = ":%s:" % (fields.get(field, field))
field_content = field_content + "\n\t%s" % (details)
field_prev = field
else:
output = line
# Re-split on any added newlines in any above parsing.
if output != None:
for separated in output.split('\n'):
result.append(separated)
# Update the state machine when we find heading separators.
if line.startswith('----------'):
if prev.startswith('Descriptions'):
descriptions = True
if prev.startswith('Maintainers'):
maintainers = True
# Retain previous line for state machine transitions.
prev = line
# Flush pending field contents.
if field_content != "":
for separated in field_content.split('\n'):
result.append(separated)
output = "\n".join(result)
# For debugging the pre-rendered results...
#print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
self.state_machine.insert_input(
statemachine.string2lines(output), path)
self.state.document.settings.record_dependencies.add(path)
self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
"""Include the MAINTAINERS file as part of this reST file."""
if not self.state.document.settings.file_insertion_enabled:
raise self.warning('"%s" directive disabled.' % self.name)
# Walk up source path directories to find Documentation/../
path = self.state_machine.document.attributes['source']
path = os.path.realpath(path)
tail = path
while tail != "Documentation" and tail != "":
(path, tail) = os.path.split(path)
# Append "MAINTAINERS"
path = os.path.join(path, "MAINTAINERS")
try:
self.state.document.settings.record_dependencies.add(path)
lines = self.parse_maintainers(path)
self.emit()
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
return []
class MaintainersProfile(Include):
"""Generate a list with all maintainer's profiles"""
required_arguments = 0
def emit(self):
"""Parse all the MAINTAINERS lines looking for profile entries"""
env = self.state.document.settings.env
docdir = os.path.dirname(os.path.join(env.srcdir, env.docname))
path = maint_parser.path
#
# Produce a list with all maintainer profiles, sorted by subsystem name
#
output = ""
for profile, entry in sorted(maint_parser.profile_entries.items()):
name = profile.title()
if entry.startswith("http"):
output += f"- `{name} <{entry}>`_\n"
elif entry.startswith("`"):
output += f"- {name}: {entry}\n"
self.warning(f"{profile}: Invalid 'P' tag: {entry}\n")
else:
output += f"- {entry}\n"
#
# Create a hidden TOC table with all profiles. That allows adding
# profiles without needing to add them on any index.rst file.
#
output += "\n.. toctree::\n"
output += " :hidden:\n\n"
for f in sorted(maint_parser.profile_toc):
fname = os.path.join(maint_parser.base_dir, "Documentation", f)
fname = os.path.relpath(fname, docdir)
output += f" {fname}\n"
output += "\n"
# For debugging the pre-rendered results...
#print(output, file=open("/tmp/profiles.rst", "w"))
self.state.document.settings.record_dependencies.add(path)
self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
"""Include the MAINTAINERS file as part of this reST file."""
if not self.state.document.settings.file_insertion_enabled:
raise self.warning('"%s" directive disabled.' % self.name)
try:
self.emit()
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
return []
# pylint: disable=W0613
def add_filter_script(app, pagename, templatename, context, doctree):
"""Add Filter javascript only to maintainers page"""
if doctree and doctree.get('maintainers_included'):
app.add_js_file(None, body=JS_FILTER)
def setup(app):
"""Setup Sphinx extension"""
global maint_parser # pylint: disable=W0603
app_dir = os.path.abspath(app.srcdir)
match = re.match(r"(.*/)Documentation", app_dir)
if not match:
raise ValueError('Documentation directory not found.')
base_dir = match.group(1)
path = os.path.join(base_dir, "MAINTAINERS")
maint_parser = MaintainersParser(base_dir, app_dir, path)
app.add_directive("maintainers-include", MaintainersInclude)
app.add_directive("maintainers-profile-toc", MaintainersProfile)
app.connect("html-page-context", add_filter_script)
return {
"version": __version__,
"parallel_read_safe": True,
"parallel_write_safe": True,
}

4
Documentation/spi/spi-summary.rst
View File

@@ -249,7 +249,7 @@ And SOC-specific utility code might look something like::
{
struct mysoc_spi_data *pdata2;
pdata2 = kmalloc(sizeof *pdata2, GFP_KERNEL);
pdata2 = kmalloc_obj(*pdata2);
*pdata2 = pdata;
...
if (n == 2) {
@@ -373,7 +373,7 @@ a bus (appearing under /sys/class/spi_master).
return -ENODEV;
/* get memory for driver's per-chip state */
chip = kzalloc(sizeof *chip, GFP_KERNEL);
chip = kzalloc(*chip);
if (!chip)
return -ENOMEM;
spi_set_drvdata(spi, chip);

2
Documentation/staging/crc32.rst
View File

@@ -119,7 +119,7 @@ the byte-at-a-time table method, popularized by Dilip V. Sarwate,
v.31 no.8 (August 1988) p. 1008-1013.
Here, rather than just shifting one bit of the remainder to decide
in the correct multiple to subtract, we can shift a byte at a time.
on the correct multiple to subtract, we can shift a byte at a time.
This produces a 40-bit (rather than a 33-bit) intermediate remainder,
and the correct multiple of the polynomial to subtract is found using
a 256-entry lookup table indexed by the high 8 bits.

2
Documentation/staging/lzo.rst
View File

@@ -75,7 +75,7 @@ Description
are called under the assumption that a certain number of bytes follow
because it has already been guaranteed before parsing the instructions.
They just have to "refill" this credit if they consume extra bytes. This
is an implementation design choice independent on the algorithm or
is an implementation design choice independent of the algorithm or
encoding.
Versions

2
Documentation/staging/remoteproc.rst
View File

@@ -24,7 +24,7 @@ handlers, and then all rpmsg drivers will then just work
(for more information about the virtio-based rpmsg bus and its drivers,
please read Documentation/staging/rpmsg.rst).
Registration of other types of virtio devices is now also possible. Firmwares
just need to publish what kind of virtio devices do they support, and then
just need to publish what kind of virtio devices they support, and then
remoteproc will add those devices. This makes it possible to reuse the
existing virtio drivers with remote processor backends at a minimal development
cost.

2
Documentation/staging/static-keys.rst
View File

@@ -90,7 +90,7 @@ out-of-line true branch. Thus, changing branch direction is expensive but
branch selection is basically 'free'. That is the basic tradeoff of this
optimization.
This lowlevel patching mechanism is called 'jump label patching', and it gives
This low-level patching mechanism is called 'jump label patching', and it gives
the basis for the static keys facility.
Static key label API, usage and examples

2
Documentation/trace/histogram-design.rst
View File

@@ -247,7 +247,7 @@ field's size and offset, is used to grab that subkey's data from the
current trace record.
Note, the hist field function use to be a function pointer in the
hist_field stucture. Due to spectre mitigation, it was converted into
hist_field structure. Due to spectre mitigation, it was converted into
a fn_num and hist_fn_call() is used to call the associated hist field
function that corresponds to the fn_num of the hist_field structure.

7
Documentation/trace/rv/monitor_sched.rst
View File

@@ -36,7 +36,7 @@ Specifications
--------------
The specifications included in sched are currently a work in progress, adapting the ones
defined in by Daniel Bristot in [1].
defined by Daniel Bristot in [1]_.
Currently we included the following:
@@ -365,4 +365,7 @@ constraints when processing the events::
References
----------
[1] - https://bristot.me/linux-task-model
.. [1] Daniel Bristot de Oliveira et al.:
`A thread synchronization model for the PREEMPT_RT Linux kernel
<https://www.iris.sssup.it/bitstream/11382/533630/1/Elsevier-JSA-2020.pdf>`_,
J. Syst. Archit., 2020.

4
Documentation/translations/it_IT/kernel-hacking/locking.rst
View File

@@ -462,7 +462,7 @@ e tutti gli oggetti che contiene. Ecco il codice::
{
struct object *obj;
if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
if ((obj = kmalloc_obj(*obj)) == NULL)
return -ENOMEM;
strscpy(obj->name, name, sizeof(obj->name));
@@ -537,7 +537,7 @@ sono quelle rimosse, mentre quelle ``+`` sono quelle aggiunte.
struct object *obj;
+ unsigned long flags;
if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
if ((obj = kmalloc_obj(*obj)) == NULL)
return -ENOMEM;
@@ -63,30 +64,33 @@
obj->id = id;

4
Documentation/translations/it_IT/locking/locktypes.rst
View File

@@ -488,7 +488,7 @@ o rwlock_t. Per esempio, la sezione critica non deve fare allocazioni di
memoria. Su un kernel non-PREEMPT_RT il seguente codice funziona perfettamente::
raw_spin_lock(&lock);
p = kmalloc(sizeof(*p), GFP_ATOMIC);
p = kmalloc_obj(*p, GFP_ATOMIC);
Ma lo stesso codice non funziona su un kernel PREEMPT_RT perché l'allocatore di
memoria può essere oggetto di prelazione e quindi non può essere chiamato in un
@@ -497,7 +497,7 @@ trattiene un blocco *non-raw* perché non disabilitano la prelazione sui kernel
PREEMPT_RT::
spin_lock(&lock);
p = kmalloc(sizeof(*p), GFP_ATOMIC);
p = kmalloc_obj(*p, GFP_ATOMIC);
bit spinlocks

2
Documentation/translations/it_IT/process/coding-style.rst
View File

@@ -943,7 +943,7 @@ Il modo preferito per passare la dimensione di una struttura è il seguente:
.. code-block:: c
p = kmalloc(sizeof(*p), ...);
p = kmalloc_obj(*p, ...);
La forma alternativa, dove il nome della struttura viene scritto interamente,
peggiora la leggibilità e introduce possibili bachi quando il tipo di

2
Documentation/translations/it_IT/process/submit-checklist.rst
View File

@@ -122,7 +122,7 @@ Verificate il vostro codice
1) La patch è stata verificata con le seguenti opzioni abilitate
contemporaneamente: ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``,
``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``,
``CONFIG_SLUB_DEBUG``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``,
``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``,
``CONFIG_PROVE_RCU`` e ``CONFIG_DEBUG_OBJECTS_RCU_HEAD``.

237
Documentation/translations/ja_JP/process/submitting-patches.rst
View File

@@ -83,19 +83,18 @@ Linux の多くの環境は、上流から特定のパッチだけを取り込
詳しく説明してください。コードが意図したとおりに動作していることを
レビューアが確認できるよう、変更内容を平易な言葉で書き下すことが重要です。
パッチの説明が Linux のソースコード管理システム ``git`` の「コミットログ」
としてそのまま取り込める形で書かれていれば、メンテナは助かります。
詳細は原文の該当節 ("The canonical patch format") を参照してください。
パッチ説明を Linux のソースコード管理システム ``git`` の
「コミットログ」としてそのまま取り込める形で書けば、メンテナは
助かります。詳細は原文の該当節 ("The canonical patch format") を
参照してください。
.. TODO: Convert to file-local cross-reference when the destination is
translated.
1 つのパッチでは 1 つの問題だけを解決してください。記述が長くなり
始めたら、それはパッチを分割すべきサインです。
詳細は原文の該当節 ("Separate your changes") を参照してください。
始めたら、パッチを分割すべきサインです。詳細は `変更を分割する`_ を
参照してください。
.. TODO: Convert to file-local cross-reference when the destination is
translated.
パッチまたはパッチシリーズを投稿／再投稿する際は、その完全な
説明と、それを正当化する理由を含めてください。単に「これはパッチ
@@ -179,3 +178,227 @@ URL は禁止です。
$ git log -1 --pretty=fixes 54a4f0239f2e
Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")
変更を分割する
--------------
各 **論理的な変更** は、個別のパッチに分けてください。
たとえば、単一のドライバに対する変更にバグ修正と性能改善の
両方が含まれるなら、それらは 2 つ以上のパッチに分けてください。
変更に API の更新と、その新しい API を使う新しいドライバが
含まれるなら、それらは 2 つのパッチに分けてください。
一方、多数のファイルに対して単一の変更を行う場合は、それらを
1 つのパッチにまとめてください。つまり、1 つの論理的な変更は
1 つのパッチに含めるべきです。
覚えておくべき点は、各パッチがレビューアに理解しやすく、
検証できる変更であるべきだということです。各パッチは、
それ自体の妥当性で正当化できなければなりません。
変更を完成させるために、あるパッチが別のパッチに依存するなら、
それでも構いません。単に、パッチの説明に
**"this patch depends on patch X"** と記してください。
変更を一連のパッチに分ける際は、シリーズ中の各パッチを
適用した後でも、カーネルが正しくビルドされ、正常に動作することを
特に注意して確認してください。問題の追跡に ``git bisect`` を
使う開発者は、あなたのパッチシリーズを任意の地点で分割する
ことがあります。途中でバグを持ち込めば、彼らに感謝されることは
ないでしょう。
パッチセットをこれ以上小さくできないなら、一度に投稿するのは
15 個程度までにして、レビューと統合を待ってください。
変更のスタイルを確認する
------------------------
パッチに基本的なスタイル違反がないか確認してください。詳細は
Documentation/process/coding-style.rst を参照してください。
これを怠ると、単にレビューアの時間を無駄にするだけでなく、
パッチはおそらく読まれもせずに却下されます。
大きな例外が 1 つあります。コードをあるファイルから別の
ファイルへ移動する場合です。このときは、コードを移動する
その同じパッチの中で、移動したコードを一切変更してはいけません。
そうすることで、コードの移動という行為と、あなたの変更とを
明確に区別できます。これは実際の差分のレビューを大いに助け、
ツールがコード自体の履歴をより適切に追跡できるようにします。
提出前に、パッチスタイルチェッカー
(``scripts/checkpatch.pl``) でパッチを確認してください。
ただし、スタイルチェッカーは指針として見るべきであり、
人間の判断に取って代わるものではないことに注意してください。
違反があっても、その方がコードの見栄えがよいなら、
そのままにしておくのが最善でしょう。
チェッカーは 3 つのレベルで報告します:
- ERROR: 間違っている可能性が非常に高いもの
- WARNING: 慎重なレビューを要するもの
- CHECK: 検討を要するもの
パッチに残した違反については、すべて理由を説明できなければ
なりません。
パッチの宛先を選択する
----------------------
各パッチでは、そのコードを保守する適切なサブシステムメンテナと
メーリングリストを、必ず Cc に入れてください。誰がその
メンテナかは、MAINTAINERS ファイルとソースコードの改訂履歴を
調べて確認してください。この段階では ``scripts/get_maintainer.pl``
が非常に役立ちます（パッチへのパスを引数として
``scripts/get_maintainer.pl`` に渡してください）。作業中の
サブシステムのメンテナが見つからない場合は、Andrew Morton
(akpm@linux-foundation.org) が最後の手段となるメンテナです。
すべてのパッチでは、デフォルトで linux-kernel@vger.kernel.org を
使うべきですが、このリストの流量が多いため、目を通さなくなった
開発者も少なくありません。とはいえ、無関係なメーリングリストや
無関係な人々にスパムを送らないでください。
カーネル関連のメーリングリストの多くは kernel.org で運営されており、
その一覧は https://subspace.kernel.org で確認できます。ただし、
他所で運営されているカーネル関連のメーリングリストもあります。
Linux カーネルに採用されるすべての変更の最終的な裁定者は
Linus Torvalds です。彼のメールアドレスは
<torvalds@linux-foundation.org> です。Linus は大量のメールを
受け取っており、現時点では彼に直接届くパッチはごくわずかなので、
通常は彼にメールを送ることを極力避けてください。
悪用可能なセキュリティバグを修正するパッチがあるなら、
そのパッチを security@kernel.org に送ってください。深刻なバグに
ついては、ディストリビュータがユーザーにパッチを配布できるよう、
短期間の embargo が検討される場合があります。そのような場合、
そのパッチを公開メーリングリストに送るべきではありません。
Documentation/process/security-bugs.rst も参照してください。
リリース済みカーネルの深刻なバグを修正するパッチは、次のような行を
パッチの sign-off 欄に入れることで、stable メンテナへ向けてください::
Cc: stable@vger.kernel.org
これはメールの受信者ではないことに注意してください。また、
この文書に加えて Documentation/process/stable-kernel-rules.rst も
読んでください。
変更がユーザーランドとカーネルのインターフェースに影響する場合は、
MAINTAINERS ファイルに記載されている MAN-PAGES メンテナに
man-pages パッチ、少なくとも変更の通知を送って、情報が
マニュアルページに反映されるようにしてください。ユーザー空間 API の
変更は、linux-api@vger.kernel.org にも Cc してください。
MIME・リンク・圧縮・添付なし、プレーンテキストのみ
----------------------------------------------------
Linus や他のカーネル開発者は、あなたが投稿する変更を読み、
コメントできる必要があります。カーネル開発者が標準的な
メールツールを使ってあなたの変更を「引用」し、コードの特定の
箇所についてコメントできることが重要です。
このため、すべてのパッチはメール本文中に ``inline`` で投稿すべきです。
これを行う最も簡単な方法は ``git send-email`` を使うことであり、
強く推奨されます。``git send-email`` の対話型チュートリアルは
https://git-send-email.io で利用できます。
``git send-email`` を使わないことを選ぶ場合:
.. warning::
パッチをコピー＆ペーストする場合は、エディタの word-wrap によって
パッチが壊れないよう注意してください。
圧縮の有無にかかわらず、パッチを MIME 添付ファイルとして添付しては
いけません。多くの一般的なメールアプリケーションは、MIME 添付
ファイルを常にプレーンテキストとして送信するとは限らず、あなたの
コードにコメントできなくなります。MIME 添付ファイルは Linus が
処理するのにも少し余分な時間がかかるため、MIME 添付された変更が
受け入れられる可能性を下げます。
例外: メーラがパッチを壊してしまう場合は、誰かから MIME を使って
再送するよう求められることがあります。
パッチを変更せずに送信するようメールクライアントを設定するための
ヒントについては、Documentation/process/email-clients.rst を参照してください。
レビューコメントに返答する
--------------------------
あなたのパッチには、ほぼ確実に、パッチを改善する方法について
レビューアからコメントが付きます。それは、あなたのメールへの返信という
形で届きます。それらのコメントには必ず返答してください。レビューアを
無視することは、こちらも無視されるためのよい方法です。コメントに
答えるには、単にそのメールへ返信すれば構いません。コード変更に
つながらないレビューコメントや質問であっても、次のレビューアが状況を
よりよく理解できるように、ほぼ確実にコメントまたは changelog エントリに
反映すべきです。
どのような変更を行うのかをレビューアに必ず伝え、時間を割いてくれた
ことに感謝してください。コードレビューは疲れる、時間のかかる作業であり、
レビューアが不機嫌になることもあります。そのような場合であっても、
丁寧に返答し、指摘された問題に対応してください。次の版を送るときは、
cover letter または個々のパッチに ``patch changelog`` を追加し、前回の
投稿との差分を説明してください。詳細は原文の該当節
("The canonical patch format") を参照してください。
.. TODO: Convert to file-local cross-reference when the destination is
translated.
あなたのパッチにコメントした人には、パッチの Cc リストに追加して、
新しい版を知らせてください。
メールクライアントとメーリングリストでの作法についての推奨事項は、
Documentation/process/email-clients.rst を参照してください。
メール議論では不要な引用を削った interleaved replies を使う
------------------------------------------------------------
Linux カーネル開発の議論では、top-posting は強く非推奨とされています。
Interleaved replies、または ``inline`` replies を使うと、会話の流れを
ずっと追いやすくなります。詳細は次を参照してください:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
メーリングリストでは、よく次のように引用されます::
A: http://en.wikipedia.org/wiki/Top_post
Q: Where do I find info about this thing called top-posting?
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
A: Top-posting.
Q: What is the most annoying thing in e-mail?
同様に、返信に関係のない不要な引用はすべて削ってください。
そうすることで、返答を見つけやすくなり、時間と容量を節約できます。
詳細は次を参照してください: http://daringfireball.net/2007/07/on_top ::
A: No.
Q: Should I include quotations after my reply?
落胆しない、そして急がない
--------------------------
変更を投稿した後は、辛抱強く待ってください。レビューアは忙しい人たちであり、
あなたのパッチをすぐに見られるとは限りません。
かつては、パッチが何のコメントもなく虚空へ消えていくこともありましたが、
現在の開発プロセスはそれよりも円滑に機能しています。数週間以内、
通常は 2〜3 週間以内にコメントを受け取るはずです。そうならない場合は、
パッチを正しい場所へ送ったか確認してください。再投稿したりレビューアに
ping したりする前に、少なくとも 1 週間は待ってください。merge window の
ような忙しい時期には、さらに長く待つ方がよい場合もあります。
数週間後に、subject line に "RESEND" を追加して、パッチまたは
パッチシリーズを再送しても構いません::
[PATCH Vx RESEND] sub/sys: Condensed patch summary
パッチまたはパッチシリーズの修正版を投稿する場合は、"RESEND" を
追加しないでください。"RESEND" は、前回の投稿から一切変更していない
パッチまたはパッチシリーズを再送する場合にのみ使います。

3
Documentation/translations/pt_BR/index.rst
View File

@@ -67,6 +67,9 @@ kernel e sobre como ver seu trabalho integrado.
:maxdepth: 1
Introdução <process/1.Intro>
Guia do Processo de Desenvolvimento <process/development-process>
Index de documentos do Kernel <process/kernel-docs>
Regras de licenciamento <process/license-rules>
Como começar <process/howto>
Requisitos mínimos <process/changes>
Conclave (Continuidade do projeto) <process/conclave>

520
Documentation/translations/pt_BR/process/2.Process.rst Normal file
View File

@@ -0,0 +1,520 @@
.. SPDX-License-Identifier: GPL-2.0
Como funciona o processo de desenvolvimento
===========================================
O desenvolvimento do kernel Linux no início dos anos 1990 era uma
atividade bastante informal, envolvendo um número relativamente pequeno de
usuários e desenvolvedores. Com uma base de usuários atualmente na casa
dos milhões e com cerca de 2.000 desenvolvedores envolvidos ao longo de
um ano, o kernel desde então teve que evoluir uma série de processos
para manter o desenvolvimento acontecendo de forma fluida. Uma
compreensão sólida de como o processo funciona é necessária para ser uma
parte eficaz dele.
A Visão Geral
-------------
O kernel Linux usa um modelo de desenvolvimento de lançamento contínuo
(*rolling release*), vagamente baseado em tempo. Um novo lançamento de
versão principal do kernel (que chamaremos, como exemplo, de 9.x) [1]_
ocorre a cada dois ou três meses, trazendo novos recursos, alterações em
APIs internas e muito mais. Um lançamento típico pode conter cerca de
13.000 conjuntos de alterações (*changesets*) com modificações em várias
centenas de milhares de linhas de código. Lançamentos recentes,
juntamente com suas datas, podem ser encontrados na `Wikipedia
<https://en.wikipedia.org/wiki/Linux_kernel_version_history>`_.
.. [1] Rigorosamente falando, o kernel Linux não utiliza o esquema de
numeração de versionamento semântico, mas, em vez disso, o par
9.x identifica a versão de lançamento principal como um número
inteiro. Para cada lançamento, x é incrementado, mas o 9 é
incrementado apenas se x for considerado grande o suficiente
(por exemplo, o Linux 5.0 foi lançado após o Linux 4.20).
O processo de integração (*merging*) de patches segue um fluxo simples a
cada lançamento. No início de cada ciclo de desenvolvimento, abre-se a
**"janela de integração" (*merge window*)**. Durante esse período, todo
código considerado estável e aprovado pela comunidade é unificado ao
kernel principal (*mainline*). A maior parte das novidades e todas as
grandes mudanças estruturais — entra obrigatoriamente nessa fase, em um
ritmo frenético que chega a **1.000 patches (ou conjuntos de alterações)
por dia**.
(Como observação secundária, vale destacar que as mudanças integradas durante
a janela de integração não surgem do nada; elas foram coletadas, testadas e
organizadas com antecedência. Como esse processo funciona será descrito em
detalhes mais adiante).
A janela de integração dura aproximadamente duas semanas. Ao final desse
período, Linus Torvalds declarará que a janela está fechada e lançará o
primeiro dos kernels "rc". Para o kernel que está destinado a ser o 9.x,
por exemplo, o lançamento que ocorre ao final da janela de integração será
chamado de 9.x-rc1. O lançamento -rc1 é o sinal de que o prazo para integrar
novos recursos terminou e que o período para estabilizar o próximo kernel
começou.
Ao longo das próximas seis a dez semanas, apenas patches que corrijam
problemas devem ser submetidos ao kernel principal. Ocasionalmente, uma
mudança mais significativa será permitida, mas esses casos são raros;
desenvolvedores que tentam integrar novos recursos fora da janela de
integração costumam receber uma recepção pouco amigável. Como regra geral,
se você perder a janela de integração para um determinado recurso, o melhor
a fazer é esperar pelo próximo ciclo de desenvolvimento. (Abre-se uma
exceção ocasional para drivers de hardware que antes não eram suportados;
se eles não modificarem nenhum código já existente na árvore, não podem
causar regressões e deve ser seguro adicioná-los a qualquer momento).
À medida que as correções são integradas ao kernel principal, o ritmo de
envio de patches diminui com o tempo. Linus lança novos kernels -rc cerca
de uma vez por semana; uma série normal chega a algo entre -rc6 e -rc9 antes
que o kernel seja considerado suficientemente estável e o lançamento final
seja realizado. Nesse ponto, todo o processo recomeça.
Como exemplo, veja como ocorreu o ciclo de desenvolvimento da versão 5.4
(todas as datas são de 2019):
============== ===============================
Setembro 15 5.3 Lançamento estável do 5.3
Setembro 30 5.4-rc1, fechamento da janela de integração
Outubro 6 5.4-rc2
Outubro 13 5.4-rc3
Outubro 20 5.4-rc4
October 27 5.4-rc5
Novembro 3 5.4-rc6
Novembro 10 5.4-rc7
Novembro 17 5.4-rc8
Novembro 24 5.4 Lançamento estável do 5.4
============== ===============================
Como os desenvolvedores decidem quando encerrar o ciclo de desenvolvimento
e criar o lançamento estável? A métrica mais significativa utilizada é a
lista de regressões de lançamentos anteriores. Nenhum bug é bem-vindo, mas
aqueles que quebram sistemas que funcionavam no passado são considerados
especialmente graves. Por esta razão, patches que causam regressões são
vistos de forma desfavorável e têm grande probabilidade de serem revertidos
durante o período de estabilização.
O objetivo dos desenvolvedores é corrigir todas as regressões conhecidas
antes que o lançamento estável seja feito. No mundo real, esse tipo de
perfeição é difícil de alcançar; há simplesmente variáveis demais em um
projeto deste tamanho. Chega um ponto em que adiar o lançamento final apenas
torna o problema pior; o volume de mudanças esperando pela próxima janela de
integração crescerá ainda mais, criando ainda mais regressões no ciclo
seguinte. Portanto, a maioria dos kernels é lançada com um pequeno número de
regressões conhecidas, embora, felizmente, nenhuma delas seja grave.
Assim que um lançamento estável é feito, sua manutenção contínua é passada
para a "equipe estável" (*stable team*), atualmente composta por Greg
Kroah-Hartman e Sasha Levin. A equipe estável lançará atualizações ocasionais
para a versão estável utilizando o esquema de numeração 9.x.y.
Para ser considerado para um lançamento de atualização, um patch deve (1)
corrigir um bug significativo e (2) já estar integrado ao kernel principal
(*mainline*) para o próximo kernel de desenvolvimento. Os kernels normalmente
receberão atualizações estáveis por um pouco mais de um ciclo de
desenvolvimento após o seu lançamento inicial. Assim, por exemplo, o histórico
do kernel 5.2 ocorreu da seguinte forma (todas as datas são de 2019):
============== ===============================
7 de Julho Lançamento estável do 5.2
14 de Julho 5.2.1
21 de Julho 5.2.2
26 de Julho 5.2.3
28 de Julho 5.2.4
31 de Julho 5.2.5
... ...
11 de Outubro 5.2.21
============== ===============================
A versão 5.2.21 foi a última atualização estável do lançamento 5.2.
Alguns kernels são designados como kernels de "longo prazo" (*long term*);
eles receberão suporte por um período mais longo. Por favor, consulte o
seguinte link para obter a lista de versões ativas do kernel de longo prazo
e seus respectivos mantenedores:
https://www.kernel.org/category/releases.html
A seleção de um kernel para suporte de longo prazo é puramente uma questão
de um mantenedor ter a necessidade e o tempo para manter esse lançamento.
Não há planos conhecidos para suporte de longo prazo para nenhum lançamento
futuro específico.
O Ciclo de Vida de um Patch
---------------------------
Os patches não vão diretamente do teclado do desenvolvedor para o kernel
principal. Em vez disso, existe um processo um tanto complexo (embora um
tanto informal) projetado para garantir que cada patch seja revisado quanto
à sua qualidade e que cada patch implemente uma mudança que seja desejável
ter no mainline. Esse processo pode acontecer rapidamente para correções
menores ou, no caso de mudanças grandes e controversas, arrastar-se por
anos. Grande parte da frustração dos desenvolvedores vem da falta de
compreensão desse processo ou de tentativas de burlá-lo.
Com a esperança de reduzir essa frustração, este documento descreverá como
um patch entra no kernel. O que se segue abaixo é uma introdução que
descreve o processo de uma forma um tanto idealizada. Um tratamento muito
mais detalhado virá nas seções posteriores.
As etapas pelas quais um patch passa são, geralmente:
- Design. É aqui que os requisitos reais para o patch e a forma
como esses requisitos serão atendidos são definidos. O trabalho de
design geralmente é feito sem envolver a comunidade, mas é melhor realizar
esse trabalho abertamente, se possível; isso pode economizar muito tempo
evitando ter que refazer o projeto mais tarde.
- Revisão inicial. Os patches são postados na lista de
discussão relevante, e os desenvolvedores dessa lista respondem com os
comentários que tiverem. Se tudo correr bem, esse processo deve apontar
qualquer problema grave no patch.
- Revisão ampla. Quando o patch estiver próximo de estar
pronto para inclusão no mainline, ele deve ser aceito por um mantenedor de
subsistema relevante — embora essa aceitação não seja uma garantia de que
o patch chegará até o kernel principal. O patch aparecerá na árvore de
subsistema do mantenedor e nas árvores -next. Quando o processo funciona,
esta etapa leva a uma revisão mais ampla do patch e à descoberta de
quaisquer problemas resultantes da integração deste patch com o trabalho
que está sendo feito por outros.
- Por favor, note que a maioria dos mantenedores também tem seus empregos
regulares, portanto, integrar o seu patch pode não ser a maior prioridade
deles. Se o seu patch estiver recebendo feedback sobre alterações que são
necessárias, você deve fazer essas alterações ou justificar por que elas
não devem ser feitas. Se o seu patch não tiver nenhuma objeção de revisão,
mas não estiver sendo integrado pelo mantenedor do subsistema ou driver
adequado, você deve ser persistente em atualizar o patch para o kernel
atual (garantindo que ele seja aplicado de forma limpa) e continuar
enviando-o para revisão e integração.
- Integração no mainline. Eventualmente, um
patch bem-sucedido será integrado ao repositório principal (*mainline*)
gerenciado por Linus Torvalds. Mais comentários e/ou problemas podem surgir
neste momento; é importante que o desenvolvedor seja responsivo a eles e
corrija quaisquer problemas que venham a aparecer.
- Lançamento estável. O número de usuários potencialmente
afetados pelo patch agora é grande, portanto, mais uma vez, novos
problemas podem surgir.
- Manutenção de longo prazo. Embora seja perfeitamente
possível para um desenvolvedor esquecer o código após integrá-lo, esse
tipo de comportamento tende a deixar uma má impressão na comunidade de
desenvolvimento. Integrar o código elimina parte do fardo de manutenção,
já que outros corrigirão problemas causados por mudanças de API. No entanto,
o desenvolvedor original deve continuar assumindo a responsabilidade pelo
código se ele quiser que este permaneça útil no longo prazo.
Um dos maiores erros cometidos por desenvolvedores do kernel (ou por seus
empregadores) é tentar reduzir todo o processo a uma única etapa de
"integração no mainline". Essa abordagem invariavelmente leva à frustração
de todos os envolvidos.
Como os patches entram no Kernel
--------------------------------
Existe exatamente uma pessoa que pode integrar patches no repositório do
kernel principal: Linus Torvalds. Mas, por exemplo, dos mais de 9.500 patches
que entraram no kernel 2.6.38, apenas 112 (cerca de 1,3%) foram escolhidos
diretamente pelo próprio Linus. O projeto do kernel há muito tempo cresceu
para um tamanho onde nenhum desenvolvedor sozinho conseguiria inspecionar e
selecionar cada patch sem ajuda. A maneira como os desenvolvedores do kernel
lidaram com esse crescimento foi através do uso de um sistema de "tenentes"
(*lieutenant system*) construído em torno de uma cadeia de confiança.
A base de código do kernel é logicamente dividida em um conjunto de
subsistemas: rede, suporte a arquiteturas específicas,
gerenciamento de memória, dispositivos de vídeo, etc. A maioria dos
subsistemas possui um mantenedor designado, um desenvolvedor que tem a
responsabilidade geral pelo código dentro daquele subsistema. Esses
mantenedores de subsistemas são os guardiões (de forma flexível)
da parte do kernel que gerenciam; são eles que (geralmente) aceitarão um
patch para inclusão no kernel principal.
Cada um dos mantenedores de subsistemas gerencia sua própria versão da árvore
de fontes do kernel, geralmente (mas certamente nem sempre) usando a
ferramenta de gerenciamento de código-fonte Git. Ferramentas como o Git
(e ferramentas relacionadas como o quilt ou mercurial) permitem que os
mantenedores acompanhem uma lista de patches, incluindo informações de
autoria e outros metadados. A qualquer momento, o mantenedor pode identificar
quais patches em seu repositório não são encontrados no mainline.
Quando a janela de integração se abre, os mantenedores de
alto nível pedirão a Linus para realizar o pull de seus repositórios os patches
que selecionaram para integração. Se Linus concordar, o fluxo de patches
subirá para o seu repositório, tornando-se parte do kernel principal. A
quantidade de atenção que Linus dedica a patches específicos
recebidos em uma operação de pull varia. Está claro que, às vezes, ele os
examina bem de perto. Mas, como regra geral, Linus confia que os mantenedores
de subsistemas não enviarão patches ruins para o upstream.
Os mantenedores de subsistemas, por sua vez, podem realizar o pull dos patches
de outros mantenedores. Por exemplo, a árvore de rede é
construída a partir de patches que se acumularam primeiro em árvores dedicadas
a drivers de dispositivos de rede, rede sem fio, etc. Essa cadeia
de repositórios pode ser arbitrariamente longa, embora raramente exceda dois
ou três elos. Como cada mantenedor na cadeia confia naqueles que gerenciam as
árvores de nível inferior, esse processo é conhecido como a "cadeia de
confiança".
Claramente, em um sistema como este, colocar patches no kernel depende de
encontrar o mantenedor correto. Enviar patches diretamente para Linus
normalmente não é o caminho certo a seguir.
Árvore -next
-------------
A cadeia de árvores de subsistemas orienta o fluxo de patches para o kernel,
mas também levanta uma questão interessante: e se alguém quiser dar uma
olhada em todos os patches que estão sendo preparados para a próxima janela
de integração? Os desenvolvedores estarão interessados em saber quais outras
mudanças estão pendentes para ver se há conflitos com os quais se preocupar; um
patch que altera o protótipo de uma função central do kernel, por exemplo,
entrará em conflito com quaisquer outros patches que usem a forma mais antiga
dessa função. Revisores e testadores querem ter acesso às mudanças em sua forma
integrada antes que todas essas alterações cheguem ao kernel principal. Seria
possível realizar o pull das mudanças de todas as árvores de subsistemas
interessantes, mas isso seria um trabalho enorme e propenso a erros.
A resposta vem na forma das árvores -next, onde as árvores de subsistemas
são coletadas para testes e revisão. A mais antiga dessas árvores, mantida
por Andrew Morton, é chamada de "-mm" (de *memory management*, gerenciamento
de memória, que foi como ela começou). A árvore -mm integra patches de uma
longa lista de árvores de subsistemas; ela também possui alguns patches
destinados a ajudar na depuração (*debugging*).
Além disso, a árvore -mm contém uma coleção significativa de patches que
foram selecionados diretamente por Andrew. Esses patches podem ter sido
postados em uma lista de discussão ou podem se aplicar a uma parte do kernel
para a qual não existe uma árvore de subsistema designada. Como resultado, a
-mm opera como uma espécie de árvore de subsistema de "último recurso"; se
não houver outro caminho óbvio para um patch entrar no mainline, é provável
que ele acabe na -mm. Patches diversos que se acumulam na
-mm eventualmente serão encaminhados para uma árvore de subsistema adequada
ou enviados diretamente para Linus. Em um ciclo de desenvolvimento típico,
aproximadamente 5% a 10% do total de patches que entram no mainline chegam
lá por meio da -mm.
O patch -mm atual está disponível no diretório "mmotm" (*-mm of the moment*)
em:
https://www.ozlabs.org/~akpm/mmotm/
O uso da árvore MMOTM, no entanto, provavelmente será uma experiência
frustrante; existe uma chance real de que ela sequer compile.
A árvore primária para a integração de patches do próximo ciclo é a
linux-next, mantida por Mark Brown. A árvore linux-next é, por design, um
snapshot do que se espera que o mainline se pareça após o
fechamento da próxima janela de integração. As árvores
linux-next são anunciadas nas listas de discussão linux-kernel e linux-next
quando são montadas; elas podem ser baixadas em:
https://www.kernel.org/pub/linux/kernel/next/
A linux-next tornou-se uma parte integrante do processo de desenvolvimento
do kernel; todos os patches integrados durante uma determinada janela de
integração devem, idealmente, ter encontrado seu caminho para a linux-next algum
tempo antes da abertura da janela de integração.
Árvores de laboratório
----------------------
A árvore de fontes do kernel contém o diretório drivers/staging/, onde residem
muitos subdiretórios para drivers ou sistemas de arquivos que estão a caminho
de serem adicionados à árvore do kernel. Eles permanecem em drivers/staging/
enquanto ainda precisam de mais trabalho; uma vez concluídos, podem ser movidos
para o kernel proper Esta é uma maneira de acompanhar drivers que não estão à
altura dos padrões de codificação ou de qualidade do kernel Linux, mas que as
pessoas podem querer usar e acompanhar o desenvolvimento.
Greg Kroah-Hartman atualmente mantém a árvore de staging. Os drivers que
ainda precisam de trabalho são enviados a ele, com cada driver tendo seu
próprio subdiretório em drivers/staging/. Junto com os arquivos de código-fonte
do driver, um arquivo TODO também deve estar presente no diretório. O arquivo
TODO lista o trabalho pendente que o driver precisa para ser aceito no kernel
propriamente dito, bem como uma lista de pessoas que devem receber cópia
(*Cc'd*) em quaisquer patches para o driver. As regras atuais exigem que os
drivers contribuídos para o staging devem, no mínimo, compilar corretamente.
O staging pode ser uma maneira relativamente fácil de colocar novos drivers
no mainline onde, com sorte, eles chamarão a atenção de outros desenvolvedores
e melhorarão rapidamente. No entanto, a entrada no staging não é o fim da
história; o código no staging que não apresentar progresso regular será,
eventualmente, removido. Os distribuidores também tendem a ser relativamente
relutantes em habilitar drivers do staging. Portanto, o staging é, na melhor
das hipóteses, uma parada no caminho para se tornar um driver mainline adequado.
Ferramentas
-----------
Como pode ser visto no texto acima, o processo de desenvolvimento do kernel
depende fortemente da capacidade de guiar coleções de patches em várias
direções. Todo esse sistema não funcionaria nem de longe tão bem quanto
funciona sem ferramentas adequadamente poderosas. Tutoriais sobre como usar
essas ferramentas estão muito além do escopo deste documento, mas há espaço
para algumas indicações.
De longe, o sistema de gerenciamento de código-fonte dominante usado pela
comunidade do kernel é o Git. O Git é um entre vários sistemas de controle
de versão distribuídos desenvolvidos na comunidade de software livre. Ele é
bem sintonizado para o desenvolvimento do kernel, uma vez que apresenta um
excelente desempenho ao lidar com grandes repositórios e grandes volumes de
patches. Ele também tem a reputação de ser difícil de aprender e usar, embora
tenha melhorado ao longo do tempo. Algum tipo de familiaridade com o Git é
quase um requisito para os desenvolvedores do kernel; mesmo que não o usem
em seu próprio trabalho, eles precisarão do Git para acompanhar o que outros
desenvolvedores (e o mainline) estão fazendo.
O Git agora é empacotado por quase todas as distribuições Linux. Existe uma
página inicial em:
https://git-scm.com/
Essa página possui indicações para documentações e tutoriais.
Entre os desenvolvedores do kernel que não usam o Git, a escolha mais popular
é, quase certamente, o Mercurial:
https://www.selenic.com/mercurial/
O Mercurial compartilha muitos recursos com o Git, mas oferece uma interface
que muitos consideram mais fácil de usar.
A outra ferramenta que vale a pena conhecer é o Quilt:
https://savannah.nongnu.org/projects/quilt/
O Quilt é um sistema de gerenciamento de patches, em vez de um sistema de
gerenciamento de código-fonte. Ele não rastreia o histórico ao longo do
tempo; em vez disso, ele é orientado a rastrear um conjunto específico de
alterações em relação a uma base de código em evolução. Alguns mantenedores
de grandes subsistemas usam o Quilt para gerenciar patches destinados a ir
para o upstream. Para o gerenciamento de certos tipos de árvores (-mm, por
exemplo), o Quilt é a melhor ferramenta para o trabalho.
Listas de discussão
-------------------
Uma grande parte do trabalho de desenvolvimento do kernel Linux é realizada por
meio de listas de discussão. É difícil ser um membro plenamente ativo da
comunidade sem se inscrever em pelo menos uma lista em algum lugar. No entanto,
as listas de discussão do Linux também representam um risco potencial para os
desenvolvedores, que correm o risco de serem soterrados por uma avalanche de
e-mails, de violar as convenções utilizadas nas listas do Linux, ou ambos.
A maioria das listas de discussão do kernel é hospedada no kernel.org; a
lista mestre pode ser encontrada em:
https://subspace.kernel.org
Existem listas hospedadas em outros locais; por favor, verifique o arquivo
MAINTAINERS para encontrar a lista relevante para qualquer subsistema específico.
A lista de discussão central para o desenvolvimento do kernel é, naturalmente,
a linux-kernel. Esta lista é um lugar intimidador para se estar; o volume pode
atingir 500 mensagens por dia, a quantidade de ruído é alta, a conversa pode
ser severamente técnica e os participantes nem sempre estão preocupados em
demonstrar um alto grau de polidez. No entanto, não há outro lugar onde a
comunidade de desenvolvimento do kernel se reúna como um todo; desenvolvedores
que evitam esta lista perderão informações importantes.
Existem algumas dicas que podem ajudar na sobrevivência na lista linux-kernel:
- Faça com que a lista seja entregue em uma pasta separada, em vez de na sua
caixa de entrada principal. É preciso ser capaz de ignorar o fluxo de e-mails
por períodos prolongados de tempo.
- Não tente acompanhar cada conversa ninguém mais faz isso. É importante
filtrar tanto pelo tópico de interesse (embora note que conversas longas
podem se desviar do assunto original sem que a linha de assunto do e-mail
seja alterada) quanto pelas pessoas que estão participando.
- Não alimente os trolls. Se alguém estiver tentando provocar uma resposta
irada, ignore-o.
- Ao responder a um e-mail da lista linux-kernel (o mesmo valendo para outras
listas), preserve o cabeçalho Cc: para todos os envolvidos. Na ausência de um
motivo forte (como uma solicitação explícita), você nunca deve remover
destinatários. Sempre certifique-se de que a pessoa a quem você está
respondendo esteja na lista de Cc:. Essa convenção também torna desnecessário
solicitar explicitamente ser copiado em respostas às suas postagens.
- Pesquise nos arquivos da lista (e na internet como um todo) antes de fazer
perguntas. Alguns desenvolvedores podem ficar impacientes com pessoas que
claramente não fizeram sua lição de casa.
- Use respostas intercaladas, o que torna sua resposta mais fácil
de ler. (ou seja, evite o "top-posting" — a prática de colocar sua resposta
acima do texto citado ao qual você está respondendo). Para mais detalhes, veja
:ref:`Documentation/process/submitting-patches.rst <interleaved_replies>`.
- Pergunte na lista de discussão correta. A lista linux-kernel pode até ser o
ponto de encontro geral, mas não é o melhor lugar para encontrar desenvolvedores
de todos os subsistemas.
O último ponto, encontrar a lista de discussão correta é um lugar comum
onde os desenvolvedores iniciantes costumam errar. Alguém que faça uma pergunta
relacionada a redes na lista linux-kernel quase certamente receberá uma
sugestão educada para perguntar na lista netdev em seu lugar, já que essa é a
lista frequentada pela maioria dos desenvolvedores de redes. Existem outras
listas para os subsistemas SCSI, video4linux, IDE, filesystem (sistemas de
arquivos), etc. O melhor lugar para procurar por listas de discussão é no
arquivo MAINTAINERS empacotado junto com o código-fonte do kernel.
Começando com o desenvolvimento do kernel
-----------------------------------------
Perguntas sobre como começar com o processo de desenvolvimento do kernel são
comuns — tanto por parte de indivíduos quanto de empresas. Igualmente comuns
são os passos em falso que tornam o início do relacionamento mais difícil do
que precisa ser.
As empresas frequentemente buscam contratar desenvolvedores bem conhecidos para
dar o pontapé inicial em um grupo de desenvolvimento. Esta pode, de fato, ser
uma técnica eficaz. No entanto, ela também tende a ser cara e não faz muito para
expandir o grupo de desenvolvedores de kernel experientes. É possível capacitar
desenvolvedores internos no desenvolvimento do kernel Linux, desde que haja o
investimento de um pouco de tempo. Dedicar esse tempo pode dotar um empregador
de um grupo de desenvolvedores que entendem tanto o kernel quanto a própria
empresa, e que também podem ajudar a treinar outros. A médio prazo, esta é
frequentemente a abordagem mais lucrativa.
Desenvolvedores individuais frequentemente, e de forma compreensível, ficam sem
saber por onde começar. Iniciar com um grande projeto pode ser intimidante;
muitas vezes deseja-se testar o terreno com algo menor primeiro. Este é o ponto
onde alguns desenvolvedores saltam para a criação de patches que corrigem erros
de ortografia ou pequenos problemas de estilo de código. Infelizmente, tais
patches criam um nível de ruído que distrai a comunidade de desenvolvimento
como um todo, por isso, cada vez mais, eles são vistos com desdém. Novos
desenvolvedores que desejam se apresentar à comunidade não receberão o tipo de
recepção que desejam por esses meios.
Andrew Morton dá este conselho para aspirantes a desenvolvedores do kernel:
::
"O projeto número um para todos os iniciantes no kernel certamente deveria
ser 'certificar-se de que o kernel funcione perfeitamente o tempo todo em
todas as máquinas em que você conseguir colocar as mãos'. Normalmente, a
maneira de fazer isso é trabalhar com outros para resolver as coisas (isso
pode exigir persistência!), mas tudo bem — isso é parte do desenvolvimento
do kernel."
(https://lwn.net/Articles/283982/).
Na ausência de problemas óbvios para corrigir, os desenvolvedores são
aconselhados a olhar para as listas atuais de regressões e bugs abertos em
geral. Nunca há escassez de problemas que precisam de correção; ao abordar
esses problemas, os desenvolvedores ganharão experiência com o processo
enquanto, ao mesmo tempo, constroem respeito com o restante da comunidade de
desenvolvimento.

233
Documentation/translations/pt_BR/process/3.Early-stage.rst Normal file
View File

@@ -0,0 +1,233 @@
.. SPDX-License-Identifier: GPL-2.0
Planejamento em estágio inicial
===============================
Ao contemplar um projeto de desenvolvimento do kernel Linux, pode ser tentador
dar um salto direto e começar a codificar. No entanto, como ocorre com qualquer
projeto significativo, grande parte da base para o sucesso é melhor estabelecida
antes que a primeira linha de código seja escrita. Um tempo gasto no planejamento
e na comunicação iniciais pode economizar muito mais tempo mais adiante.
Especificando o problema
------------------------
Como qualquer projeto de engenharia, um aprimoramento bem-sucedido do kernel
começa com uma descrição clara do problema a ser resolvido. Em alguns casos,
esta etapa é fácil: quando um driver é necessário para um componente de
hardware específico, por exemplo. Em outros, no entanto, é tentador confundir o
problema real com a solução proposta, e isso pode levar a dificuldades.
Considere um exemplo: alguns anos atrás, desenvolvedores que trabalhavam com o
áudio do Linux buscavam uma maneira de executar aplicativos sem interrupções
(*dropouts*) ou outros artefatos causados por latência excessiva no sistema. A
solução a que chegaram foi um módulo do kernel destinado a se conectar à
estrutura do Linux Security Module (LSM); esse módulo poderia ser configurado
para dar a aplicativos específicos acesso ao escalonador de tempo real. Esse
módulo foi implementado e enviado para a lista de discussão linux-kernel, onde
imediatamente encontrou problemas.
Para os desenvolvedores de áudio, esse módulo de segurança era suficiente para
resolver o problema imediato deles. Para a comunidade mais ampla do kernel, no
entanto, ele foi visto como um uso indevido da estrutura LSM (que não tem a
intenção de conceder privilégios a processos que eles de outra forma não
teriam) e um risco para a estabilidade do sistema. As soluções preferidas da
comunidade envolviam o acesso ao escalonamento de tempo real via mecanismo
rlimit a curto prazo, e o trabalho contínuo de redução de latência a longo prazo.
A comunidade de áudio, no entanto, não conseguia enxergar além da solução
específica que havia implementado; eles não estavam dispostos a aceitar
alternativas. O desacordo resultante deixou esses desenvolvedores sentindo-se
desiludidos com todo o processo de desenvolvimento do kernel; um deles voltou
para uma lista de áudio e postou isto:
"Existe um bom número de desenvolvedores muito bons no kernel Linux, mas eles
tendem a ser abafados por uma grande multidão de tolos arrogantes. Tentar
comunicar os requisitos dos usuários a essas pessoas é uma perda de tempo.
Eles são 'inteligentes' demais para ouvir os meros mortais."
(https://lwn.net/Articles/131776/).
A realidade da situação era diferente; os desenvolvedores do kernel estavam muito
mais preocupados com a estabilidade do sistema, com a manutenção a longo prazo e
em encontrar a solução correta para o problema do que com um módulo específico.
A moral da história é focar no problema — e não em uma solução específica — e
discuti-lo com a comunidade de desenvolvimento antes de investir na criação de
um conjunto de códigos.
Portanto, ao contemplar um projeto de desenvolvimento do kernel, deve-se
obter respostas para um pequeno conjunto de perguntas:
- Qual é, exatamente, o problema que precisa ser resolvido?
- Quem são os usuários afetados por esse problema? Quais casos de uso a
solução deve abranger?
- De que forma o kernel deixa a desejar em resolver esse problema atualmente?
Só então faz sentido começar a considerar possíveis soluções.
Discussão inicial
-----------------
Ao planejar um projeto de desenvolvimento do kernel, faz todo o sentido realizar
discussões com a comunidade antes de iniciar a implementação. A comunicação
inicial pode economizar tempo e problemas de várias maneiras:number of ways:
- Pode muito bem ser que o problema já seja tratado pelo kernel de maneiras
que você não compreendeu. O kernel Linux é grande e possui uma série de
recursos e capacidades que não são imediatamente óbvios. Nem todas as
capacidades do kernel são documentadas tão bem quanto se gostaria, e é fácil
deixar passar algumas coisas. Este autor já viu a postagem de um driver
completo que duplicava um driver existente do qual o novo autor não tinha
conhecimento. Códigos que reinventam as rodas existentes não são apenas um
desperdício; eles também não serão aceitos no kernel principal (*mainline*).
- Pode haver elementos na solução proposta que não serão aceitáveis para a
integração no kernel principal . É melhor descobrir problemas
como este antes de escrever o código.
- É inteiramente possível que outros desenvolvedores já tenham pensado sobre
o problema; eles podem ter ideias para uma solução melhor e podem estar
dispostos a ajudar na criação dessa solução.
Anos de experiência com a comunidade de desenvolvimento do kernel ensinaram uma
lição clara: códigos do kernel que são projetados e desenvolvidos a portas
fechadas invariavelmente apresentam problemas que só são revelados quando o
código é lançado na comunidade. Às vezes, esses problemas são graves, exigindo
meses ou anos de esforço antes que o código possa ser adequado aos padrões da
comunidade do kernel. Alguns exemplos incluem:
- A pilha de rede Devicescape foi projetada e implementada para sistemas
monoprocessados. Ela não pôde ser integrada ao kernel principal (*mainline*)
até que fosse adaptada para sistemas multiprocessados. Ajustar retroativamente
mecanismos de travamento (*locking*) e afins em um código é uma tarefa difícil;
como resultado, a integração desse código (hoje chamado mac80211) foi atrasada
por mais de um ano.
- O sistema de arquivos Reiser4 incluía uma série de capacidades que, na
opinião dos desenvolvedores principais do kernel, deveriam ter sido
implementadas na camada de sistema de arquivos virtual (*Virtual Filesystem*
ou VFS). Ele também incluía recursos que não podiam ser facilmente
implementados sem expor o sistema a travamentos mútuos (*deadlocks*) causados
pelo usuário. A revelação tardia desses problemas — e a recusa em corrigir
alguns deles — fez com que o Reiser4 permanecesse fora do kernel principal
(*mainline*).
- O módulo de segurança AppArmor fazia uso de estruturas de dados internas
do sistema de arquivos virtual de maneiras que eram
consideradas inseguras e não confiáveis. Essa preocupação (entre outras)
manteve o AppArmor fora do kernel principal (*mainline*) por anos.
In each of these cases, a great deal of pain and extra work could have been
avoided with some early discussion with the kernel developers.
Como encontrar os mantenedores?
-------------------------------
Quando os desenvolvedores decidem tornar seus planos públicos, a próxima
pergunta será: por onde começamos? A resposta é encontrar a(s) lista(s) de
discussão correta(s) e o mantenedor adequado. Para listas de discussão, a
melhor abordagem é procurar no arquivo MAINTAINERS por um local relevante para
postar. Se houver uma lista de subsistema adequada, postar nela costuma ser
preferível a postar na linux-kernel; é mais provável que você alcance
desenvolvedores com experiência no subsistema relevante e o ambiente pode ser
mais acolhedor.
Encontrar os mantenedores pode ser um pouco mais difícil. Novamente, o arquivo
MAINTAINERS é o lugar para começar. No entanto, esse arquivo tende a não estar
sempre atualizado, e nem todos os subsistemas estão representados ali. A
pessoa listada no arquivo MAINTAINERS pode, na verdade, não ser quem está
atuando nessa função atualmente. Portanto, quando houver dúvidas sobre quem
contactar, um truque útil é usar o git (e o "git log" em particular) para ver
quem está ativo no momento dentro do subsistema de interesse. Observe quem
está escrevendo os patches e quem, se houver alguém, está anexando linhas
"Signed-off-by" a esses patches. Essas são as pessoas que estarão em melhor
posição para ajudar com um novo projeto de desenvolvimento.
A tarefa de encontrar o mantenedor correto às vezes é desafiadora o suficiente
para que os desenvolvedores do kernel tenham adicionado um script para facilitar
o processo:
::
.../scripts/get_maintainer.pl
Este script retornará o(s) mantenedor(es) atual(is) para um determinado arquivo
ou diretório quando fornecida a opção "-f". Se receber um patch na linha de
comando, ele listará os mantenedores que provavelmente devem receber cópias do
patch. Esta é a maneira preferencial (ao contrário da opção "-f") de obter a
lista de pessoas para incluir em cópia (Cc) nos seus patches. Há uma série de
opções que regulam o quão profundamente o get_maintainer.pl buscará por
mantenedores; por favor, tenha cuidado ao usar as opções mais agressivas, pois
você pode acabar incluindo desenvolvedores que não têm interesse real no código
que você está modificando.
Se tudo mais falhar, falar com Andrew Morton pode ser uma maneira eficaz de
rastrear um mantenedor para um trecho específico de código.
Quando postar?
--------------
Se possível, postar seus planos durante os estágios iniciais só pode
ser útil. Descreva o problema que está sendo resolvido e quaisquer
planos que tenham sido feitos sobre como a implementação será feita.
Qualquer informação que você possa fornecer pode ajudar a comunidade de
desenvolvimento a dar contribuições úteis sobre o projeto.
Uma coisa desanimadora que pode acontecer neste estágio não é uma
reação hostil, mas, em vez disso, pouca ou nenhuma reação. A triste
verdade sobre o assunto é que (1) os desenvolvedores do kernel tendem a
estar ocupados, (2) não há escassez de pessoas com planos grandiosos e
pouco código (ou mesmo perspectiva de código) para apoiá-los, e (3)
ninguém é obrigado a revisar ou comentar sobre ideias postadas por
outros. Além disso, designs de alto nível frequentemente escondem
problemas que só são revelados quando alguém realmente tenta
implementar esses designs; por essa razão, os desenvolvedores do kernel
preferem ver o código.
Se uma postagem de pedido de comentários (RFC) render poucos
comentários, não presuma que isso significa que não há interesse no
projeto. Infelizmente, você também não pode presumir que não há
problemas com sua ideia. A melhor coisa a fazer nesta situação é
prosseguir, mantendo a comunidade informada à medida que avança.
Obter a aprovação oficial
-------------------------
Se o seu trabalho estiver sendo realizado em um ambiente corporativo como é o
caso da maior parte do trabalho no kernel do Linux —, você deve, obviamente, ter
a permissão de gerentes devidamente autorizados antes de poder publicar os
planos ou o código da sua empresa em uma lista de discussão pública.
A publicação de código que não tenha sido liberado para lançamento sob uma
licença compatível com a GPL pode ser especialmente problemática; quanto mais
cedo a gerência e a equipe jurídica de uma empresa puderem entrar em acordo
sobre a publicação de um projeto de desenvolvimento do kernel, melhor será para
todos os envolvidos.
Alguns leitores podem estar pensando, neste ponto, que o seu trabalho no kernel
se destina a dar suporte a um produto que ainda não tem uma existência oficialmente
reconhecida. Revelar os planos de seu empregador em uma lista de discussão pública
pode não ser uma opção viável. Em casos como esse, vale a pena considerar se o
segredo é realmente necessário; muitas vezes não há uma real necessidade de manter
os planos de desenvolvimento a portas fechadas.
Dito isso, também existem casos em que uma empresa legitimamente não pode
revelar seus planos logo no início do processo de desenvolvimento. Empresas com
desenvolvedores de kernel experientes podem optar por prosseguir de maneira isolada
(em "malha aberta"), partindo do pressuposto de que serão capazes de evitar problemas
graves de integração mais tarde. Para empresas que não possuem esse tipo de expertise
interna, a melhor opção costuma ser a contratação de um desenvolvedor externo para
revisar os planos sob um acordo de confidencialidade (NDA). A Linux Foundation opera
um programa de NDA projetado para ajudar nesse tipo de situação; mais informações
podem ser encontradas em:
https://www.linuxfoundation.org/nda/
Esse tipo de revisão costuma ser suficiente para evitar problemas graves mais
tarde, sem a necessidade de uma divulgação pública do projeto.

56
Documentation/translations/pt_BR/process/changes.rst
View File

@@ -20,7 +20,8 @@ Requisitos Mínimos Atuais
Atualize para pelo menos estas revisões de software antes de pensar que
encontrou um bug! Se não tiver certeza de qual versão está executando atualmente
, o comando sugerido deve lhe informar.
, o comando sugerido deve lhe informar. Para uma lista dos programas em seu
sistema, incluindo as versões, execute ./scripts/ver_linux.
Novamente, tenha em mente que esta lista pressupõe que você já possui um kernel
Linux em execução funcional. Além disso, nem todas as ferramentas são
@@ -28,20 +29,21 @@ necessárias em todos os sistemas; obviamente, se você não possui nenhum hardw
PC Card por exemplo, provavelmente não precisará se preocupar com o pcmciautils.
====================== =============== ========================================
Programa Versão mínima Comando para verificar a versão
Programa Versão mínima Comando para verificar a versão
====================== =============== ========================================
GNU C 8.1 gcc --version
Clang/LLVM (optional) 17.0.1 clang --version
Rust (optional) 1.78.0 rustc --version
bindgen (optional) 0.65.1 bindgen --version
Rust (optional) 1.85.0 rustc --version
bindgen (optional) 0.71.1 bindgen --version
GNU make 4.0 make --version
bash 4.2 bash --version
binutils 2.30 ld -v
flex 2.5.35 flex --version
gdb 7.2 gdb --version
bison 2.0 bison --version
pahole 1.16 pahole --version
pahole 1.22 pahole --version
util-linux 2.10o mount --version
kmod 13 depmod -V
kmod 13 kmod -V
e2fsprogs 1.41.4 e2fsck -V
jfsutils 1.1.3 fsck.jfs -V
xfsprogs 2.6.0 xfs_db -V
@@ -52,13 +54,13 @@ quota-tools 3.09 quota -V
PPP 2.4.0 pppd --version
nfs-utils 1.0.5 showmount --version
procps 3.2.0 ps --version
udev 081 udevd --version
udev 081 udevadm --version
grub 0.93 grub --version || grub-install --version
mcelog 0.6 mcelog --version
iptables 1.4.2 iptables -V
openssl & libcrypto 1.0.0 openssl version
bc 1.06.95 bc --version
Sphinx\ [#f1]_ 3.4.3 sphinx-build --version
Sphinx [#f1]_ 3.4.3 sphinx-build --version
GNU tar 1.28 tar --version
gtags (opcional) 6.6.5 gtags --version
mkimage (opcional) 2017.01 mkimage --version
@@ -81,11 +83,11 @@ Clang/LLVM (opcional)
---------------------
A versão formal mais recente do clang e dos utilitários LLVM (de acordo com
releases.llvm.org <https://releases.llvm.org>_) é suportada para a compilação
`releases.llvm.org <https://releases.llvm.org>`_) é suportada para a compilação
de kernels. Versões anteriores não têm funcionamento garantido, e poderemos
remover do kernel soluções de contorno (workarounds) que eram utilizadas para
suportar versões mais antigas. Por favor, veja a documentação adicional em:
ref:Building Linux with Clang/LLVM <kbuild_llvm>.
suportar versões mais antigas. Por favor, veja a documentação adicional em
:ref:`Building Linux with Clang/LLVM <kbuild_llvm>`.
Rust (opcional)
---------------
@@ -124,7 +126,7 @@ pkg-config
O sistema de compilação, a partir da versão 4.18, requer o pkg-config para
verificar as ferramentas kconfig instaladas e para determinar as configurações
de flags para uso em make {g,x}config. Anteriormente, o pkg-config já era
de flags para uso em 'make {g,x}config'. Anteriormente, o pkg-config já era
utilizado, mas não era verificado nem documentado.
Flex
@@ -145,7 +147,7 @@ pahole
Desde o Linux 5.2, se CONFIG_DEBUG_INFO_BTF estiver selecionado, o sistema de
compilação gera BTF (BPF Type Format) a partir do DWARF no vmlinux, e um pouco
depois para os módulos do kernel também. Isso requer o pahole v1.16 ou superior.
depois para os módulos do kernel também. Isso requer o pahole v1.22 ou superior.
Ele pode ser encontrado nos pacotes ``dwarves`` ou ``pahole`` das
distribuições, ou em https://fedorapeople.org/~acme/dwarves/.
@@ -153,8 +155,8 @@ distribuições, ou em https://fedorapeople.org/~acme/dwarves/.
Perl
----
Você precisará do perl 5 e dos seguintes módulos: Getopt::Long,
Getopt::Std, File::Basename e File::Find para compilar o kernel.
Você precisará do perl 5 e dos seguintes módulos: ``Getopt::Long``,
``Getopt::Std``, ``File::Basename`` e ``File::Find`` para compilar o kernel.
Python
------
@@ -191,14 +193,14 @@ gtags / GNU GLOBAL (optional)
-----------------------------
A compilação do kernel requer o GNU GLOBAL versão 6.6.5 ou superior para gerar
arquivos de tags através de make gtags. Isso se deve ao uso da flag -C
(--directory) pelo gtags.
arquivos de tags através de make gtags. Isso se deve ao uso da flag ``-C
(--directory)`` pelo ``gtags``.
mkimage
-------
Esta ferramenta é utilizada ao gerar uma Flat Image Tree (FIT), comumente usada
em plataformas ARM. A ferramenta está disponível através do pacote u-boot-tools
em plataformas ARM. A ferramenta está disponível através do pacote ``u-boot-tools``
ou pode ser compilada a partir do código-fonte do U-Boot. Veja as instruções em
https://docs.u-boot.org/en/latest/build/tools.html#building-tools-for-linux
@@ -225,13 +227,13 @@ A documentação das funções do Linux está migrando para a documentação emb
definições no código-fonte. Esses comentários podem ser combinados com arquivos
ReST no diretório Documentation/ para criar uma documentação enriquecida, que
pode então ser convertida para arquivos PostScript, HTML, LaTeX, ePUB e PDF.
Para converter do formato ReST para o formato de sua escolha,você precisará do
Para converter do formato ReST para o formato de sua escolha, você precisará do
Sphinx.
Util-linux
----------
Novas versões do util-linux oferecem suporte no fdisk para discos maiores,
Novas versões do util-linux oferecem suporte no ``fdisk`` para discos maiores,
suporte a novas opções para o mount, reconhecimento de mais tipos de partição e
outras funcionalidades interessantes. Você provavelmente vai querer atualizar.
@@ -240,23 +242,23 @@ Ksymoops
Se o impensável acontecer e o seu kernel sofrer um oops, você pode precisar da
ferramenta ksymoops para decodificá-lo, mas na maioria dos casos, não será
necessário. É geralmente preferível compilar o kernel com CONFIG_KALLSYMS para
necessário. É geralmente preferível compilar o kernel com ``CONFIG_KALLSYMS`` para
que ele produza dumps legíveis que possam ser usados no estado em que se
encontram (isso também gera uma saída melhor do que a do ksymoops).
Se por algum motivo o seu kernel não for compilado com CONFIG_KALLSYMS e você
Se por algum motivo o seu kernel não for compilado com ``CONFIG_KALLSYMS`` e você
não tiver como recompilar e reproduzir o oops com essa opção, você ainda poderá
decodificá-lo com o ksymoops.
Mkinitrd
--------
Estas mudanças no layout da árvore de arquivos /lib/modules também exigem que o
Estas mudanças no layout da árvore de arquivos ``/lib/modules`` também exigem que o
mkinitrd seja atualizado.
E2fsprogs
---------
A versão mais recente do e2fsprogs corrige diversos bugs no fsck e no debugfs.
A versão mais recente do ``e2fsprogs`` corrige diversos bugs no fsck e no debugfs.
Obviamente, é uma boa ideia atualizar.
JFSutils
@@ -270,8 +272,6 @@ utilitários estão disponíveis:
- ``mkfs.jfs`` - cria uma partição formatada em JFS.
- Para o seu arquivo changes.rst, a tradução técnica adequada é:
Outros utilitários de sistema de arquivos também estão disponíveis neste pacote.
Xfsprogs
@@ -309,7 +309,7 @@ usando o udev, você poderá precisar de::
mknod /dev/cpu/microcode c 10 184
chmod 0644 /dev/cpu/microcode
Se você não estiver usando o udev, você poderá precisar executar os comandos
você poderá precisar executar os comandos
acima como root antes de poder usar isso. Você provavelmente também desejará
obter o utilitário de espaço de usuário ``microcode_ctl`` para utilizar em
conjunto com este driver.
@@ -318,7 +318,7 @@ udev
----
O udev é uma aplicação de espaço de usuário para popular o diretório /dev
dinamicamente, apenas com entradas para dispositivos de fat presentes no
dinamicamente, apenas com entradas para dispositivos de fato presentes no
sistema. O udev substitui a funcionalidade básica do devfs, permitindo ao mesmo
tempo a nomeação persistente de dispositivos.

22
Documentation/translations/pt_BR/process/development-process.rst Normal file
View File

@@ -0,0 +1,22 @@
.. SPDX-License-Identifier: GPL-2.0
Guia para o Processo de Desenvolvimento do Kernel
=================================================
O objetivo deste documento é ajudar desenvolvedores (e seus gerentes)
a trabalhar com a comunidade de desenvolvimento com o mínimo de frustração.
É uma tentativa de documentar como esta comunidade funciona de uma forma
que seja acessível àqueles que não estão intimamente familiarizados com o
desenvolvimento do kernel Linux (ou, de fato, com o desenvolvimento de
software livre em geral). Embora haja algum material técnico aqui, esta
é fundamentalmente uma discussão orientada ao processo, que não requer um
conhecimento profundo de programação de kernel para ser compreendida.
.. toctree::
:caption: Contents
:numbered:
:maxdepth: 2
1.Intro
2.Process
3.Early-stage

373
Documentation/translations/pt_BR/process/kernel-docs.rst Normal file
View File

@@ -0,0 +1,373 @@
.. SPDX-License-Identifier: GPL-2.0
Índice de Documentação Adicional do Kernel
==========================================
A necessidade de um documento como este tornou-se evidente na lista de discussão
linux-kernel, uma vez que as mesmas perguntas, solicitando referências de
informações, apareciam repetidamente.
Felizmente, à medida que cada vez mais pessoas chegam ao GNU/Linux, mais pessoas
se interessam pelo Kernel. No entanto, ler o código-fonte nem sempre é o
suficiente. É fácil entender o código, mas perder os conceitos, a filosofia
e as decisões de design por trás dele.
Infelizmente, não há muitos documentos disponíveis para iniciantes começarem.
E, mesmo quando existem, não havia um local "bem conhecido" que os centralizasse.
Estas linhas tentam suprir essa falta.
POR FAVOR, se você conhece algum artigo não listado aqui ou se escrever um novo
documento, inclua uma referência a ele aqui, seguindo o processo de envio de
patches do kernel. Quaisquer correções, ideias ou comentários também são
bem-vindos.
Todos os documentos estão catalogados com os seguintes campos: o "Título" do
documento, o(s) "Autor(es)", a "URL" onde podem ser encontrados, algumas
"Palavras-chave" úteis para pesquisar tópicos específicos e uma breve
"Descrição" do documento.
.. note::
Os documentos em cada seção deste documento estão ordenados por sua data de
publicação, do mais recente para o mais antigo. O(s) mantenedor(es) deve(m)
remover periodicamente recursos à medida que se tornem obsoletos ou
desatualizados; com exceção de livros fundamentais.
Documentação na árvore do Kernel
--------------------------------
Os manuais Sphinx devem ser compilados com ``make {htmldocs | pdfdocs | epubdocs}``.
* Nome: **linux/Documentation**
:Autor: Muitos.
:Localização: Documentation/
:Palavras-chave: arquivos de texto, Sphinx.
:Descrição: Documentação que acompanha o código-fonte do kernel,
dentro do diretório Documentation. Algumas páginas deste documento
(incluindo este próprio documento) foram movidas para lá e podem
estar mais atualizadas do que a versão web.
Documentação on-line
--------------------
* Título: **Linux Kernel Mailing List Glossary**
:Autor: diversos
:URL: https://kernelnewbies.org/KernelGlossary
:Data: versão contínua (rolling)
:Palavras-chave: glossário, termos, linux-kernel.
:Descrição: Da introdução: "Este glossário destina-se a ser uma breve
descrição de algumas das siglas e termos que você poderá ouvir durante
as discussões sobre o kernel Linux".
* Título: **The Linux Kernel Module Programming Guide**
:Autor: Peter Jay Salzman, Michael Burian, Ori Pomerantz, Bob Mottram,
Jim Huang.
:URL: https://sysprog21.github.io/lkmpg/
:Data: 2021
:Palavras-chave: módulos, livro GPL, /proc, ioctls, chamadas de sistema,
manipuladores de interrupção.
:Descrição: Um excelente livro sob licença GPL sobre o tópico de
programação de módulos. Repleto de exemplos. Atualmente, a nova versão
está sendo mantida ativamente em https://github.com/sysprog21/lkmpg.
Livros Publicados
-----------------
* Title: **The Linux Memory Manager**
:Autor: Lorenzo Stoakes
:Editora: No Starch Press
:Data: Fevereiro 2025
:Páginas: 1300
:ISBN: 978-1718504462
:Notas: Gerenciamento de memória. Rascunho completo disponível como acesso
antecipado para ré-venda, lançamento completo agendado para o
outono de 2025. Veja https://nostarch.com/linux-memory-manager
para mais informações.
* Title: **Practical Linux System Administration: A Guide to Installation, Configuration, and Management, 1st Edition**
:Autor: Kenneth Hess
:Editora: O'Reilly Media
:Data: Maio, 2023
:Páginas: 246
:ISBN: 978-1098109035
:Notas: Administração de sistemas
* Title: **Linux Kernel Debugging: Leverage proven tools and advanced techniques to effectively debug Linux kernels and kernel modules**
:Autor: Kaiwan N Billimoria
:Editora: Packt Publishing Ltd
:Data: Agosto, 2022
:Páginas: 638
:ISBN: 978-1801075039
:Notas: Livro sobre depuração (debugging)
* Title: **Linux Kernel Programming: A Comprehensive Guide to Kernel Internals, Writing Kernel Modules, and Kernel Synchronization**
:Autor: Kaiwan N Billimoria
:Editora: Packt Publishing Ltd
:Data: Março, 2021 (Segunda edição publicada em 2024)
:Páginas: 754
:ISBN: 978-1789953435 (O ISBN da segunda edição é 978-1803232225)
* Title: **Linux Kernel Programming Part 2 - Char Device Drivers and Kernel Synchronization: Create user-kernel interfaces, work with peripheral I/O, and handle hardware interrupts**
:Autor: Kaiwan N Billimoria
:Editora: Packt Publishing Ltd
:Data: Março, 2021
:Páginas: 452
:ISBN: 978-1801079518
* Title: **Linux System Programming: Talking Directly to the Kernel and C Library**
:Autor: Robert Love
:Editora: O'Reilly Media
:Data: Junho, 2013
:Páginas: 456
:ISBN: 978-1449339531
:Notas: Livro fundamental
* Título: **Linux Kernel Development, 3rd Edition**
:Autor: Robert Love
:Editora: Addison-Wesley
:Data: Julho de 2010
:Páginas: 440
:ISBN: 978-0672329463
:Notas: Livro fundamental
* Título: **Linux Device Drivers, 3rd Edition**
:Autores: Jonathan Corbet, Alessandro Rubini e Greg Kroah-Hartman
:Editora: O'Reilly & Associates
:Data: 2005
:Páginas: 636
:ISBN: 0-596-00590-3
:Notas: Livro fundamental. Mais informações em
http://www.oreilly.com/catalog/linuxdrive3/
Formato PDF, URL: https://lwn.net/Kernel/LDD3/
* Título: **The Design of the UNIX Operating System**
:Autor: Maurice J. Bach
:Editora: Prentice Hall
:Data: 1986
:Páginas: 471
:ISBN: 0-13-201757-1
:Notas: Livro fundamental
Diversos
--------
* Nome: **Cross-Referencing Linux**
:URL: https://elixir.bootlin.com/
:Palavras-chave: Navegação em código-fonte.
:Descrição: Outro navegador web para o código-fonte do kernel Linux.
Possui muitas referências cruzadas para variáveis e funções. Você pode
ver onde elas são definidas e onde são utilizadas.
* Nome: **Linux Weekly News**
:URL: https://lwn.net
:Palavras-chave: últimas notícias do kernel.
:Descrição: O título diz tudo. Há uma seção fixa sobre o kernel que
resume o trabalho dos desenvolvedores, correções de bugs, novos recursos
e versões produzidas durante a semana.
* Nome: **The home page of Linux-MM**
:Autor: A equipe Linux-MM.
:URL: https://linux-mm.org/
:Palavras-chave: gerenciamento de memória, Linux-MM, mm patches, TODO,
docs, mailing list.
:Descrição: Site dedicado ao desenvolvimento do Gerenciamento de Memória
do Linux. Patches relacionados à memória, HOWTOs, links, desenvolvedores
mm... Não perca se você estiver interessado no desenvolvimento do
gerenciamento de memória!
* Nome: **Kernel Newbies IRC Channel and Website**
:URL: https://www.kernelnewbies.org
:Palavras-chave: IRC, novatos, canal, tirar dúvidas.
:Descrição: #kernelnewbies em irc.oftc.net.
O canal #kernelnewbies é uma rede de IRC dedicada ao hacker de kernel
"novato" (newbie). O público consiste principalmente de pessoas que estão
aprendendo sobre o kernel, trabalhando em projetos do kernel ou hackers
profissionais que desejam ajudar pessoas menos experientes.
O #kernelnewbies está na rede de IRC OFTC.
Tente acessar irc.oftc.net como seu servidor e então digite /join #kernelnewbies.
O site kernelnewbies também hospeda artigos, documentos, FAQs...
* Nome: **linux-kernel mailing list archives and search engines**
:URL: https://subspace.kernel.org
:URL: https://lore.kernel.org
:Palavras-chave: linux-kernel, arquivos, busca.
:Descrição: Alguns dos arquivadores da lista de discussão linux-kernel.
Se você conhece algum outro (ou um melhor), por favor, me avise.
* Nome: **The Linux Foundation YouTube channel**
:URL: https://www.youtube.com/user/thelinuxfoundation
:Palavras-chave: linux, vídeos, linux-foundation, youtube.
:Descrição: A Linux Foundation faz o upload de gravações de vídeo de seus
eventos colaborativos, conferências de Linux (incluindo a LinuxCon) e
outras pesquisas originais e conteúdos relacionados ao Linux e ao
desenvolvimento de software.
Rust
----
* Título: **Rust for Linux**
:Autor: diversos
:URL: https://rust-for-linux.com/
:Data: versão contínua (rolling)
:Palavras-chave: glossário, termos, linux-kernel, rust.
:Descrição Do site: "Rust for Linux é o projeto que adiciona suporte à
linguagem Rust ao kernel Linux. Este site pretende ser um hub de links,
documentação e recursos relacionados ao projeto".
* Título: **Learn Rust the Dangerous Way**
:Autor: Cliff L. Biffle
:URL: https://cliffle.com/p/dangerust/
:Data: Acessado em 11 de setembro de 2024
:Palavras-chave: rust, blog.
:Descrição: Do site: "LRtDW é uma série de artigos que coloca os recursos
do Rust em contexto para programadores C de baixo nível que talvez não
tenham uma formação formal em Ciência da Computação, o tipo de pessoa
que trabalha com firmware, engines de jogos, kernels de SO e afins.
Basicamente, pessoas como eu.". O site ilustra conversões de linha por
linha de C para Rust.
* Título: **The Rust Book**
:Autor: Steve Klabnik e Carol Nichols, com contribuições da comunidade Rust
:URL: https://doc.rust-lang.org/book/
:Data: Acessado em 11 de setembro de 2024
:Palavras-chave: rust, livro.
:Descrição: Do site: "Este livro abraça totalmente o potencial do Rust para
capacitar seus usuários. É um texto amigável e acessível destinado a
ajudá-lo a elevar não apenas seu conhecimento de Rust, mas também seu
alcance e confiança como programador em geral. Então mergulhe de cabeça,
prepare-se para aprender e bem-vindo à comunidade Rust!".
* Título: **Rust for the Polyglot Programmer**
:Autor: Ian Jackson
:URL: https://www.chiark.greenend.org.uk/~ianmdlvl/rust-polyglot/index.html
:Data: Dezembro de 2022
:Palavras-chave: rust, blog, tooling.
:Descrição: Do site: "Existem muitos guias e introduções ao Rust. Este é
algo diferente: destina-se ao programador experiente que já conhece
muitas outras linguagens de programação. Tento ser abrangente o suficiente
para servir de ponto de partida para qualquer área do Rust, mas evito
entrar em detalhes excessivos, exceto onde as coisas não são como você
poderia esperar. Além disso, este guia não é inteiramente isento de
opiniões, incluindo recomendações de bibliotecas (crates), ferramentas, etc.".
* Título: **Fasterthanli.me**
:Autor: Amos Wenger
:URL: https://fasterthanli.me/
:Data: Acessado em 11 de setembro de 2024
:Palavras-chave: rust, blog, notícias.
:Descrição: Do site: "Eu crio artigos e vídeos sobre como os computadores
funcionam. Meu conteúdo é de formato longo, didático e exploratório
e frequentemente uma desculpa para ensinar Rust!".
* Título: **Comprehensive Rust**
:Autor: Equipe Android do Google
:URL: https://google.github.io/comprehensive-rust/
:Data: Acessado em 13 de setembro de 2024
:Palavras-chave: rust, blog.
:Descrição: Do site: "O curso cobre todo o espectro do Rust, desde a
sintaxe básica até tópicos avançados como genéricos e tratamento de erros".
* Título: **The Embedded Rust Book**
:Autor: Múltiplos colaboradores, principalmente Jorge Aparicio
:URL: https://docs.rust-embedded.org/book/
:Data: Acessado em 13 de setembro de 2024
:Palavras-chave: rust, blog.
:Descrição: Do site: "Um livro introdutório sobre o uso da linguagem de
programação Rust em sistemas embarcados 'Bare Metal', como microcontroladores".
* Título: **Experiment: Improving the Rust Book**
:Autor: Cognitive Engineering Lab na Brown University
:URL: https://rust-book.cs.brown.edu/
:Data: Acessado em 22 de setembro de 2024
:Palavras-chave: rust, blog.
:Descrição: Do site: "O objetivo deste experimento é avaliar e melhorar o
conteúdo do Rust Book para ajudar as pessoas a aprenderem Rust de forma
mais eficaz".
* Título: **New Rustacean** (podcast)
:Autor: Chris Krycho
:URL: https://newrustacean.com/
:Data: Acessado em 22 de setembro de 2024
:Palavras-chave: rust, podcast.
:Descrição: Do site: "Este é um podcast sobre aprender a linguagem de
programação Rust do zero! Além desta página inicial elegante, todo o
conteúdo do site é construído com as próprias ferramentas de documentação
do Rust".
* Título: **Opsem-team** (repositório)
:Autor: Equipe de semântica operacional (Operational semantics team)
:URL: https://github.com/rust-lang/opsem-team/tree/main
:Data: Acessado em 22 de setembro de 2024
:Palavras-chave: rust, repositório.
:Descrição: Do README: "A equipe opsem é a sucessora do grupo de trabalho
unsafe-code-guidelines e é responsável por responder a muitas das perguntas
difíceis sobre a semântica do Rust inseguro (unsafe Rust)".
* Título: **You Can't Spell Trust Without Rust**
:Autor: Alexis Beingessner
:URL: https://repository.library.carleton.ca/downloads/1j92g820w?locale=en
:Data: 2015
:Palavras-chave: rust, mestrado, tese.
:Descrição: Esta tese foca no sistema de propriedade (ownership) do Rust,
que garante a segurança de memória ao controlar a manipulação de dados e
o tempo de vida, enquanto também destaca suas limitações e o compara a
sistemas semelhantes no Cyclone e C++.
* Nome: **Apresentações de Rust no Linux Plumbers (LPC) 2024**
:Título: Rust microconference
:URL: https://lpc.events/event/18/sessions/186/#20240918
:Título: Rust for Linux
:URL: https://lpc.events/event/18/contributions/1912/
:Título: Journey of a C kernel engineer starting a Rust driver project
:URL: https://lpc.events/event/18/contributions/1911/
:Título: Crafting a Linux kernel scheduler that runs in user-space using Rust
:URL: https://lpc.events/event/18/contributions/1723/
:Título: openHCL: A Linux and Rust based paravisor
:URL: https://lpc.events/event/18/contributions/1956/
:Palavras-chave: rust, lpc, apresentações.
:Descrição: Uma série de palestras do LPC relacionadas ao Rust.
* Nome: **The Rustacean Station Podcast**
:URL: https://rustacean-station.org/
:Palavras-chave: rust, podcasts.
:Descrição: Um projeto comunitário para a criação de conteúdo em podcast
sobre a linguagem de programação Rust.
-------
Este documento foi originalmente baseado em:
https://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html
e escrito por Juan-Mariano de Goyeneche.

483
Documentation/translations/pt_BR/process/license-rules.rst Normal file
View File

@@ -0,0 +1,483 @@
.. SPDX-License-Identifier: GPL-2.0
Regras de licenciamento do kernel Linux
=======================================
O Kernel Linux é fornecido apenas sob os termos da licença GNU General Public
License versão 2 (GPL-2.0), conforme estabelecido em LICENSES/preferred/GPL-2.0,
com uma exceção explícita para syscalls descrita em
LICENSES/exceptions/Linux-syscall-note, conforme descrito no arquivo COPYING.
Este arquivo de documentação fornece uma descrição de como cada arquivo-fonte
deve ser anotado para tornar sua licença clara e inequívoca. Ele não substitui
a licença do Kernel.
A licença descrita no arquivo COPYING aplica-se ao código-fonte do kernel como
um todo, embora arquivos-fonte individuais possam ter uma licença diferente, a
qual deve ser obrigatoriamente compatível com a GPL-2.0::
GPL-1.0+ : GNU General Public License v1.0 ou posterior
GPL-2.0+ : GNU General Public License v2.0 ou posterior
LGPL-2.0 : GNU Library General Public License v2 apenas
LGPL-2.0+ : GNU Library General Public License v2 ou posterior
LGPL-2.1 : GNU Lesser General Public License v2.1 apenas
LGPL-2.1+ : GNU Lesser General Public License v2.1 ou posterior
Além disso, arquivos individuais podem ser fornecidos sob uma licença dupla
(dual license), por exemplo, uma das variantes GPL compatíveis e,
alternativamente, sob uma licença permissiva como BSD, MIT, etc.
Os arquivos de cabeçalho da API do espaço do usuário (UAPI), que descrevem a
interface dos programas do espaço do usuário com o kernel, são um caso especial.
De acordo com a nota no arquivo COPYING do kernel, a interface de syscall é um
limite claro, que não estende os requisitos da GPL a qualquer software que a
utilize para se comunicar com o kernel. Como os cabeçalhos UAPI devem ser
passíveis de inclusão em quaisquer arquivos-fonte que criem um executável
executado no kernel Linux, a exceção deve ser documentada por uma expressão de
licença especial.
A forma comum de expressar a licença de um arquivo-fonte é adicionar o texto
padrão (boilerplate) correspondente no comentário inicial do arquivo. Devido a
variações de formatação, erros de digitação, etc., esses "textos padrão" são
difíceis de validar por ferramentas usadas no contexto de conformidade de
licença.
Uma alternativa aos textos padrão é o uso de identificadores de licença
Software Package Data Exchange (SPDX) em cada arquivo-fonte. Os identificadores
de licença SPDX são abreviações precisas e analisáveis por máquina para a
licença sob a qual o conteúdo do arquivo é contribuído. Os identificadores de
licença SPDX são gerenciados pelo Grupo de Trabalho SPDX na Linux Foundation e
foram acordados por parceiros em toda a indústria, fornecedores de ferramentas
e equipes jurídicas. Para mais informações, consulte https://spdx.org/
O kernel Linux exige o identificador SPDX preciso em todos os arquivos-fonte.
Os identificadores válidos usados no kernel são explicados na seção
`Identificadores de Licença`_ e foram obtidos da lista de licenças
oficial do SPDX em https://spdx.org/licenses/ junto com os textos das licenças.
Sintaxe do identificador de licença
-----------------------------------
1. Posicionamento:
O identificador de licença SPDX em arquivos do kernel deve ser adicionado na
primeira linha possível do arquivo que possa conter um comentário. Para a
maioria dos arquivos, esta é a primeira linha, exceto para scripts que
requerem o '#!CAMINHO_PARA_INTERPRETADOR' na primeira linha. Para esses
scripts, o identificador de licença SPDX deve ser colocado na segunda linha.
A linha do identificador de licença pode então ser seguida por uma ou
múltiplas linhas de SPDX-FileCopyrightText, se desejado.
2. Estilo:
O identificador de licença SPDX é adicionado na forma de um comentário. O
estilo do comentário depende do tipo de arquivo::
Fonte C: // SPDX-License-Identifier: <Expressão de Licença SPDX>
Cabeçalho C:/* SPDX-License-Identifier: <Expressão de Licença SPDX> */
ASM: /* SPDX-License-Identifier: <Expressão de Licença SPDX> */
scripts: # SPDX-License-Identifier: <Expressão de Licença SPDX>
.rst: .. SPDX-License-Identifier: <Expressão de Licença SPDX>
.dts{i}: // SPDX-License-Identifier: <Expressão de Licença SPDX>
Se uma ferramenta específica não conseguir lidar com o estilo de comentário
padrão, então deve ser utilizado o mecanismo de comentário apropriado que a
ferramenta aceite. Este é o motivo para ter o comentário no estilo ``/* */``
em arquivos de cabeçalho C. Foi observada uma quebra de build com arquivos
.lds gerados, onde o 'ld' falhou ao analisar o comentário C++. Isso já foi
corrigido, mas ainda existem ferramentas de assembler mais antigas que não
conseguem lidar com comentários no estilo C++.
3. Sintaxe:
Uma <Expressão de Licença SPDX> pode ser um identificador SPDX simplificado
encontrado na Lista de Licenças SPDX, ou a combinação de dois desses
identificadores separados por "WITH", caso uma exceção de licença se aplique.
Quando múltiplas licenças são aplicáveis, a expressão utiliza as palavras-chave
"AND" ou "OR" para separar as sub-expressões, que devem ser delimitadas
por parênteses "(", ")".
Para licenças como [L]GPL, utiliza-se o sufixo "+" para indicar a opção
'ou posterior'::
// SPDX-License-Identifier: GPL-2.0+
// SPDX-License-Identifier: LGPL-2.1+
O termo "WITH" deve ser usado sempre que houver um modificador necessário
para a licença. Por exemplo, os arquivos UAPI do kernel Linux utilizam a
expressão::
// SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note
// SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note
Outros exemplos de uso da cláusula "WITH" para exceções no kernel são::
// SPDX-License-Identifier: GPL-2.0 WITH mif-exception
// SPDX-License-Identifier: GPL-2.0+ WITH GCC-exception-2.0
As exceções só podem ser aplicadas a identificadores de licença específicos.
Os identificadores válidos estão listados nas tags do arquivo de texto de
cada exceção. Para detalhes, veja o ponto `Exceções`_ no capítulo
`Identificadores de Licença`_.
O termo "OR" deve ser usado se o arquivo possuir licenciamento duplo (dual
licensed) e apenas uma das licenças puder ser selecionada. Por exemplo,
alguns arquivos dtsi estão disponíveis sob licença dupla::
// SPDX-License-Identifier: GPL-2.0 OR BSD-3-Clause
Exemplos de expressões para arquivos com licenciamento duplo no kernel::
// SPDX-License-Identifier: GPL-2.0 OR MIT
// SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause
// SPDX-License-Identifier: GPL-2.0 OR Apache-2.0
// SPDX-License-Identifier: GPL-2.0 OR MPL-1.1
// SPDX-License-Identifier: (GPL-2.0 WITH Linux-syscall-note) OR MIT
// SPDX-License-Identifier: GPL-1.0+ OR BSD-3-Clause OR OpenSSL
O termo "AND" deve ser usado se o arquivo possuir múltiplas licenças cujos
termos devem ser aplicados simultaneamente. Por exemplo, se um código herdado
de outro projeto foi incorporado ao kernel, mas os termos da licença original
ainda precisam ser respeitados::
// SPDX-License-Identifier: (GPL-2.0 WITH Linux-syscall-note) AND MIT
Outro exemplo onde ambos os conjuntos de termos devem ser cumpridos é::
// SPDX-License-Identifier: GPL-1.0+ AND LGPL-2.1+
Identificadores de Licença
--------------------------
As licenças atualmente em uso, bem como as licenças para código adicionado ao
kernel, podem ser divididas em:
4. _`Licenças preferenciais`:
Sempre que possível, estas licenças devem ser utilizadas, pois são conhecidas
por serem totalmente compatíveis e amplamente usadas. Estas licenças estão
disponíveis no diretório::
LICENSES/preferred/
na árvore de diretórios do código-fonte do kernel.
Os arquivos neste diretório contêm o texto completo da licença e as
`Metatags`_. Os nomes dos arquivos são idênticos ao identificador de licença
SPDX que deve ser utilizado para a licença nos arquivos-fonte.
Exemplos::
LICENSES/preferred/GPL-2.0
Contém o texto da licença GPL versão 2 e as metatags obrigatórias::
LICENSES/preferred/MIT
Contém o texto da licença MIT e as metatags obrigatórias.
_`Metatags`:
As seguintes metatags devem estar presentes em um arquivo de licença:
- Valid-License-Identifier:
Uma ou mais linhas que declaram quais Identificadores de Licença são válidos
dentro do projeto para referenciar este texto de licença específico.
Geralmente, trata-se de um único identificador válido, mas, por exemplo,
para licenças com as opções 'ou posterior' (or later), dois identificadores
são válidos.
- SPDX-URL:
A URL da página SPDX que contém informações adicionais relacionadas à licença.
- Usage-Guidance:
Texto livre para conselhos de uso. O texto deve incluir exemplos corretos
para os identificadores de licença SPDX, conforme eles devem ser colocados
nos arquivos-fonte de acordo com as diretrizes de
`Sintaxe do identificador de licença`_.
- License-Text:
Todo o texto após esta tag é tratado como o texto original da licença.
Exemplos de formato de arquivo::
Valid-License-Identifier: GPL-2.0
Valid-License-Identifier: GPL-2.0+
SPDX-URL: https://spdx.org/licenses/GPL-2.0.html
Usage-Guide:
Para usar esta licença no código-fonte, coloque um dos seguintes pares
SPDX tag/valor em um comentário, de acordo com as diretrizes de
posicionamento na documentação das regras de licenciamento.
Para 'GNU General Public License (GPL) version 2 only', use:
SPDX-License-Identifier: GPL-2.0
Para 'GNU General Public License (GPL) version 2 or any later version', use:
SPDX-License-Identifier: GPL-2.0+
License-Text:
Texto completo da licença
::
Valid-License-Identifier: MIT
SPDX-URL: https://spdx.org/licenses/MIT.html
Usage-Guide:
Para usar esta licença no código-fonte, coloque o seguinte par SPDX
tag/valor em um comentário, de acordo com as diretrizes de
posicionamento na documentação das regras de licenciamento.
SPDX-License-Identifier: MIT
License-Text:
Texto completo da licença
5. Licenças obsoletas:
Estas licenças devem ser utilizadas apenas para código já existente ou para
a importação de código de outros projetos. Estas licenças estão disponíveis
no diretório::
LICENSES/deprecated/
na árvore de fontes do kernel.
Os arquivos neste diretório contêm o texto completo da licença e as
`Metatags`_. Os nomes dos arquivos são idênticos ao identificador de
licença SPDX que deve ser utilizado para a licença nos arquivos fonte.
Exemplos::
LICENSES/deprecated/ISC
Contém o texto da licença *Internet Systems Consortium* e as metatags
necessárias::
LICENSES/deprecated/GPL-1.0
Contém o texto da licença GPL versão 1 e as metatags necessárias.
Metatags:
Os requisitos de metatags para "outras" licenças são idênticos aos
requisitos das `Licenças preferenciais`_.
Exemplo de formato de arquivo::
Valid-License-Identifier: ISC
SPDX-URL: https://spdx.org/licenses/ISC.html
Usage-Guide:
O uso desta licença no kernel para novos códigos é desencorajado
e deve ser utilizada exclusivamente para importar código de um
projeto já existente.
Para usar esta licença no código-fonte, coloque o seguinte par
tag/valor SPDX em um comentário, seguindo as diretrizes de
posicionamento na documentação das regras de licenciamento.
SPDX-License-Identifier: ISC
License-Text:
Texto completo da licença
6. Apenas Licenciamento Duplo
Estas licenças devem ser usadas apenas para o licenciamento duplo de código
com outra licença, além de uma licença preferencial. Estas licenças estão
disponíveis no diretório::
LICENSES/dual/
No código-fonte do kernel.
Os arquivos neste diretório contêm o texto completo da licença e as
`Metatags`_. Os nomes dos arquivos são idênticos ao identificador de licença
SPDX que deve ser usado para a licença nos arquivos fonte.
Exemplos::
LICENSES/dual/MPL-1.1
Contém o texto da licença Mozilla Public License versão 1.1 e as metatags
necessárias::
LICENSES/dual/Apache-2.0
Contém o texto da licença Apache License versão 2.0 e as metatags
necessárias.
Metatags:
Os requisitos de metatags para 'outras' licenças são idênticos aos
requisitos das `Licenças preferenciais`_.
Exemplo de formato de arquivo::
Valid-License-Identifier: MPL-1.1
SPDX-URL: https://spdx.org/licenses/MPL-1.1.html
Usage-Guide:
NÃO use. A licença MPL-1.1 não é compatível com a GPL2. Ela só pode ser
usada para arquivos com licenciamento duplo onde a outra licença seja
compatível com a GPL2.
Se você acabar utilizando-a, ela DEVE ser usada em conjunto com uma
licença compatível com a GPL2 utilizando "OR".
Para usar a Mozilla Public License versão 1.1, coloque o seguinte par
tag/valor SPDX em um comentário, de acordo com as diretrizes de
posicionamento na documentação das regras de licenciamento:
SPDX-License-Identifier: MPL-1.1
License-Text:
Texto completo da licença
|
7. _`Exceções`:
Algumas licenças podem ser alteradas com exceções que concedem certos direitos
que a licença original não concede. Estas exceções estão disponíveis no
diretório::
LICENSES/exceptions/
no código-fonte do kernel. Os arquivos neste diretório contêm o texto completo
da exceção e as `Metatags de Exceção`_ necessárias.
Exemplos::
LICENSES/exceptions/Linux-syscall-note
Contém a exceção de syscall do Linux, conforme documentado no arquivo COPYING
do kernel Linux, que é usada para arquivos de cabeçalho UAPI.
ex: /\* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note \*/::
LICENSES/exceptions/GCC-exception-2.0
Contém a 'exceção de vinculação' do GCC, que permite
vincular qualquer binário, independente de sua licença, à versão compilada
de um arquivo marcado com esta exceção. Isso é necessário para criar
executáveis funcionais a partir de código-fonte que não seja compatível
com a GPL.
_`Metatags de Exceção`:
As seguintes meta tags devem estar disponíveis em um arquivo de exceção:
- SPDX-Exception-Identifier:
Um identificador de exceção que pode ser usado com identificadores de
licença SPDX.
- SPDX-URL:
A URL da página SPDX que contém informações adicionais relacionadas
à exceção.
- SPDX-Licenses:
Uma lista separada por vírgulas de identificadores de licença SPDX para os
quais a exceção pode ser usada.
- Usage-Guidance:
Texto de formato livre para conselhos de uso. O texto deve ser seguido por
exemplos corretos para os identificadores de licença SPDX, conforme devem
ser colocados nos arquivos fonte de acordo com as diretrizes de
`Sintaxe do identificador de licença`_.
- Exception-Text:
Todo o texto após esta tag é tratado como o texto original da exceção.
Exemplos de formato de arquivo::
SPDX-Exception-Identifier: Linux-syscall-note
SPDX-URL: https://spdx.org/licenses/Linux-syscall-note.html
SPDX-Licenses: GPL-2.0, GPL-2.0+, GPL-1.0+, LGPL-2.0, LGPL-2.0+, LGPL-2.1, LGPL-2.1+
Usage-Guidance:
Esta exceção é usada em conjunto com uma das SPDX-Licenses acima para
marcar arquivos de cabeçalho de API do espaço do usuário (uapi), para que
possam ser incluídos em código de aplicativo de espaço do usuário que não
esteja em conformidade com a GPL.
Para usar esta exceção, adicione-a com a palavra-chave WITH a um dos
identificadores na tag SPDX-Licenses:
SPDX-License-Identifier: <SPDX-License> WITH Linux-syscall-note
Exception-Text:
Texto completo da exceção
Exemplos de formato de arquivo::
SPDX-Exception-Identifier: GCC-exception-2.0
SPDX-URL: https://spdx.org/licenses/GCC-exception-2.0.html
SPDX-Licenses: GPL-2.0, GPL-2.0+
Usage-Guidance:
A "GCC Runtime Library exception 2.0" é usada em conjunto com uma das
SPDX-Licenses acima para código importado da biblioteca de tempo de
execução (runtime) do GCC.
Para usar esta exceção, adicione-a com a palavra-chave WITH a um dos
identificadores na tag SPDX-Licenses:
SPDX-License-Identifier: <SPDX-License> WITH GCC-exception-2.0
Exception-Text:
Texto completo da exceção
Todos os identificadores de licença e exceções SPDX devem ter um arquivo
correspondente nos subdiretórios LICENSES. Isso é necessário para permitir a
verificação por ferramentas (ex: checkpatch.pl) e para que as licenças estejam
prontas para leitura e extração diretamente da fonte, o que é recomendado por
várias organizações de FOSS (Software Livre e de Código Aberto), como a
`iniciativa REUSE da FSFE <https://reuse.software/>`_.
_`MODULE_LICENSE`
-----------------
Módulos carregáveis do kernel também exigem uma tag MODULE_LICENSE(). Esta tag
não substitui as informações adequadas de licença do código-fonte
(SPDX-License-Identifier), nem é de forma alguma relevante para expressar ou
determinar a licença exata sob a qual o código-fonte do módulo é fornecido.
O único propósito desta tag é fornecer informações suficientes ao carregador
de módulos do kernel e às ferramentas de espaço do usuário sobre o módulo ser
software livre ou proprietário.
As strings de licença válidas para MODULE_LICENSE() são::
============================= =============================================
"GPL" O módulo está licenciado sob a GPL versão 2.
Isso não expressa nenhuma distinção entre
GPL-2.0-only ou GPL-2.0-or-later. A informação
exata da licença só pode ser determinada por
meio das informações de licença nos arquivos
fonte correspondentes.
"GPL v2" O mesmo que "GPL". Existe por razões
históricas.
"GPL and additional rights" Variante histórica para expressar que o fonte
do módulo possui licenciamento duplo sob uma
variante da GPL v2 e a licença MIT. Por favor,
não use em códigos novos.
"Dual MIT/GPL" A maneira correta de expressar que o módulo
possui licenciamento duplo sob uma escolha de
variante GPL v2 ou licença MIT.
"Dual BSD/GPL" O módulo possui licenciamento duplo sob uma
escolha de variante GPL v2 ou licença BSD. A
variante exata da licença BSD só pode ser
determinada por meio das informações de
licença nos arquivos fonte correspondentes.
"Dual MPL/GPL" O módulo possui licenciamento duplo sob uma
escolha de variante GPL v2 ou Mozilla Public
License (MPL). A variante exata da licença
MPL só pode ser determinada por meio das
informações de licença nos arquivos fonte
correspondentes.
"Proprietary" O módulo está sob uma licença proprietária.
"Proprietary" deve ser entendido apenas como
"A licença não é compatível com GPLv2". Esta
string é exclusiva para módulos de terceiros
não compatíveis com GPL2 e não pode ser usada
para módulos que tenham seu código-fonte na
árvore do kernel. Módulos marcados dessa forma
contaminam (tainting) o kernel com a flag 'P'
quando carregados, e o carregador de módulos
recusa-se a vincular tais módulos a símbolos
exportados com EXPORT_SYMBOL_GPL().
============================= =============================================

18
Documentation/translations/pt_BR/process/maintainer-handbooks.rst
View File

@@ -6,13 +6,17 @@ Notas sobre o processo de desenvolvimento de subsistemas e mantenedores
O propósito deste documento é fornecer informações específicas de
subsistemas que são suplementares ao manual geral do processo de
desenvolvimento.
:ref:`Documentation/process <development_process_main>`.
Conteúdos:
Para desenvolvedores, veja abaixo todos os guias específicos de
subsistemas conhecidos. Se o subsistema para o qual você está
contribuindo não tiver um guia listado aqui, é recomendável buscar
esclarecimentos sobre as questões levantadas em
Documentation/maintainer/maintainer-entry-profile.rst.
.. toctree::
:numbered:
:maxdepth: 2
Para mantenedores, considere documentar requisitos adicionais e
expectativas caso as submissões frequentemente deixem de atender
a critérios específicos de submissão. Veja
Documentation/maintainer/maintainer-entry-profile.rst.
maintainer-netdev
maintainer-soc
maintainer-soc-clean-dts
.. maintainers-profile-toc::

12
Documentation/translations/pt_BR/process/maintainer-soc.rst
View File

@@ -8,7 +8,7 @@ Visão Geral
-----------
O subsistema SoC é um local de agregação para códigos específicos de SoC
System on Chip). Os principais componentes do subsistema são:
(System on Chip). Os principais componentes do subsistema são:
* Devicetrees (DTS) para ARM de 32 e 64 bits e RISC-V.
* Arquivos de placa (board files) ARM de 32 bits (arch/arm/mach*).
@@ -220,3 +220,13 @@ A linha de assunto de um pull request deve começar com "[GIT PULL]" e ser feita
usando uma tag assinada, em vez de um branch. Esta tag deve conter uma breve
descrição resumindo as alterações no pull request. Para mais detalhes sobre o
envio de pull requests, consulte ``Documentation/maintainer/pull-requests.rst``.
Propósito dos Defconfigs
~~~~~~~~~~~~~~~~~~~~~~~~
Defconfigs são usados principalmente pelos desenvolvedores do kernel, porque as
distribuições têm suas próprias configurações. Uma mudança que adiciona novas
opções CONFIG a um defconfig deve explicar por que os desenvolvedores do kernel
em geral gostariam de tal opção, por exemplo, fornecendo o nome de uma máquina/placa
suportada usando essa nova opção. Isso implica que habilitar opções em defconfig
para máquinas não upstream não deve ser aceito.

2
Documentation/translations/sp_SP/process/coding-style.rst
View File

@@ -955,7 +955,7 @@ La forma preferida para pasar el tamaño de una estructura es la siguiente:
.. code-block:: c
p = kmalloc(sizeof(*p), ...);
p = kmalloc_obj(*p, ...);
La forma alternativa donde se deletrea el nombre de la estructura perjudica
la legibilidad, y presenta una oportunidad para un error cuando se cambia

2
Documentation/translations/sp_SP/process/submit-checklist.rst
View File

@@ -76,7 +76,7 @@ y en otros lugares con respecto al envío de parches del kernel de Linux.
cualquier problema.
12) Ha sido probado con ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``,
``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``,
``CONFIG_SLUB_DEBUG``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``,
``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``
``CONFIG_PROVE_RCU`` y ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` todos
habilitados simultáneamente.

4
Documentation/translations/zh_CN/core-api/kref.rst
View File

@@ -52,7 +52,7 @@ kref可以出现在数据结构体中的任何地方。
struct my_data *data;
data = kmalloc(sizeof(*data), GFP_KERNEL);
data = kmalloc_obj(*data);
if (!data)
return -ENOMEM;
kref_init(&data->refcount);
@@ -106,7 +106,7 @@ Kref规则
int rv = 0;
struct my_data *data;
struct task_struct *task;
data = kmalloc(sizeof(*data), GFP_KERNEL);
data = kmalloc_obj(*data);
if (!data)
return -ENOMEM;
kref_init(&data->refcount);

2
Documentation/translations/zh_CN/process/coding-style.rst
View File

@@ -813,7 +813,7 @@ Documentation/translations/zh_CN/core-api/memory-allocation.rst 。
.. code-block:: c
p = kmalloc(sizeof(*p), ...);
p = kmalloc_obj(*p, ...);
另外一种传递方式中，sizeof 的操作数是结构体的名字，这样会降低可读性，并且可能
会引入 bug。有可能指针变量类型被改变时，而对应的传递给内存分配函数的 sizeof

2
Documentation/translations/zh_CN/process/submit-checklist.rst
View File

@@ -65,7 +65,7 @@ Linux内核补丁提交检查单
:ref:`kernel-doc <kernel_doc_zh>` 并修复任何问题。
12) 通过以下选项同时启用的测试： ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``,
``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``,
``CONFIG_SLUB_DEBUG``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``,
``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``,
``CONFIG_PROVE_RCU`` 和 ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` 。

2
Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
View File

@@ -799,7 +799,7 @@ int my_open(struct file *file)
...
my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);
my_fh = kzalloc_obj(*my_fh);
...

2
Documentation/translations/zh_TW/process/coding-style.rst
View File

@@ -827,7 +827,7 @@ Documentation/translations/zh_CN/core-api/memory-allocation.rst 。
.. code-block:: c
p = kmalloc(sizeof(*p), ...);
p = kmalloc_obj(*p, ...);
另外一種傳遞方式中，sizeof 的操作數是結構體的名字，這樣會降低可讀性，並且可能
會引入 bug。有可能指針變量類型被改變時，而對應的傳遞給內存分配函數的 sizeof

2
Documentation/translations/zh_TW/process/submit-checklist.rst
View File

@@ -68,7 +68,7 @@ Linux內核補丁提交檢查單
:ref:`kernel-doc <kernel_doc_zh>` 並修復任何問題。
12) 通過以下選項同時啓用的測試： ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``,
``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``,
``CONFIG_SLUB_DEBUG``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``,
``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``,
``CONFIG_PROVE_RCU`` 和 ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` 。

2
Documentation/virt/uml/user_mode_linux_howto_v2.rst
View File

@@ -234,7 +234,7 @@ an ioctl to setup the tun interface and/or use raw sockets where needed.
This can be achieved by granting the user a particular capability instead
of running UML as root. In case of vector transport, a user can add the
capability ``CAP_NET_ADMIN`` or ``CAP_NET_RAW`` to the uml binary.
Thenceforth, UML can be run with normal user privilges, along with
Thenceforth, UML can be run with normal user privileges, along with
full networking.
For example::

4
Documentation/watchdog/mlx-wdt.rst
View File

@@ -28,7 +28,7 @@ Type 3:
Same as Type 2 with extended maximum timeout period.
Maximum timeout is 65535 sec.
Type 1 HW watchdog implementation exist in old systems and
Type 1 HW watchdog implementation exists in old systems and
all new systems have type 2 HW watchdog.
Two types of HW implementation have also different register map.
@@ -48,7 +48,7 @@ which is optional.
Watchdog can be started during a probe, in this case it will be
pinged by watchdog core before watchdog device will be opened by
user space application.
Watchdog can be initialised in nowayout way, i.e. oncse started
Watchdog can be initialised in nowayout mode, i.e. once started
it can't be stopped.
This mlx-wdt driver supports both HW watchdog implementations.

19
Documentation/watchdog/pcwd-watchdog.rst
View File

@@ -29,7 +29,7 @@ Documentation and Driver by Ken Hollis <kenji@bitgate.com>
to run the program with an "&" to run it in the background!)
If you want to write a program to be compatible with the PC Watchdog
driver, simply use of modify the watchdog test program:
driver, simply use or modify the watchdog test program:
tools/testing/selftests/watchdog/watchdog-test.c
@@ -37,16 +37,23 @@ Documentation and Driver by Ken Hollis <kenji@bitgate.com>
WDIOC_GETSUPPORT
This returns the support of the card itself. This
returns in structure "PCWDS" which returns:
returns in structure watchdog_info:
identity = "PCWD"
options = list of supported options::
WDIOF_OVERHEAT
WDIOF_CARDRESET
WDIOF_KEEPALIVEPING
WDIOF_SETTIMEOUT
WDIOF_MAGICCLOSE
options = WDIOS_TEMPPANIC
(This card supports temperature)
firmware_version = xxxx
(Firmware version of the card)
WDIOC_GETSTATUS
This returns the status of the card, with the bits of
WDIOF_* bitwise-anded into the value. (The comments
WDIOF_* bitwise-ored into the value. (The comments
are in include/uapi/linux/watchdog.h)
WDIOC_GETBOOTSTATUS
@@ -55,7 +62,7 @@ Documentation and Driver by Ken Hollis <kenji@bitgate.com>
WDIOC_GETTEMP
This returns the temperature of the card. (You can also
read /dev/watchdog, which gives a temperature update
read /dev/temperature, which gives a temperature update
every second.)
WDIOC_SETOPTIONS

38
Documentation/watchdog/watchdog-api.rst
View File

@@ -39,12 +39,12 @@ The simplest API
All drivers support the basic mode of operation, where the watchdog
activates as soon as /dev/watchdog is opened and will reboot unless
the watchdog is pinged within a certain time, this time is called the
the watchdog is pinged within a certain time; this time is called the
timeout or margin. The simplest way to ping the watchdog is to write
some data to the device. So a very simple watchdog daemon would look
like this source file: see samples/watchdog/watchdog-simple.c
A more advanced driver could for example check that a HTTP server is
A more advanced driver could for example check that an HTTP server is
still responding before doing the write call to ping the watchdog.
When the device is closed, the watchdog is disabled, unless the "Magic
@@ -87,13 +87,13 @@ replaced with::
sleep(10);
}
the argument to the ioctl is ignored.
The argument to the ioctl is ignored.
Setting and getting the timeout
===============================
For some drivers it is possible to modify the watchdog timeout on the
fly with the SETTIMEOUT ioctl, those drivers have the WDIOF_SETTIMEOUT
fly with the SETTIMEOUT ioctl; those drivers have the WDIOF_SETTIMEOUT
flag set in their option field. The argument is an integer
representing the timeout in seconds. The driver returns the real
timeout used in the same variable, and this timeout might differ from
@@ -110,7 +110,7 @@ Starting with the Linux 2.4.18 kernel, it is possible to query the
current timeout using the GETTIMEOUT ioctl::
ioctl(fd, WDIOC_GETTIMEOUT, &timeout);
printf("The timeout was is %d seconds\n", timeout);
printf("The timeout is %d seconds\n", timeout);
Pretimeouts
===========
@@ -133,7 +133,7 @@ seconds. Setting a pretimeout to zero disables it.
There is also a get function for getting the pretimeout::
ioctl(fd, WDIOC_GETPRETIMEOUT, &timeout);
printf("The pretimeout was is %d seconds\n", timeout);
printf("The pretimeout is %d seconds\n", timeout);
Not all watchdog drivers will support a pretimeout.
@@ -145,13 +145,13 @@ before the system will reboot. The WDIOC_GETTIMELEFT is the ioctl
that returns the number of seconds before reboot::
ioctl(fd, WDIOC_GETTIMELEFT, &timeleft);
printf("The timeout was is %d seconds\n", timeleft);
printf("The timeout is %d seconds\n", timeleft);
Environmental monitoring
========================
All watchdog drivers are required return more information about the system,
some do temperature, fan and power level monitoring, some can tell you
All watchdog drivers are required to return more information about the system.
Some do temperature, fan and power level monitoring; some can tell you
the reason for the last reboot of the system. The GETSUPPORT ioctl is
available to ask what the device can do::
@@ -166,7 +166,7 @@ the fields returned in the struct watchdog_info are:
options a flags describing what the device supports
================ =============================================
the options field can have the following bits set, and describes what
The options field can have the following bits set, and describes what
kind of information that the GET_STATUS and GET_BOOT_STATUS ioctls can
return.
@@ -175,13 +175,13 @@ return.
================ =========================
The machine was last rebooted by the watchdog because the thermal limit was
exceeded:
exceeded.
============== ==========
WDIOF_FANFAULT Fan failed
============== ==========
A system fan monitored by the watchdog card has failed
A system fan monitored by the watchdog card has failed.
============= ================
WDIOF_EXTERN1 External relay 1
@@ -195,26 +195,26 @@ a reset.
WDIOF_EXTERN2 External relay 2
============= ================
External monitoring relay/source 2 was triggered
External monitoring relay/source 2 was triggered.
================ =====================
WDIOF_POWERUNDER Power bad/power fault
================ =====================
The machine is showing an undervoltage status
The machine is showing an undervoltage status.
=============== =============================
WDIOF_CARDRESET Card previously reset the CPU
=============== =============================
The last reboot was caused by the watchdog card
The last reboot was caused by the watchdog card.
================ =====================
WDIOF_POWEROVER Power over voltage
================ =====================
The machine is showing an overvoltage status. Note that if one level is
under and one over both bits will be set - this may seem odd but makes
under and one over, both bits will be set - this may seem odd but makes
sense.
=================== =====================
@@ -227,12 +227,14 @@ The watchdog saw a keepalive ping since it was last queried.
WDIOF_SETTIMEOUT Can set/get the timeout
================ =======================
The watchdog can do pretimeouts.
The watchdog can get/set the timeout.
================ ================================
WDIOF_PRETIMEOUT Pretimeout (in seconds), get/set
================ ================================
The watchdog can do pretimeouts.
For those drivers that return any bits set in the option field, the
GETSTATUS and GETBOOTSTATUS ioctls can be used to ask for the current
@@ -255,7 +257,7 @@ returned value is the temperature in degrees Fahrenheit::
ioctl(fd, WDIOC_GETTEMP, &temperature);
Finally the SETOPTIONS ioctl can be used to control some aspects of
the cards operation::
the card's operation::
int options = 0;
ioctl(fd, WDIOC_SETOPTIONS, &options);

20
Documentation/watchdog/watchdog-kernel-api.rst
View File

@@ -38,8 +38,8 @@ The watchdog_unregister_device routine deregisters a registered watchdog timer
device. The parameter of this routine is the pointer to the registered
watchdog_device structure.
The watchdog subsystem includes an registration deferral mechanism,
which allows you to register an watchdog as early as you wish during
The watchdog subsystem includes a registration deferral mechanism,
which allows you to register a watchdog as early as you wish during
the boot process.
There is also a resource-managed watchdog_register_device(),
@@ -68,13 +68,14 @@ The watchdog device structure looks like this::
unsigned int max_hw_heartbeat_ms;
struct notifier_block reboot_nb;
struct notifier_block restart_nb;
struct notifier_block pm_nb;
void *driver_data;
struct watchdog_core_data *wd_data;
unsigned long status;
struct list_head deferred;
};
It contains following fields:
It contains the following fields:
* id: set by watchdog_register_device, id 0 is special. It has both a
/dev/watchdog0 cdev (dynamic major, minor 0) as well as the old
@@ -113,6 +114,8 @@ It contains following fields:
internal use only. If a watchdog is capable of restarting the machine, it
should define ops->restart. Priority can be changed through
watchdog_set_restart_priority.
* pm_nb: coordinates watchdog_dev_suspend/resume to cancel a ping worker
during suspend and restore it during resume.
* bootstatus: status of the device after booting (reported with watchdog
WDIOF_* status bits).
* driver_data: a pointer to the drivers private data of a watchdog device.
@@ -212,7 +215,7 @@ they are supported. These optional routines/operations are:
If the watchdog driver does not have to perform any action but setting the
watchdog_device.timeout, this callback can be omitted.
If set_timeout is not provided but, WDIOF_SETTIMEOUT is set, the watchdog
If set_timeout is not provided but WDIOF_SETTIMEOUT is set, the watchdog
infrastructure updates the timeout value of the watchdog_device internally
to the requested value.
@@ -228,7 +231,7 @@ they are supported. These optional routines/operations are:
the watchdog". A value of 0 disables pretimeout notification.
(Note: the WDIOF_PRETIMEOUT needs to be set in the options field of the
watchdog's info structure).
watchdog's info structure.)
If the watchdog driver does not have to perform any action but setting the
watchdog_device.pretimeout, this callback can be omitted. That means if
@@ -247,7 +250,7 @@ they are supported. These optional routines/operations are:
The status bits should (preferably) be set with the set_bit and clear_bit alike
bit-operations. The status bits that are defined are:
* WDOG_ACTIVE: this status bit indicates whether or not a watchdog timer device
* WDOG_ACTIVE: this status bit indicates whether a watchdog timer device
is active or not from user perspective. User space is expected to send
heartbeat requests to the driver while this flag is set.
* WDOG_NO_WAY_OUT: this bit stores the nowayout setting for the watchdog.
@@ -262,6 +265,9 @@ bit-operations. The status bits that are defined are:
then opening /dev/watchdog will skip the start operation but send a keepalive
request instead.
Helper Functions
~~~~~~~~~~~~~~~~
To set the WDOG_NO_WAY_OUT status bit (before registering your watchdog
timer device) you can either:
@@ -339,7 +345,7 @@ To raise a pretimeout notification, the following function should be used::
void watchdog_notify_pretimeout(struct watchdog_device *wdd)
The function can be called in the interrupt context. If watchdog pretimeout
governor framework (kbuild CONFIG_WATCHDOG_PRETIMEOUT_GOV symbol) is enabled,
governor framework (kconfig CONFIG_WATCHDOG_PRETIMEOUT_GOV symbol) is enabled,
an action is taken by a preconfigured pretimeout governor preassigned to
the watchdog device. If watchdog pretimeout governor framework is not
enabled, watchdog_notify_pretimeout() prints a notification message to

11
Documentation/watchdog/watchdog-parameters.rst
View File

@@ -14,13 +14,22 @@ modules.
-------------------------------------------------
watchdog core:
handle_boot_enabled:
Watchdog core auto-updates boot-enabled watchdogs before userspace
takes over. Default is set by the kconfig option
CONFIG_WATCHDOG_HANDLE_BOOT_ENABLED.
open_timeout:
Maximum time, in seconds, for which the watchdog framework will take
care of pinging a running hardware watchdog until userspace opens the
corresponding /dev/watchdogN device. A value of 0 means an infinite
timeout. Setting this to a non-zero value can be useful to ensure that
either userspace comes up properly, or the board gets reset and allows
fallback logic in the bootloader to try something else.
fallback logic in the bootloader to try something else. Default is set
by the kconfig option CONFIG_WATCHDOG_OPEN_TIMEOUT.
stop_on_reboot:
Stops watchdogs on reboot (0 = keep watching, 1 = stop).
-------------------------------------------------

8
MAINTAINERS
View File

@@ -25,9 +25,9 @@ Descriptions of section entries and preferred order
C: URI for *chat* protocol, server and channel where developers
usually hang out, for example irc://server/channel.
P: *Subsystem Profile* document for more details submitting
patches to the given subsystem. This is either an in-tree file,
or a URI. See Documentation/maintainer/maintainer-entry-profile.rst
for details.
patches to the given subsystem. This is either an in-tree .rst file
inside Documentation/, or a URI.
See Documentation/maintainer/maintainer-entry-profile.rst for details.
T: *SCM* tree type and location.
Type is one of: git, hg, quilt, stgit, topgit
F: *Files* and directories wildcard patterns.
@@ -23516,7 +23516,7 @@ S: Maintained
W: https://rust-for-linux.com/pin-init
B: https://github.com/Rust-for-Linux/pin-init/issues
C: zulip://rust-for-linux.zulipchat.com
P: rust/pin-init/CONTRIBUTING.md
P: https://github.com/Rust-for-Linux/pin-init/blob/main/CONTRIBUTING.md
T: git https://github.com/Rust-for-Linux/linux.git pin-init-next
F: rust/kernel/init.rs
F: rust/pin-init/

92
fs/cramfs/README
View File

@@ -104,94 +104,4 @@ Tools
-----
The cramfs user-space tools, including mkcramfs and cramfsck, are
located at <http://sourceforge.net/projects/cramfs/>.
Future Development
==================
Block Size
----------
(Block size in cramfs refers to the size of input data that is
compressed at a time. It's intended to be somewhere around
PAGE_SIZE for cramfs_read_folio's convenience.)
The superblock ought to indicate the block size that the fs was
written for, since comments in <linux/pagemap.h> indicate that
PAGE_SIZE may grow in future (if I interpret the comment
correctly).
Currently, mkcramfs #define's PAGE_SIZE as 4096 and uses that
for blksize, whereas Linux-2.3.39 uses its PAGE_SIZE, which in
turn is defined as PAGE_SIZE (which can be as large as 32KB on arm).
This discrepancy is a bug, though it's not clear which should be
changed.
One option is to change mkcramfs to take its PAGE_SIZE from
<asm/page.h>. Personally I don't like this option, but it does
require the least amount of change: just change `#define
PAGE_SIZE (4096)' to `#include <asm/page.h>'. The disadvantage
is that the generated cramfs cannot always be shared between different
kernels, not even necessarily kernels of the same architecture if
PAGE_SIZE is subject to change between kernel versions
(currently possible with arm and ia64).
The remaining options try to make cramfs more sharable.
One part of that is addressing endianness. The two options here are
`always use little-endian' (like ext2fs) or `writer chooses
endianness; kernel adapts at runtime'. Little-endian wins because of
code simplicity and little CPU overhead even on big-endian machines.
The cost of swabbing is changing the code to use the le32_to_cpu
etc. macros as used by ext2fs. We don't need to swab the compressed
data, only the superblock, inodes and block pointers.
The other part of making cramfs more sharable is choosing a block
size. The options are:
1. Always 4096 bytes.
2. Writer chooses blocksize; kernel adapts but rejects blocksize >
PAGE_SIZE.
3. Writer chooses blocksize; kernel adapts even to blocksize >
PAGE_SIZE.
It's easy enough to change the kernel to use a smaller value than
PAGE_SIZE: just make cramfs_read_folio read multiple blocks.
The cost of option 1 is that kernels with a larger PAGE_SIZE
value don't get as good compression as they can.
The cost of option 2 relative to option 1 is that the code uses
variables instead of #define'd constants. The gain is that people
with kernels having larger PAGE_SIZE can make use of that if
they don't mind their cramfs being inaccessible to kernels with
smaller PAGE_SIZE values.
Option 3 is easy to implement if we don't mind being CPU-inefficient:
e.g. get read_folio to decompress to a buffer of size MAX_BLKSIZE (which
must be no larger than 32KB) and discard what it doesn't need.
Getting read_folio to read into all the covered pages is harder.
The main advantage of option 3 over 1, 2, is better compression. The
cost is greater complexity. Probably not worth it, but I hope someone
will disagree. (If it is implemented, then I'll re-use that code in
e2compr.)
Another cost of 2 and 3 over 1 is making mkcramfs use a different
block size, but that just means adding and parsing a -b option.
Inode Size
----------
Given that cramfs will probably be used for CDs etc. as well as just
silicon ROMs, it might make sense to expand the inode a little from
its current 12 bytes. Inodes other than the root inode are followed
by filename, so the expansion doesn't even have to be a multiple of 4
bytes.
located at <https://github.com/npitre/cramfs-tools>.

54
tools/lib/python/kdoc/kdoc_parser.py
View File

@@ -380,9 +380,36 @@ class KernelDoc:
#
if dtype == '':
if param.endswith("..."):
if len(param) > 3: # there is a name provided, use that
named_variadic = len(param) > 3
if named_variadic: # there is a name provided, use that
#
# If the user documented the parameter using the
# ``@name...:`` form, the description is stored in
# parameterdescs under the unstripped key. Migrate
# it to the stripped key so the user's text is not
# silently dropped during output, and so the new
# excess-parameter check in check_sections() does
# not flag the unstripped key as orphaned.
#
orig = self.entry.parameterdescs.pop(param, None)
param = param[:-3]
if orig is not None and \
not self.entry.parameterdescs.get(param):
self.entry.parameterdescs[param] = orig
if not self.entry.parameterdescs.get(param):
#
# For a named variadic (e.g. ``args...``), emit the
# standard "not described" warning before auto-filling
# so a missing or mistyped ``@<name>:`` doc tag does
# not go undetected. The bare ``...`` form has no
# natural name for the user to document and so always
# gets the auto-generated text.
#
if named_variadic and decl_type == 'function':
self.emit_msg(ln,
f"function parameter '{param}' "
f"not described in "
f"'{declaration_name}'")
self.entry.parameterdescs[param] = "variable arguments"
elif (not param) or param == "void":
@@ -546,6 +573,31 @@ class KernelDoc:
self.emit_msg(ln,
f"Excess {dname} '{section}' description in '{decl_name}'")
#
# Check that documented parameter names (from doc comments, including
# inline ``/** @member: */`` tags) actually match real members in
# the declaration. This catches mismatched or stale kernel-doc
# member tags that don't correspond to any actual struct/union
# member or function parameter.
#
for param_name, desc in self.entry.parameterdescs.items():
# Skip auto-generated entries from push_parameter()
if desc == self.undescribed:
continue
if desc in ("no arguments", "anonymous\n", "variable arguments"):
continue
if param_name.startswith("{unnamed_"):
continue
if param_name in self.entry.parameterlist:
continue
if decl_type == 'function':
dname = f"{decl_type} parameter"
else:
dname = f"{decl_type} member"
self.emit_msg(ln,
f"Excess {dname} '{param_name}' description in '{decl_name}'")
def check_return_section(self, ln, declaration_name, return_type):
"""
If the function doesn't return void, warns about the lack of a

22
tools/lib/python/kdoc/xforms_lists.py
View File

@@ -29,6 +29,7 @@ class CTransforms:
(CMatch("__aligned"), ""),
(CMatch("__counted_by"), ""),
(CMatch("__counted_by_(le|be)"), ""),
(CMatch("__counted_by_ptr"), ""),
(CMatch("__guarded_by"), ""),
(CMatch("__pt_guarded_by"), ""),
(CMatch("__packed"), ""),
@@ -48,16 +49,6 @@ class CTransforms:
(CMatch("DEFINE_DMA_UNMAP_ADDR"), r"dma_addr_t \1"),
(CMatch("DEFINE_DMA_UNMAP_LEN"), r"__u32 \1"),
(CMatch("VIRTIO_DECLARE_FEATURES"), r"union { u64 \1; u64 \1_array[VIRTIO_FEATURES_U64S]; }"),
(CMatch("__cond_acquires"), ""),
(CMatch("__cond_releases"), ""),
(CMatch("__acquires"), ""),
(CMatch("__releases"), ""),
(CMatch("__must_hold"), ""),
(CMatch("__must_not_hold"), ""),
(CMatch("__must_hold_shared"), ""),
(CMatch("__cond_acquires_shared"), ""),
(CMatch("__acquires_shared"), ""),
(CMatch("__releases_shared"), ""),
(CMatch("__attribute__"), ""),
#
@@ -93,10 +84,21 @@ class CTransforms:
(CMatch("__weak"), ""),
(CMatch("__sched"), ""),
(CMatch("__always_unused"), ""),
(CMatch("__maybe_unused"), ""),
(CMatch("__printf"), ""),
(CMatch("__(?:re)?alloc_size"), ""),
(CMatch("__diagnose_as"), ""),
(CMatch("DECL_BUCKET_PARAMS"), r"\1, \2"),
(CMatch("__cond_acquires"), ""),
(CMatch("__cond_releases"), ""),
(CMatch("__acquires"), ""),
(CMatch("__releases"), ""),
(CMatch("__must_hold"), ""),
(CMatch("__must_not_hold"), ""),
(CMatch("__must_hold_shared"), ""),
(CMatch("__cond_acquires_shared"), ""),
(CMatch("__acquires_shared"), ""),
(CMatch("__releases_shared"), ""),
(CMatch("__no_context_analysis"), ""),
(CMatch("__attribute_const__"), ""),
(CMatch("__attribute__"), ""),

1
tools/unittests/test_cmatch.py
View File

@@ -320,6 +320,7 @@ class TestSubWithLocalXforms(TestCaseDiff):
(CMatch('__aligned'), ' '),
(CMatch('__counted_by'), ' '),
(CMatch('__counted_by_(le|be)'), ' '),
(CMatch('__counted_by_ptr'), ' '),
(CMatch('__guarded_by'), ' '),
(CMatch('__pt_guarded_by'), ' '),