Minki/linux
1
0
Fork 1
mirror of https://github.com/torvalds/linux.git synced 2024-09-20 06:53:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

Nothing hugely exciting happening in the documentation tree this time

Browse Source 
around, mostly more of the usual:
 
 - More Spanish, Italian, and Chinese translations
 
 - A new script, scripts/checktransupdate.py, can be used to see which
   commits have touched an (English) document since a given translation was
   last updated.
 
 - A couple of "best practices" suggestions (on Link: tags and off-list
   discussions) that were not entirely at consensus level, but I concluded
   they were close enough to accept.
 
 - Some nice cleanups removing documentation for kernel parameters that have
   not been recognized for ... a long time.
 
 ...along with the usual updates, typo fixes, and such.
 -----BEGIN PGP SIGNATURE-----
 
 iQFDBAABCAAtFiEEIw+MvkEiF49krdp9F0NaE2wMflgFAmaZbLMPHGNvcmJldEBs
 d24ubmV0AAoJEBdDWhNsDH5Y7PkH/jk1LverE9XOXZO5Uq+eEwWlNI2khjQ0hI+M
 b0GZlIfeHsted0I8CsYapbehhqve700QJQ8/dmst9jPEwiQq9omSNp8ux/mpIvk+
 OjeCLoApZ1slYj9HeiDkwuLDw5o0bKOep6fmrlnnc2uJezqBbjSLmUgocqfCnZb1
 fHikvSP0McKjffei76+KH1PYK8BmJwredsHvmfehLJpETHQhe11tO3byPM48iLcy
 mybECacqB8zfy7wkvVTWhd+QFkT7x+BE4g/Z07L8z4m9HRxmJbV6EJF1GPlpDJWZ
 TV0u86cOAlpMeUy44pfUnej6E9ntafeaHmX7CJpcgskh3h4J/qc=
 =uk19
 -----END PGP SIGNATURE-----

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

Pull documentation updates from Jonathan Corbet:
 "Nothing hugely exciting happening in the documentation tree this time
  around, mostly more of the usual:

   - More Spanish, Italian, and Chinese translations

   - A new script, scripts/checktransupdate.py, can be used to see which
     commits have touched an (English) document since a given
     translation was last updated.

   - A couple of "best practices" suggestions (on Link: tags and
     off-list discussions) that were not entirely at consensus level,
     but I concluded they were close enough to accept.

   - Some nice cleanups removing documentation for kernel parameters
     that have not been recognized for ... a long time.

  ...along with the usual updates, typo fixes, and such"

* tag 'docs-6.11' of git://git.lwn.net/linux: (57 commits)
  Documentation: Document user_events ioctl code
  docs/pinctrl: fix typo in mapping example
  docs: maintainer: discourage taking conversations off-list
  docs: driver-model: platform: update the definition of platform_driver
  docs/sp_SP: Add translation for scheduler/sched-design-CFS.rst
  writing_musb_glue_layer.rst: Fix broken URL
  zh_CN/admin-guide: one typo fix
  docs/zh_CN/virt: Update the translation of guest-halt-polling.rst
  Documentation: add reference from dynamic debug to loglevel kernel params
  Documentation: best practices for using Link trailers
  Documentation: fix links to mailing list services
  Documentation: exception-tables.rst: Fix the wrong steps referenced
  docs/zh_CN: add process/researcher-guidelines Chinese translation
  Documentation/tools/rv: fix document header
  docs/sp_SP: Add translation of process/maintainer-kvm-x86.rst
  docs/admin-guide/mm: correct typo 'quired' to 'queried'
  Add libps2 to the input section of driver-api
  Docs/mm/index: move allocation profiling document to unsorted documents chapter
  Docs/mm/index: rename 'Legacy Documentation' to 'Unsorted Documentation'
  Docs/mm/index: Remove 'Memory Management Guide' chapter marker
  ...
This commit is contained in:
Linus Torvalds 2024-07-18 15:54:16 -07:00
commit cf05e93af4
77 changed files with 1982 additions and 425 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.clang-format
View File

@ -4,7 +4,7 @@
#
# For more information, see:
#
# Documentation/process/clang-format.rst
# Documentation/dev-tools/clang-format.rst
# https://clang.llvm.org/docs/ClangFormat.html
# https://clang.llvm.org/docs/ClangFormatStyleOptions.html
#

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

@ -26,6 +26,11 @@ Dynamic debug provides:
- format string
- class name (as known/declared by each module)
NOTE: To actually get the debug-print output on the console, you may
need to adjust the kernel ``loglevel=``, or use ``ignore_loglevel``.
Read about these kernel parameters in
Documentation/admin-guide/kernel-parameters.rst.
Viewing Dynamic Debug Behaviour
===============================

1
Documentation/admin-guide/kernel-parameters.rst
View File

@ -118,7 +118,6 @@ is applicable::
HIBERNATION HIBERNATION is enabled.
HW Appropriate hardware is enabled.
HYPER_V HYPERV support is enabled.
IA-64 IA-64 architecture is enabled.
IMA Integrity measurement architecture is enabled.
IP_PNP IP DHCP, BOOTP, or RARP is enabled.
IPV6 IPv6 support is enabled.

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

