diff options
| author | Linus Torvalds <torvalds@linux-foundation.org> | 2024-07-18 15:54:16 -0700 |
|---|---|---|
| committer | Linus Torvalds <torvalds@linux-foundation.org> | 2024-07-18 15:54:16 -0700 |
| commit | cf05e93af423b225fb3e3237e7d46493c7909f2b (patch) | |
| tree | 8eadf02e46fb36faf6d5a3467b35bdf4d15e75ff | |
| parent | 7dd894c1bf65a9591ba27f6175cf3238748deb47 (diff) | |
| parent | 702418f7559fb1828646f0b51d9ca7c8b9ee7bff (diff) | |
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
...
77 files changed, 1976 insertions, 419 deletions
diff --git a/.clang-format b/.clang-format index ccc9b93972a9..252820d9c80a 100644 --- a/.clang-format +++ b/.clang-format @@ -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 # diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst index 0e9b48daf690..7c036590cd07 100644 --- a/Documentation/admin-guide/dynamic-debug-howto.rst +++ b/Documentation/admin-guide/dynamic-debug-howto.rst @@ -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 =============================== diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst index e8bdf5e86a9b..fdea7c26ef80 100644 --- a/Documentation/admin-guide/kernel-parameters.rst +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -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. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 0ca8452ea1ad..2deccf57ecee 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -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. diff --git a/Documentation/admin-guide/mm/index.rst b/Documentation/admin-guide/mm/index.rst index 1f883abf3f00..8b35795b664b 100644 --- a/Documentation/admin-guide/mm/index.rst +++ b/Documentation/admin-guide/mm/index.rst @@ -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 diff --git a/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst b/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst index c389d4fd7599..6281eae9e6bc 100644 --- a/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst +++ b/Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst @@ -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') ======================================== diff --git a/Documentation/arch/x86/cpuinfo.rst b/Documentation/arch/x86/cpuinfo.rst index 8895784d4784..6ef426a52cdc 100644 --- a/Documentation/arch/x86/cpuinfo.rst +++ b/Documentation/arch/x86/cpuinfo.rst @@ -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. ------------------------------------------------ diff --git a/Documentation/arch/x86/exception-tables.rst b/Documentation/arch/x86/exception-tables.rst index efde1fef4fbd..6e7177363f8f 100644 --- a/Documentation/arch/x86/exception-tables.rst +++ b/Documentation/arch/x86/exception-tables.rst @@ -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 diff --git a/Documentation/core-api/genericirq.rst b/Documentation/core-api/genericirq.rst index 4a460639ab1c..582bde9bf5a9 100644 --- a/Documentation/core-api/genericirq.rst +++ b/Documentation/core-api/genericirq.rst @@ -210,7 +210,7 @@ implemented (simplified excerpt):: } } - noop(struct irq_data *data)) + noop(struct irq_data *data) { } diff --git a/Documentation/crypto/async-tx-api.rst b/Documentation/crypto/async-tx-api.rst index 27c146b54d71..f88a7809385e 100644 --- a/Documentation/crypto/async-tx-api.rst +++ b/Documentation/crypto/async-tx-api.rst @@ -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(); diff --git a/Documentation/process/clang-format.rst b/Documentation/dev-tools/clang-format.rst index 1d089a847c1b..1d089a847c1b 100644 --- a/Documentation/process/clang-format.rst +++ b/Documentation/dev-tools/clang-format.rst diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst index 6971ed581c08..53d4d124f9c5 100644 --- a/Documentation/dev-tools/index.rst +++ b/Documentation/dev-tools/index.rst @@ -16,6 +16,7 @@ Documentation/dev-tools/testing-overview.rst testing-overview checkpatch + clang-format coccinelle sparse kcov diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index d6f7efefea42..e6ffd59bb8f0 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -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); diff --git a/Documentation/driver-api/driver-model/platform.rst b/Documentation/driver-api/driver-model/platform.rst index 1fe5c6c6199c..7beb8a9648c5 100644 --- a/Documentation/driver-api/driver-model/platform.rst +++ b/Documentation/driver-api/driver-model/platform.rst @@ -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 diff --git a/Documentation/driver-api/input.rst b/Documentation/driver-api/input.rst index 4bbb26ae2a89..bd7a3578ade7 100644 --- a/Documentation/driver-api/input.rst +++ b/Documentation/driver-api/input.rst @@ -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: diff --git a/Documentation/driver-api/pin-control.rst b/Documentation/driver-api/pin-control.rst index 4639912dc9cc..27ea1236307e 100644 --- a/Documentation/driver-api/pin-control.rst +++ b/Documentation/driver-api/pin-control.rst @@ -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"), }; diff --git a/Documentation/driver-api/usb/writing_musb_glue_layer.rst b/Documentation/driver-api/usb/writing_musb_glue_layer.rst index 10416cc11cd5..e755c8551bba 100644 --- a/Documentation/driver-api/usb/writing_musb_glue_layer.rst +++ b/Documentation/driver-api/usb/writing_musb_glue_layer.rst @@ -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 diff --git a/Documentation/maintainer/feature-and-driver-maintainers.rst b/Documentation/maintainer/feature-and-driver-maintainers.rst index f04cc183e1de..fb94a9b29061 100644 --- a/Documentation/maintainer/feature-and-driver-maintainers.rst +++ b/Documentation/maintainer/feature-and-driver-maintainers.rst @@ -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 ======================== diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst index b49fb6dc4d0c..cda5d691e967 100644 --- a/Documentation/maintainer/maintainer-entry-profile.rst +++ b/Documentation/maintainer/maintainer-entry-profile.rst @@ -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 diff --git a/Documentation/mm/allocation-profiling.rst b/Documentation/mm/allocation-profiling.rst index d3b733b41ae6..ffd6655b7be2 100644 --- a/Documentation/mm/allocation-profiling.rst +++ b/Documentation/mm/allocation-profiling.rst @@ -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 =================== diff --git a/Documentation/mm/index.rst b/Documentation/mm/index.rst index 48b9b559ca7b..0be1c7503a01 100644 --- a/Documentation/mm/index.rst +++ b/Documentation/mm/index.rst @@ -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 diff --git a/Documentation/mm/vmalloced-kernel-stacks.rst b/Documentation/mm/vmalloced-kernel-stacks.rst index fc8c67833af6..4edca515bfd7 100644 --- a/Documentation/mm/vmalloced-kernel-stacks.rst +++ b/Documentation/mm/vmalloced-kernel-stacks.rst @@ -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>`. diff --git a/Documentation/process/2.Process.rst b/Documentation/process/2.Process.rst index 613a01da4717..ef3b116492df 100644 --- a/Documentation/process/2.Process.rst +++ b/Documentation/process/2.Process.rst @@ -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 diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst index c2046dec0c2f..80bcc1cabc23 100644 --- a/Documentation/process/4.Coding.rst +++ b/Documentation/process/4.Coding.rst @@ -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 diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 5685d7bfe4d0..8d225a9f65a2 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -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 diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 7e768c65aa92..04f6aa377a5d 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -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 diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst index 471e1f93fa09..dd22c46d1d02 100644 --- a/Documentation/process/email-clients.rst +++ b/Documentation/process/email-clients.rst @@ -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. diff --git a/Documentation/process/handling-regressions.rst b/Documentation/process/handling-regressions.rst index 49ba1410cfce..1f5ab49c48a4 100644 --- a/Documentation/process/handling-regressions.rst +++ b/Documentation/process/handling-regressions.rst @@ -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? ~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index eebda4910a88..9438e03d6f50 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -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 diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index de9cbb7bd7eb..6455eba3ef0c 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -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 diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst index 8660493b91d0..55552ec4b043 100644 --- a/Documentation/process/kernel-docs.rst +++ b/Documentation/process/kernel-docs.rst @@ -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: diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst index 5e1fcfad1c4c..fe8616397d63 100644 --- a/Documentation/process/maintainer-netdev.rst +++ b/Documentation/process/maintainer-netdev.rst @@ -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 diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst index 64739968afa6..ba312345d030 100644 --- a/Documentation/process/maintainer-tip.rst +++ b/Documentation/process/maintainer-tip.rst @@ -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. diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 66029999b587..f310f2f36666 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -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: diff --git a/Documentation/scheduler/sched-design-CFS.rst b/Documentation/scheduler/sched-design-CFS.rst index e030876fbd68..bc1e507269c6 100644 --- a/Documentation/scheduler/sched-design-CFS.rst +++ b/Documentation/scheduler/sched-design-CFS.rst @@ -1,3 +1,5 @@ +.. _sched_design_CFS: + ============= CFS Scheduler ============= diff --git a/Documentation/staging/index.rst b/Documentation/staging/index.rst index 71592f3ce89b..77bae5e5328b 100644 --- a/Documentation/staging/index.rst +++ b/Documentation/staging/index.rst @@ -8,6 +8,7 @@ Unsorted Documentation crc32 lzo + magic-number remoteproc rpmsg speculation diff --git a/Documentation/process/magic-number.rst b/Documentation/staging/magic-number.rst index 7029c3c084ee..7029c3c084ee 100644 --- a/Documentation/process/magic-number.rst +++ b/Documentation/staging/magic-number.rst diff --git a/Documentation/tools/rv/rv-mon.rst b/Documentation/tools/rv/rv-mon.rst index af0f329a7c9c..4d86fd55eb59 100644 --- a/Documentation/tools/rv/rv-mon.rst +++ b/Documentation/tools/rv/rv-mon.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0 -======= -rv-list -======= +====== +rv-mon +====== ----------------------- List available monitors ----------------------- diff --git a/Documentation/translations/it_IT/riscv/patch-acceptance.rst b/Documentation/translations/it_IT/arch/riscv/patch-acceptance.rst index 2d7afb1f6959..e0ad63643f1b 100644 --- a/Documentation/translations/it_IT/riscv/patch-acceptance.rst +++ b/Documentation/translations/it_IT/arch/riscv/patch-acceptance.rst @@ -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 ------------------------------------------------------------------------- diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst index 74057d203539..aa0e31d353d6 100644 --- a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst +++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst @@ -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 ----------------------- diff --git a/Documentation/translations/it_IT/doc-guide/parse-headers.rst b/Documentation/translations/it_IT/doc-guide/parse-headers.rst index c7076a21667a..026a23e49767 100644 --- a/Documentation/translations/it_IT/doc-guide/parse-headers.rst +++ b/Documentation/translations/it_IT/doc-guide/parse-headers.rst @@ -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 diff --git a/Documentation/translations/it_IT/process/5.Posting.rst b/Documentation/translations/it_IT/process/5.Posting.rst index a7e2a3238415..a61d9e6f7433 100644 --- a/Documentation/translations/it_IT/process/5.Posting.rst +++ b/Documentation/translations/it_IT/process/5.Posting.rst @@ -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 diff --git a/Documentation/translations/it_IT/process/6.Followthrough.rst b/Documentation/translations/it_IT/process/6.Followthrough.rst index df7d5fb28832..685eee5690f3 100644 --- a/Documentation/translations/it_IT/process/6.Followthrough.rst +++ b/Documentation/translations/it_IT/process/6.Followthrough.rst @@ -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 diff --git a/Documentation/translations/it_IT/process/7.AdvancedTopics.rst b/Documentation/translations/it_IT/process/7.AdvancedTopics.rst index a83fcfe18024..b3d8b62f3b57 100644 --- a/Documentation/translations/it_IT/process/7.AdvancedTopics.rst +++ b/Documentation/translations/it_IT/process/7.AdvancedTopics.rst @@ -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. diff --git a/Documentation/translations/it_IT/process/changes.rst b/Documentation/translations/it_IT/process/changes.rst index ade695a7de19..0bcf8423cc80 100644 --- a/Documentation/translations/it_IT/process/changes.rst +++ b/Documentation/translations/it_IT/process/changes.rst @@ -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 diff --git a/Documentation/translations/it_IT/process/clang-format.rst b/Documentation/translations/it_IT/process/clang-format.rst index 29f83c198025..6fab07772da0 100644 --- a/Documentation/translations/it_IT/process/clang-format.rst +++ b/Documentation/translations/it_IT/process/clang-format.rst @@ -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: diff --git a/Documentation/translations/it_IT/process/index.rst b/Documentation/translations/it_IT/process/index.rst index 73c643dcc541..c24500f74660 100644 --- a/Documentation/translations/it_IT/process/index.rst +++ b/Documentation/translations/it_IT/process/index.rst @@ -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 diff --git a/Documentation/translations/it_IT/process/magic-number.rst b/Documentation/translations/it_IT/process/magic-number.rst index ae92ab633c16..cd8f23571835 100644 --- a/Documentation/translations/it_IT/process/magic-number.rst +++ b/Documentation/translations/it_IT/process/magic-number.rst @@ -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: diff --git a/Documentation/translations/it_IT/process/stable-kernel-rules.rst b/Documentation/translations/it_IT/process/stable-kernel-rules.rst index a2577a806a18..b1592f10f7a7 100644 --- a/Documentation/translations/it_IT/process/stable-kernel-rules.rst +++ b/Documentation/translations/it_IT/process/stable-kernel-rules.rst @@ -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,177 +45,204 @@ 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. -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. +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: +Per lasciare una nota per la squadra "stable", usate commenti in linea in stile +shell (leggere oltre per maggiori dettagli). -Opzione 2 -********* +* Specificate i prerequisiti per le patch aggiuntive:: -Dopo che la patch è 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 kernel la vorreste vedere. + 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> -.. _it_option_3: + La sequenza di etichette ha il seguente significato:: -Opzione 3 -********* + git cherry-pick a1f84a3 + git cherry-pick 1b9508f + git cherry-pick fd21073 + git cherry-pick <this commit> -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. + 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:: -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). + patch1 + patch2 -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. + dove patch2 dipende da patch1, non dovete elencare patch1 come requisito per + patch2 se avete già menzionato patch1 per l'inclusione in "stable" -L'identificativo del commit nei sorgenti principali dev'essere indicato sopra -al messaggio della patch, così: +* Evidenziate le patch che hanno dei requisiti circa la versione del kernel:: -.. code-block:: none + Cc: <stable@vger.kernel.org> # 3.3.x - commit <sha1> upstream. + L'etichetta ha il seguente significato:: -o in alternativa: + git cherry-pick <this commit> -.. code-block:: none + per ogni sorgente "-stable" che inizia con la versione indicata. - [ Upstream commit <sha1> ] + Notate che queste etichette non sono necessarie se la squadre "stable" può + dedurre la versione dalle etichette Fixes: -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: +* Ritardare l'inclusione di patch:: + Cc: <stable@vger.kernel.org> # after -rc3 -.. code-block:: none +* Evidenziare problemi noti:: - 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> + Cc: <stable@vger.kernel.org> # see patch description, needs adjustments for <= 6.3 -La sequenza di etichette ha il seguente significato: +Esiste un'ulteriore variante per l'etichetta "stable" che permette di comunicare +allo strumento di *backporting* di ignorare un cambiamento:: -.. code-block:: none + Cc: <stable+noautosel@kernel.org> # reason goes here, and must be present - 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: +.. _it_option_2: -.. code-block:: none +Opzione 2 +********* - Cc: <stable@vger.kernel.org> # 3.3.x +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 quali versioni +del kernel la vorreste vedere. -L'etichetta ha il seguente significato: +.. _it_option_3: -.. code-block:: none +Opzione 3 +********* - git cherry-pick <this commit> +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.:: -per ogni sorgente "-stable" che inizia con la versione indicata. + commit <sha1> upstream. -Dopo la sottomissione: +o in alternativa:: - - 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. + [ Upstream commit <sha1> ] +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. + +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. 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. diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst index 4c6a276bdc08..a7252e73937a 100644 --- a/Documentation/translations/it_IT/process/submitting-patches.rst +++ b/Documentation/translations/it_IT/process/submitting-patches.rst @@ -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 ----------- diff --git a/Documentation/translations/sp_SP/index.rst b/Documentation/translations/sp_SP/index.rst index 274ef4ad96b9..aae7018b0d1a 100644 --- a/Documentation/translations/sp_SP/index.rst +++ b/Documentation/translations/sp_SP/index.rst @@ -78,3 +78,4 @@ Traducciones al español process/index wrappers/memory-barriers + scheduler/index diff --git a/Documentation/translations/sp_SP/process/coding-style.rst b/Documentation/translations/sp_SP/process/coding-style.rst index b5a84df44cea..025223be9706 100644 --- a/Documentation/translations/sp_SP/process/coding-style.rst +++ b/Documentation/translations/sp_SP/process/coding-style.rst @@ -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 diff --git a/Documentation/translations/sp_SP/process/index.rst b/Documentation/translations/sp_SP/process/index.rst index 4892159310ff..adb2cc845928 100644 --- a/Documentation/translations/sp_SP/process/index.rst +++ b/Documentation/translations/sp_SP/process/index.rst @@ -29,3 +29,4 @@ submit-checklist howto development-process + maintainer-kvm-x86 diff --git a/Documentation/translations/sp_SP/process/magic-number.rst b/Documentation/translations/sp_SP/process/magic-number.rst index 32a99aac2f6c..beb4b4c1de11 100644 --- a/Documentation/translations/sp_SP/process/magic-number.rst +++ b/Documentation/translations/sp_SP/process/magic-number.rst @@ -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: diff --git a/Documentation/translations/sp_SP/process/maintainer-kvm-x86.rst b/Documentation/translations/sp_SP/process/maintainer-kvm-x86.rst new file mode 100644 index 000000000000..053b6a06db01 --- /dev/null +++ b/Documentation/translations/sp_SP/process/maintainer-kvm-x86.rst @@ -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. diff --git a/Documentation/translations/sp_SP/scheduler/index.rst b/Documentation/translations/sp_SP/scheduler/index.rst new file mode 100644 index 000000000000..768488d6f001 --- /dev/null +++ b/Documentation/translations/sp_SP/scheduler/index.rst @@ -0,0 +1,8 @@ +.. include:: ../disclaimer-sp.rst + +.. _sp_scheduler_index: + +.. toctree:: + :maxdepth: 1 + + sched-design-CFS diff --git a/Documentation/translations/sp_SP/scheduler/sched-design-CFS.rst b/Documentation/translations/sp_SP/scheduler/sched-design-CFS.rst new file mode 100644 index 000000000000..90a153cad4e8 --- /dev/null +++ b/Documentation/translations/sp_SP/scheduler/sched-design-CFS.rst @@ -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 diff --git a/Documentation/translations/zh_CN/admin-guide/index.rst b/Documentation/translations/zh_CN/admin-guide/index.rst index ac2960da33e6..0db80ab830a0 100644 --- a/Documentation/translations/zh_CN/admin-guide/index.rst +++ b/Documentation/translations/zh_CN/admin-guide/index.rst @@ -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 diff --git a/Documentation/translations/zh_CN/admin-guide/numastat.rst b/Documentation/translations/zh_CN/admin-guide/numastat.rst new file mode 100644 index 000000000000..4d9817b91870 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/numastat.rst @@ -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统计数据。 diff --git a/Documentation/translations/zh_CN/dev-tools/gdb-kernel-debugging.rst b/Documentation/translations/zh_CN/dev-tools/gdb-kernel-debugging.rst index 17b5ce85a90c..3c133a918f30 100644 --- a/Documentation/translations/zh_CN/dev-tools/gdb-kernel-debugging.rst +++ b/Documentation/translations/zh_CN/dev-tools/gdb-kernel-debugging.rst @@ -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”参数 diff --git a/Documentation/translations/zh_CN/dev-tools/index.rst b/Documentation/translations/zh_CN/dev-tools/index.rst index fa900f5beb68..c540e4a7d5db 100644 --- a/Documentation/translations/zh_CN/dev-tools/index.rst +++ b/Documentation/translations/zh_CN/dev-tools/index.rst @@ -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 diff --git a/Documentation/translations/zh_CN/dev-tools/kasan.rst b/Documentation/translations/zh_CN/dev-tools/kasan.rst index 2b1e8f74904b..4491ad2830ed 100644 --- a/Documentation/translations/zh_CN/dev-tools/kasan.rst +++ b/Documentation/translations/zh_CN/dev-tools/kasan.rst @@ -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: + ... + ================================================================== + 实施细则 -------- diff --git a/Documentation/translations/zh_CN/dev-tools/testing-overview.rst b/Documentation/translations/zh_CN/dev-tools/testing-overview.rst index c91f9b60f9f1..286ed6b01f65 100644 --- a/Documentation/translations/zh_CN/dev-tools/testing-overview.rst +++ b/Documentation/translations/zh_CN/dev-tools/testing-overview.rst @@ -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 中找到。 diff --git a/Documentation/translations/zh_CN/driver-api/index.rst b/Documentation/translations/zh_CN/driver-api/index.rst index 92ff1b7fc3d3..4050a2fb51c6 100644 --- a/Documentation/translations/zh_CN/driver-api/index.rst +++ b/Documentation/translations/zh_CN/driver-api/index.rst @@ -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 diff --git a/Documentation/translations/zh_CN/driver-api/phy/index.rst b/Documentation/translations/zh_CN/driver-api/phy/index.rst new file mode 100644 index 000000000000..2cdce17b74a9 --- /dev/null +++ b/Documentation/translations/zh_CN/driver-api/phy/index.rst @@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============ +PHY 通用框架 +============ + +.. toctree:: + + phy + +Todolist: + +* samsung-usb2 + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/driver-api/phy/phy.rst b/Documentation/translations/zh_CN/driver-api/phy/phy.rst new file mode 100644 index 000000000000..0d7489081b90 --- /dev/null +++ b/Documentation/translations/zh_CN/driver-api/phy/phy.rst @@ -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 diff --git a/Documentation/translations/zh_CN/process/4.Coding.rst b/Documentation/translations/zh_CN/process/4.Coding.rst index 7cac9424f5d5..4cc35d410dbc 100644 --- a/Documentation/translations/zh_CN/process/4.Coding.rst +++ b/Documentation/translations/zh_CN/process/4.Coding.rst @@ -54,7 +54,7 @@ 注意您还可以使用 ``clang-format`` 工具来帮助您处理这些规则，快速自动重新格式 化部分代码，和审阅完整的文件以发现代码样式错误、拼写错误和可能的改进。它还 可以方便地排序 ``#includes`` 、对齐变量/宏、重排文本和其他类似任务。有关详细 -信息，请参阅文档 :ref:`Documentation/process/clang-format.rst <clangformat>` +信息，请参阅文档 :ref:`Documentation/dev-tools/clang-format.rst <clangformat>` 抽象层 ****** diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst index 3bc2810b151d..10b9cb4f6a65 100644 --- a/Documentation/translations/zh_CN/process/coding-style.rst +++ b/Documentation/translations/zh_CN/process/coding-style.rst @@ -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 配置文件 diff --git a/Documentation/translations/zh_CN/process/index.rst b/Documentation/translations/zh_CN/process/index.rst index 5c6c8ccdd50d..5a5cd7c01c62 100644 --- a/Documentation/translations/zh_CN/process/index.rst +++ b/Documentation/translations/zh_CN/process/index.rst @@ -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 diff --git a/Documentation/translations/zh_CN/process/magic-number.rst b/Documentation/translations/zh_CN/process/magic-number.rst index 4e4aeaca796c..4ebc84cc0c54 100644 --- a/Documentation/translations/zh_CN/process/magic-number.rst +++ b/Documentation/translations/zh_CN/process/magic-number.rst @@ -1,6 +1,6 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: Documentation/process/magic-number.rst +:Original: Documentation/staging/magic-number.rst :翻译: diff --git a/Documentation/translations/zh_CN/process/researcher-guidelines.rst b/Documentation/translations/zh_CN/process/researcher-guidelines.rst new file mode 100644 index 000000000000..1f2da68fc4e8 --- /dev/null +++ b/Documentation/translations/zh_CN/process/researcher-guidelines.rst @@ -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>。 diff --git a/Documentation/translations/zh_CN/virt/guest-halt-polling.rst b/Documentation/translations/zh_CN/virt/guest-halt-polling.rst index b798d1cf0b48..463d1d829062 100644 --- a/Documentation/translations/zh_CN/virt/guest-halt-polling.rst +++ b/Documentation/translations/zh_CN/virt/guest-halt-polling.rst @@ -76,7 +76,7 @@ guest_halt_poll_ns将保持高位）。 默认值: Y -模块参数可以从Debugfs文件中设置，在:: +模块参数可以从sysfs文件中设置，在:: /sys/module/haltpoll/parameters/ diff --git a/Documentation/translations/zh_TW/process/4.Coding.rst b/Documentation/translations/zh_TW/process/4.Coding.rst index bdd2abe4daf4..e90a6b51fb98 100644 --- a/Documentation/translations/zh_TW/process/4.Coding.rst +++ b/Documentation/translations/zh_TW/process/4.Coding.rst @@ -57,7 +57,7 @@ 注意您還可以使用 ``clang-format`` 工具來幫助您處理這些規則，快速自動重新格式 化部分代碼，和審閱完整的文件以發現代碼樣式錯誤、拼寫錯誤和可能的改進。它還 可以方便地排序 ``#includes`` 、對齊變量/宏、重排文本和其他類似任務。有關詳細 -信息，請參閱文檔 :ref:`Documentation/process/clang-format.rst <clangformat>` +信息，請參閱文檔 :ref:`Documentation/dev-tools/clang-format.rst <clangformat>` 抽象層 ****** diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/translations/zh_TW/process/coding-style.rst index c7ac504f6f40..311c6f6bad0b 100644 --- a/Documentation/translations/zh_TW/process/coding-style.rst +++ b/Documentation/translations/zh_TW/process/coding-style.rst @@ -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 配置文件 diff --git a/Documentation/translations/zh_TW/process/magic-number.rst b/Documentation/translations/zh_TW/process/magic-number.rst index 199cd5d63973..5582df6d7ca7 100644 --- a/Documentation/translations/zh_TW/process/magic-number.rst +++ b/Documentation/translations/zh_TW/process/magic-number.rst @@ -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。如果你使用英文交流有困難的話，也可 以向中文版維護者求助。如果本翻譯更新不及時或者翻譯存在問題，請聯繫中文版維護者:: diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst index 9a97030c6c8d..9224723992fd 100644 --- a/Documentation/userspace-api/ioctl/ioctl-number.rst +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst @@ -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 diff --git a/scripts/checktransupdate.py b/scripts/checktransupdate.py new file mode 100755 index 000000000000..5a0fc99e3f93 --- /dev/null +++ b/scripts/checktransupdate.py @@ -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() |