Skip to content

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

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
  ...
parents 7dd894c1 702418f7
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 1976 additions and 419 deletions
.clang-format
View file @ cf05e93a
......@@ -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
#
......
Documentation/admin-guide/dynamic-debug-howto.rst
View file @ cf05e93a
......@@ -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
===============================
......
Documentation/admin-guide/kernel-parameters.rst
View file @ cf05e93a
......@@ -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.
......
Documentation/admin-guide/kernel-parameters.txt
View file @ cf05e93a
......@@ -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.
......
Documentation/admin-guide/mm/index.rst
View file @ cf05e93a
......@@ -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
......
Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
View file @ cf05e93a
......@@ -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')
========================================
......
Documentation/arch/x86/cpuinfo.rst
View file @ cf05e93a
......@@ -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.
------------------------------------------------
......
Documentation/arch/x86/exception-tables.rst
View file @ cf05e93a
......@@ -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
......
Documentation/core-api/genericirq.rst
View file @ cf05e93a
......@@ -210,7 +210,7 @@ implemented (simplified excerpt)::
}
}
noop(struct irq_data *data))
noop(struct irq_data *data)
{
}
......
Documentation/crypto/async-tx-api.rst
View file @ cf05e93a
......@@ -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();
......
Documentation/dev-tools/index.rst
View file @ cf05e93a
......@@ -16,6 +16,7 @@ Documentation/dev-tools/testing-overview.rst
testing-overview
checkpatch
clang-format
coccinelle
sparse
kcov
......
Documentation/doc-guide/kernel-doc.rst
View file @ cf05e93a
......@@ -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);
......
Documentation/driver-api/driver-model/platform.rst
View file @ cf05e93a
......@@ -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
......
Documentation/driver-api/input.rst
View file @ cf05e93a
......@@ -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:
Documentation/driver-api/pin-control.rst
View file @ cf05e93a
......@@ -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"),
};
......
Documentation/driver-api/usb/writing_musb_glue_layer.rst
View file @ cf05e93a
......@@ -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
Documentation/maintainer/feature-and-driver-maintainers.rst
View file @ cf05e93a
......@@ -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
========================
......
Documentation/maintainer/maintainer-entry-profile.rst
View file @ cf05e93a
......@@ -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
Documentation/mm/allocation-profiling.rst
View file @ cf05e93a
......@@ -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
===================
......
Documentation/mm/index.rst
View file @ cf05e93a
......@@ -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
......
Documentation/mm/vmalloced-kernel-stacks.rst
View file @ cf05e93a
......@@ -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>`.
......
Documentation/process/2.Process.rst
View file @ cf05e93a
......@@ -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
......
Documentation/process/4.Coding.rst
View file @ cf05e93a
......@@ -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
......
Documentation/process/changes.rst
View file @ cf05e93a
......@@ -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
......
Documentation/process/coding-style.rst
View file @ cf05e93a
......@@ -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
......
Documentation/process/email-clients.rst
View file @ cf05e93a
......@@ -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.
Documentation/process/handling-regressions.rst
View file @ cf05e93a
......@@ -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?
~~~~~~~~~~~~~~~~~~~~~~~~~
......
Documentation/process/howto.rst
View file @ cf05e93a
......@@ -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
......
Documentation/process/index.rst
View file @ cf05e93a
......@@ -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
......
Documentation/process/kernel-docs.rst
View file @ cf05e93a
......@@ -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:
......
Documentation/process/maintainer-netdev.rst
View file @ cf05e93a
......@@ -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
......
Documentation/process/maintainer-tip.rst
View file @ cf05e93a
......@@ -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.
......
Documentation/process/submitting-patches.rst
View file @ cf05e93a
......@@ -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:
......
Documentation/scheduler/sched-design-CFS.rst
View file @ cf05e93a
.. _sched_design_CFS:
=============
CFS Scheduler
=============
......
Documentation/staging/index.rst
View file @ cf05e93a
......@@ -8,6 +8,7 @@ Unsorted Documentation
crc32
lzo
magic-number
remoteproc
rpmsg
speculation
......
Documentation/tools/rv/rv-mon.rst
View file @ cf05e93a
.. SPDX-License-Identifier: GPL-2.0
=======
rv-list
=======
======
rv-mon
======
-----------------------
List available monitors
-----------------------
......
Documentation/translations/it_IT/riscv/patch-acceptance.rst → Documentation/translations/it_IT/arch/riscv/patch-acceptance.rst
View file @ cf05e93a
.. 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
-------------------------------------------------------------------------
......
Documentation/translations/it_IT/doc-guide/kernel-doc.rst
View file @ cf05e93a
......@@ -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
-----------------------
......
Documentation/translations/it_IT/doc-guide/parse-headers.rst
View file @ cf05e93a
......@@ -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
......
Documentation/translations/it_IT/process/5.Posting.rst
View file @ cf05e93a
......@@ -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
......
Documentation/translations/it_IT/process/6.Followthrough.rst
View file @ cf05e93a
......@@ -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
......
Documentation/translations/it_IT/process/7.AdvancedTopics.rst
View file @ cf05e93a
......@@ -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.
......
Documentation/translations/it_IT/process/changes.rst
View file @ cf05e93a
......@@ -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
......
Documentation/translations/it_IT/process/clang-format.rst
View file @ cf05e93a
.. 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:
......
Documentation/translations/it_IT/process/index.rst
View file @ cf05e93a
......@@ -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
......
Documentation/translations/it_IT/process/magic-number.rst
View file @ cf05e93a
.. 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:
......
Documentation/translations/it_IT/process/submitting-patches.rst
View file @ cf05e93a
......@@ -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
-----------
......
Documentation/translations/sp_SP/index.rst
View file @ cf05e93a
......@@ -78,3 +78,4 @@ Traducciones al español
process/index
wrappers/memory-barriers
scheduler/index
Documentation/translations/sp_SP/process/coding-style.rst
View file @ cf05e93a
......@@ -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
......
Documentation/translations/sp_SP/process/index.rst
View file @ cf05e93a
......@@ -29,3 +29,4 @@
submit-checklist
howto
development-process
maintainer-kvm-x86
Documentation/translations/sp_SP/process/magic-number.rst
View file @ cf05e93a
.. 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:
......
Documentation/translations/sp_SP/scheduler/index.rst 0 → 100644
View file @ cf05e93a
.. include:: ../disclaimer-sp.rst
.. _sp_scheduler_index:
.. toctree::
:maxdepth: 1
sched-design-CFS
Documentation/translations/zh_CN/admin-guide/index.rst
View file @ cf05e93a
......@@ -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
......
Documentation/translations/zh_CN/admin-guide/numastat.rst 0 → 100644
View file @ cf05e93a
.. 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统计数据。
Documentation/translations/zh_CN/dev-tools/gdb-kernel-debugging.rst
View file @ cf05e93a
......@@ -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”参数
......
Documentation/translations/zh_CN/dev-tools/index.rst
View file @ cf05e93a
......@@ -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
Documentation/translations/zh_CN/dev-tools/kasan.rst
View file @ cf05e93a
......@@ -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:
...
==================================================================
实施细则
--------
......
Documentation/translations/zh_CN/dev-tools/testing-overview.rst
View file @ cf05e93a
......@@ -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 中找到。
......
Documentation/translations/zh_CN/driver-api/index.rst
View file @ cf05e93a
......@@ -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
......
Documentation/translations/zh_CN/driver-api/phy/index.rst 0 → 100644
View file @ cf05e93a
.. SPDX-License-Identifier: GPL-2.0
============
PHY 通用框架
============
.. toctree::
phy
Todolist:
* samsung-usb2
.. only:: subproject and html
Indices
=======
* :ref:`genindex`
Documentation/translations/zh_CN/driver-api/phy/phy.rst 0 → 100644
View file @ cf05e93a
.. 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
Documentation/translations/zh_CN/process/4.Coding.rst
View file @ cf05e93a
......@@ -54,7 +54,7 @@
注意您还可以使用 ``clang-format`` 工具来帮助您处理这些规则，快速自动重新格式
化部分代码，和审阅完整的文件以发现代码样式错误、拼写错误和可能的改进。它还
可以方便地排序 ``#includes`` 、对齐变量/宏、重排文本和其他类似任务。有关详细
信息，请参阅文档 :ref:`Documentation/process/clang-format.rst <clangformat>`
信息，请参阅文档 :ref:`Documentation/dev-tools/clang-format.rst <clangformat>`
抽象层
******
......
Documentation/translations/zh_CN/process/coding-style.rst
View file @ cf05e93a
......@@ -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 配置文件
......
Documentation/translations/zh_CN/process/index.rst
View file @ cf05e93a
......@@ -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
......
Documentation/translations/zh_CN/process/magic-number.rst
View file @ cf05e93a
.. include:: ../disclaimer-zh_CN.rst
:Original: Documentation/process/magic-number.rst
:Original: Documentation/staging/magic-number.rst
:翻译:
......
Documentation/translations/zh_CN/process/researcher-guidelines.rst 0 → 100644
View file @ cf05e93a
.. 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>。
Documentation/translations/zh_CN/virt/guest-halt-polling.rst
View file @ cf05e93a
......@@ -76,7 +76,7 @@ guest_halt_poll_ns将保持高位）。
默认值: Y
模块参数可以从Debugfs文件中设置，在::
模块参数可以从sysfs文件中设置，在::
/sys/module/haltpoll/parameters/
......
Documentation/translations/zh_TW/process/4.Coding.rst
View file @ cf05e93a
......@@ -57,7 +57,7 @@
注意您還可以使用 ``clang-format`` 工具來幫助您處理這些規則，快速自動重新格式
化部分代碼，和審閱完整的文件以發現代碼樣式錯誤、拼寫錯誤和可能的改進。它還
可以方便地排序 ``#includes`` 、對齊變量/宏、重排文本和其他類似任務。有關詳細
信息，請參閱文檔 :ref:`Documentation/process/clang-format.rst <clangformat>`
信息，請參閱文檔 :ref:`Documentation/dev-tools/clang-format.rst <clangformat>`
抽象層
******
......
Documentation/translations/zh_TW/process/coding-style.rst
View file @ cf05e93a
......@@ -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 配置文件
......
Documentation/translations/zh_TW/process/magic-number.rst
View file @ cf05e93a
......@@ -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。如果你使用英文交流有困難的話，也可
以向中文版維護者求助。如果本翻譯更新不及時或者翻譯存在問題，請聯繫中文版維護者::
......
Documentation/userspace-api/ioctl/ioctl-number.rst
View file @ cf05e93a
......@@ -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
......
scripts/checktransupdate.py 0 → 100755
View file @ cf05e93a
#!/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()
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7