@ -1742,8 +1742,6 @@
for 64-bit NUMA, off otherwise.
Format: 0 | 1 (for off | on)
hcl= [IA-64] SGI's Hardware Graph compatibility layer
hd= [EIDE] (E)IDE hard drive subsystem geometry
Format: <cyl>,<head>,<sect>
@ -2502,7 +2500,7 @@
keepinitrd [HW,ARM] See retain_initrd.
kernelcore= [KNL,X86,IA-64,PPC,EARLY]
kernelcore= [KNL,X86,PPC,EARLY]
Format: nn[KMGTPE] | nn% | "mirror"
This parameter specifies the amount of memory usable by
the kernel for non-movable allocations. The requested
@ -3142,26 +3140,16 @@
unlikely, in the extreme case this might damage your
hardware.
ltpc= [NET]
Format: <io>,<irq>,<dma>
lsm.debug [SECURITY] Enable LSM initialization debugging output.
lsm=lsm1,...,lsmN
[SECURITY] Choose order of LSM initialization. This
overrides CONFIG_LSM, and the "security=" parameter.
machvec= [IA-64] Force the use of a particular machine-vector
(machvec) in a generic kernel.
Example: machvec=hpzx1
machtype= [Loongson] Share the same kernel image file between
different yeeloong laptops.
Example: machtype=lemote-yeeloong-2f-7inch
max_addr=nn[KMG] [KNL,BOOT,IA-64] All physical memory greater
than or equal to this physical address is ignored.
maxcpus= [SMP,EARLY] Maximum number of processors that an SMP kernel
will bring up during bootup. maxcpus=n : n >= 0 limits
the kernel to bring up 'n' processors. Surely after
@ -3399,9 +3387,6 @@
Enable or disable the microcode minimal revision
enforcement for the runtime microcode loader.
min_addr=nn[KMG] [KNL,BOOT,IA-64] All physical memory below this
physical address is ignored.
mini2440= [ARM,HW,KNL]
Format:[0..2][b][c][t]
Default: "0tb"
@ -3566,7 +3551,7 @@
mousedev.yres= [MOUSE] Vertical screen resolution, used for devices
reporting absolute coordinates, such as tablets
movablecore= [KNL,X86,IA-64,PPC,EARLY]
movablecore= [KNL,X86,PPC,EARLY]
Format: nn[KMGTPE] | nn%
This parameter is the complement to kernelcore=, it
specifies the amount of memory used for migratable
@ -3592,11 +3577,6 @@
mtdparts= [MTD]
See drivers/mtd/parsers/cmdlinepart.c
mtdset= [ARM]
ARM/S3C2412 JIVE boot control
See arch/arm/mach-s3c/mach-jive.c
mtouchusb.raw_coordinates=
[HW] Make the MicroTouch USB driver use raw coordinates
('y', default) or cooked coordinates ('n')
@ -3845,8 +3825,6 @@
no_entry_flush [PPC,EARLY] Don't flush the L1-D cache when entering the kernel.
noexec [IA-64]
noexec32 [X86-64]
This affects only 32-bit executables.
noexec32=on: enable non-executable mappings (default)
@ -3866,13 +3844,6 @@
register save and restore. The kernel will only save
legacy floating-point registers on task switch.
nohalt [IA-64] Tells the kernel not to use the power saving
function PAL_HALT_LIGHT when idle. This increases
power-consumption. On the positive side, it reduces
interrupt wake-up latency, which may improve performance
in certain environments such as networked servers or
real-time systems.
no_hash_pointers
[KNL,EARLY]
Force pointers printed to the console or buffers to be
@ -3890,7 +3861,7 @@
nohibernate [HIBERNATION] Disable hibernation and resume.
nohlt [ARM,ARM64,MICROBLAZE,MIPS,PPC,SH] Forces the kernel to
nohlt [ARM,ARM64,MICROBLAZE,MIPS,PPC,RISCV,SH] Forces the kernel to
busy wait in do_idle() and not use the arch_cpu_idle()
implementation; requires CONFIG_GENERIC_IDLE_POLL_SETUP
to be effective. This is useful on platforms where the
@ -3927,8 +3898,6 @@
remapping.
[Deprecated - use intremap=off]
nointroute [IA-64]
noinvpcid [X86,EARLY] Disable the INVPCID cpu feature.
noiotrap [SH] Disables trapped I/O port accesses.
@ -3938,8 +3907,6 @@
noisapnp [ISAPNP] Disables ISA PnP code.
nojitter [IA-64] Disables jitter checking for ITC timers.
nokaslr [KNL,EARLY]
When CONFIG_RANDOMIZE_BASE is set, this disables
kernel and module base offset ASLR (Address Space
@ -3954,8 +3921,6 @@
nolapic_timer [X86-32,APIC,EARLY] Do not use the local APIC timer.
nomca [IA-64] Disable machine check abort handling
nomce [X86-32] Disable Machine Check Exception
nomfgpt [X86-32] Disable Multi-Function General Purpose
@ -4007,8 +3972,6 @@
noresume [SWSUSP] Disables resume and restores original swap
space.
nosbagart [IA-64]
no-scroll [VGA] Disables scrollback.
This is required for the Braillex ib80-piezo Braille
reader made by F.H. Papenmeier (Germany).
@ -4109,19 +4072,6 @@
parameter, xsave area per process might occupy more
memory on xsaves enabled systems.
nps_mtm_hs_ctr= [KNL,ARC]
This parameter sets the maximum duration, in
cycles, each HW thread of the CTOP can run
without interruptions, before HW switches it.
The actual maximum duration is 16 times this
parameter's value.
Format: integer between 1 and 255
Default: 255
nptcg= [IA-64] Override max number of concurrent global TLB
purges which is reported from either PAL_VM_SUMMARY or
SAL PALO.
nr_cpus= [SMP,EARLY] Maximum number of processors that an SMP kernel
could support. nr_cpus=n : n >= 1 limits the kernel to
support 'n' processors. It could be larger than the
@ -5774,9 +5724,6 @@
2 The "airplane mode" button toggles between everything
blocked and everything unblocked.
rhash_entries= [KNL,NET]
Set number of hash buckets for route cache
ring3mwait=disable
[KNL] Disable ring 3 MONITOR/MWAIT feature on supported
CPUs.
@ -6010,9 +5957,6 @@
apic=verbose is specified.
Example: apic=debug show_lapic=all
simeth= [IA-64]
simscsi=
slab_debug[=options[,slabs][;[options[,slabs]]...] [MM]
Enabling slab_debug allows one to determine the
culprit if slab objects become corrupted. Enabling
@ -6280,11 +6224,6 @@
Not specifying this option is equivalent to
spec_store_bypass_disable=auto.
spia_io_base= [HW,MTD]
spia_fio_base=
spia_pedr=
spia_peddr=
split_lock_detect=
[X86] Enable split lock detection or bus lock detection
@ -6540,7 +6479,7 @@
This parameter controls use of the Protected
Execution Facility on pSeries.
swiotlb= [ARM,IA-64,PPC,MIPS,X86,EARLY]
swiotlb= [ARM,PPC,MIPS,X86,S390,EARLY]
Format: { <int> [,<int>] | force | noforce }
<int> -- Number of I/O TLB slabs
<int> -- Second integer after comma. Number of swiotlb
@ -6621,12 +6560,6 @@
e.g. base its process migration decisions on it.
Default is on.
topology_updates= [KNL, PPC, NUMA]
Format: {off}
Specify if the kernel should ignore (off)
topology updates sent by the hypervisor to this
LPAR.
torture.disable_onoff_at_boot= [KNL]
Prevent the CPU-hotplug component of torturing
until after init has spawned.
@ -6646,8 +6579,6 @@
torture.verbose_sleep_duration= [KNL]
Duration of each verbose-printk() sleep in jiffies.
tp720= [HW,PS2]
tpm_suspend_pcr=[HW,TPM]
Format: integer pcr id
Specify that at suspend time, the tpm driver
@ -7184,9 +7115,6 @@
Try vdso32=0 if you encounter an error that says:
dl_main: Assertion `(void *) ph->p_vaddr == _rtld_local._dl_sysinfo_dso' failed!
vector= [IA-64,SMP]
vector=percpu: enable percpu vector domain
video= [FB,EARLY] Frame buffer configuration
See Documentation/fb/modedb.rst.

2
Documentation/admin-guide/mm/index.rst
View File

@ -10,7 +10,7 @@ processes address space and many other cool things.
Linux memory management is a complex system with many configurable
settings. Most of these settings are available via ``/proc``
filesystem and can be quired and adjusted using ``sysctl``. These APIs
filesystem and can be queried and adjusted using ``sysctl``. These APIs
are described in Documentation/admin-guide/sysctl/vm.rst and in `man 5 proc`_.
.. _man 5 proc: http://man7.org/linux/man-pages/man5/proc.5.html

2
Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
View File

@ -23,7 +23,7 @@ mistakes occasionally made even by experienced developers.
up in the reference section, then jump back to where you left off.
..
Find the latest rendered version of this text here:
https://docs.kernel.org/admin-guide/verify-bugs-and-bisect-regressions.rst.html
https://docs.kernel.org/admin-guide/verify-bugs-and-bisect-regressions.html
The essence of the process (aka 'TL;DR')
========================================

2
Documentation/arch/x86/cpuinfo.rst
View File

@ -112,7 +112,7 @@ conditions are met, the features are enabled by the set_cpu_cap or
setup_force_cpu_cap macros. For example, if bit 5 is set in MSR_IA32_CORE_CAPS,
the feature X86_FEATURE_SPLIT_LOCK_DETECT will be enabled and
"split_lock_detect" will be displayed. The flag "ring3mwait" will be
displayed only when running on INTEL_FAM6_XEON_PHI_[KNL|KNM] processors.
displayed only when running on INTEL_XEON_PHI_[KNL|KNM] processors.
d: Flags can represent purely software features.
------------------------------------------------

2
Documentation/arch/x86/exception-tables.rst
View File

@ -297,7 +297,7 @@ vma occurs?
c) execution continues at local label 2 (address of the
instruction immediately after the faulting user access).
The steps 8a to 8c in a certain way emulate the faulting instruction.
The steps a to c above in a certain way emulate the faulting instruction.
That's it, mostly. If you look at our example, you might ask why
we set EAX to -EFAULT in the exception handler code. Well, the

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

@ -210,7 +210,7 @@ implemented (simplified excerpt)::
}
}
noop(struct irq_data *data))
noop(struct irq_data *data)
{
}

30
Documentation/crypto/async-tx-api.rst
View File

@ -150,38 +150,38 @@ of an operation.
Perform a xor->copy->xor operation where each operation depends on the
result from the previous operation::
void callback(void *param)
{
struct completion *cmp = param;
#include <linux/async_tx.h>
complete(cmp);
static void callback(void *param)
{
complete(param);
}
void run_xor_copy_xor(struct page **xor_srcs,
int xor_src_cnt,
struct page *xor_dest,
size_t xor_len,
struct page *copy_src,
struct page *copy_dest,
size_t copy_len)
#define NDISKS 2
static void run_xor_copy_xor(struct page **xor_srcs,
struct page *xor_dest,
size_t xor_len,
struct page *copy_src,
struct page *copy_dest,
size_t copy_len)
{
struct dma_async_tx_descriptor *tx;
addr_conv_t addr_conv[xor_src_cnt];
struct async_submit_ctl submit;
addr_conv_t addr_conv[NDISKS];
struct completion cmp;
init_async_submit(&submit, ASYNC_TX_XOR_DROP_DST, NULL, NULL, NULL,
addr_conv);
tx = async_xor(xor_dest, xor_srcs, 0, xor_src_cnt, xor_len, &submit)
tx = async_xor(xor_dest, xor_srcs, 0, NDISKS, xor_len, &submit);
submit->depend_tx = tx;
submit.depend_tx = tx;
tx = async_memcpy(copy_dest, copy_src, 0, 0, copy_len, &submit);
init_completion(&cmp);
init_async_submit(&submit, ASYNC_TX_XOR_DROP_DST | ASYNC_TX_ACK, tx,
callback, &cmp, addr_conv);
tx = async_xor(xor_dest, xor_srcs, 0, xor_src_cnt, xor_len, &submit);
tx = async_xor(xor_dest, xor_srcs, 0, NDISKS, xor_len, &submit);
async_tx_issue_pending_all();

0
Documentation/process/clang-format.rst → Documentation/dev-tools/clang-format.rst
View File

1
Documentation/dev-tools/index.rst
View File

@ -16,6 +16,7 @@ Documentation/dev-tools/testing-overview.rst
testing-overview
checkpatch
clang-format
coccinelle
sparse
kcov

4
Documentation/doc-guide/kernel-doc.rst
View File

@ -143,7 +143,7 @@ Return values
~~~~~~~~~~~~~
The return value, if any, should be described in a dedicated section
named ``Return``.
named ``Return`` (or ``Returns``).
.. note::
@ -337,7 +337,7 @@ Typedefs with function prototypes can also be documented::
* Description of the type.
*
* Context: Locking context.
* Return: Meaning of the return value.
* Returns: Meaning of the return value.
*/
typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);

7
Documentation/driver-api/driver-model/platform.rst
View File

@ -41,13 +41,14 @@ and shutdown notifications using the standard conventions::
struct platform_driver {
int (*probe)(struct platform_device *);
int (*remove)(struct platform_device *);
void (*remove)(struct platform_device *);
void (*shutdown)(struct platform_device *);
int (*suspend)(struct platform_device *, pm_message_t state);
int (*suspend_late)(struct platform_device *, pm_message_t state);
int (*resume_early)(struct platform_device *);
int (*resume)(struct platform_device *);
struct device_driver driver;
const struct platform_device_id *id_table;
bool prevent_deferred_probe;
bool driver_managed_dma;
};
Note that probe() should in general verify that the specified device hardware

7
Documentation/driver-api/input.rst
View File

@ -40,3 +40,10 @@ Sparse keymap support
.. kernel-doc:: drivers/input/sparse-keymap.c
:export:
PS/2 protocol support
---------------------
.. kernel-doc:: include/linux/libps2.h
:internal:
.. kernel-doc:: drivers/input/serio/libps2.c
:export:

2
Documentation/driver-api/pin-control.rst
View File

@ -1002,7 +1002,7 @@ it even more compact which assumes you want to use pinctrl-foo and position
.. code-block:: c
static struct pinctrl_map mapping[] __initdata = {
PIN_MAP_MUX_GROUP("foo-i2c.o", PINCTRL_STATE_DEFAULT,
PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,
"pinctrl-foo", NULL, "i2c0"),
};

2
Documentation/driver-api/usb/writing_musb_glue_layer.rst
View File

@ -717,4 +717,4 @@ https://www.maximintegrated.com/app-notes/index.mvp/id/1822
:ref:`Writing USB Device Drivers <writing-usb-driver>`
Texas Instruments USB Configuration Wiki Page:
http://processors.wiki.ti.com/index.php/Usbgeneralpage
https://web.archive.org/web/20201215135015/http://processors.wiki.ti.com/index.php/Usbgeneralpage

11
Documentation/maintainer/feature-and-driver-maintainers.rst
View File

@ -83,6 +83,17 @@ bugs as well, if the report is of reasonable quality or indicates a
problem that might be severe -- especially if they have *Supported*
status of the codebase in the MAINTAINERS file.
Open development
----------------
Discussions about user reported issues, and development of new code
should be conducted in a manner typical for the larger subsystem.
It is common for development within a single company to be conducted
behind closed doors. However, development and discussions initiated
by community members must not be redirected from public to closed forums
or to private email conversations. Reasonable exceptions to this guidance
include discussions about security related issues.
Selecting the maintainer
========================

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

@ -109,3 +109,4 @@ to do something different in the near future.
../driver-api/vfio-pci-device-specific-driver-acceptance
../nvme/feature-and-quirk-policy
../filesystems/xfs/xfs-maintainer-entry-profile
../mm/damon/maintainer-profile

1
Documentation/mm/allocation-profiling.rst
View File

@ -46,7 +46,6 @@ Example output::
55M 4887 mm/slub.c:2259 func:alloc_slab_page
122M 31168 mm/page_ext.c:270 func:alloc_page_ext
===================
Theory of operation
===================

19
Documentation/mm/index.rst
View File

@ -2,9 +2,6 @@
Memory Management Documentation
===============================
Memory Management Guide
=======================
This is a guide to understanding the memory management subsystem
of Linux. If you are looking for advice on simply allocating memory,
see the :ref:`memory_allocation`. For controlling and tuning guides,
@ -26,21 +23,21 @@ see the :doc:`admin guide <../admin-guide/mm/index>`.
page_cache
shmfs
oom
allocation-profiling
Legacy Documentation
====================
Unsorted Documentation
======================
This is a collection of older documents about the Linux memory management
(MM) subsystem internals with different level of details ranging from
notes and mailing list responses for elaborating descriptions of data
structures and algorithms. It should all be integrated nicely into the
above structured documentation, or deleted if it has served its purpose.
This is a collection of unsorted documents about the Linux memory management
(MM) subsystem internals with different level of details ranging from notes and
mailing list responses for elaborating descriptions of data structures and
algorithms. It should all be integrated nicely into the above structured
documentation, or deleted if it has served its purpose.
.. toctree::
:maxdepth: 1
active_mm
allocation-profiling
arch_pgtable_helpers
balance
damon/index

10
Documentation/mm/vmalloced-kernel-stacks.rst
View File

@ -22,7 +22,7 @@ Kernel stack overflows are often hard to debug and make the kernel
susceptible to exploits. Problems could show up at a later time making
it difficult to isolate and root-cause.
Virtually-mapped kernel stacks with guard pages causes kernel stack
Virtually mapped kernel stacks with guard pages cause kernel stack
overflows to be caught immediately rather than causing difficult to
diagnose corruptions.
@ -57,7 +57,7 @@ enable this bool configuration option. The requirements are:
VMAP_STACK
----------
VMAP_STACK bool configuration option when enabled allocates virtually
When enabled, the VMAP_STACK bool configuration option allocates virtually
mapped task stacks. This option depends on HAVE_ARCH_VMAP_STACK.
- Enable this if you want the use virtually-mapped kernel stacks
@ -83,7 +83,7 @@ the latest code base:
Allocation
-----------
When a new kernel thread is created, thread stack is allocated from
When a new kernel thread is created, a thread stack is allocated from
virtually contiguous memory pages from the page level allocator. These
pages are mapped into contiguous kernel virtual space with PAGE_KERNEL
protections.
@ -103,8 +103,8 @@ with PAGE_KERNEL protections.
- This does not address interrupt stacks - according to the original patch
Thread stack allocation is initiated from clone(), fork(), vfork(),
kernel_thread() via kernel_clone(). Leaving a few hints for searching
the code base to understand when and how thread stack is allocated.
kernel_thread() via kernel_clone(). These are a few hints for searching
the code base to understand when and how a thread stack is allocated.
Bulk of the code is in:
`kernel/fork.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/kernel/fork.c>`.

8
Documentation/process/2.Process.rst
View File

@ -392,13 +392,13 @@ represent a potential hazard to developers, who risk getting buried under a
load of electronic mail, running afoul of the conventions used on the Linux
lists, or both.
Most kernel mailing lists are run on vger.kernel.org; the master list can
Most kernel mailing lists are hosted at kernel.org; the master list can
be found at:
http://vger.kernel.org/vger-lists.html
https://subspace.kernel.org
There are lists hosted elsewhere, though; a number of them are at
redhat.com/mailman/listinfo.
There are lists hosted elsewhere; please check the MAINTAINERS file for
the list relevant for any particular subsystem.
The core mailing list for kernel development is, of course, linux-kernel.
This list is an intimidating place to be; volume can reach 500 messages per

2
Documentation/process/4.Coding.rst
View File

@ -63,7 +63,7 @@ these rules, to quickly re-format parts of your code automatically,
and to review full files in order to spot coding style mistakes,
typos and possible improvements. It is also handy for sorting ``#includes``,
for aligning variables/macros, for reflowing text and other similar tasks.
See the file :ref:`Documentation/process/clang-format.rst <clangformat>`
See the file :ref:`Documentation/dev-tools/clang-format.rst <clangformat>`
for more details.
Some basic editor settings, such as indentation and line endings, will be

1
Documentation/process/changes.rst
View File

@ -63,6 +63,7 @@ cpio any cpio --version
GNU tar 1.28 tar --version
gtags (optional) 6.6.5 gtags --version
mkimage (optional) 2017.01 mkimage --version
Python (optional) 3.5.x python3 --version
====================== =============== ========================================
.. [#f1] Sphinx is needed only to build the Kernel documentation

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

@ -732,7 +732,7 @@ these rules, to quickly re-format parts of your code automatically,
and to review full files in order to spot coding style mistakes,
typos and possible improvements. It is also handy for sorting ``#includes``,
for aligning variables/macros, for reflowing text and other similar tasks.
See the file :ref:`Documentation/process/clang-format.rst <clangformat>`
See the file :ref:`Documentation/dev-tools/clang-format.rst <clangformat>`
for more details.
Some basic editor settings, such as indentation and line endings, will be

25
Documentation/process/email-clients.rst
View File

@ -351,22 +351,11 @@ although tab2space problem can be solved with external editor.
Another problem is that Gmail will base64-encode any message that has a
non-ASCII character. That includes things like European names.
Proton Mail
***********
HacKerMaiL (TUI)
****************
Proton Mail has a "feature" where it looks up keys using Web Key Directory
(WKD) and encrypts mail to any recipients for which it finds a key.
Kernel.org publishes the WKD for all developers who have kernel.org accounts.
As a result, emails sent using Proton Mail to kernel.org addresses will be
encrypted.
Unfortunately, Proton Mail does not provide a mechanism to disable the
automatic encryption, viewing it as a privacy feature.
The automatic encryption feature is also enabled for mail sent via the Proton
Mail Bridge, so this affects all outgoing messages, including patches sent with
``git send-email``.
Encrypted mail adds unnecessary friction, as other developers may not have mail
clients, or tooling, configured for use with encrypted mail and some mail
clients may encrypt responses to encrypted mail for all recipients, including
the mailing lists.
Unless a way to disable this "feature" is introduced, Proton Mail is unsuited
to kernel development.
HacKerMaiL (hkml) is a public-inbox based simple mails management tool that
doesn't require subscription of mailing lists. It is developed and maintained
by the DAMON maintainer and aims to support simple development workflows for
DAMON and general kernel subsystems. Refer to the README
(https://github.com/sjp38/hackermail/blob/master/README.md) for details.

30
Documentation/process/handling-regressions.rst
View File

@ -40,10 +40,13 @@ The important bits (aka "The TL;DR")
#regzbot from: Some N. Ice Human <some.human@example.com>
#regzbot monitor: http://some.bugtracker.example.com/ticket?id=123456789
#. When submitting fixes for regressions, add "Link:" tags to the patch
#. When submitting fixes for regressions, add "Closes:" tags to the patch
description pointing to all places where the issue was reported, as
mandated by Documentation/process/submitting-patches.rst and
:ref:`Documentation/process/5.Posting.rst <development_posting>`.
:ref:`Documentation/process/5.Posting.rst <development_posting>`. If you are
only fixing part of the issue that caused the regression, you may use
"Link:" tags instead. regzbot currently makes no distinction between the
two.
#. Try to fix regressions quickly once the culprit has been identified; fixes
for most regressions should be merged within two weeks, but some need to be
@ -91,10 +94,10 @@ When doing either, consider making the Linux kernel regression tracking bot
Note the caret (^) before the "introduced": it tells regzbot to treat the
parent mail (the one you reply to) as the initial report for the regression
you want to see tracked; that's important, as regzbot will later look out
for patches with "Link:" tags pointing to the report in the archives on
for patches with "Closes:" tags pointing to the report in the archives on
lore.kernel.org.
* When forwarding a regressions reported to a bug tracker, include a paragraph
* When forwarding a regression reported to a bug tracker, include a paragraph
with these regzbot commands::
#regzbot introduced: 1f2e3d4c5b6a
@ -102,7 +105,7 @@ When doing either, consider making the Linux kernel regression tracking bot
#regzbot monitor: http://some.bugtracker.example.com/ticket?id=123456789
Regzbot will then automatically associate patches with the report that
contain "Link:" tags pointing to your mail or the mentioned ticket.
contain "Closes:" tags pointing to your mail or the mentioned ticket.
What's important when fixing regressions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -112,10 +115,14 @@ remember to do what Documentation/process/submitting-patches.rst,
:ref:`Documentation/process/5.Posting.rst <development_posting>`, and
Documentation/process/stable-kernel-rules.rst already explain in more detail:
* Point to all places where the issue was reported using "Link:" tags::
* Point to all places where the issue was reported using "Closes:" tags::
Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/
Link: https://bugzilla.kernel.org/show_bug.cgi?id=1234567890
Closes: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/
Closes: https://bugzilla.kernel.org/show_bug.cgi?id=1234567890
If you are only fixing part of the issue, you may use "Link:" instead as
described in the first document mentioned above. regzbot currently treats
both of these equivalently and considers the linked reports as resolved.
* Add a "Fixes:" tag to specify the commit causing the regression.
@ -126,7 +133,7 @@ All this is expected from you and important when it comes to regression, as
these tags are of great value for everyone (you included) that might be looking
into the issue weeks, months, or years later. These tags are also crucial for
tools and scripts used by other kernel developers or Linux distributions; one of
these tools is regzbot, which heavily relies on the "Link:" tags to associate
these tools is regzbot, which heavily relies on the "Closes:" tags to associate
reports for regression with changes resolving them.
Expectations and best practices for fixing regressions
@ -326,7 +333,7 @@ How does regression tracking work with regzbot?
The bot watches for replies to reports of tracked regressions. Additionally,
it's looking out for posted or committed patches referencing such reports
with "Link:" tags; replies to such patch postings are tracked as well.
with "Closes:" tags; replies to such patch postings are tracked as well.
Combined this data provides good insights into the current state of the fixing
process.
@ -338,8 +345,7 @@ take care of that using ``#regzbot ^introduced``.
For developers there normally is no extra work involved, they just need to make
sure to do something that was expected long before regzbot came to light: add
"Link:" tags to the patch description pointing to all reports about the issue
fixed.
links to the patch description pointing to all reports about the issue fixed.
Do I have to use regzbot?
~~~~~~~~~~~~~~~~~~~~~~~~~

10
Documentation/process/howto.rst
View File

@ -331,7 +331,7 @@ they need to be integration-tested. For this purpose, a special
testing repository exists into which virtually all subsystem trees are
pulled on an almost daily basis:
https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git
https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git
This way, the linux-next gives a summary outlook onto what will be
expected to go into the mainline kernel at the next merge period.
@ -373,12 +373,12 @@ As some of the above documents describe, the majority of the core kernel
developers participate on the Linux Kernel Mailing list. Details on how
to subscribe and unsubscribe from the list can be found at:
http://vger.kernel.org/vger-lists.html#linux-kernel
https://subspace.kernel.org/subscribing.html
There are archives of the mailing list on the web in many different
places. Use a search engine to find these archives. For example:
https://lore.kernel.org/lkml/
https://lore.kernel.org/linux-kernel/
It is highly recommended that you search the archives about the topic
you want to bring up, before you post it to the list. A lot of things
@ -393,13 +393,13 @@ groups.
Many of the lists are hosted on kernel.org. Information on them can be
found at:
http://vger.kernel.org/vger-lists.html
https://subspace.kernel.org
Please remember to follow good behavioral habits when using the lists.
Though a bit cheesy, the following URL has some simple guidelines for
interacting with the list (or any list):
http://www.albion.com/netiquette/
https://subspace.kernel.org/etiquette.html
If multiple people respond to your mail, the CC: list of recipients may
get pretty large. Don't remove anybody from the CC: list without a good

11
Documentation/process/index.rst
View File

@ -107,17 +107,6 @@ developers:
kernel-docs
deprecated
These are some overall technical guides that have been put here for now for
lack of a better place.
.. toctree::
:maxdepth: 1
magic-number
clang-format
../arch/riscv/patch-acceptance
../core-api/unaligned-memory-access
.. only:: subproject and html
Indices

73
Documentation/process/kernel-docs.rst
View File

@ -3,27 +3,27 @@
Index of Further Kernel Documentation
=====================================
The need for a document like this one became apparent in the
linux-kernel mailing list as the same questions, asking for pointers
to information, appeared again and again.
The need for a document like this one became apparent in the linux-kernel
mailing list as the same questions, asking for pointers to information,
appeared again and again.
Fortunately, as more and more people get to GNU/Linux, more and more
get interested in the Kernel. But reading the sources is not always
enough. It is easy to understand the code, but miss the concepts, the
philosophy and design decisions behind this code.
Fortunately, as more and more people get to GNU/Linux, more and more get
interested in the Kernel. But reading the sources is not always enough. It
is easy to understand the code, but miss the concepts, the philosophy and
design decisions behind this code.
Unfortunately, not many documents are available for beginners to
start. And, even if they exist, there was no "well-known" place which
kept track of them. These lines try to cover this lack.
Unfortunately, not many documents are available for beginners to start.
And, even if they exist, there was no "well-known" place which kept track
of them. These lines try to cover this lack.
PLEASE, if you know any paper not listed here or write a new document,
include a reference to it here, following the kernel's patch submission
process. Any corrections, ideas or comments are also welcome.
All documents are cataloged with the following fields: the document's
"Title", the "Author"/s, the "URL" where they can be found, some
"Keywords" helpful when searching for specific topics, and a brief
"Description" of the Document.
"Title", the "Author"/s, the "URL" where they can be found, some "Keywords"
helpful when searching for specific topics, and a brief "Description" of
the Document.
.. note::
@ -72,9 +72,29 @@ On-line docs
programming. Lots of examples. Currently the new version is being
actively maintained at https://github.com/sysprog21/lkmpg.
* Title: **Rust for Linux**
:Author: various
:URL: https://rust-for-linux.com/
:Date: rolling version
:Keywords: glossary, terms, linux-kernel.
:Description: From the website: "Rust for Linux is the project adding
support for the Rust language to the Linux kernel. This website is
intended as a hub of links, documentation and resources related to
the project".
Published books
---------------
* Title: **Practical Linux System Administration: A Guide to Installation, Configuration, and Management, 1st Edition**
:Author: Kenneth Hess
:Publisher: O'Reilly Media
:Date: May, 2023
:Pages: 246
:ISBN: 978-1098109035
:Notes: System administration
* Title: **Linux Kernel Debugging: Leverage proven tools and advanced techniques to effectively debug Linux kernels and kernel modules**
:Author: Kaiwan N Billimoria
@ -88,9 +108,9 @@ Published books
:Author: Kaiwan N Billimoria
:Publisher: Packt Publishing Ltd
:Date: March, 2021
:Date: March, 2021 (Second Edition published in 2024)
:Pages: 754
:ISBN: 978-1789953435
:ISBN: 978-1789953435 (Second Edition ISBN is 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**
@ -118,15 +138,6 @@ Published books
:ISBN: 978-0672329463
:Notes: Foundational book
* Title: **Practical Linux System Administration: A Guide to Installation, Configuration, and Management, 1st Edition**
:Author: Kenneth Hess
:Publisher: O'Reilly Media
:Date: May, 2023
:Pages: 246
:ISBN: 978-1098109035
:Notes: System administration
.. _ldd3_published:
* Title: **Linux Device Drivers, 3rd Edition**
@ -194,13 +205,21 @@ Miscellaneous
* Name: **linux-kernel mailing list archives and search engines**
:URL: http://vger.kernel.org/vger-lists.html
:URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html
:URL: http://groups.google.com/group/mlist.linux.kernel
:URL: https://subspace.kernel.org
:URL: https://lore.kernel.org
:Keywords: linux-kernel, archives, search.
:Description: Some of the linux-kernel mailing list archivers. If
you have a better/another one, please let me know.
* Name: **The Linux Foundation YouTube channel**
:URL: https://www.youtube.com/user/thelinuxfoundation
:Keywords: linux, videos, linux-foundation, youtube.
:Description: The Linux Foundation uploads video recordings of their
collaborative events, Linux conferences including LinuxCon, and
other original research and content related to Linux and software
development.
-------
This document was originally based on:

5
Documentation/process/maintainer-netdev.rst
View File

@ -25,9 +25,8 @@ drivers/net (i.e. hardware specific drivers) in the Linux source tree.
Note that some subsystems (e.g. wireless drivers) which have a high
volume of traffic have their own specific mailing lists and trees.
The netdev list is managed (like many other Linux mailing lists) through
VGER (http://vger.kernel.org/) with archives available at
https://lore.kernel.org/netdev/
Like many other Linux mailing lists, the netdev list is hosted at
kernel.org with archives available at https://lore.kernel.org/netdev/.
Aside from subsystems like those mentioned above, all network-related
Linux development (i.e. RFC, review, comments, etc.) takes place on

30
Documentation/process/maintainer-tip.rst
View File

@ -372,17 +372,31 @@ following tag ordering scheme:
- Link: ``https://link/to/information``
For referring to an email on LKML or other kernel mailing lists,
please use the lore.kernel.org redirector URL::
For referring to an email posted to the kernel mailing lists, please
use the lore.kernel.org redirector URL::
https://lore.kernel.org/r/email-message@id
Link: https://lore.kernel.org/email-message-id@here
The kernel.org redirector is considered a stable URL, unlike other email
archives.
This URL should be used when referring to relevant mailing list
topics, related patch sets, or other notable discussion threads.
A convenient way to associate ``Link:`` trailers with the commit
message is to use markdown-like bracketed notation, for example::
Maintainers will add a Link tag referencing the email of the patch
submission when they apply a patch to the tip tree. This tag is useful
for later reference and is also used for commit notifications.
A similar approach was attempted before as part of a different
effort [1], but the initial implementation caused too many
regressions [2], so it was backed out and reimplemented.
Link: https://lore.kernel.org/some-msgid@here # [1]
Link: https://bugzilla.example.org/bug/12345 # [2]
You can also use ``Link:`` trailers to indicate the origin of the
patch when applying it to your git tree. In that case, please use the
dedicated ``patch.msgid.link`` domain instead of ``lore.kernel.org``.
This practice makes it possible for automated tooling to identify
which link to use to retrieve the original patch submission. For
example::
Link: https://patch.msgid.link/patch-source-message-id@here
Please do not use combined tags, e.g. ``Reported-and-tested-by``, as
they just complicate automated extraction of tags.

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

@ -119,10 +119,10 @@ web, point to it.
When linking to mailing list archives, preferably use the lore.kernel.org
message archiver service. To create the link URL, use the contents of the
``Message-Id`` header of the message without the surrounding angle brackets.
``Message-ID`` header of the message without the surrounding angle brackets.
For example::
Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/
Link: https://lore.kernel.org/30th.anniversary.repost@klaava.Helsinki.FI
Please check the link to make sure that it is actually working and points
to the relevant message.
@ -243,11 +243,9 @@ linux-kernel@vger.kernel.org should be used by default for all patches, but the
volume on that list has caused a number of developers to tune it out. Please
do not spam unrelated lists and unrelated people, though.
Many kernel-related lists are hosted on vger.kernel.org; you can find a
list of them at http://vger.kernel.org/vger-lists.html. There are
kernel-related lists hosted elsewhere as well, though.
Do not send more than 15 patches at once to the vger mailing lists!!!
Many kernel-related lists are hosted at kernel.org; you can find a list
of them at https://subspace.kernel.org. There are kernel-related lists
hosted elsewhere as well, though.
Linus Torvalds is the final arbiter of all changes accepted into the
Linux kernel. His e-mail address is <torvalds@linux-foundation.org>.
@ -866,9 +864,6 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
<http://www.kroah.com/log/linux/maintainer-06.html>
NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
<https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net>
Kernel Documentation/process/coding-style.rst
Linus Torvalds's mail on the canonical patch format:

2
Documentation/scheduler/sched-design-CFS.rst
View File

@ -1,3 +1,5 @@
.. _sched_design_CFS:
=============
CFS Scheduler
=============

1
Documentation/staging/index.rst
View File

@ -8,6 +8,7 @@ Unsorted Documentation
crc32
lzo
magic-number
remoteproc
rpmsg
speculation

0
Documentation/process/magic-number.rst → Documentation/staging/magic-number.rst
View File

6
Documentation/tools/rv/rv-mon.rst
View File

@ -1,8 +1,8 @@
.. SPDX-License-Identifier: GPL-2.0
=======
rv-list
=======
======
rv-mon
======
-----------------------
List available monitors
-----------------------

24
Documentation/translations/it_IT/riscv/patch-acceptance.rst → Documentation/translations/it_IT/arch/riscv/patch-acceptance.rst
View File

@ -1,6 +1,6 @@
.. include:: ../disclaimer-ita.rst
.. include:: ../../disclaimer-ita.rst
:Original: :doc:`../../../arch/riscv/patch-acceptance`
:Original: :doc:`../../../../arch/riscv/patch-acceptance`
:Translator: Federico Vaga <federico.vaga@vaga.pv.it>
arch/riscv linee guida alla manutenzione per gli sviluppatori
@ -22,6 +22,26 @@ sperimentale. Desideriamo estendere questi stessi principi al codice
relativo all'architettura RISC-V che verrà accettato per l'inclusione
nel kernel.
Patchwork
---------
RISC-V ha un'istanza di patchwork dov'è possibile controllare lo stato delle patch:
https://patchwork.kernel.org/project/linux-riscv/list/
Se la vostra patch non appare nella vista predefinita, i manutentori di RISC-V
hanno probabilmente richiesto delle modifiche o si aspettano che venga applicata
a un altro albero.
Il processo automatico viene eseguito su questa istanza di patchwork, costruendo
e collaudando le patch man mano che arrivano. Il processo applica le patch al
riferimento HEAD corrente dei rami `for-next` e `fixes` dei sorgenti RISC-V,
questo a seconda che la patch sia stata o meno individuata come correzione. In
caso contrario, utilizzerà il ramo `master` di RISC-V. L'esatto commit a cui è
stata applicata una serie di patch sarà annotato su patchwork. È improbabile che
vengano applicate Le patch che non passano i controlli, nella maggior parte dei
casi dovranno essere ripresentate.
In aggiunta alla lista delle verifiche da fare prima di inviare una patch
-------------------------------------------------------------------------

44
Documentation/translations/it_IT/doc-guide/kernel-doc.rst
View File

@ -370,6 +370,50 @@ Anche i tipi di dato per prototipi di funzione possono essere documentati::
*/
typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
Documentazione di macro simili a oggetti
----------------------------------------
Le macro simili a oggetti si distinguono dalle macro simili a funzione. Esse si
distinguono in base al fatto che il nome della macro simile a funzione sia
immediatamente seguito da una parentesi sinistra ('(') mentre in quelle simili a
oggetti no.
Le macro simili a funzioni sono gestite come funzioni da ``scripts/kernel-doc``.
Possono avere un elenco di parametri. Le macro simili a oggetti non hanno un
elenco di parametri.
Il formato generale di un commento kernel-doc per una macro simile a oggetti è::
/**
* define object_name - Brief description.
*
* Description of the object.
*/
Esempio::
/**
* define MAX_ERRNO - maximum errno value that is supported
*
* Kernel pointers have redundant information, so we can use a
* scheme where we can return either an error code or a normal
* pointer with the same return value.
*/
#define MAX_ERRNO 4095
Esempio::
/**
* define DRM_GEM_VRAM_PLANE_HELPER_FUNCS - \
* Initializes struct drm_plane_helper_funcs for VRAM handling
*
* This macro initializes struct drm_plane_helper_funcs to use the
* respective helper functions.
*/
#define DRM_GEM_VRAM_PLANE_HELPER_FUNCS \
.prepare_fb = drm_gem_vram_plane_helper_prepare_fb, \
.cleanup_fb = drm_gem_vram_plane_helper_cleanup_fb
Marcatori e riferimenti
-----------------------

2
Documentation/translations/it_IT/doc-guide/parse-headers.rst
View File

@ -63,7 +63,7 @@ DESCRIZIONE
***********
Converte un file d'intestazione o un file sorgente C (C_FILE) in un testo
ReStructuredText incluso mediante il blocco ..parsed-literal
reStructuredText incluso mediante il blocco ..parsed-literal
con riferimenti alla documentazione che descrive l'API. Opzionalmente,
il programma accetta anche un altro file (EXCEPTIONS_FILE) che
descrive quali elementi debbano essere ignorati o il cui riferimento

27
Documentation/translations/it_IT/process/5.Posting.rst
View File

@ -223,8 +223,9 @@ Un'etichetta ci può dire quale commit ha introdotto il problema che viene corre
Fixes: 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID")
Un'altra etichetta viene usata per fornire collegamenti a pagine web contenenti
maggiori informazioni, per esempio un rapporto circa il baco risolto dalla
patch, oppure un documento con le specifiche implementate dalla patch::
maggiori informazioni, per esempio una discussione avvenuta precedentemente
circa il baco risolto dalla patch, oppure un documento con le specifiche
implementate dalla patch::
Link: https://example.com/somewhere.html optional-other-stuff
@ -233,7 +234,19 @@ alla più recente discussione pubblica. A volte questo è fatto automaticamente
alcuni strumenti come b4 or un *hook* git come quello descritto qui
'Documentation/translations/it_IT/maintainer/configure-git.rst'
Un terzo tipo di etichetta viene usato per indicare chi ha contribuito allo
Se il collegamento indirizza verso un rapporto su un baco risolto dalla patch,
allora usate l'etichetta "Closes:"::
Closes: https://example.com/issues/1234 optional-other-stuff
Alcune piattaforme di tracciamento di bachi hanno la capacità di chiudere
automaticamente il problema se l'etichetta è presente nel messaggio. Alcuni
automatismi che monitorano la liste di discussione possono anche tracciare
queste etichette e intraprendere azioni. Piattaforme private e URL invalidi sono
proibiti.
Un altro tipo di etichetta viene usato per indicare chi ha contribuito allo
sviluppo della patch. Tutte queste etichette seguono il formato::
tag: Full Name <email address> optional-other-stuff
@ -267,7 +280,13 @@ Le etichette in uso più comuni sono:
- Reported-by: menziona l'utente che ha riportato il problema corretto da
questa patch; quest'etichetta viene usata per dare credito alle persone che
hanno verificato il codice e ci hanno fatto sapere quando le cose non
funzionavano correttamente. Se esiste un rapporto disponibile sul web, allora
funzionavano correttamente. Questa etichetta dovrebbe essere seguita da
quella Closes: con un indirizzo al rapporto, a meno che questo non sia
disponibile sul web. L'etichetta Link: può essere usata in alternativa a
Closes: se la patch corregge solo in parte il problema riportato nel
rapporto.
Se esiste un rapporto disponibile sul web, allora
L'etichetta dovrebbe essere seguita da un collegamento al suddetto rapporto.
- Cc: la persona menzionata ha ricevuto una copia della patch ed ha avuto

7
Documentation/translations/it_IT/process/6.Followthrough.rst
View File

@ -60,6 +60,13 @@ resa molto più facile se tenete presente alcuni dettagli:
stanno lavorando per la creazione del miglior kernel possibile; non
stanno cercando di creare un disagio ad aziende concorrenti.
- Preparatevi a richieste apparentemente sciocche di modifiche allo stile di
codifica e a richieste di trasferire parte del vostro codice in parti
condivise del kernel. Uno dei compiti dei manutentori è quello di mantenere
lo aspetto del codice. A volte questo significa che l'ingegnoso stratagemma
nel vostro driver per aggirare un problema deve diventare una caratteristica
generalizzata del kernel pronta per essere riutilizzata.
Quello che si sta cercando di dire è che, quando i revisori vi inviano degli
appunti dovete fare attenzione alle osservazioni tecniche che vi stanno
facendo. Non lasciate che il loro modo di esprimersi o il vostro orgoglio

2
Documentation/translations/it_IT/process/7.AdvancedTopics.rst
View File

@ -200,7 +200,7 @@ all'ABI dello spazio utente, eccetera. Qualunque tipo di revisione è ben
accetta e di valore, se porta ad avere un codice migliore nel kernel.
Non esistono requisiti particolarmente stringenti per l'uso di etichette come
``Reviewd-by``. Tuttavia, perché la revisione sia efficace ci si aspetta un
``Reviewed-by``. Tuttavia, perché la revisione sia efficace ci si aspetta un
qualche tipo di messaggio che dica "ho verificato A, B e C nel codice che è
appena stato inviato e mi sembra tutto in ordine". Inoltre, questo permette ai
manutentori di prendere conoscenza circa una revisione avvenuta per davvero.

4
Documentation/translations/it_IT/process/changes.rst
View File

@ -33,8 +33,8 @@ PC Card, per esempio, probabilmente non dovreste preoccuparvi di pcmciautils.
Programma Versione minima Comando per verificare la versione
====================== ================= ========================================
GNU C 5.1 gcc --version
Clang/LLVM (optional) 11.0.0 clang --version
Rust (opzionale) 1.74.1 rustc --version
Clang/LLVM (optional) 13.0.0 clang --version
Rust (opzionale) 1.76.0 rustc --version
bindgen (opzionale) 0.65.1 bindgen --version
GNU make 3.81 make --version
bash 4.2 bash --version

2
Documentation/translations/it_IT/process/clang-format.rst
View File

@ -1,6 +1,6 @@
.. include:: ../disclaimer-ita.rst
:Original: :ref:`Documentation/process/clang-format.rst <clangformat>`
:Original: :ref:`Documentation/dev-tools/clang-format.rst <clangformat>`
:Translator: Federico Vaga <federico.vaga@vaga.pv.it>
.. _it_clangformat:

2
Documentation/translations/it_IT/process/index.rst
View File

@ -107,7 +107,7 @@ perché non si è trovato un posto migliore.
magic-number
clang-format
../riscv/patch-acceptance
../arch/riscv/patch-acceptance
.. only:: subproject and html

2
Documentation/translations/it_IT/process/magic-number.rst
View File

@ -1,6 +1,6 @@
.. include:: ../disclaimer-ita.rst
:Original: :ref:`Documentation/process/magic-number.rst <magicnumbers>`
:Original: :ref:`Documentation/staging/magic-number.rst <magicnumbers>`
:Translator: Federico Vaga <federico.vaga@vaga.pv.it>
.. _it_magicnumbers:

322
Documentation/translations/it_IT/process/stable-kernel-rules.rst
View File

@ -11,32 +11,31 @@ Tutto quello che volevate sapere sui rilasci -stable di Linux
Regole sul tipo di patch che vengono o non vengono accettate nei sorgenti
"-stable":
- Ovviamente dev'essere corretta e verificata.
- Non dev'essere più grande di 100 righe, incluso il contesto.
- Deve correggere una cosa sola.
- Deve correggere un baco vero che sta disturbando gli utenti (non cose del
tipo "Questo potrebbe essere un problema ...").
- Deve correggere un problema di compilazione (ma non per cose già segnate
con CONFIG_BROKEN), un kernel oops, un blocco, una corruzione di dati,
un vero problema di sicurezza, o problemi del tipo "oh, questo non va bene".
In pratica, qualcosa di critico.
- Problemi importanti riportati dagli utenti di una distribuzione potrebbero
essere considerati se correggono importanti problemi di prestazioni o di
interattività. Dato che questi problemi non sono così ovvi e la loro
correzione ha un'alta probabilità d'introdurre una regressione, dovrebbero
essere sottomessi solo dal manutentore della distribuzione includendo un
link, se esiste, ad un rapporto su bugzilla, e informazioni aggiuntive
sull'impatto che ha sugli utenti.
- Non deve correggere problemi relativi a una "teorica sezione critica",
a meno che non venga fornita anche una spiegazione su come questa si
possa verificare.
- Non deve includere alcuna correzione "banale" (correzioni grammaticali,
pulizia dagli spazi bianchi, eccetera).
- Deve rispettare le regole scritte in
:ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`
- Questa patch o una equivalente deve esistere già nei sorgenti principali di
Linux
- Questa patch o una equivalente deve esistere già nei sorgenti principali di
Linux (upstream)
- Ovviamente dev'essere corretta e verificata.
- Non dev'essere più grande di 100 righe, incluso il contesto.
- Deve rispettare le regole scritte in
:ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`
- Deve correggere un vero baco che causi problemi agli utenti oppure aggiunge
un nuovo identificatore di dispositivo. Maggiori dettagli per il primo caso:
- Corregge un problema come un oops, un blocco, una corruzione di dati, un
vero problema di sicurezza, una stranezza hardware, un problema di
compilazione (ma non per cose già segnate con CONFIG_BROKEN), o problemi
del tipo "oh, questo non va bene".
- Problemi importanti riportati dagli utenti di una distribuzione potrebbero
essere considerati se correggono importanti problemi di prestazioni o di
interattività. Dato che questi problemi non sono così ovvi e la loro
correzione ha un'alta probabilità d'introdurre una regressione,
dovrebbero essere sottomessi solo dal manutentore della distribuzione
includendo un link, se esiste, ad un rapporto su bugzilla, e informazioni
aggiuntive sull'impatto che ha sugli utenti.
- Non si accettano cose del tipo "Questo potrebbe essere un problema ..."
come una teorica sezione critica, senza aver fornito anche una spiegazione
su come il baco possa essere sfruttato.
- Non deve includere alcuna correzione "banale" (correzioni grammaticali,
pulizia dagli spazi bianchi, eccetera).
Procedura per sottomettere patch per i sorgenti -stable
-------------------------------------------------------
@ -46,33 +45,114 @@ Procedura per sottomettere patch per i sorgenti -stable
di revisione -stable, ma dovrebbe seguire le procedure descritte in
:ref:`Documentation/translations/it_IT/process/security-bugs.rst <it_securitybugs>`.
Per tutte le altre sottomissioni, scegliere una delle seguenti procedure
------------------------------------------------------------------------
Ci sono tre opzioni per inviare una modifica per i sorgenti -stable:
1. Aggiungi un'etichetta 'stable' alla descrizione della patch al momento della
sottomissione per l'inclusione nei sorgenti principali.
2. Chiedere alla squadra "stable" di prendere una patch già applicata sui
sorgenti principali
3. Sottomettere una patch alla squadra "stable" equivalente ad una modifica già
fatta sui sorgenti principali.
Le seguenti sezioni descrivono con maggiori dettagli ognuna di queste opzioni
L':ref:`it_option_1` è **fortemente** raccomandata; è il modo più facile e
usato. L':ref:`it_option_2` si usa quando al momento della sottomissione non si
era pensato di riportare la modifica su versioni precedenti.
L':ref:`it_option_3` è un'alternativa ai due metodi precedenti quando la patch
nei sorgenti principali ha bisogno di aggiustamenti per essere applicata su
versioni precedenti (per esempio a causa di cambiamenti dell'API).
Quando si utilizza l'opzione 2 o 3 è possibile chiedere che la modifica sia
inclusa in specifiche versioni stabili. In tal caso, assicurarsi che la correzione
o una equivalente sia applicabile, o già presente in tutti i sorgenti
stabili più recenti ancora supportati. Questo ha lo scopo di prevenire
regressioni che gli utenti potrebbero incontrare in seguito durante
l'aggiornamento, se ad esempio una correzione per 5.19-rc1 venisse
riportata a 5.10.y, ma non a 5.15.y.
.. _it_option_1:
Opzione 1
*********
Per far sì che una patch venga automaticamente inclusa nei sorgenti stabili,
aggiungete l'etichetta
Aggiungete la seguente etichetta nell'area delle firme per far sì che una patch
che state inviando per l'inclusione nei sorgenti principali venga presa
automaticamente anche per quelli stabili::
.. code-block:: none
Cc: stable@vger.kernel.org
Cc: stable@vger.kernel.org
Invece, usate ``Cc: stable@vger.kernel.org`` quando state inviando correzioni
per vulnerabilità non ancora di pubblico dominio: questo riduce il rischio di
esporre accidentalmente al pubblico la correzione quando si usa 'git
send-email', perché i messaggi inviati a quell'indirizzo non vengono inviati da
nessuna parte.
Una volta che la patch è stata inclusa, verrà applicata anche sui sorgenti
stabili senza che l'autore o il manutentore del sottosistema debba fare
qualcosa.
Per lasciare una nota per la squadra "stable", usate commenti in linea in stile
shell (leggere oltre per maggiori dettagli).
* Specificate i prerequisiti per le patch aggiuntive::
Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle
Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle
Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic
Cc: <stable@vger.kernel.org> # 3.3.x
Signed-off-by: Ingo Molnar <mingo@elte.hu>
La sequenza di etichette ha il seguente significato::
git cherry-pick a1f84a3
git cherry-pick 1b9508f
git cherry-pick fd21073
git cherry-pick <this commit>
Notate che per una serie di patch non dovere elencare come necessarie tutte
le patch della serie stessa. Per esempio se avete la seguente serie::
patch1
patch2
dove patch2 dipende da patch1, non dovete elencare patch1 come requisito per
patch2 se avete già menzionato patch1 per l'inclusione in "stable"
* Evidenziate le patch che hanno dei requisiti circa la versione del kernel::
Cc: <stable@vger.kernel.org> # 3.3.x
L'etichetta ha il seguente significato::
git cherry-pick <this commit>
per ogni sorgente "-stable" che inizia con la versione indicata.
Notate che queste etichette non sono necessarie se la squadre "stable" può
dedurre la versione dalle etichette Fixes:
* Ritardare l'inclusione di patch::
Cc: <stable@vger.kernel.org> # after -rc3
* Evidenziare problemi noti::
Cc: <stable@vger.kernel.org> # see patch description, needs adjustments for <= 6.3
Esiste un'ulteriore variante per l'etichetta "stable" che permette di comunicare
allo strumento di *backporting* di ignorare un cambiamento::
Cc: <stable+noautosel@kernel.org> # reason goes here, and must be present
nell'area dedicata alla firme. Una volta che la patch è stata inclusa, verrà
applicata anche sui sorgenti stabili senza che l'autore o il manutentore
del sottosistema debba fare qualcosa.
.. _it_option_2:
Opzione 2
*********
Dopo che la patch è stata inclusa nei sorgenti Linux, inviate una mail a
Se la patch è già stata inclusa nei sorgenti Linux, inviate una mail a
stable@vger.kernel.org includendo: il titolo della patch, l'identificativo
del commit, il perché pensate che debba essere applicata, e in quale versione
del commit, il perché pensate che debba essere applicata, e in quali versioni
del kernel la vorreste vedere.
.. _it_option_3:
@ -80,143 +160,89 @@ del kernel la vorreste vedere.
Opzione 3
*********
Inviata la patch, dopo aver verificato che rispetta le regole descritte in
precedenza, a stable@vger.kernel.org. Dovete annotare nel changelog
l'identificativo del commit nei sorgenti principali, così come la versione
del kernel nel quale vorreste vedere la patch.
L':ref:`it_option_1` è fortemente raccomandata; è il modo più facile e usato.
L':ref:`it_option_2` e l':ref:`it_option_3` sono più utili quando, al momento
dell'inclusione dei sorgenti principali, si ritiene che non debbano essere
incluse anche in quelli stabili (per esempio, perché si crede che si dovrebbero
fare più verifiche per eventuali regressioni). L':ref:`it_option_3` è
particolarmente utile se una patch dev'essere riportata su una versione
precedente (per esempio la patch richiede modifiche a causa di cambiamenti di
API).
Notate che per l':ref:`it_option_3`, se la patch è diversa da quella nei
sorgenti principali (per esempio perché è stato necessario un lavoro di
adattamento) allora dev'essere ben documentata e giustificata nella descrizione
della patch.
L'identificativo del commit nei sorgenti principali dev'essere indicato sopra
al messaggio della patch, così:
.. code-block:: none
Dopo aver verificato che rispetta le regole descritte in precedenza, inviata la
patch a stable@vger.kernel.org facendo anche menzione delle versioni nella quale
si vorrebbe applicarla. Nel farlo, dovete annotare nel changelog
l'identificativo del commit nei sorgenti principali, così come la versione del
kernel nel quale vorreste vedere la patch.::
commit <sha1> upstream.
o in alternativa:
.. code-block:: none
o in alternativa::
[ Upstream commit <sha1> ]
In aggiunta, alcune patch inviate attraverso l':ref:`it_option_1` potrebbero
dipendere da altre che devo essere incluse. Questa situazione può essere
indicata nel seguente modo nell'area dedicata alle firme:
Se la patch inviata devia rispetto all'originale presente nei sorgenti
principali (per esempio per adattarsi ad un cambiamento di API), allora questo
dev'essere giustificato e dettagliato in modo chiaro nella descrizione.
.. code-block:: none
Dopo la sottomissione
---------------------
Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle
Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle
Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic
Cc: <stable@vger.kernel.org> # 3.3.x
Signed-off-by: Ingo Molnar <mingo@elte.hu>
La sequenza di etichette ha il seguente significato:
.. code-block:: none
git cherry-pick a1f84a3
git cherry-pick 1b9508f
git cherry-pick fd21073
git cherry-pick <this commit>
Inoltre, alcune patch potrebbero avere dei requisiti circa la versione del
kernel. Questo può essere indicato usando il seguente formato nell'area
dedicata alle firme:
.. code-block:: none
Cc: <stable@vger.kernel.org> # 3.3.x
L'etichetta ha il seguente significato:
.. code-block:: none
git cherry-pick <this commit>
per ogni sorgente "-stable" che inizia con la versione indicata.
Dopo la sottomissione:
- Il mittente riceverà un ACK quando la patch è stata accettata e messa in
coda, oppure un NAK se la patch è stata rigettata. A seconda degli impegni
degli sviluppatori, questa risposta potrebbe richiedere alcuni giorni.
- Se accettata, la patch verrà aggiunta alla coda -stable per essere
revisionata dal altri sviluppatori e dal principale manutentore del
sottosistema.
Il mittente riceverà un ACK quando la patch è stata accettata e messa in coda,
oppure un NAK se la patch è stata rigettata. La risposta potrebbe richiedere
alcuni giorni in funzione dei piani dei membri della squadra "stable",
Se accettata, la patch verrà aggiunta alla coda -stable per essere revisionata
dal altri sviluppatori e dal principale manutentore del sottosistema.
Ciclo di una revisione
----------------------
- Quando i manutentori -stable decidono di fare un ciclo di revisione, le
patch vengono mandate al comitato per la revisione, ai manutentori soggetti
alle modifiche delle patch (a meno che il mittente non sia anche il
manutentore di quell'area del kernel) e in CC: alla lista di discussione
linux-kernel.
- La commissione per la revisione ha 48 ore per dare il proprio ACK o NACK
alle patch.
- Se una patch viene rigettata da un membro della commissione, o un membro
della lista linux-kernel obietta la bontà della patch, sollevando problemi
che i manutentori ed i membri non avevano compreso, allora la patch verrà
rimossa dalla coda.
- Le patch che hanno ricevuto un ACK verranno inviate nuovamente come parte di
un rilascio candidato (-rc) al fine di essere verificate dagli sviluppatori e
dai testatori.
- Solitamente si pubblica solo una -rc, tuttavia se si riscontrano problemi
importanti, alcune patch potrebbero essere modificate o essere scartate,
oppure nuove patch potrebbero essere messe in coda. Dunque, verranno pubblicate
nuove -rc e così via finché non si ritiene che non vi siano più problemi.
- Si può rispondere ad una -rc scrivendo sulla lista di discussione un'email
con l'etichetta "Tested-by:". Questa etichetta verrà raccolta ed aggiunta al
commit rilascio.
- Alla fine del ciclo di revisione il nuovo rilascio -stable conterrà tutte le
patch che erano in coda e sono state verificate.
- Le patch di sicurezza verranno accettate nei sorgenti -stable direttamente
dalla squadra per la sicurezza del kernel, e non passerà per il normale
ciclo di revisione. Contattate la suddetta squadra per maggiori dettagli
su questa procedura.
- Quando i manutentori -stable decidono di fare un ciclo di revisione, le
patch vengono mandate al comitato per la revisione, ai manutentori soggetti
alle modifiche delle patch (a meno che il mittente non sia anche il
manutentore di quell'area del kernel) e in CC: alla lista di discussione
linux-kernel.
- La commissione per la revisione ha 48 ore per dare il proprio ACK o NACK
alle patch.
- Se una patch viene rigettata da un membro della commissione, o un membro
della lista linux-kernel obietta la bontà della patch, sollevando problemi
che i manutentori ed i membri non avevano compreso, allora la patch verrà
rimossa dalla coda.
- Le patch che hanno ricevuto un ACK verranno inviate nuovamente come parte di
un rilascio candidato (-rc) al fine di essere verificate dagli sviluppatori e
dai testatori.
- Solitamente si pubblica solo una -rc, tuttavia se si riscontrano problemi
importanti, alcune patch potrebbero essere modificate o essere scartate,
oppure nuove patch potrebbero essere messe in coda. Dunque, verranno pubblicate
nuove -rc e così via finché non si ritiene che non vi siano più problemi.
- Si può rispondere ad una -rc scrivendo sulla lista di discussione un'email
con l'etichetta "Tested-by:". Questa etichetta verrà raccolta ed aggiunta al
commit rilascio.
- Alla fine del ciclo di revisione il nuovo rilascio -stable conterrà tutte le
patch che erano in coda e sono state verificate.
- Le patch di sicurezza verranno accettate nei sorgenti -stable direttamente
dalla squadra per la sicurezza del kernel, e non passerà per il normale
ciclo di revisione. Contattate la suddetta squadra per maggiori dettagli
su questa procedura.
Sorgenti
--------
- La coda delle patch, sia quelle già applicate che in fase di revisione,
possono essere trovate al seguente indirizzo:
- La coda delle patch, sia quelle già applicate che in fase di revisione,
possono essere trovate al seguente indirizzo:
https://git.kernel.org/pub/scm/linux/kernel/git/stable/stable-queue.git
https://git.kernel.org/pub/scm/linux/kernel/git/stable/stable-queue.git
- Il rilascio definitivo, e marchiato, di tutti i kernel stabili può essere
trovato in rami distinti per versione al seguente indirizzo:
- Il rilascio definitivo, e marchiato, di tutti i kernel stabili può essere
trovato in rami distinti per versione al seguente indirizzo:
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
- I rilasci candidati di tutti i kernel stabili possono essere trovati al
seguente indirizzo:
- I rilasci candidati di tutti i kernel stabili possono essere trovati al
seguente indirizzo:
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable-rc.git/
.. warning::
I sorgenti -stable-rc sono un'istantanea dei sorgenti stable-queue e
subirà frequenti modifiche, dunque verrà anche trapiantato spesso.
Dovrebbe essere usato solo allo scopo di verifica (per esempio in un
sistema di CI)
.. warning::
I sorgenti -stable-rc sono un'istantanea dei sorgenti stable-queue e
subirà frequenti modifiche, dunque verrà anche trapiantato spesso.
Dovrebbe essere usato solo allo scopo di verifica (per esempio in un
sistema di CI)
Comitato per la revisione
-------------------------
- Questo comitato è fatto di sviluppatori del kernel che si sono offerti
volontari per questo lavoro, e pochi altri che non sono proprio volontari.
- Questo comitato è fatto di sviluppatori del kernel che si sono offerti
volontari per questo lavoro, e pochi altri che non sono proprio volontari.

135
Documentation/translations/it_IT/process/submitting-patches.rst
View File

@ -106,9 +106,29 @@ do frotz" piuttosto che "[This patch] makes xyzzy do frotz" or "[I] changed
xyzzy to do frotz", come se steste dando ordini al codice di cambiare il suo
comportamento.
Se volete far riferimento a uno specifico commit, non usate solo
l'identificativo SHA-1. Per cortesia, aggiungete anche la breve riga
riassuntiva del commit per rendere la chiaro ai revisori l'oggetto.
Per esempio::
Commit e21d2170f36602ae2708 ("video: remove unnecessary
platform_set_drvdata()") removed the unnecessary
platform_set_drvdata(), but left the variable "dev" unused,
delete it.
Dovreste anche assicurarvi di usare almeno i primi 12 caratteri
dell'identificativo SHA-1. Il repositorio del kernel ha *molti* oggetti e
questo rende possibile la collisione fra due identificativi con pochi
caratteri. Tenete ben presente che anche se oggi non ci sono collisioni con il
vostro identificativo a 6 caratteri, potrebbero essercene fra 5 anni da oggi.
Se ci sono delle discussioni, o altre informazioni d'interesse, che fanno
riferimento alla patch, allora aggiungete l'etichetta 'Link:' per farvi
riferimento. Per esempio, se la vostra patch corregge un baco potete aggiungere
riferimento. Se la patch è il risultato di una discussione avvenuta
precedentemente o di un documento sul presente sul web, allora fatevi
riferimento.
Per esempio, se la vostra patch corregge un baco potete aggiungere
quest'etichetta per fare riferimento ad un rapporto su una lista di discussione
o un *bug tracker*. Un altro esempio; potete usare quest'etichetta per far
riferimento ad una discussione precedentemente avvenuta su una lista di
@ -129,21 +149,16 @@ Tuttavia, provate comunque a dare una spiegazione comprensibile anche senza
accedere alle fonti esterne. Inoltre, riassumente i punti più salienti che hanno
condotto all'invio della patch.
Se volete far riferimento a uno specifico commit, non usate solo
l'identificativo SHA-1. Per cortesia, aggiungete anche la breve riga
riassuntiva del commit per rendere la chiaro ai revisori l'oggetto.
Per esempio::
Se il collegamento indirizza verso un rapporto su un baco risolto dalla patch,
allora usate l'etichetta "Closes:"::
Commit e21d2170f36602ae2708 ("video: remove unnecessary
platform_set_drvdata()") removed the unnecessary
platform_set_drvdata(), but left the variable "dev" unused,
delete it.
Closes: https://example.com/issues/1234 optional-other-stuff
Dovreste anche assicurarvi di usare almeno i primi 12 caratteri
dell'identificativo SHA-1. Il repositorio del kernel ha *molti* oggetti e
questo rende possibile la collisione fra due identificativi con pochi
caratteri. Tenete ben presente che anche se oggi non ci sono collisioni con il
vostro identificativo a 6 caratteri, potrebbero essercene fra 5 anni da oggi.
Alcune piattaforme di tracciamento di bachi hanno la capacità di chiudere
automaticamente il problema se l'etichetta è presente nel messaggio. Alcuni
automatismi che monitorano la liste di discussione possono anche tracciare
queste etichette e intraprendere azioni. Piattaforme private e URL invalidi sono
proibiti.
Se la vostra patch corregge un baco in un commit specifico, per esempio avete
trovato un problema usando ``git bisect``, per favore usate l'etichetta
@ -237,13 +252,19 @@ nella vostra patch.
5) Selezionate i destinatari della vostra patch
-----------------------------------------------
Dovreste sempre inviare una copia della patch ai manutentori dei sottosistemi
interessati dalle modifiche; date un'occhiata al file MAINTAINERS e alla storia
delle revisioni per scoprire chi si occupa del codice. Lo script
scripts/get_maintainer.pl può esservi d'aiuto (passategli il percorso alle
vostre patch). Se non riuscite a trovare un manutentore per il sottosistema su
cui state lavorando, allora Andrew Morton (akpm@linux-foundation.org) sarà la
vostra ultima possibilità.
Dovreste sempre inviare una copia della patch ai manutentori e alle liste di
discussione dei sottosistemi interessati dalle modifiche; date un'occhiata al
file MAINTAINERS e alla storia delle revisioni per scoprire chi si occupa del
codice. Lo script scripts/get_maintainer.pl può esservi d'aiuto (passategli il
percorso alle vostre patch). Se non riuscite a trovare un manutentore per il
sottosistema su cui state lavorando, allora Andrew Morton
(akpm@linux-foundation.org) sarà la vostra ultima possibilità.
La lista linux-kernel@vger.kernel.org dovrebbe essere usata per l'invio di tutte
le patch, ma il volume ha raggiunto un livello tale d'aver spinto alcuni
sviluppatori a non seguirla più. Dunque, per favore, evitate di inviare messaggi
scorrelati al tema della lista o a persone che non dovrebbero essere
interessate all'argomento.
Normalmente, dovreste anche scegliere una lista di discussione a cui inviare la
vostra serie di patch. La lista di discussione linux-kernel@vger.kernel.org
@ -343,7 +364,8 @@ questo caso, rispondete con educazione e concentratevi sul problema che hanno
evidenziato. Quando inviate una versione successiva ricordatevi di aggiungere un
``patch changelog`` alla email di intestazione o ad ogni singola patch spiegando
le differenze rispetto a sottomissioni precedenti (vedere
:ref:`it_the_canonical_patch_format`).
:ref:`it_the_canonical_patch_format`). Aggiungete a CC tutte le persone che
vi hanno fornito dei commenti per notificarle di eventuali nuove versioni.
Leggete Documentation/translations/it_IT/process/email-clients.rst per
le raccomandazioni sui programmi di posta elettronica e l'etichetta da usare
@ -385,10 +407,10 @@ Dopo che avete inviato le vostre modifiche, siate pazienti e aspettate.
I revisori sono persone occupate e potrebbero non ricevere la vostra patch
immediatamente.
Un tempo, le patch erano solite scomparire nel vuoto senza alcun commento,
ma ora il processo di sviluppo funziona meglio. Dovreste ricevere commenti
in una settimana o poco più; se questo non dovesse accadere, assicuratevi di
aver inviato le patch correttamente. Aspettate almeno una settimana prima di
Un tempo, le patch erano solite scomparire nel vuoto senza alcun commento, ma
ora il processo di sviluppo funziona meglio. Dovreste ricevere commenti in poche
settimane (tipicamente 2 o 3); se questo non dovesse accadere, assicuratevi di
aver inviato le patch correttamente. Aspettate almeno una settimana prima di
rinviare le modifiche o sollecitare i revisori - probabilmente anche di più
durante la finestra d'integrazione.
@ -552,6 +574,10 @@ e si spera che questo possa ispirarli ad aiutarci nuovamente in futuro.
Rammentate che se il baco è stato riportato in privato, dovrete chiedere il
permesso prima di poter utilizzare l'etichetta Reported-by. Questa etichetta va
usata per i bachi, dunque non usatela per richieste di nuove funzionalità.
Questa etichetta dovrebbe essere seguita da quella Closes: con un indirizzo al
rapporto, a meno che questo non sia disponibile sul web. L'etichetta Link: può
essere usata in alternativa a Closes: se la patch corregge solo in parte il
problema riportato nel rapporto.
L'etichetta Tested-by: indica che la patch è stata verificata con successo
(su un qualche sistema) dalla persona citata. Questa etichetta informa i
@ -808,6 +834,63 @@ giungla di riferimenti all'interno dei programmi di posta. Se un collegamento
ad una versione precedente di una serie di patch (per esempio, potete usarlo
per l'email introduttiva alla serie).
Fornire informazioni circa i sorgenti
-------------------------------------
Quando gli altri sviluppatori ricevono le vostre patch e iniziano il processo di
revisione, è assolutamente necessario che sappiano qual è il commit/ramo di base
su cui si base il vostro lavoro: considerate l'enorme quantità di sorgenti dei
manutentori presenti al giorno d'oggi. Si noti ancora una volta la voce **T:**
nel file MAINTAINERS spiegato sopra.
Questo è ancora più importante per i processi automatizzati di CI che tentano di
eseguire una serie di test per stabilire la qualità del codice prima che il
manutentore inizi la revisione.
Se si usa ``git format-patch`` per generare le patch, si possono includere
automaticamente le informazioni sull'albero di base nell'invio usando il flag
``--base``. Il modo più semplice e comodo di usare questa opzione è con i rami
topici::
$ git checkout -t -b my-topical-branch master
Branch 'my-topical-branch' set up to track local branch 'master'.
Switched to a new branch 'my-topical-branch'
[perform your edits and commits]
$ git format-patch --base=auto --cover-letter -o outgoing/ master
outgoing/0000-cover-letter.patch
outgoing/0001-First-Commit.patch
outgoing/...
Aprendo ``outgoing/0000-cover-letter.patch`` per la modifica, si noterà
che ha ``base-commit:`` in fondo, questo fornisce al revisore e agli
strumenti CI informazioni sufficienti per eseguire correttamente ``git am``
senza preoccuparsi dei conflitti::
$ git checkout -b patch-review [base-commit-id]
Switched to a new branch 'patch-review'
$ git am patches.mbox
Applying: First Commit
Applying: ...
Consultate ``man git-format-patch`` per maggiori informazioni circa questa
opzione.
.. note::
L'opzione ``--base`` fu introdotta con git versione 2.9.0
Se non si usa git per produrre le patch, si può comunque includere
``base-commit`` per indicare l'hash del commit dei sorgenti su cui si basa il
lavoro. Dovreste aggiungerlo nella lettera di accompagnamento o nella prima
patch della serie e dovrebbe essere collocato sotto la riga ``---`` o in fondo a
tutti gli altri contenuti, subito prima della vostra firma e-mail.
Assicuratevi che il commit si basi su sorgenti ufficiali del
manutentore/mainline e non su sorgenti interni, accessibile solo a voi,
altrimenti sarebbe inutile.
Riferimenti
-----------

1
Documentation/translations/sp_SP/index.rst
View File

@ -78,3 +78,4 @@ Traducciones al español
process/index
wrappers/memory-barriers
scheduler/index

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

@ -754,7 +754,7 @@ código automáticamente, y revisar archivos completos para detectar errores
de estilo del código, errores tipográficos y posibles mejoras. También es
útil para ordenar ``#includes``, para alinear variables/macros, para
redistribuir texto y otras tareas similares. Vea el archivo
:ref:`Documentation/process/clang-format.rst <clangformat>` para más
:ref:`Documentation/dev-tools/clang-format.rst <clangformat>` para más
detalles.
10) Archivos de configuración de Kconfig

1
Documentation/translations/sp_SP/process/index.rst
View File

@ -29,3 +29,4 @@
submit-checklist
howto
development-process
maintainer-kvm-x86

2
Documentation/translations/sp_SP/process/magic-number.rst
View File

@ -1,6 +1,6 @@
.. include:: ../disclaimer-sp.rst
:Original: :ref:`Documentation/process/magic-number.rst <magicnumbers>`
:Original: :ref:`Documentation/staging/magic-number.rst <magicnumbers>`
:Translator: Carlos Bilbao <carlos.bilbao.osdev@gmail.com>
.. _sp_magicnumbers:

465
Documentation/translations/sp_SP/process/maintainer-kvm-x86.rst Normal file
View File

@ -0,0 +1,465 @@
.. include:: ../disclaimer-sp.rst
:Original: Documentation/process/maintainer-kvm-x86.rst
:Translator: Juan Embid <jembid@ucm.es>
KVM x86
=======
Prólogo
--------
KVM se esfuerza por ser una comunidad acogedora; las contribuciones de los
recién llegados son valoradas e incentivadas. Por favor, no se desanime ni
se sienta intimidado por la extensión de este documento y las numerosas
normas/directrices que contiene. Todos cometemos errores y todos hemos sido
principiantes en algún momento. Mientras haga un esfuerzo honesto por
seguir las directrices de KVM x86, sea receptivo a los comentarios, y
aprenda de los errores que cometa, será recibido con los brazos abiertos,
no con antorchas y horcas.
TL;DR
-----
Las pruebas son obligatorias. Sea coherente con los estilos y patrones
establecidos.
Árboles
-------
KVM x86 se encuentra actualmente en un período de transición de ser parte
del árbol principal de KVM, a ser "sólo otra rama de KVM". Como tal, KVM
x86 está dividido entre el árbol principal de KVM,
``git.kernel.org/pub/scm/virt/kvm/kvm.git``, y un árbol específico de KVM
x86, ``github.com/kvm-x86/linux.git``.
Por lo general, las correcciones para el ciclo en curso se aplican
directamente al árbol principal de KVM, mientras que todo el desarrollo
para el siguiente ciclo se dirige a través del árbol de KVM x86. En el
improbable caso de que una corrección para el ciclo actual se dirija a
través del árbol KVM x86, se aplicará a la rama ``fixes`` antes de llegar
al árbol KVM principal.
Tenga en cuenta que se espera que este periodo de transición dure bastante
tiempo, es decir, que será el statu quo en un futuro previsible.
Ramas
~~~~~
El árbol de KVM x86 está organizado en múltiples ramas por temas. El
propósito de utilizar ramas temáticas más específicas es facilitar el
control de un área de desarrollo, y para limitar los daños colaterales de
errores humanos y/o commits con errores, por ejemplo, borrar el commit HEAD
de una rama temática no tiene impacto en los hashes SHA1 de otros commit
en en camino, y tener que rechazar una solicitud de pull debido a errores
retrasa sólo esa rama temática.
Todas las ramas temáticas, excepto ``next`` y ``fixes``, se agrupan en
``next`` a través de un Cthulhu merge en función de las necesidades, es
decir, cuando se actualiza una rama temática. Como resultado, los push
forzados a ``next`` son comunes.
Ciclo de Vida
~~~~~~~~~~~~~
Las correcciones dirigidas a la versión actual, también conocida como
mainline, suelen aplicarse directamente al árbol principal de KVM, es
decir, no pasan por el árbol x86 de KVM.
Los cambios dirigidos a la siguiente versión se dirigen a través del árbol
KVM x86. Se envían pull requests (de KVM x86 a KVM main) para cada rama
temática de KVM x86, normalmente la semana antes de que Linus abra la
ventana de fusión, por ejemplo, la semana siguiente a rc7 para las
versiones "normales". Si todo va bien, las ramas temáticas son subidas en
el pull request principal de KVM enviado durante la ventana de fusión de
Linus.
El árbol de KVM x86 no tiene su propia ventana de fusión oficial, pero hay
un cierre suave alrededor de rc5 para nuevas características, y un cierre
suave alrededor de rc6 para correcciones (para la próxima versión; fíjese
más arriba para las correcciones dirigidas a la versión actual).
Cronología
~~~~~~~~~~
Normalmente, los envíos se revisan y aplican en orden FIFO, con cierto
margen de maniobra en función del tamaño de la serie, los parches que están
"calientes en caché", etc. Correcciones, especialmente para la versión
actual y/o árboles estables, consiguen saltar la cola. Los parches que se
lleven a través de un árbol que no sea KVM (la mayoría de las veces a
través del árbol de consejos) y/o que tengan otros acks/revisiones también
saltan la cola hasta cierto punto.
Tenga en cuenta que la mayor parte de la revisión se realiza entre rc1 y
rc6, más o menos. El periodo entre la rc6 y la siguiente rc1 se utiliza
para ponerse al día en otras tareas, es decir, la falta de envíos durante
este periodo no es inusual.
Los pings para obtener una actualización del estado son bienvenidos, pero
tenga en cuenta el calendario del ciclo de publicación actual y tenga
expectativas realistas. Si está haciendo ping para la aceptación, es decir,
no sólo para obtener comentarios o una actualización, por favor haga todo
lo posible, dentro de lo razonable, para asegurarse de que sus parches
están listos para ser fusionados. Los pings sobre series que rompen la
compilación o fallan en las pruebas provocan el descontento de los
mantenedores.
Desarrollo
-----------
Árbol base/Rama
~~~~~~~~~~~~~~~
Las correcciones dirigidas a la versión actual, también conocida como
mainline, deben basarse en
``git://git.kernel.org/pub/scm/virt/kvm/kvm.git master``. Tenga en cuenta
que las correcciones no garantizan automáticamente la inclusión en la
versión actual. No hay una regla única, pero normalmente sólo las
correcciones de errores urgentes, críticos y/o introducidos en la versión
actual deberían incluirse en la versión actual.
Todo lo demás debería basarse en ``kvm-x86/next``, es decir, no hay
necesidad de seleccionar una rama temática específica como base. Si hay
conflictos y/o dependencias entre ramas, es trabajo del mantenedor
resolverlos.
La única excepción al uso de ``kvm-x86/next`` como base es si un
parche/serie es una serie multi-arquitectura, es decir, tiene
modificaciones no triviales en el código común de KVM y/o tiene cambios más
que superficiales en el código de otras arquitecturas. Los parches/series
multi-arquitectura deberían basarse en un punto común y estable en la
historia de KVM, por ejemplo, la versión candidata en la que se basa
``kvm-x86 next``. Si no está seguro de si un parche/serie es realmente
multiarquitectura, sea precavido y trátelo como multiarquitectura, es
decir, utilice una base común.
Estilo del codigo
~~~~~~~~~~~~~~~~~~~~~~
Cuando se trata de estilo, nomenclatura, patrones, etc., la coherencia es
la prioridad número uno en KVM x86. Si todo lo demás falla, haga coincidir
lo que ya existe.
Con algunas advertencias que se enumeran a continuación, siga las
recomendaciones de los responsables del árbol de consejos
:ref:`maintainer-tip-coding-style`, ya que los parches/series a menudo
tocan tanto archivos x86 KVM como no KVM, es decir, llaman la atención de
los mantenedores de KVM *y* del árbol de consejos.
El uso del abeto inverso, también conocido como árbol de Navidad inverso o
árbol XMAS inverso, para las declaraciones de variables no es estrictamente
necesario, aunque es preferible.
Excepto para unos pocos apuntes especiales, no utilice comentarios
kernel-doc para las funciones. La gran mayoría de las funciones "públicas"
de KVM no son realmente públicas, ya que están destinadas únicamente al
consumo interno de KVM (hay planes para privatizar las cabeceras y
exportaciones de KVM para reforzar esto).
Comentarios
~~~~~~~~~~~
Escriba los comentarios en modo imperativo y evite los pronombres. Utilice
los comentarios para ofrecer una visión general de alto nivel del código
y/o para explicar por qué el código hace lo que hace. No reitere lo que el
código hace literalmente; deje que el código hable por sí mismo. Si el
propio código es inescrutable, los comentarios no servirán de nada.
Referencias SDM y APM
~~~~~~~~~~~~~~~~~~~~~~
Gran parte de la base de código de KVM está directamente vinculada al
comportamiento de la arquitectura definido en El Manual de Desarrollo de
Software (SDM) de Intel y el Manual del Programador de Arquitectura (APM)
de AMD. El uso de "SDM de Intel" y "APM de AMD", o incluso sólo "SDM" o
"APM", sin contexto adicional es correcto.
No haga referencia a secciones específicas, tablas, figuras, etc. por su
número, especialmente en los comentarios. En su lugar, si es necesario
(véase más abajo), copie y pegue el fragmento correspondiente y haga
referencia a las secciones/tablas/figuras por su nombre. Los diseños del
SDM y el APM cambian constantemente, por lo que los números/etiquetas no
son estables.
En general, no haga referencia explícita ni copie-pegue del SDM o APM en
los comentarios. Con pocas excepciones, KVM *debe* respetar el
comportamiento de la arquitectura, por lo que está implícito que el
comportamiento de KVM está emulando el comportamiento de SDM y/o APM. Tenga
en cuenta que hacer referencia al SDM/APM en los registros de cambios para
justificar el cambio y proporcionar contexto es perfectamente correcto y
recomendable.
Shortlog
~~~~~~~~
El formato de prefijo más recomendable es ``KVM: <topic>:``, donde
``<topic>`` es uno de los siguientes::
- x86
- x86/mmu
- x86/pmu
- x86/xen
- autocomprobaciones
- SVM
- nSVM
- VMX
- nVMX
**¡NO use x86/kvm!** ``x86/kvm`` se usa exclusivamente para cambios de
Linux virtualizado por KVM, es decir, para arch/x86/kernel/kvm.c. No use
nombres de archivos o archivos completos como prefijo de asunto/shortlog.
Tenga en cuenta que esto no coincide con las ramas temáticas (las ramas
temáticas se preocupan mucho más por los conflictos de código).
Todos los nombres distinguen entre mayúsculas y minúsculas. ``KVM: x86:``
es correcto, ``kvm: vmx:`` no lo es.
Escriba en mayúsculas la primera palabra de la descripción condensada del
parche, pero omita la puntuación final. Por ejemplo::
KVM: x86: Corregir una desviación de puntero nulo en function_xyz()
no::
kvm: x86: corregir una desviación de puntero nulo en function_xyz.
Si un parche afecta a varios temas, recorra el árbol conceptual hasta
encontrar el primer padre común (que suele ser simplemente ``x86``). En
caso de duda, ``git log path/to/file`` debería proporcionar una pista
razonable.
De vez en cuando surgen nuevos temas, pero le rogamos que inicie un debate
en la lista si desea proponer la introducción de un nuevo tema, es decir,
no se ande con rodeos.
Consulte :ref:`the_canonical_patch_format` para obtener más información,
con una enmienda: no trate el límite de 70-75 caracteres como un límite
absoluto y duro. En su lugar, utilice 75 caracteres como límite firme, pero
no duro, y 80 caracteres como límite duro. Es decir, deje que el registro
corto sobrepase en algunos caracteres el límite estándar si tiene una buena
razón para hacerlo.
Registro de cambios
~~~~~~~~~~~~~~~~~~~
Y lo que es más importante, escriba los registros de cambios en modo
imperativo y evite los pronombres.
Consulte :ref:`describe_changes` para obtener más información, con una
recomendación: comience con un breve resumen de los cambios reales y
continúe con el contexto y los antecedentes. Nota. Este orden entra en
conflicto directo con el enfoque preferido del árbol de sugerencias. Por
favor, siga el estilo preferido del árbol de sugerencias cuando envíe
parches. que se dirigen principalmente a código arch/x86 que _NO_ es código
KVM.
KVM x86 prefiere indicar lo que hace un parche antes de entrar en detalles
por varias razones. En primer lugar, el código que realmente se está
cambiando es posiblemente la información más importante, por lo que esa
información debe ser fácil de encontrar. Changelogs que entierran el "qué
está cambiando realmente" en una sola línea después de 3+ párrafos de fondo
hacen muy difícil encontrar esa información.
Para la revisión inicial, se podría argumentar que "lo que está roto" es
más importante, pero para hojear los registros y la arqueología git, los
detalles escabrosos importan cada vez menos. Por ejemplo, al hacer una
serie de "git blame", los detalles de cada cambio a lo largo del camino son
inútiles, los detalles sólo importan para el culpable. Proporcionar el "qué
ha cambiado" facilita determinar rápidamente si una confirmación puede ser
de interés o no.
Otra ventaja de decir primero "qué cambia" es que casi siempre es posible
decir "qué cambia" en una sola frase. A la inversa, todo menos los errores
más simples requieren varias frases o párrafos para describir el problema.
Si tanto "qué está cambiando" como "cuál es el fallo" son muy breves, el
orden no importa. Pero si uno es más corto (casi siempre el "qué está
cambiando"), entonces cubrir el más corto primero es ventajoso porque es
menos inconveniente para los lectores/revisores que tienen una preferencia
estricta de orden. Por ejemplo, tener que saltarse una frase para llegar al
contexto es menos doloroso que tener que saltarse tres párrafos para llegar
a "lo que cambia".
Arreglos
~~~~~~~~
Si un cambio corrige un error de KVM/kernel, añada una etiqueta Fixes:
incluso si el cambio no necesita ser retroportado a kernels estables, e
incluso si el cambio corrige un error en una versión anterior.
Por el contrario, si es necesario hacer una corrección, etiquete
explícitamente el parche con "Cc: stable@vger.kernel" (aunque no es
necesario que el correo electrónico incluya Cc: stable); KVM x86 opta por
excluirse del backporting Correcciones: por defecto. Algunos parches
seleccionados automáticamente se retroportan, pero requieren la aprobación
explícita de los mantenedores (busque MANUALSEL).
Referencias a Funciones
~~~~~~~~~~~~~~~~~~~~~~~
Cuando se mencione una función en un comentario, registro de cambios o
registro abreviado (o en cualquier otro lugar), utilice el formato
``nombre_de_la_función()``. Los paréntesis proporcionan contexto y
desambiguan la referencia.
Pruebas
~~~~~~~
Como mínimo, *todos* los parches de una serie deben construirse limpiamente
para KVM_INTEL=m KVM_AMD=m, y KVM_WERROR=y. Construir todas las
combinaciones posibles de Kconfigs no es factible, pero cuantas más mejor.
KVM_SMM, KVM_XEN, PROVE_LOCKING, y X86_64 son particularmente interesantes.
También es obligatorio ejecutar las autopruebas y las pruebas unitarias de
KVM (y, como es obvio, las pruebas deben pasar). La única excepción es para
los cambios que tienen una probabilidad insignificante de afectar al
comportamiento en tiempo de ejecución, por ejemplo, parches que sólo
modificar los comentarios. Siempre que sea posible y pertinente, se
recomienda encarecidamente realizar pruebas tanto en Intel como en AMD. Se
recomienda arrancar una máquina virtual real, pero no es obligatorio.
Para cambios que afecten al código de paginación en la sombra de KVM, es
obligatorio ejecutar con TDP (EPT/NPT) deshabilitado. Para cambios que
afecten al código MMU común de KVM, se recomienda encarecidamente ejecutar
con TDP deshabilitado. Para todos los demás cambios, si el código que se
está modificando depende de y/o interactúa con un parámetro del módulo, es
obligatorio realizar pruebas con la configuración correspondiente.
Tenga en cuenta que las autopruebas de KVM y las pruebas de unidad de KVM
tienen fallos conocidos. Si sospecha que un fallo no se debe a sus cambios,
verifique que el *exactamente el mismo* fallo se produce con y sin sus
cambios.
Los cambios que afecten a la documentación de texto reestructurado, es
decir, a los archivos .rst, deben generar htmldocs de forma limpia, es
decir, sin advertencias ni errores.
Si no puede probar completamente un cambio, por ejemplo, por falta de
hardware, indique claramente qué nivel de pruebas ha podido realizar, por
ejemplo, en la carta de presentación.
Novedades
~~~~~~~~~
Con una excepción, las nuevas características *deben* venir con cobertura
de pruebas. Las pruebas específicas de KVM no son estrictamente necesarias,
por ejemplo, si la cobertura se proporciona mediante la ejecución de una
prueba de VM huésped suficientemente habilitada, o ejecutando una
autoprueba de kernel relacionada en una VM, pero en todos los casos se
prefieren las pruebas KVM dedicadas. Los casos de prueba negativos en
particular son obligatorios para la habilitación de nuevas características
de hardware, ya que los flujos de errores y excepciones rara vez se
ejercitan simplemente ejecutando una VM.
La única excepción a esta regla es si KVM está simplemente anunciando
soporte para un a través de KVM_GET_SUPPORTED_CPUID, es decir, para
instrucciones/funciones que KVM no puede impedir que utilice una VM y
para las que no existe una verdadera habilitación.
Tenga en cuenta que "nuevas características" no significa sólo "nuevas
características de hardware". Las nuevas funcionalidades que no puedan ser
validadas usando las pruebas existentes de KVM y/o las pruebas unitarias de
KVM deben venir con pruebas.
Es más que bienvenido el envío de nuevos desarrollos de características sin
pruebas para obtener un feedback temprano, pero tales envíos deben ser
etiquetados como RFC, y la carta de presentación debe indicar claramente
qué tipo de feedback se solicita/espera. No abuse del proceso de RFC; las
RFC no suelen recibir una revisión en profundidad.
Corrección de Errores
~~~~~~~~~~~~~~~~~~~~~
Salvo en el caso de fallos "obvios" detectados por inspección, las
correcciones deben ir acompañadas de un reproductor del fallo corregido. En
muchos casos, el reproductor está implícito, por ejemplo, para errores de
compilación y fallos de prueba, pero debe quedar claro para lectores qué es
lo que no funciona y cómo verificar la solución. Se concede cierto margen a
los errores detectados mediante cargas de trabajo/pruebas no públicas, pero
se recomienda encarecidamente que se faciliten pruebas de regresión para
dichos errores.
En general, las pruebas de regresión son preferibles para cualquier fallo
que no sea trivial de encontrar. Por ejemplo, incluso si el error fue
encontrado originalmente por un fuzzer como syzkaller, una prueba de
regresión dirigida puede estar justificada si el error requiere golpear una
condición de carrera de tipo uno en un millón.
Recuerde que los fallos de KVM rara vez son urgentes *y* no triviales de
reproducir. Pregúntate si un fallo es realmente el fin del mundo antes de
publicar una corrección sin un reproductor.
Publicación
-----------
Enlaces
~~~~~~~
No haga referencia explícita a informes de errores, versiones anteriores de
un parche/serie, etc. mediante cabeceras ``In-Reply-To:``. Usar
``In-Reply-To:`` se convierte en un lío para grandes series y/o cuando el
número de versiones es alto, y ``In-Reply-To:`` es inútil para cualquiera
que no tenga el mensaje original, por ejemplo, si alguien no recibió un Cc
en el informe de error o si la lista de destinatarios cambia entre
versiones.
Para enlazar con un informe de error, una versión anterior o cualquier cosa
de interés, utiliza enlaces lore. Para hacer referencia a versiones
anteriores, en general no incluya un Enlace: en el registro de cambios, ya
que no hay necesidad de registrar la historia en git, es decir, ponga el
enlace en la carta de presentación o en la sección que git ignora.
Proporcione un Enlace: formal para los informes de errores y/o discusiones
que condujeron al parche. El contexto de por qué se hizo un cambio es muy
valioso para futuros lectores.
Basado en Git
~~~~~~~~~~~~~
Si utilizas la versión 2.9.0 o posterior de git (Googlers, ¡os incluimos a
todos!), utilice ``git format-patch`` con el indicador ``--base`` para
incluir automáticamente la información del árbol base en los parches
generados.
Tenga en cuenta que ``--base=auto`` funciona como se espera si y sólo si el
upstream de una rama se establece en la rama temática base, por ejemplo,
hará lo incorrecto si su upstream se establece en su repositorio personal
con fines de copia de seguridad. Una solución "automática" alternativa es
derivar los nombres de tus ramas de desarrollo basándose en su KVM x86, e
introdúzcalo en ``--base``. Por ejemplo, ``x86/pmu/mi_nombre_de_rama``, y
luego escribir un pequeño wrapper para extraer ``pmu`` del nombre de la
rama actual para obtener ``--base=x/pmu``, donde ``x`` es el nombre que su
repositorio utiliza para rastrear el remoto KVM x86.
Tests de Co-Publicación
~~~~~~~~~~~~~~~~~~~~~~~
Las autopruebas de KVM asociadas a cambios de KVM, por ejemplo, pruebas de
regresión para correcciones de errores, deben publicarse junto con los
cambios de KVM como una única serie. Se aplicarán las reglas estándar del
núcleo para la bisección, es decir, los cambios de KVM que provoquen fallos
en las pruebas se ordenarán después de las actualizaciones de las
autopruebas, y viceversa. Las pruebas que fallan debido a errores de KVM
deben ordenarse después de las correcciones de KVM.
KVM-unit-tests debería *siempre* publicarse por separado. Las herramientas,
por ejemplo b4 am, no saben que KVM-unit-tests es un repositorio separado y
se confunden cuando los parches de una serie se aplican en diferentes
árboles. Para vincular los parches de KVM-unit-tests a Parches KVM, primero
publique los cambios KVM y luego proporcione un enlace lore Link: al
parche/serie KVM en el parche(s) KVM-unit-tests.
Notificaciones
~~~~~~~~~~~~~~
Cuando se acepte oficialmente un parche/serie, se enviará un correo
electrónico de notificación en respuesta a la publicación original (carta
de presentación para series de varios parches). La notificación incluirá el
árbol y la rama temática, junto con los SHA1 de los commits de los parches
aplicados.
Si se aplica un subconjunto de parches, se indicará claramente en la
notificación. A menos que se indique lo contrario, se sobreentiende que
todos los parches del Las series que no han sido aceptadas necesitan más
trabajo y deben presentarse en una nueva versión.
Si por alguna razón se retira un parche después de haber sido aceptado
oficialmente, se enviará una respuesta al correo electrónico de
notificación explicando por qué se ha retirado el parche, así como los
pasos siguientes.
Estabilidad SHA1
~~~~~~~~~~~~~~~~
Los SHA1 no son 100% estables hasta que llegan al árbol de Linus. Un SHA1
es *normalmente* estable una vez que se ha enviado una notificación, pero
ocurren cosas. En la mayoría de los casos, se proporcionará una
actualización del correo electrónico de notificación si se aplica un SHA1
del parche. Sin embargo, en algunos escenarios, por ejemplo, si todas las
ramas de KVM x86 necesitan ser rebasadas, no se darán notificaciones
individuales.
Vulnerabilidades
~~~~~~~~~~~~~~~~
Los fallos que pueden ser explotados por la VM (el "guest") para atacar al
host (kernel o espacio de usuario), o que pueden ser explotados por una VM
anidada a *su* host (L2 atacando a L1), son de particular interés para KVM.
Por favor, siga el protocolo para :ref:`securitybugs` si sospecha que un
fallo puede provocar una filtración de datos, etc.

8
Documentation/translations/sp_SP/scheduler/index.rst Normal file
View File

@ -0,0 +1,8 @@
.. include:: ../disclaimer-sp.rst
.. _sp_scheduler_index:
.. toctree::
:maxdepth: 1
sched-design-CFS

277
Documentation/translations/sp_SP/scheduler/sched-design-CFS.rst Normal file
View File

@ -0,0 +1,277 @@
.. include:: ../disclaimer-sp.rst
:Original: :ref:`Documentation/scheduler/sched-design-CFS.rst <sched_design_CFS>`
:Translator: Sergio González Collado <sergio.collado@gmail.com>
.. _sp_sched_desing_CFS:
====================
Gestor de tareas CFS
====================
1. VISIÓN GENERAL
==================
CFS viene de las siglas en inglés de "Gestor de tareas totalmente justo"
("Completely Fair Scheduler"), y es el nuevo gestor de tareas de escritorio
implementado por Ingo Molnar e integrado en Linux 2.6.23. Es el sustituto de
el previo gestor de tareas SCHED_OTHER.
Nota: El planificador EEVDF fue incorporado más recientemente al kernel.
El 80% del diseño de CFS puede ser resumido en una única frase: CFS
básicamente modela una "CPU ideal, precisa y multi-tarea" sobre hardware
real.
"una CPU multitarea ideal" es una CPU (inexistente :-)) que tiene un 100%
de potencia y que puede ejecutar cualquier tarea exactamente a la misma
velocidad, en paralelo, y cada una a 1/n velocidad. Por ejemplo, si hay dos
tareas ejecutándose, entonces cada una usa un 50% de la potencia --- es decir,
como si se ejecutaran en paralelo.
En hardware real, se puede ejecutar una única tarea a la vez, así que
se ha usado el concepto de "tiempo de ejecución virtual". El tiempo
de ejecución virtual de una tarea específica cuando la siguiente porción
de ejecución podría empezar en la CPU ideal multi-tarea descrita anteriormente.
En la práctica, el tiempo de ejecución virtual de una tarea es el
tiempo de ejecución real normalizado con respecto al número total de
tareas ejecutándose.
2. UNOS CUANTOS DETALLES DE IMPLEMENTACIÓN
===========================================
En CFS, el tiempo de ejecución virtual se expresa y se monitoriza por
cada tarea, en su valor de p->se.vruntime (en unidades de nanosegundos).
De este modo, es posible temporizar con precisión y medir el "tiempo
de CPU esperado" que una tarea debería tener.
Un pequeño detalle: en hardware "ideal", en cualquier momento todas las
tareas pueden tener el mismo valor de p->se.vruntime --- i.e., tareas
se podrían ejecutar simultáneamente y ninguna tarea podría escaparse del
"balance" de la partición "ideal" del tiempo compartido de la CPU.
La lógica de elección del tareas de CFS se basa en el valor de p->se.vruntime
y por tanto es muy sencilla: siempre intenta ejecutar la tarea con el valor
p->se.vruntime más pequeño (i.e., la tarea que se ha ejecutado menos hasta el
momento). CFS siempre intenta dividir el espacio de tiempo entre tareas
en ejecución tan próximo a la "ejecución multitarea ideal del hardware" como
sea posible.
El resto del diseño de CFS simplemente se escapa de este simple concepto,
con unos cuantos añadidos como los niveles "nice" ("nice" significa "amable"
en inglés), multi-tarea y varias variantes del algoritmo para identificar
tareas "durmiendo".
3. EL ÁRBOL ROJO-NEGRO
=======================
El diseño de CFS es bastante radical: no utiliza las antiguas estructuras
de datos para las colas de ejecución (en inglés "runqueues"), pero usa una
estructura de árbol rojo-negro (en inglés "red-black tree") ordenado cronológicamente
para construir un línea de ejecución en el futuro, y por eso no tiene ningún
artificio de "cambio de tareas" (algo que previamente era usado por el gestor
anterior y RSDL/SD).
CFS también mantiene el valor de rq->cfs.min_vruntime, el cual crece
monotónicamente siguiendo el valor más pequeño de vruntime de entre todas
las tareas en la cola de ejecución. La cantidad total de trabajo realizado
por el sistema es monitorizado usado min_vruntime; este valor es usado
para situar las nuevas tareas en la parte izquierda del árbol tanto
como sea posible.
El valor total de tareas ejecutándose en la cola de ejecución es
contabilizado mediante el valor rq->cfs.load, el cual es la suma de los
de esas tareas que están en la cola de ejecución.
CFS mantiene un árbol rojo-negro cronológicamente ordenado, donde todas las
tareas que pueden ser ejecutadas están ordenadas por su valor de
p->se.vruntime. CFS selecciona la tarea más hacia la izquierda de este
árbol y la mantiene. Según el sistema continúa, las tareas ejecutadas
se ponen en este árbol más y más hacia la derecha --- lentamente pero
de forma continuada dando una oportunidad a cada tarea de ser la que
está "la más hacia la izquierda" y por tanto obtener la CPU una cantidad
determinista de tiempo.
Resumiendo, CFS funciona así: ejecuta una tarea un tiempo, y cuando la
tarea se gestiona (o sucede un tic del gestor de tareas) se considera
que el tiempo de uso de la CPU se ha completado, y se añade a
p->se.vruntime. Una vez p->se.vruntime ha aumentado lo suficiente como
para que otra tarea sea "la tarea más hacia la izquierda" del árbol
rojo-negro ordenado cronológicamente esta mantienen (más una cierta pequeña
cantidad de distancia relativa a la tarea más hacia la izquierda para
que no se sobre-reserven tareas y perjudique a la cache), entonces la
nueva tarea "que está a la izquierda del todo", es la que se elige
para que se ejecute, y la tarea en ejecución es interrumpida.
4. ALGUNAS CARACTERÍSTICAS DE CFS
==================================
CFS usa una granularidad de nanosegundos y no depende de ningún
jiffie o detalles como HZ. De este modo, el gestor de tareas CFS no tiene
noción de "ventanas de tiempo" de la forma en que tenía el gestor de
tareas previo, y tampoco tiene heurísticos. Únicamente hay un parámetro
central ajustable (se ha de cambiar en CONFIG_SCHED_DEBUG):
/sys/kernel/debug/sched/base_slice_ns
El cual puede ser usado para afinar desde el gestor de tareas del "escritorio"
(i.e., bajas latencias) hacia cargas de "servidor" (i.e., bueno con
procesamientos). Su valor por defecto es adecuado para tareas de escritorio.
SCHED_BATCH también es gestionado por el gestor de tareas CFS.
Debido a su diseño, el gestor de tareas CFS no es proclive a ninguno de los
ataques que existen a día de hoy contra los heurísticos del gestor de tareas:
fiftyp.c, thud.c, chew.c, ring-test.c, massive_intr.c todos trabajan
correctamente y no tienen impacto en la interacción y se comportan de la forma
esperada.
El gestor de tareas CFS tiene una gestión mucho más firme de los niveles
"nice" y SCHED_BATCH que los previos gestores de tareas: ambos tipos de
tareas están aisladas de forma más eficiente.
El balanceo de tareas SMP ha sido rehecho/mejorado: el avance por las
colas de ejecución de tareas ha desaparecido del código de balanceo de
carga, y ahora se usan iteradores en la gestión de módulos. El balanceo
del código ha sido simplificado como resultado esto.
5. Políticas de gestión de tareas
==================================
CFS implementa tres políticas de gestión de tareas:
- SCHED_NORMAL (tradicionalmente llamada SCHED_OTHER): Gestión de
tareas que se usan para tareas normales.
- SCHED_BATCH: No interrumpe tareas tan a menudo como las tareas
normales harían, por eso permite a las tareas ejecutarse durante
ventanas de tiempo mayores y hace un uso más efectivo de las
caches pero al coste de la interactividad. Esto es adecuado
para trabajos de procesado de datos.
- SCHED_IDLE: Esta política es más débil incluso que nice 19, pero
no es un gestor "idle" para evitar caer en el problema de la
inversión de prioridades que causaría un bloqueo de la máquina
(deadlock).
SCHED_FIFO/_RR se implementan en sched/rt.c y son específicos de
POSIX.
El comando chrt de util-linux-ng 2.13.1.1. puede asignar cualquiera de
estas políticas excepto SCHED_IDLE.
6. CLASES DE GESTIÓN
=====================
El nuevo gestor de tareas CFS ha sido diseñado de tal modo para incluir
"clases de gestión", una jerarquía ampliable de módulos que pueden tener
distintas políticas de gestión de tareas. Estos módulos encapsulan los
detalles de las politicas de gestión y son manejadas por el núcleo del
gestor de tareas sin que este tenga que presuponer mucho sobre estas clases.
sched/fair.c implementa el gestor de tareas CFS descrito antes.
sched/rt.c implementa la semántica de SCHED_FIFO y SCHED_RR, de una forma
más sencilla que el gestor de tareas anterior. Usa 100 colas de ejecución
(por todos los 100 niveles de prioridad RT, en vez de las 140 que necesitaba
el gestor de tareas anterior) y no necesita las listas de expiración.
Las clases de gestión de tareas son implementadas por medio de la estructura
sched_class, la cual tiene llamadas a las funciones que deben de llamarse
cuando quiera que ocurra un evento interesante.
Esta es la lista parcial de llamadas:
- enqueue_task(...)
Llamada cuando una tarea entra en el estado de lista para ejecución.
Pone la entidad a ser gestionada (la tarea) en el árbol rojo-negro
e incrementa la variable nr_running.
- dequeue_task(...)
Cuando una tarea deja de ser ejecutable, esta función se llama para
mantener a la entidad gestionada fuera del árbol rojo-negor. Esto
decrementa la variable nr_running.
- yield_task(...)
Esta función es básicamente desencolar, seguido por encolar, a menos que
sysctl compat_yield esté activado; en ese caso, sitúa la entidad a gestionar
en la parte más hacia la derecha del árbol rojo-negro.
- check_preempt_curr(...)
Esta función comprueba si una tarea que ha entrado en el estado de
poder ser ejecutada, podría reemplazar a la tarea que actualmente
se esté ejecutando.
- pick_next_task(...)
Esta función elige la tarea más apropiada para ser ejecutada a continuación.
- set_curr_task(...)
Esta función se llama cuando una tarea cambia su clase de gestión o
cambia su grupo de tareas.
- task_tick(...)
Esta función es llamada la mayoría de las veces desde la función de tiempo
tick; esto puede llevar a un cambio de procesos. Esto dirige el reemplazo
de las tareas.
7. EXTENSIONES DE GRUPOS PARA CFS
==================================
Normalmente, el gestor de tareas gestiona tareas individuales e intenta
proporcionar una cantidad justa de CPU a cada tarea. Algunas veces, puede
ser deseable agrupar las tareas y proporcionarles una cantidad justa
de tiempo de CPU a cada una de las tareas de ese grupo. Por ejemplo,
podría ser deseable que primero se proporcione una cantidad justa de
tiempo de CPU a cada usuario del sistema y después a cada tarea
que pertenezca a un usuario.
CONFIG_CGROUP_SCHED destaca en conseguir exactamente eso. Permite a las
tareas ser agrupadas y divide el tiempo de CPU de forma just entre esos
grupos.
CONFIG_RT_GROUP_SCHED permite agrupar tareas de tiempo real (i.e.,
SCHED_FIFO y SCHED_RR).
CONFIG_FAIR_GROUP_SCHED permite agrupar tareas de CFS (i.e., SCHED_NORMAL y
SCHED_BATCH).
Estas opciones necesitan CONFIG_CGROUPS para ser definidas, y permitir
al administrador crear grupos arbitrarios de tareas, usando el pseudo
sistema de archivos "cgroup". Vease la documentación para más información
sobre este sistema de archivos: Documentation/admin-guide/cgroup-v1/cgroups.rst
Cuando CONFIG_FAIR_GROUP_SCHED es definido, un archivo
"cpu.shares" es creado por cada grupo creado usado en el pseudo
sistema de archivos. Véanse por ejemplo los pasos a continuación
para crear grupos de tareas y modificar cuanto comparten de la CPU
usando el pseudo sistema de archivos "cgroup" ::
# mount -t tmpfs cgroup_root /sys/fs/cgroup
# mkdir /sys/fs/cgroup/cpu
# mount -t cgroup -ocpu none /sys/fs/cgroup/cpu
# cd /sys/fs/cgroup/cpu
# mkdir multimedia # crear un grupo de tareas "multimedia"
# mkdir browser # crear un grupo de tareas "browser"
# #Configurar el grupo multimedia para tener el doble de tiempo de CPU
# #que el grupo browser
# echo 2048 > multimedia/cpu.shares
# echo 1024 > browser/cpu.shares
# firefox & # Lanzar firefox y moverlo al grupo "browser"
# echo <firefox_pid> > browser/tasks
# #Lanzar gmplayer (o su programa favorito de reproducción de películas)
# echo <movie_player_pid> > multimedia/tasks

2
Documentation/translations/zh_CN/admin-guide/index.rst
View File

@ -68,6 +68,7 @@ Todolist:
cpu-load
cputopology
lockup-watchdogs
numastat
unicode
sysrq
mm/index
@ -109,7 +110,6 @@ Todolist:
* module-signing
* mono
* namespaces/index
* numastat
* parport
* perf-security
* pm/index

48
Documentation/translations/zh_CN/admin-guide/numastat.rst Normal file
View File

@ -0,0 +1,48 @@
.. SPDX-License-Identifier: GPL-2.0
.. include:: ../disclaimer-zh_CN.rst
:Original: Documentation/admin-guide/numastat.rst
:Translator: Tao Zou <wodemia@linux.alibaba.com>
=======================
Numa策略命中/未命中统计
=======================
/sys/devices/system/node/node*/numastat
所有数据的单位都是页面。巨页有独立的计数器。
numa_hit、numa_miss和numa_foreign计数器反映了进程是否能够在他们偏好的节点上分配内存。
如果进程成功在偏好的节点上分配内存则在偏好的节点上增加numa_hit计数，否则在偏好的节点上增
加numa_foreign计数同时在实际内存分配的节点上增加numa_miss计数。
通常，偏好的节点是进程运行所在的CPU的本地节点，但是一些限制可以改变这一行为，比如内存策略，
因此同样有两个基于CPU本地节点的计数器。local_node和numa_hit类似，当在CPU所在的节点上分
配内存时增加local_node计数，other_node和numa_miss类似，当在CPU所在节点之外的其他节点
上成功分配内存时增加other_node计数。需要注意，没有和numa_foreign对应的计数器。
更多细节内容:
=============== ============================================================
numa_hit 一个进程想要从本节点分配内存并且成功。
numa_miss 一个进程想要从其他节点分配内存但是最终在本节点完成内存分配。
numa_foreign 一个进程想要在本节点分配内存但是最终在其他节点完成内存分配。
local_node 一个进程运行在本节点的CPU上并且从本节点上获得了内存。
other_node 一个进程运行在其他节点的CPU上但是在本节点上获得了内存。
interleave_hit 内存交叉分配策略下想要从本节点分配内存并且成功。
=============== ============================================================
你可以使用numactl软件包（http://oss.sgi.com/projects/libnuma/）中的numastat工具
来辅助阅读。需要注意，numastat工具目前只在有少量CPU的机器上运行良好。
需要注意，在包含无内存节点（一个节点有CPUs但是没有内存）的系统中numa_hit、numa_miss和
numa_foreign统计数据会被严重曲解。在当前的内核实现中，如果一个进程偏好一个无内存节点（即
进程正在该节点的一个本地CPU上运行），实际上会从距离最近的有内存节点中挑选一个作为偏好节点。
结果会导致相应的内存分配不会增加无内存节点上的numa_foreign计数器，并且会扭曲最近节点上的
numa_hit、numa_miss和numa_foreign统计数据。

4
Documentation/translations/zh_CN/dev-tools/gdb-kernel-debugging.rst
View File

@ -34,6 +34,10 @@ Kgdb内核调试器、QEMU等虚拟机管理程序或基于JTAG的硬件接口
但这通常仅在不依赖内核模块时才有效。有关此模式的更多详细信息，请参阅QEMU文档。
在这种情况下，如果架构支持KASLR，应该在禁用CONFIG_RANDOMIZE_BASE的情况下构建内核。
- 构建gdb脚本（适用于内核v5.1版本及以上）
make scripts_gdb
- 启用QEMU/KVM的gdb stub，可以通过如下方式实现
- 在VM启动时，通过在QEMU命令行中添加“-s”参数

6
Documentation/translations/zh_CN/dev-tools/index.rst
View File

@ -20,18 +20,22 @@ Documentation/translations/zh_CN/dev-tools/testing-overview.rst
testing-overview
sparse
kcov
gcov
kasan
kcov
ubsan
kmemleak
gdb-kernel-debugging
Todolist:
- checkpatch
- coccinelle
- kmsan
- kcsan
- kfence
- kgdb
- kselftest
- kunit/index
- ktap
- checkuapi

18
Documentation/translations/zh_CN/dev-tools/kasan.rst
View File

@ -235,6 +235,24 @@ slab对象的描述以及关于访问的内存页的信息。
通用KASAN还报告两个辅助调用堆栈跟踪。这些堆栈跟踪指向代码中与对象交互但不直接
出现在错误访问堆栈跟踪中的位置。目前，这包括 call_rcu() 和排队的工作队列。
CONFIG_KASAN_EXTRA_INFO
~~~~~~~~~~~~~~~~~~~~~~~
启用 CONFIG_KASAN_EXTRA_INFO 选项允许 KASAN 记录和报告更多信息。目前支持的
额外信息包括分配和释放时的 CPU 编号和时间戳。更多的信息可以帮助找到内核错误的原因，
并将错误与其他系统事件关联起来，但代价是用额外的内存来记录更多信息（有关更多
开销的细节，请参见 CONFIG_KASAN_EXTRA_INFO 选项的帮助文本）。
以下为 CONFIG_KASAN_EXTRA_INFO 开启后的报告（仅显示不同部分）::
==================================================================
...
Allocated by task 134 on cpu 5 at 229.133855s:
...
Freed by task 136 on cpu 3 at 230.199335s:
...
==================================================================
实施细则
--------

2
Documentation/translations/zh_CN/dev-tools/testing-overview.rst
View File

@ -99,6 +99,8 @@ Documentation/dev-tools/kcov.rst 是能够构建在内核之中，用于在每
参阅 Documentation/dev-tools/kfence.rst
* lockdep是一个锁定正确性检测器。参阅
Documentation/locking/lockdep-design.rst
* 运行时确认（Runtime Verification）支持检查给定子系统的特定行为。参阅
Documentation/trace/rv/runtime-verification.rst。
* 除此以外，在内核中还有一些其它的调试工具，大多数能在
lib/Kconfig.debug 中找到。

2
Documentation/translations/zh_CN/driver-api/index.rst
View File

@ -23,6 +23,7 @@ Linux驱动实现者的API指南
gpio/index
io_ordering
phy/index
Todolist:
@ -103,7 +104,6 @@ Todolist:
* parport-lowlevel
* pps
* ptp
* phy/index
* pwm
* pldmfw/index
* rfkill

20
Documentation/translations/zh_CN/driver-api/phy/index.rst Normal file
View File

@ -0,0 +1,20 @@
.. SPDX-License-Identifier: GPL-2.0
============
PHY 通用框架
============
.. toctree::
phy
Todolist:
* samsung-usb2
.. only:: subproject and html
Indices
=======
* :ref:`genindex`

212
Documentation/translations/zh_CN/driver-api/phy/phy.rst Normal file
View File

@ -0,0 +1,212 @@
.. SPDX-License-Identifier: GPL-2.0
.. include:: ../../disclaimer-zh_CN.rst
:Original: Documentation/driver-api/phy/phy.rst
:翻译:
司延腾 Yanteng Si <siyanteng@loongson.cn>
=========
PHY子系统
=========
:作者: Kishon Vijay Abraham I <kishon@ti.com>
本文档解释了 PHY 的通用框架和提供的API，以及使用方法。
简介
====
*PHY* 是物理层的缩写，它被用来把设备连接到一个物理媒介，例如USB控制器
有一个提供序列化、反序列化、编码、解码和负责获取所需的数据传输速率的 PHY。
注意，有些USB控制器内嵌了 PHY 的功能，其它的则使用了一个外置的PHY，此外
使用 PHY 的设备还有无线网、以太网、SATA等（控制器）。
创建这个框架的目的是将遍布 Linux 内核的 PHY 驱动程序融入到 drivers/phy，
以增加代码的可复用性，进而提高代码的可维护性。
该框架仅适用于使用外部 PHY（PHY 功能未嵌入控制器内）的设备。
注册/注销PHY provider
=====================
PHY provider是指实现一个或多个 PHY 实例的实体。对于 PHY provider 仅
实现单个 PHY 实例的简单情况，框架在 of_phy_simple_xlate 中提供其自己
的 of_xlate 实现。如果 PHY provider 实现多个实例，则应提供其自己的
of_xlate 实现。of_xlate 仅用于 dt 启动情况。
::
#define of_phy_provider_register(dev, xlate) \
__of_phy_provider_register((dev), NULL, THIS_MODULE, (xlate))
#define devm_of_phy_provider_register(dev, xlate) \
__devm_of_phy_provider_register((dev), NULL, THIS_MODULE,
(xlate))
of_phy_provider_register 和 devm_of_phy_provider_register 宏
可用于注册 phy_provider，它以 device 和 of_xlate 作为参数。对于 dt
启动情况，所有 PHY provider 都应使用上述两个宏之一来注册 PHY provider。
与 PHY provider 关联的设备树节点通常包含一组子节点，每个子节点代表一个
PHY。某些绑定可能会为了上下文和可扩展性将子节点嵌套在特别的层级中，在这种
情况下，可以使用低级别的 of_phy_provider_register_full() 和
devm_of_phy_provider_register_full() 宏来覆盖包含子节点的节点。
::
#define of_phy_provider_register_full(dev, children, xlate) \
__of_phy_provider_register(dev, children, THIS_MODULE, xlate)
#define devm_of_phy_provider_register_full(dev, children, xlate) \
__devm_of_phy_provider_register_full(dev, children,
THIS_MODULE, xlate)
void devm_of_phy_provider_unregister(struct device *dev,
struct phy_provider *phy_provider);
void of_phy_provider_unregister(struct phy_provider *phy_provider);
devm_of_phy_provider_unregister 和 of_phy_provider_unregister
可以被用来注销PHY.
创建PHY
=======
PHY 驱动程序应创建 PHY，以便其他外围（芯片）控制器能够使用它。PHY 框架
提供了 2 个 API 来创建 PHY。
::
struct phy *phy_create(struct device *dev, struct device_node *node,
const struct phy_ops *ops);
struct phy *devm_phy_create(struct device *dev,
struct device_node *node,
const struct phy_ops *ops);
PHY 驱动程序可以使用上述两个 API 之一，通过传递设备指针和 phy_ops
来创建 PHY。
phy_ops 是一组用于执行 PHY 操作（例如 init、exit、power_on 和
power_off）的函数指针。
在 phy_ops 中，PHY provider驱动程序在创建 PHY 后使用 phy_set_drvdata()
设置私有数据，使用 phy_get_drvdata() 获取私有数据。
获取对 PHY 的引用
=================
控制器必须先获取对 PHY 的引用，然后才能使用 PHY。此框架提供以下 API
来获取对 PHY 的引用。
::
struct phy *phy_get(struct device *dev, const char *string);
struct phy *devm_phy_get(struct device *dev, const char *string);
struct phy *devm_phy_optional_get(struct device *dev,
const char *string);
struct phy *devm_of_phy_get(struct device *dev, struct device_node *np,
const char *con_id);
struct phy *devm_of_phy_optional_get(struct device *dev,
struct device_node *np,
const char *con_id);
struct phy *devm_of_phy_get_by_index(struct device *dev,
struct device_node *np,
int index);
phy_get、devm_phy_get 和 devm_phy_optional_get 可用于在 dt
启动的情况下获取 PHY，字符串参数应包含 dt 数据中给出的 phy 名称，在
非 dt 启动的情况下，它应包含 PHY 的标签。两个 devm_phy_get 在成功
获取 PHY 后使用 devres 将设备与 PHY 关联。在驱动程序分离时，将在
devres 数据上调用 release 函数并释放 devres 数据。当 phy 是可选
的时，应使用 _optional_get 变体。这些函数永远不会返回 -ENODEV，而
是在找不到 phy 时返回 NULL。一些通用驱动程序（例如 ehci）可能使用
多个 phy。在这种情况下，devm_of_phy_get 或 devm_of_phy_get_by_index
用于根据名称或索引获取 phy 引用。
需要注意的是，NULL 是有效的 phy 引用。NULL phy 上的所有 phy 使用
者调用都将成为 NOP。也就是说释放调用，当应用于 NULL phy 时，release
调用、phy_init()/phy_exit() 调用、phy_power_on()/phy_power_off()
调用都是 NOP。NULL phy 在处理可选的 phy 设备中很有用。
API的调用顺序
=============
通常，调用顺序应该是::
[devm_][of_]phy_get()
phy_init()
phy_power_on()
[phy_set_mode[_ext]()]
...
phy_power_off()
phy_exit()
[[of_]phy_put()]
一些PHY驱动可能没有实现 :c:func:`phy_init` 或 :c:func:`phy_power_on`,
但是控制器应该总是调用这些函数以兼容其它PHY，有些PHY可能要求
:c:func:`phy_set_mode <phy_set_mode_ext>` 而其他 PHY 可能使用
默认模式（通常通过设备树或其他固件配置）。出于兼容性考虑，如果您知道将
使用哪种模式，则应始终调用此函数。通常，应在 :c:func:`phy_power_on`
之后调用此函数，尽管某些 PHY 驱动程序可能随时允许调用它。
释放对 PHY 的引用
=================
当控制器不再需要 PHY 时，它必须使用上一节中提到的 API 释放对已获得
的 PHY 的引用。PHY 框架提供了 2 个 API 来释放对 PHY 的引用。
::
void phy_put(struct phy *phy);
void devm_phy_put(struct device *dev, struct phy *phy);
这两个 API 都用于释放对 PHY 的引用，并且 devm_phy_put 会销毁与此
PHY 关联的设备资源。
销毁 PHY
========
当创建 PHY 的驱动程序被卸载时，它应该使用以下 2 个 API 之一销毁其创
建的 PHY::
void phy_destroy(struct phy *phy);
void devm_phy_destroy(struct device *dev, struct phy *phy);
这两个 API 都会销毁 PHY，并且 devm_phy_destroy 会销毁与此 PHY 关
联的 devres。
PM Runtime
==========
这个子系统启用了pm runtime。 所以，在创建PHY 时，将调用此子系统创建的
phy 设备的 pm_runtime_enable 函数，在销毁 PHY 时，将调用
pm_runtime_disable。请注意，此子系统创建的 phy 设备将是调用 phy_create
（PHY provider 设备）的设备的子设备。
因此，由于父子关系，此子系统创建的 phy_device 的 pm_runtime_get_sync
调用 PHY provider 设备的 pm_runtime_get_sync。还应注意，
phy_power_on 和 phy_power_off 分别执行 phy_pm_runtime_get_sync 和
phy_pm_runtime_put。有导出的 API，如 phy_pm_runtime_get、
phy_pm_runtime_get_sync、phy_pm_runtime_put、phy_pm_runtime_put_sync、
phy_pm_runtime_allow 和 phy_pm_runtime_forbid，用于执行 PM 操作。
PHY映射
=======
为了在没有 DeviceTree 帮助的情况下获取对 PHY 的引用，框架提供了可与
clkdev 进行比较的查找，允许将 clk 结构体绑定到设备。当 struct phy 的
句柄已存在时，可以在运行时进行查找。
该框架提供以下 API 用于注册和注销查找::
int phy_create_lookup(struct phy *phy, const char *con_id,
const char *dev_id);
void phy_remove_lookup(struct phy *phy, const char *con_id,
const char *dev_id);
DeviceTree绑定
==============
PHY dt 绑定的文档可以在以下位置找到 @
Documentation/devicetree/bindings/phy/phy-bindings.txt

2
Documentation/translations/zh_CN/process/4.Coding.rst
View File

@ -54,7 +54,7 @@
注意您还可以使用 ``clang-format`` 工具来帮助您处理这些规则，快速自动重新格式
化部分代码，和审阅完整的文件以发现代码样式错误、拼写错误和可能的改进。它还
可以方便地排序 ``#includes`` 、对齐变量/宏、重排文本和其他类似任务。有关详细
信息，请参阅文档 :ref:`Documentation/process/clang-format.rst <clangformat>`
信息，请参阅文档 :ref:`Documentation/dev-tools/clang-format.rst <clangformat>`
抽象层
******

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

@ -654,7 +654,7 @@ Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。
请注意，您还可以使用 ``clang-format`` 工具帮助您处理这些规则，快速自动重新格
式化部分代码，并审阅整个文件以发现代码风格错误、打字错误和可能的改进。它还可
以方便地排序 ``#include`` ，对齐变量/宏，重排文本和其他类似任务。
详见 Documentation/process/clang-format.rst 。
详见 Documentation/dev-tools/clang-format.rst 。
10) Kconfig 配置文件

2
Documentation/translations/zh_CN/process/index.rst
View File

@ -64,6 +64,7 @@ TODOLIST:
management-style
stable-kernel-rules
submit-checklist
researcher-guidelines
TODOLIST:
@ -71,7 +72,6 @@ TODOLIST:
* kernel-docs
* deprecated
* maintainers
* researcher-guidelines
* contribution-maturity-model

2
Documentation/translations/zh_CN/process/magic-number.rst
View File

@ -1,6 +1,6 @@
.. include:: ../disclaimer-zh_CN.rst
:Original: Documentation/process/magic-number.rst
:Original: Documentation/staging/magic-number.rst
:翻译:

129
Documentation/translations/zh_CN/process/researcher-guidelines.rst Normal file
View File

@ -0,0 +1,129 @@
.. SPDX-License-Identifier: GPL-2.0-or-later
.. include:: ../disclaimer-zh_CN.rst
.. _cn_researcherguidelines:
:Original: Documentation/process/researcher-guidelines.rst
:译者:
- 慕冬亮 Dongliang Mu <dzm91@hust.edu.cn>
研究人员指南
+++++++++++++++++++++
Linux 内核社区欢迎对 Linux 内核及其开发过程中涉及的活动与任何其他副产品
进行透明的研究。Linux 从这种研究中受益匪浅，其多方面均由某种形式的研究所推动。
社区非常感谢研究人员在公开研究结果之前能分享初步发现，特别是涉及安全的研究。
早期参与有助于提高研究质量并使 Linux 受益。无论如何，推荐研究人员与社区分享
已发表研究的开放访问副本。
本文旨在澄清研究开展过程中 Linux 内核社区认可与不认可的一些做法。至少，这类
研究及相关活动应遵循标准的研究伦理规则。有关研究伦理、技术伦理以及开发者社区
研究的更多背景信息，请查阅：
* `研究伦理史 <https://www.unlv.edu/research/ORI-HSR/history-ethics>`_
* `IEEE 伦理 <https://www.ieee.org/about/ethics/index.html>`_
* `开发者和研究人员对开源项目实验伦理的看法 <https://arxiv.org/pdf/2112.13217.pdf>`_
Linux 内核社区期望与项目互动的每个人都是真诚地为了使 Linux 变得更好。
对 Linux 内核社区产生的任何公开可用的成果（包括但不限于源代码）的研究
是受欢迎的，对开发者的研究如若要开展，则必须要明确说明，获得（开发者）同意。
完全基于公开可用资源（包括公共邮件列表的帖子和公开代码库的提交）的被动研究
显然是允许的。不过，和任何研究一样，仍需遵循标准伦理。
然而，针对开发者行为的主动研究必须在获得相关开发者的明确同意和完全披露的情况下进行。
未经同意，不得与开发者互动或对其进行实验；这也是标准的研究伦理。
调查
=======
研究通常采用调查问卷的形式发送给维护者或贡献者。然而，内核社区通常从这些调查问卷中获益
甚少。内核开发过程之所以有效，是因为每个开发者都从中受益，即使与目标不同的人一起工作。
而回应调查则是对繁忙开发者的单向需求，对他们自己或整个内核社区没有相应的好处。因此，
这种研究方法不被鼓励。
内核社区成员已经收到过多的电子邮件，可能会将调查请求视为对他们时间的又一要求。发送
此类请求会剥夺社区宝贵的贡献者时间，且不太可能产生有统计意义的回应。
作为替代，研究人员应考虑参加开发者活动，举办研讨会来介绍研究项目及其对参与者的益处，
并直接与社区互动。该方式获得的信息将比电子邮件调查问卷丰富得多，且社区也能从中学习
到您的见解。
补丁
=======
澄清：向开发者发送补丁**是**与他们互动，但他们已经同意接收**善意贡献**。故意发送有缺陷/
有漏洞的补丁或在讨论中提供误导信息是不被同意的。这种交流会对开发者造成损害
（例如，消耗时间、精力和士气），并通过破坏整个开发者社区对贡献者（及其所在组织）
的信任而损害项目，削弱为贡献者提供建设性反馈的努力，并使最终用户面临软件缺陷的风险。
研究人员参与 Linux 本身的开发与其他人一样受到欢迎和鼓励。研究 Linux 代码是常见
做法，尤其是在开发或运行可产生可操作结果的分析工具时。
在与开发者社区互动时，发送补丁历来是产生影响的最佳方式。Linux 已经有很多已知的
漏洞 -- 更有帮助的是经过审核的修复。在贡献之前，请仔细阅读相关文档：
* Documentation/process/development-process.rst
* Documentation/process/submitting-patches.rst
* Documentation/admin-guide/reporting-issues.rst
* Documentation/process/security-bugs.rst
然后发送补丁（包括所有如下详细信息的提交日志）并跟进其他开发者的任何反馈。
当发送因研究而产生的补丁时，提交日志应至少包含以下详细信息，以便开发者有适当的上下文
来理解贡献。回答：
* 找到了什么具体问题？
* 在运行系统上如何触发这个问题？
* 遇到这个问题对系统会有什么影响？
* 如何发现这个问题？具体包括任何测试、静态或动态分析程序及其他用于执行工作的工具或方法的详细信息。
* 在哪个版本的 Linux 上发现了这个问题？强烈推荐使用最新的发布版本或最近的 linux-next 分支（参见 Documentation/process/howto.rst）。
* 进行了哪些更改来修复这个问题，为什么认为这些更改是正确的？
* 如何进行构建测试和运行时测试？
* 此更改修复了哪个先前的提交？这应该在 "Fixes:" 标签中，如文档所述。
* 还有谁审查了这个补丁？这应该在适当的 "Reviewed-by:" 标签中注明；见下文。
例如::
From: Author <author@email>
Subject: [PATCH] drivers/foo_bar: Add missing kfree()
The error path in foo_bar driver does not correctly free the allocated
struct foo_bar_info. This can happen if the attached foo_bar device
rejects the initialization packets sent during foo_bar_probe(). This
would result in a 64 byte slab memory leak once per device attach,
wasting memory resources over time.
This flaw was found using an experimental static analysis tool we are
developing, LeakMagic[1], which reported the following warning when
analyzing the v5.15 kernel release:
path/to/foo_bar.c:187: missing kfree() call?
Add the missing kfree() to the error path. No other references to
this memory exist outside the probe function, so this is the only
place it can be freed.
x86_64 and arm64 defconfig builds with CONFIG_FOO_BAR=y using GCC
11.2 show no new warnings, and LeakMagic no longer warns about this
code path. As we don't have a FooBar device to test with, no runtime
testing was able to be performed.
[1] https://url/to/leakmagic/details
Reported-by: Researcher <researcher@email>
Fixes: aaaabbbbccccdddd ("Introduce support for FooBar")
Signed-off-by: Author <author@email>
Reviewed-by: Reviewer <reviewer@email>
如果您是第一次参与贡献，建议在补丁在发布到公共列表前请其他人私下进行审核。（如果明确
告诉您补丁需要更仔细的内部审查，则这是必需的。）这些人预计会在最终的补丁中包含他们的
"Reviewed-by" 标签。找到熟悉 Linux 贡献的其他开发者，特别是您自己组织内的开发者，
并在将补丁发送到公共邮件列表前请他们帮助审核，往往会显著提高补丁的质量，从而减少
其他开发者的负担。
如果你找不到人内部审核补丁且需要帮助找到这样的人，或者如果您对本文档和开发者社区的期望
有任何其他问题，请联系技术咨询委员会私有邮件列表：<tech-board@groups.linuxfoundation.org>。

2
Documentation/translations/zh_CN/virt/guest-halt-polling.rst
View File

@ -76,7 +76,7 @@ guest_halt_poll_ns将保持高位）。
默认值: Y
模块参数可以从Debugfs文件中设置，在::
模块参数可以从sysfs文件中设置，在::
/sys/module/haltpoll/parameters/

2
Documentation/translations/zh_TW/process/4.Coding.rst
View File

@ -57,7 +57,7 @@
注意您還可以使用 ``clang-format`` 工具來幫助您處理這些規則，快速自動重新格式
化部分代碼，和審閱完整的文件以發現代碼樣式錯誤、拼寫錯誤和可能的改進。它還
可以方便地排序 ``#includes`` 、對齊變量/宏、重排文本和其他類似任務。有關詳細
信息，請參閱文檔 :ref:`Documentation/process/clang-format.rst <clangformat>`
信息，請參閱文檔 :ref:`Documentation/dev-tools/clang-format.rst <clangformat>`
抽象層
******

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

@ -657,7 +657,7 @@ Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。
請注意，您還可以使用 ``clang-format`` 工具幫助您處理這些規則，快速自動重新格
式化部分代碼，並審閱整個文件以發現代碼風格錯誤、打字錯誤和可能的改進。它還可
以方便地排序 ``#include`` ，對齊變量/宏，重排文本和其他類似任務。
詳見 Documentation/process/clang-format.rst 。
詳見 Documentation/dev-tools/clang-format.rst 。
10) Kconfig 配置文件

2
Documentation/translations/zh_TW/process/magic-number.rst
View File

@ -4,7 +4,7 @@
.. include:: ../disclaimer-zh_TW.rst
:Original: :ref:`Documentation/process/magic-number.rst <magicnumbers>`
:Original: :ref:`Documentation/staging/magic-number.rst <magicnumbers>`
如果想評論或更新本文的內容，請直接發信到LKML。如果你使用英文交流有困難的話，也可
以向中文版維護者求助。如果本翻譯更新不及時或者翻譯存在問題，請聯繫中文版維護者::

2
Documentation/userspace-api/ioctl/ioctl-number.rst
View File

@ -97,6 +97,8 @@ Code Seq# Include File Comments
'%' 00-0F include/uapi/linux/stm.h System Trace Module subsystem
<mailto:alexander.shishkin@linux.intel.com>
'&' 00-07 drivers/firewire/nosy-user.h
'*' 00-1F uapi/linux/user_events.h User Events Subsystem
<mailto:linux-trace-kernel@vger.kernel.org>
'1' 00-1F linux/timepps.h PPS kit from Ulrich Windl
<ftp://ftp.de.kernel.org/pub/linux/daemons/ntp/PPS/>
'2' 01-04 linux/i2o.h

203
scripts/checktransupdate.py Executable file
View File

@ -0,0 +1,203 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: GPL-2.0
"""
This script helps track the translation status of the documentation
in different locales, e.g., zh_CN. More specially, it uses `git log`
commit to find the latest english commit from the translation commit
(order by author date) and the latest english commits from HEAD. If
differences occur, report the file and commits that need to be updated.
The usage is as follows:
- ./scripts/checktransupdate.py -l zh_CN
This will print all the files that need to be updated in the zh_CN locale.
- ./scripts/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst
This will only print the status of the specified file.
The output is something like:
Documentation/translations/zh_CN/dev-tools/testing-overview.rst (1 commits)
commit 42fb9cfd5b18 ("Documentation: dev-tools: Add link to RV docs")
"""
import os
from argparse import ArgumentParser, BooleanOptionalAction
from datetime import datetime
flag_p_c = False
flag_p_uf = False
flag_debug = False
def dprint(*args, **kwargs):
if flag_debug:
print("[DEBUG] ", end="")
print(*args, **kwargs)
def get_origin_path(file_path):
paths = file_path.split("/")
tidx = paths.index("translations")
opaths = paths[:tidx]
opaths += paths[tidx + 2 :]
return "/".join(opaths)
def get_latest_commit_from(file_path, commit):
command = "git log --pretty=format:%H%n%aD%n%cD%n%n%B {} -1 -- {}".format(
commit, file_path
)
dprint(command)
pipe = os.popen(command)
result = pipe.read()
result = result.split("\n")
if len(result) <= 1:
return None
dprint("Result: {}".format(result[0]))
return {
"hash": result[0],
"author_date": datetime.strptime(result[1], "%a, %d %b %Y %H:%M:%S %z"),
"commit_date": datetime.strptime(result[2], "%a, %d %b %Y %H:%M:%S %z"),
"message": result[4:],
}
def get_origin_from_trans(origin_path, t_from_head):
o_from_t = get_latest_commit_from(origin_path, t_from_head["hash"])
while o_from_t is not None and o_from_t["author_date"] > t_from_head["author_date"]:
o_from_t = get_latest_commit_from(origin_path, o_from_t["hash"] + "^")
if o_from_t is not None:
dprint("tracked origin commit id: {}".format(o_from_t["hash"]))
return o_from_t
def get_commits_count_between(opath, commit1, commit2):
command = "git log --pretty=format:%H {}...{} -- {}".format(commit1, commit2, opath)
dprint(command)
pipe = os.popen(command)
result = pipe.read().split("\n")
# filter out empty lines
result = list(filter(lambda x: x != "", result))
return result
def pretty_output(commit):
command = "git log --pretty='format:%h (\"%s\")' -1 {}".format(commit)
dprint(command)
pipe = os.popen(command)
return pipe.read()
def check_per_file(file_path):
opath = get_origin_path(file_path)
if not os.path.isfile(opath):
dprint("Error: Cannot find the origin path for {}".format(file_path))
return
o_from_head = get_latest_commit_from(opath, "HEAD")
t_from_head = get_latest_commit_from(file_path, "HEAD")
if o_from_head is None or t_from_head is None:
print("Error: Cannot find the latest commit for {}".format(file_path))
return
o_from_t = get_origin_from_trans(opath, t_from_head)
if o_from_t is None:
print("Error: Cannot find the latest origin commit for {}".format(file_path))
return
if o_from_head["hash"] == o_from_t["hash"]:
if flag_p_uf:
print("No update needed for {}".format(file_path))
return
else:
print("{}".format(file_path), end="\t")
commits = get_commits_count_between(
opath, o_from_t["hash"], o_from_head["hash"]
)
print("({} commits)".format(len(commits)))
if flag_p_c:
for commit in commits:
msg = pretty_output(commit)
if "Merge tag" not in msg:
print("commit", msg)
def main():
script_path = os.path.dirname(os.path.abspath(__file__))
linux_path = os.path.join(script_path, "..")
parser = ArgumentParser(description="Check the translation update")
parser.add_argument(
"-l",
"--locale",
help="Locale to check when files are not specified",
)
parser.add_argument(
"--print-commits",
action=BooleanOptionalAction,
default=True,
help="Print commits between the origin and the translation",
)
parser.add_argument(
"--print-updated-files",
action=BooleanOptionalAction,
default=False,
help="Print files that do no need to be updated",
)
parser.add_argument(
"--debug",
action=BooleanOptionalAction,
help="Print debug information",
default=False,
)
parser.add_argument(
"files", nargs="*", help="Files to check, if not specified, check all files"
)
args = parser.parse_args()
global flag_p_c, flag_p_uf, flag_debug
flag_p_c = args.print_commits
flag_p_uf = args.print_updated_files
flag_debug = args.debug
# get files related to linux path
files = args.files
if len(files) == 0:
if args.locale is not None:
files = (
os.popen(
"find {}/Documentation/translations/{} -type f".format(
linux_path, args.locale
)
)
.read()
.split("\n")
)
else:
files = (
os.popen(
"find {}/Documentation/translations -type f".format(linux_path)
)
.read()
.split("\n")
)
files = list(filter(lambda x: x != "", files))
files = list(map(lambda x: os.path.relpath(os.path.abspath(x), linux_path), files))
# cd to linux root directory
os.chdir(linux_path)
for file in files:
check_per_file(file)
if __name__ == "__main__":
main()