tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
fork atom

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
...

Linus Torvalds cf05e93a 7dd894c1

+1982 -425
+1 -1
.clang-format
··· 4 4 # 5 5 # For more information, see: 6 6 # 7 - # Documentation/process/clang-format.rst 7 + # Documentation/dev-tools/clang-format.rst 8 8 # https://clang.llvm.org/docs/ClangFormat.html 9 9 # https://clang.llvm.org/docs/ClangFormatStyleOptions.html 10 10 #
+5
Documentation/admin-guide/dynamic-debug-howto.rst
··· 26 26 - format string 27 27 - class name (as known/declared by each module) 28 28 29 + NOTE: To actually get the debug-print output on the console, you may 30 + need to adjust the kernel ``loglevel=``, or use ``ignore_loglevel``. 31 + Read about these kernel parameters in 32 + Documentation/admin-guide/kernel-parameters.rst. 33 + 29 34 Viewing Dynamic Debug Behaviour 30 35 =============================== 31 36
-1
Documentation/admin-guide/kernel-parameters.rst
··· 118 118 HIBERNATION HIBERNATION is enabled. 119 119 HW Appropriate hardware is enabled. 120 120 HYPER_V HYPERV support is enabled. 121 - IA-64 IA-64 architecture is enabled. 122 121 IMA Integrity measurement architecture is enabled. 123 122 IP_PNP IP DHCP, BOOTP, or RARP is enabled. 124 123 IPV6 IPv6 support is enabled.
+4 -76
Documentation/admin-guide/kernel-parameters.txt
··· 1742 1742 for 64-bit NUMA, off otherwise. 1743 1743 Format: 0 | 1 (for off | on) 1744 1744 1745 - hcl= [IA-64] SGI's Hardware Graph compatibility layer 1746 - 1747 1745 hd= [EIDE] (E)IDE hard drive subsystem geometry 1748 1746 Format: <cyl>,<head>,<sect> 1749 1747 ··· 2500 2502 2501 2503 keepinitrd [HW,ARM] See retain_initrd. 2502 2504 2503 - kernelcore= [KNL,X86,IA-64,PPC,EARLY] 2505 + kernelcore= [KNL,X86,PPC,EARLY] 2504 2506 Format: nn[KMGTPE] | nn% | "mirror" 2505 2507 This parameter specifies the amount of memory usable by 2506 2508 the kernel for non-movable allocations. The requested ··· 3140 3142 unlikely, in the extreme case this might damage your 3141 3143 hardware. 3142 3144 3143 - ltpc= [NET] 3144 - Format: <io>,<irq>,<dma> 3145 - 3146 3145 lsm.debug [SECURITY] Enable LSM initialization debugging output. 3147 3146 3148 3147 lsm=lsm1,...,lsmN 3149 3148 [SECURITY] Choose order of LSM initialization. This 3150 3149 overrides CONFIG_LSM, and the "security=" parameter. 3151 3150 3152 - machvec= [IA-64] Force the use of a particular machine-vector 3153 - (machvec) in a generic kernel. 3154 - Example: machvec=hpzx1 3155 - 3156 3151 machtype= [Loongson] Share the same kernel image file between 3157 3152 different yeeloong laptops. 3158 3153 Example: machtype=lemote-yeeloong-2f-7inch 3159 - 3160 - max_addr=nn[KMG] [KNL,BOOT,IA-64] All physical memory greater 3161 - than or equal to this physical address is ignored. 3162 3154 3163 3155 maxcpus= [SMP,EARLY] Maximum number of processors that an SMP kernel 3164 3156 will bring up during bootup. maxcpus=n : n >= 0 limits ··· 3387 3399 Enable or disable the microcode minimal revision 3388 3400 enforcement for the runtime microcode loader. 3389 3401 3390 - min_addr=nn[KMG] [KNL,BOOT,IA-64] All physical memory below this 3391 - physical address is ignored. 3392 - 3393 3402 mini2440= [ARM,HW,KNL] 3394 3403 Format:[0..2][b][c][t] 3395 3404 Default: "0tb" ··· 3551 3566 mousedev.yres= [MOUSE] Vertical screen resolution, used for devices 3552 3567 reporting absolute coordinates, such as tablets 3553 3568 3554 - movablecore= [KNL,X86,IA-64,PPC,EARLY] 3569 + movablecore= [KNL,X86,PPC,EARLY] 3555 3570 Format: nn[KMGTPE] | nn% 3556 3571 This parameter is the complement to kernelcore=, it 3557 3572 specifies the amount of memory used for migratable ··· 3576 3591 3577 3592 mtdparts= [MTD] 3578 3593 See drivers/mtd/parsers/cmdlinepart.c 3579 - 3580 - mtdset= [ARM] 3581 - ARM/S3C2412 JIVE boot control 3582 - 3583 - See arch/arm/mach-s3c/mach-jive.c 3584 3594 3585 3595 mtouchusb.raw_coordinates= 3586 3596 [HW] Make the MicroTouch USB driver use raw coordinates ··· 3825 3845 3826 3846 no_entry_flush [PPC,EARLY] Don't flush the L1-D cache when entering the kernel. 3827 3847 3828 - noexec [IA-64] 3829 - 3830 3848 noexec32 [X86-64] 3831 3849 This affects only 32-bit executables. 3832 3850 noexec32=on: enable non-executable mappings (default) ··· 3844 3866 register save and restore. The kernel will only save 3845 3867 legacy floating-point registers on task switch. 3846 3868 3847 - nohalt [IA-64] Tells the kernel not to use the power saving 3848 - function PAL_HALT_LIGHT when idle. This increases 3849 - power-consumption. On the positive side, it reduces 3850 - interrupt wake-up latency, which may improve performance 3851 - in certain environments such as networked servers or 3852 - real-time systems. 3853 - 3854 3869 no_hash_pointers 3855 3870 [KNL,EARLY] 3856 3871 Force pointers printed to the console or buffers to be ··· 3861 3890 3862 3891 nohibernate [HIBERNATION] Disable hibernation and resume. 3863 3892 3864 - nohlt [ARM,ARM64,MICROBLAZE,MIPS,PPC,SH] Forces the kernel to 3893 + nohlt [ARM,ARM64,MICROBLAZE,MIPS,PPC,RISCV,SH] Forces the kernel to 3865 3894 busy wait in do_idle() and not use the arch_cpu_idle() 3866 3895 implementation; requires CONFIG_GENERIC_IDLE_POLL_SETUP 3867 3896 to be effective. This is useful on platforms where the ··· 3898 3927 remapping. 3899 3928 [Deprecated - use intremap=off] 3900 3929 3901 - nointroute [IA-64] 3902 - 3903 3930 noinvpcid [X86,EARLY] Disable the INVPCID cpu feature. 3904 3931 3905 3932 noiotrap [SH] Disables trapped I/O port accesses. ··· 3906 3937 disable unhandled interrupt sources. 3907 3938 3908 3939 noisapnp [ISAPNP] Disables ISA PnP code. 3909 - 3910 - nojitter [IA-64] Disables jitter checking for ITC timers. 3911 3940 3912 3941 nokaslr [KNL,EARLY] 3913 3942 When CONFIG_RANDOMIZE_BASE is set, this disables ··· 3920 3953 nolapic [X86-32,APIC,EARLY] Do not enable or use the local APIC. 3921 3954 3922 3955 nolapic_timer [X86-32,APIC,EARLY] Do not use the local APIC timer. 3923 - 3924 - nomca [IA-64] Disable machine check abort handling 3925 3956 3926 3957 nomce [X86-32] Disable Machine Check Exception 3927 3958 ··· 3971 4006 3972 4007 noresume [SWSUSP] Disables resume and restores original swap 3973 4008 space. 3974 - 3975 - nosbagart [IA-64] 3976 4009 3977 4010 no-scroll [VGA] Disables scrollback. 3978 4011 This is required for the Braillex ib80-piezo Braille ··· 4071 4108 in standard form of xsave area. By using this 4072 4109 parameter, xsave area per process might occupy more 4073 4110 memory on xsaves enabled systems. 4074 - 4075 - nps_mtm_hs_ctr= [KNL,ARC] 4076 - This parameter sets the maximum duration, in 4077 - cycles, each HW thread of the CTOP can run 4078 - without interruptions, before HW switches it. 4079 - The actual maximum duration is 16 times this 4080 - parameter's value. 4081 - Format: integer between 1 and 255 4082 - Default: 255 4083 - 4084 - nptcg= [IA-64] Override max number of concurrent global TLB 4085 - purges which is reported from either PAL_VM_SUMMARY or 4086 - SAL PALO. 4087 4111 4088 4112 nr_cpus= [SMP,EARLY] Maximum number of processors that an SMP kernel 4089 4113 could support. nr_cpus=n : n >= 1 limits the kernel to ··· 5724 5774 2 The "airplane mode" button toggles between everything 5725 5775 blocked and everything unblocked. 5726 5776 5727 - rhash_entries= [KNL,NET] 5728 - Set number of hash buckets for route cache 5729 - 5730 5777 ring3mwait=disable 5731 5778 [KNL] Disable ring 3 MONITOR/MWAIT feature on supported 5732 5779 CPUs. ··· 5956 6009 The parameter valid if only apic=debug or 5957 6010 apic=verbose is specified. 5958 6011 Example: apic=debug show_lapic=all 5959 - 5960 - simeth= [IA-64] 5961 - simscsi= 5962 6012 5963 6013 slab_debug[=options[,slabs][;[options[,slabs]]...] [MM] 5964 6014 Enabling slab_debug allows one to determine the ··· 6224 6280 Not specifying this option is equivalent to 6225 6281 spec_store_bypass_disable=auto. 6226 6282 6227 - spia_io_base= [HW,MTD] 6228 - spia_fio_base= 6229 - spia_pedr= 6230 - spia_peddr= 6231 - 6232 6283 split_lock_detect= 6233 6284 [X86] Enable split lock detection or bus lock detection 6234 6285 ··· 6479 6540 This parameter controls use of the Protected 6480 6541 Execution Facility on pSeries. 6481 6542 6482 - swiotlb= [ARM,IA-64,PPC,MIPS,X86,EARLY] 6543 + swiotlb= [ARM,PPC,MIPS,X86,S390,EARLY] 6483 6544 Format: { <int> [,<int>] | force | noforce } 6484 6545 <int> -- Number of I/O TLB slabs 6485 6546 <int> -- Second integer after comma. Number of swiotlb ··· 6560 6621 e.g. base its process migration decisions on it. 6561 6622 Default is on. 6562 6623 6563 - topology_updates= [KNL, PPC, NUMA] 6564 - Format: {off} 6565 - Specify if the kernel should ignore (off) 6566 - topology updates sent by the hypervisor to this 6567 - LPAR. 6568 - 6569 6624 torture.disable_onoff_at_boot= [KNL] 6570 6625 Prevent the CPU-hotplug component of torturing 6571 6626 until after init has spawned. ··· 6578 6645 6579 6646 torture.verbose_sleep_duration= [KNL] 6580 6647 Duration of each verbose-printk() sleep in jiffies. 6581 - 6582 - tp720= [HW,PS2] 6583 6648 6584 6649 tpm_suspend_pcr=[HW,TPM] 6585 6650 Format: integer pcr id ··· 7114 7183 7115 7184 Try vdso32=0 if you encounter an error that says: 7116 7185 dl_main: Assertion `(void *) ph->p_vaddr == _rtld_local._dl_sysinfo_dso' failed! 7117 - 7118 - vector= [IA-64,SMP] 7119 - vector=percpu: enable percpu vector domain 7120 7186 7121 7187 video= [FB,EARLY] Frame buffer configuration 7122 7188 See Documentation/fb/modedb.rst.
+1 -1
Documentation/admin-guide/mm/index.rst
··· 10 10 11 11 Linux memory management is a complex system with many configurable 12 12 settings. Most of these settings are available via ``/proc`` 13 - filesystem and can be quired and adjusted using ``sysctl``. These APIs 13 + filesystem and can be queried and adjusted using ``sysctl``. These APIs 14 14 are described in Documentation/admin-guide/sysctl/vm.rst and in `man 5 proc`_. 15 15 16 16 .. _man 5 proc: http://man7.org/linux/man-pages/man5/proc.5.html
+1 -1
Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
··· 23 23 up in the reference section, then jump back to where you left off. 24 24 .. 25 25 Find the latest rendered version of this text here: 26 - https://docs.kernel.org/admin-guide/verify-bugs-and-bisect-regressions.rst.html 26 + https://docs.kernel.org/admin-guide/verify-bugs-and-bisect-regressions.html 27 27 28 28 The essence of the process (aka 'TL;DR') 29 29 ========================================
+1 -1
Documentation/arch/x86/cpuinfo.rst
··· 112 112 setup_force_cpu_cap macros. For example, if bit 5 is set in MSR_IA32_CORE_CAPS, 113 113 the feature X86_FEATURE_SPLIT_LOCK_DETECT will be enabled and 114 114 "split_lock_detect" will be displayed. The flag "ring3mwait" will be 115 - displayed only when running on INTEL_FAM6_XEON_PHI_[KNL|KNM] processors. 115 + displayed only when running on INTEL_XEON_PHI_[KNL|KNM] processors. 116 116 117 117 d: Flags can represent purely software features. 118 118 ------------------------------------------------
+1 -1
Documentation/arch/x86/exception-tables.rst
··· 297 297 c) execution continues at local label 2 (address of the 298 298 instruction immediately after the faulting user access). 299 299 300 - The steps 8a to 8c in a certain way emulate the faulting instruction. 300 + The steps a to c above in a certain way emulate the faulting instruction. 301 301 302 302 That's it, mostly. If you look at our example, you might ask why 303 303 we set EAX to -EFAULT in the exception handler code. Well, the
+1 -1
Documentation/core-api/genericirq.rst
··· 210 210 } 211 211 } 212 212 213 - noop(struct irq_data *data)) 213 + noop(struct irq_data *data) 214 214 { 215 215 } 216 216
+15 -15
Documentation/crypto/async-tx-api.rst
··· 150 150 Perform a xor->copy->xor operation where each operation depends on the 151 151 result from the previous operation:: 152 152 153 - void callback(void *param) 154 - { 155 - struct completion *cmp = param; 153 + #include <linux/async_tx.h> 156 154 157 - complete(cmp); 155 + static void callback(void *param) 156 + { 157 + complete(param); 158 158 } 159 159 160 - void run_xor_copy_xor(struct page **xor_srcs, 161 - int xor_src_cnt, 162 - struct page *xor_dest, 163 - size_t xor_len, 164 - struct page *copy_src, 165 - struct page *copy_dest, 166 - size_t copy_len) 160 + #define NDISKS 2 161 + 162 + static void run_xor_copy_xor(struct page **xor_srcs, 163 + struct page *xor_dest, 164 + size_t xor_len, 165 + struct page *copy_src, 166 + struct page *copy_dest, 167 + size_t copy_len) 167 168 { 168 169 struct dma_async_tx_descriptor *tx; 169 - addr_conv_t addr_conv[xor_src_cnt]; 170 170 struct async_submit_ctl submit; 171 171 addr_conv_t addr_conv[NDISKS]; 172 172 struct completion cmp; 173 173 174 174 init_async_submit(&submit, ASYNC_TX_XOR_DROP_DST, NULL, NULL, NULL, 175 175 addr_conv); 176 - tx = async_xor(xor_dest, xor_srcs, 0, xor_src_cnt, xor_len, &submit) 176 + tx = async_xor(xor_dest, xor_srcs, 0, NDISKS, xor_len, &submit); 177 177 178 - submit->depend_tx = tx; 178 + submit.depend_tx = tx; 179 179 tx = async_memcpy(copy_dest, copy_src, 0, 0, copy_len, &submit); 180 180 181 181 init_completion(&cmp); 182 182 init_async_submit(&submit, ASYNC_TX_XOR_DROP_DST | ASYNC_TX_ACK, tx, 183 183 callback, &cmp, addr_conv); 184 - tx = async_xor(xor_dest, xor_srcs, 0, xor_src_cnt, xor_len, &submit); 184 + tx = async_xor(xor_dest, xor_srcs, 0, NDISKS, xor_len, &submit); 185 185 186 186 async_tx_issue_pending_all(); 187 187
+1
Documentation/dev-tools/index.rst
··· 16 16 17 17 testing-overview 18 18 checkpatch 19 + clang-format 19 20 coccinelle 20 21 sparse 21 22 kcov
+2 -2
Documentation/doc-guide/kernel-doc.rst
··· 143 143 ~~~~~~~~~~~~~ 144 144 145 145 The return value, if any, should be described in a dedicated section 146 - named ``Return``. 146 + named ``Return`` (or ``Returns``). 147 147 148 148 .. note:: 149 149 ··· 337 337 * Description of the type. 338 338 * 339 339 * Context: Locking context. 340 - * Return: Meaning of the return value. 340 + * Returns: Meaning of the return value. 341 341 */ 342 342 typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); 343 343
+4 -3
Documentation/driver-api/driver-model/platform.rst
··· 41 41 42 42 struct platform_driver { 43 43 int (*probe)(struct platform_device *); 44 - int (*remove)(struct platform_device *); 44 + void (*remove)(struct platform_device *); 45 45 void (*shutdown)(struct platform_device *); 46 46 int (*suspend)(struct platform_device *, pm_message_t state); 47 - int (*suspend_late)(struct platform_device *, pm_message_t state); 48 - int (*resume_early)(struct platform_device *); 49 47 int (*resume)(struct platform_device *); 50 48 struct device_driver driver; 49 + const struct platform_device_id *id_table; 50 + bool prevent_deferred_probe; 51 + bool driver_managed_dma; 51 52 }; 52 53 53 54 Note that probe() should in general verify that the specified device hardware
+7
Documentation/driver-api/input.rst
··· 40 40 .. kernel-doc:: drivers/input/sparse-keymap.c 41 41 :export: 42 42 43 + PS/2 protocol support 44 + --------------------- 45 + .. kernel-doc:: include/linux/libps2.h 46 + :internal: 47 + 48 + .. kernel-doc:: drivers/input/serio/libps2.c 49 + :export:
+1 -1
Documentation/driver-api/pin-control.rst
··· 1002 1002 .. code-block:: c 1003 1003 1004 1004 static struct pinctrl_map mapping[] __initdata = { 1005 - PIN_MAP_MUX_GROUP("foo-i2c.o", PINCTRL_STATE_DEFAULT, 1005 + PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, 1006 1006 "pinctrl-foo", NULL, "i2c0"), 1007 1007 }; 1008 1008
+1 -1
Documentation/driver-api/usb/writing_musb_glue_layer.rst
··· 717 717 :ref:`Writing USB Device Drivers <writing-usb-driver>` 718 718 719 719 Texas Instruments USB Configuration Wiki Page: 720 - http://processors.wiki.ti.com/index.php/Usbgeneralpage 720 + https://web.archive.org/web/20201215135015/http://processors.wiki.ti.com/index.php/Usbgeneralpage
+11
Documentation/maintainer/feature-and-driver-maintainers.rst
··· 83 83 problem that might be severe -- especially if they have *Supported* 84 84 status of the codebase in the MAINTAINERS file. 85 85 86 + Open development 87 + ---------------- 88 + 89 + Discussions about user reported issues, and development of new code 90 + should be conducted in a manner typical for the larger subsystem. 91 + It is common for development within a single company to be conducted 92 + behind closed doors. However, development and discussions initiated 93 + by community members must not be redirected from public to closed forums 94 + or to private email conversations. Reasonable exceptions to this guidance 95 + include discussions about security related issues. 96 + 86 97 Selecting the maintainer 87 98 ======================== 88 99
+1
Documentation/maintainer/maintainer-entry-profile.rst
··· 109 109 ../driver-api/vfio-pci-device-specific-driver-acceptance 110 110 ../nvme/feature-and-quirk-policy 111 111 ../filesystems/xfs/xfs-maintainer-entry-profile 112 + ../mm/damon/maintainer-profile
-1
Documentation/mm/allocation-profiling.rst
··· 46 46 55M 4887 mm/slub.c:2259 func:alloc_slab_page 47 47 122M 31168 mm/page_ext.c:270 func:alloc_page_ext 48 48 49 - =================== 50 49 Theory of operation 51 50 =================== 52 51
+8 -11
Documentation/mm/index.rst
··· 2 2 Memory Management Documentation 3 3 =============================== 4 4 5 - Memory Management Guide 6 - ======================= 7 - 8 5 This is a guide to understanding the memory management subsystem 9 6 of Linux. If you are looking for advice on simply allocating memory, 10 7 see the :ref:`memory_allocation`. For controlling and tuning guides, ··· 23 26 page_cache 24 27 shmfs 25 28 oom 26 - allocation-profiling 27 29 28 - Legacy Documentation 29 - ==================== 30 + Unsorted Documentation 31 + ====================== 30 32 31 - This is a collection of older documents about the Linux memory management 32 - (MM) subsystem internals with different level of details ranging from 33 - notes and mailing list responses for elaborating descriptions of data 34 - structures and algorithms. It should all be integrated nicely into the 35 - above structured documentation, or deleted if it has served its purpose. 33 + This is a collection of unsorted documents about the Linux memory management 34 + (MM) subsystem internals with different level of details ranging from notes and 35 + mailing list responses for elaborating descriptions of data structures and 36 + algorithms. It should all be integrated nicely into the above structured 37 + documentation, or deleted if it has served its purpose. 36 38 37 39 .. toctree:: 38 40 :maxdepth: 1 39 41 40 42 active_mm 43 + allocation-profiling 41 44 arch_pgtable_helpers 42 45 balance 43 46 damon/index
+5 -5
Documentation/mm/vmalloced-kernel-stacks.rst
··· 22 22 susceptible to exploits. Problems could show up at a later time making 23 23 it difficult to isolate and root-cause. 24 24 25 - Virtually-mapped kernel stacks with guard pages causes kernel stack 25 + Virtually mapped kernel stacks with guard pages cause kernel stack 26 26 overflows to be caught immediately rather than causing difficult to 27 27 diagnose corruptions. 28 28 ··· 57 57 VMAP_STACK 58 58 ---------- 59 59 60 - VMAP_STACK bool configuration option when enabled allocates virtually 60 + When enabled, the VMAP_STACK bool configuration option allocates virtually 61 61 mapped task stacks. This option depends on HAVE_ARCH_VMAP_STACK. 62 62 63 63 - Enable this if you want the use virtually-mapped kernel stacks ··· 83 83 Allocation 84 84 ----------- 85 85 86 - When a new kernel thread is created, thread stack is allocated from 86 + When a new kernel thread is created, a thread stack is allocated from 87 87 virtually contiguous memory pages from the page level allocator. These 88 88 pages are mapped into contiguous kernel virtual space with PAGE_KERNEL 89 89 protections. ··· 103 103 - This does not address interrupt stacks - according to the original patch 104 104 105 105 Thread stack allocation is initiated from clone(), fork(), vfork(), 106 - kernel_thread() via kernel_clone(). Leaving a few hints for searching 107 - the code base to understand when and how thread stack is allocated. 106 + kernel_thread() via kernel_clone(). These are a few hints for searching 107 + the code base to understand when and how a thread stack is allocated. 108 108 109 109 Bulk of the code is in: 110 110 `kernel/fork.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/kernel/fork.c>`.
+4 -4
Documentation/process/2.Process.rst
··· 392 392 load of electronic mail, running afoul of the conventions used on the Linux 393 393 lists, or both. 394 394 395 - Most kernel mailing lists are run on vger.kernel.org; the master list can 395 + Most kernel mailing lists are hosted at kernel.org; the master list can 396 396 be found at: 397 397 398 - http://vger.kernel.org/vger-lists.html 398 + https://subspace.kernel.org 399 399 400 - There are lists hosted elsewhere, though; a number of them are at 401 - redhat.com/mailman/listinfo. 400 + There are lists hosted elsewhere; please check the MAINTAINERS file for 401 + the list relevant for any particular subsystem. 402 402 403 403 The core mailing list for kernel development is, of course, linux-kernel. 404 404 This list is an intimidating place to be; volume can reach 500 messages per
+1 -1
Documentation/process/4.Coding.rst
··· 63 63 and to review full files in order to spot coding style mistakes, 64 64 typos and possible improvements. It is also handy for sorting ``#includes``, 65 65 for aligning variables/macros, for reflowing text and other similar tasks. 66 - See the file :ref:`Documentation/process/clang-format.rst <clangformat>` 66 + See the file :ref:`Documentation/dev-tools/clang-format.rst <clangformat>` 67 67 for more details. 68 68 69 69 Some basic editor settings, such as indentation and line endings, will be
+1
Documentation/process/changes.rst
··· 63 63 GNU tar 1.28 tar --version 64 64 gtags (optional) 6.6.5 gtags --version 65 65 mkimage (optional) 2017.01 mkimage --version 66 + Python (optional) 3.5.x python3 --version 66 67 ====================== =============== ======================================== 67 68 68 69 .. [#f1] Sphinx is needed only to build the Kernel documentation
Documentation/process/clang-format.rst Documentation/dev-tools/clang-format.rst
+1 -1
Documentation/process/coding-style.rst
··· 732 732 and to review full files in order to spot coding style mistakes, 733 733 typos and possible improvements. It is also handy for sorting ``#includes``, 734 734 for aligning variables/macros, for reflowing text and other similar tasks. 735 - See the file :ref:`Documentation/process/clang-format.rst <clangformat>` 735 + See the file :ref:`Documentation/dev-tools/clang-format.rst <clangformat>` 736 736 for more details. 737 737 738 738 Some basic editor settings, such as indentation and line endings, will be
+7 -18
Documentation/process/email-clients.rst
··· 351 351 Another problem is that Gmail will base64-encode any message that has a 352 352 non-ASCII character. That includes things like European names. 353 353 354 - Proton Mail 355 - *********** 354 + HacKerMaiL (TUI) 355 + **************** 356 356 357 - Proton Mail has a "feature" where it looks up keys using Web Key Directory 358 - (WKD) and encrypts mail to any recipients for which it finds a key. 359 - Kernel.org publishes the WKD for all developers who have kernel.org accounts. 360 - As a result, emails sent using Proton Mail to kernel.org addresses will be 361 - encrypted. 362 - Unfortunately, Proton Mail does not provide a mechanism to disable the 363 - automatic encryption, viewing it as a privacy feature. 364 - The automatic encryption feature is also enabled for mail sent via the Proton 365 - Mail Bridge, so this affects all outgoing messages, including patches sent with 366 - ``git send-email``. 367 - Encrypted mail adds unnecessary friction, as other developers may not have mail 368 - clients, or tooling, configured for use with encrypted mail and some mail 369 - clients may encrypt responses to encrypted mail for all recipients, including 370 - the mailing lists. 371 - Unless a way to disable this "feature" is introduced, Proton Mail is unsuited 372 - to kernel development. 357 + HacKerMaiL (hkml) is a public-inbox based simple mails management tool that 358 + doesn't require subscription of mailing lists. It is developed and maintained 359 + by the DAMON maintainer and aims to support simple development workflows for 360 + DAMON and general kernel subsystems. Refer to the README 361 + (https://github.com/sjp38/hackermail/blob/master/README.md) for details.
+18 -12
Documentation/process/handling-regressions.rst
··· 40 40 #regzbot from: Some N. Ice Human <some.human@example.com> 41 41 #regzbot monitor: http://some.bugtracker.example.com/ticket?id=123456789 42 42 43 - #. When submitting fixes for regressions, add "Link:" tags to the patch 43 + #. When submitting fixes for regressions, add "Closes:" tags to the patch 44 44 description pointing to all places where the issue was reported, as 45 45 mandated by Documentation/process/submitting-patches.rst and 46 - :ref:`Documentation/process/5.Posting.rst <development_posting>`. 46 + :ref:`Documentation/process/5.Posting.rst <development_posting>`. If you are 47 + only fixing part of the issue that caused the regression, you may use 48 + "Link:" tags instead. regzbot currently makes no distinction between the 49 + two. 47 50 48 51 #. Try to fix regressions quickly once the culprit has been identified; fixes 49 52 for most regressions should be merged within two weeks, but some need to be ··· 94 91 Note the caret (^) before the "introduced": it tells regzbot to treat the 95 92 parent mail (the one you reply to) as the initial report for the regression 96 93 you want to see tracked; that's important, as regzbot will later look out 97 - for patches with "Link:" tags pointing to the report in the archives on 94 + for patches with "Closes:" tags pointing to the report in the archives on 98 95 lore.kernel.org. 99 96 100 - * When forwarding a regressions reported to a bug tracker, include a paragraph 97 + * When forwarding a regression reported to a bug tracker, include a paragraph 101 98 with these regzbot commands:: 102 99 103 100 #regzbot introduced: 1f2e3d4c5b6a ··· 105 102 #regzbot monitor: http://some.bugtracker.example.com/ticket?id=123456789 106 103 107 104 Regzbot will then automatically associate patches with the report that 108 - contain "Link:" tags pointing to your mail or the mentioned ticket. 105 + contain "Closes:" tags pointing to your mail or the mentioned ticket. 109 106 110 107 What's important when fixing regressions 111 108 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ··· 115 112 :ref:`Documentation/process/5.Posting.rst <development_posting>`, and 116 113 Documentation/process/stable-kernel-rules.rst already explain in more detail: 117 114 118 - * Point to all places where the issue was reported using "Link:" tags:: 115 + * Point to all places where the issue was reported using "Closes:" tags:: 119 116 120 - Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ 121 - Link: https://bugzilla.kernel.org/show_bug.cgi?id=1234567890 117 + Closes: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ 118 + Closes: https://bugzilla.kernel.org/show_bug.cgi?id=1234567890 119 + 120 + If you are only fixing part of the issue, you may use "Link:" instead as 121 + described in the first document mentioned above. regzbot currently treats 122 + both of these equivalently and considers the linked reports as resolved. 122 123 123 124 * Add a "Fixes:" tag to specify the commit causing the regression. 124 125 ··· 133 126 these tags are of great value for everyone (you included) that might be looking 134 127 into the issue weeks, months, or years later. These tags are also crucial for 135 128 tools and scripts used by other kernel developers or Linux distributions; one of 136 - these tools is regzbot, which heavily relies on the "Link:" tags to associate 129 + these tools is regzbot, which heavily relies on the "Closes:" tags to associate 137 130 reports for regression with changes resolving them. 138 131 139 132 Expectations and best practices for fixing regressions ··· 333 326 334 327 The bot watches for replies to reports of tracked regressions. Additionally, 335 328 it's looking out for posted or committed patches referencing such reports 336 - with "Link:" tags; replies to such patch postings are tracked as well. 329 + with "Closes:" tags; replies to such patch postings are tracked as well. 337 330 Combined this data provides good insights into the current state of the fixing 338 331 process. 339 332 ··· 345 338 346 339 For developers there normally is no extra work involved, they just need to make 347 340 sure to do something that was expected long before regzbot came to light: add 348 - "Link:" tags to the patch description pointing to all reports about the issue 349 - fixed. 341 + links to the patch description pointing to all reports about the issue fixed. 350 342 351 343 Do I have to use regzbot? 352 344 ~~~~~~~~~~~~~~~~~~~~~~~~~
+5 -5
Documentation/process/howto.rst
··· 331 331 testing repository exists into which virtually all subsystem trees are 332 332 pulled on an almost daily basis: 333 333 334 - https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git 334 + https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git 335 335 336 336 This way, the linux-next gives a summary outlook onto what will be 337 337 expected to go into the mainline kernel at the next merge period. ··· 373 373 developers participate on the Linux Kernel Mailing list. Details on how 374 374 to subscribe and unsubscribe from the list can be found at: 375 375 376 - http://vger.kernel.org/vger-lists.html#linux-kernel 376 + https://subspace.kernel.org/subscribing.html 377 377 378 378 There are archives of the mailing list on the web in many different 379 379 places. Use a search engine to find these archives. For example: 380 380 381 - https://lore.kernel.org/lkml/ 381 + https://lore.kernel.org/linux-kernel/ 382 382 383 383 It is highly recommended that you search the archives about the topic 384 384 you want to bring up, before you post it to the list. A lot of things ··· 393 393 Many of the lists are hosted on kernel.org. Information on them can be 394 394 found at: 395 395 396 - http://vger.kernel.org/vger-lists.html 396 + https://subspace.kernel.org 397 397 398 398 Please remember to follow good behavioral habits when using the lists. 399 399 Though a bit cheesy, the following URL has some simple guidelines for 400 400 interacting with the list (or any list): 401 401 402 - http://www.albion.com/netiquette/ 402 + https://subspace.kernel.org/etiquette.html 403 403 404 404 If multiple people respond to your mail, the CC: list of recipients may 405 405 get pretty large. Don't remove anybody from the CC: list without a good
-11
Documentation/process/index.rst
··· 107 107 kernel-docs 108 108 deprecated 109 109 110 - These are some overall technical guides that have been put here for now for 111 - lack of a better place. 112 - 113 - .. toctree:: 114 - :maxdepth: 1 115 - 116 - magic-number 117 - clang-format 118 - ../arch/riscv/patch-acceptance 119 - ../core-api/unaligned-memory-access 120 - 121 110 .. only:: subproject and html 122 111 123 112 Indices
+46 -27
Documentation/process/kernel-docs.rst
··· 3 3 Index of Further Kernel Documentation 4 4 ===================================== 5 5 6 - The need for a document like this one became apparent in the 7 - linux-kernel mailing list as the same questions, asking for pointers 8 - to information, appeared again and again. 6 + The need for a document like this one became apparent in the linux-kernel 7 + mailing list as the same questions, asking for pointers to information, 8 + appeared again and again. 9 9 10 - Fortunately, as more and more people get to GNU/Linux, more and more 11 - get interested in the Kernel. But reading the sources is not always 12 - enough. It is easy to understand the code, but miss the concepts, the 13 - philosophy and design decisions behind this code. 10 + Fortunately, as more and more people get to GNU/Linux, more and more get 11 + interested in the Kernel. But reading the sources is not always enough. It 12 + is easy to understand the code, but miss the concepts, the philosophy and 13 + design decisions behind this code. 14 14 15 - Unfortunately, not many documents are available for beginners to 16 - start. And, even if they exist, there was no "well-known" place which 17 - kept track of them. These lines try to cover this lack. 15 + Unfortunately, not many documents are available for beginners to start. 16 + And, even if they exist, there was no "well-known" place which kept track 17 + of them. These lines try to cover this lack. 18 18 19 19 PLEASE, if you know any paper not listed here or write a new document, 20 20 include a reference to it here, following the kernel's patch submission 21 21 process. Any corrections, ideas or comments are also welcome. 22 22 23 23 All documents are cataloged with the following fields: the document's 24 - "Title", the "Author"/s, the "URL" where they can be found, some 25 - "Keywords" helpful when searching for specific topics, and a brief 26 - "Description" of the Document. 24 + "Title", the "Author"/s, the "URL" where they can be found, some "Keywords" 25 + helpful when searching for specific topics, and a brief "Description" of 26 + the Document. 27 27 28 28 .. note:: 29 29 ··· 72 72 programming. Lots of examples. Currently the new version is being 73 73 actively maintained at https://github.com/sysprog21/lkmpg. 74 74 75 + * Title: **Rust for Linux** 76 + 77 + :Author: various 78 + :URL: https://rust-for-linux.com/ 79 + :Date: rolling version 80 + :Keywords: glossary, terms, linux-kernel. 81 + :Description: From the website: "Rust for Linux is the project adding 82 + support for the Rust language to the Linux kernel. This website is 83 + intended as a hub of links, documentation and resources related to 84 + the project". 85 + 75 86 Published books 76 87 --------------- 88 + 89 + * Title: **Practical Linux System Administration: A Guide to Installation, Configuration, and Management, 1st Edition** 90 + 91 + :Author: Kenneth Hess 92 + :Publisher: O'Reilly Media 93 + :Date: May, 2023 94 + :Pages: 246 95 + :ISBN: 978-1098109035 96 + :Notes: System administration 77 97 78 98 * Title: **Linux Kernel Debugging: Leverage proven tools and advanced techniques to effectively debug Linux kernels and kernel modules** 79 99 ··· 108 88 109 89 :Author: Kaiwan N Billimoria 110 90 :Publisher: Packt Publishing Ltd 111 - :Date: March, 2021 91 + :Date: March, 2021 (Second Edition published in 2024) 112 92 :Pages: 754 113 - :ISBN: 978-1789953435 93 + :ISBN: 978-1789953435 (Second Edition ISBN is 978-1803232225) 114 94 115 95 * 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** 116 96 ··· 137 117 :Pages: 440 138 118 :ISBN: 978-0672329463 139 119 :Notes: Foundational book 140 - 141 - * Title: **Practical Linux System Administration: A Guide to Installation, Configuration, and Management, 1st Edition** 142 - 143 - :Author: Kenneth Hess 144 - :Publisher: O'Reilly Media 145 - :Date: May, 2023 146 - :Pages: 246 147 - :ISBN: 978-1098109035 148 - :Notes: System administration 149 120 150 121 .. _ldd3_published: 151 122 ··· 205 194 206 195 * Name: **linux-kernel mailing list archives and search engines** 207 196 208 - :URL: http://vger.kernel.org/vger-lists.html 209 - :URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html 210 - :URL: http://groups.google.com/group/mlist.linux.kernel 197 + :URL: https://subspace.kernel.org 198 + :URL: https://lore.kernel.org 211 199 :Keywords: linux-kernel, archives, search. 212 200 :Description: Some of the linux-kernel mailing list archivers. If 213 201 you have a better/another one, please let me know. 202 + 203 + * Name: **The Linux Foundation YouTube channel** 204 + 205 + :URL: https://www.youtube.com/user/thelinuxfoundation 206 + :Keywords: linux, videos, linux-foundation, youtube. 207 + :Description: The Linux Foundation uploads video recordings of their 208 + collaborative events, Linux conferences including LinuxCon, and 209 + other original research and content related to Linux and software 210 + development. 214 211 215 212 ------- 216 213
Documentation/process/magic-number.rst Documentation/staging/magic-number.rst
+2 -3
Documentation/process/maintainer-netdev.rst
··· 25 25 Note that some subsystems (e.g. wireless drivers) which have a high 26 26 volume of traffic have their own specific mailing lists and trees. 27 27 28 - The netdev list is managed (like many other Linux mailing lists) through 29 - VGER (http://vger.kernel.org/) with archives available at 30 - https://lore.kernel.org/netdev/ 28 + Like many other Linux mailing lists, the netdev list is hosted at 29 + kernel.org with archives available at https://lore.kernel.org/netdev/. 31 30 32 31 Aside from subsystems like those mentioned above, all network-related 33 32 Linux development (i.e. RFC, review, comments, etc.) takes place on
+22 -8
Documentation/process/maintainer-tip.rst
··· 372 372 373 373 - Link: ``https://link/to/information`` 374 374 375 - For referring to an email on LKML or other kernel mailing lists, 376 - please use the lore.kernel.org redirector URL:: 375 + For referring to an email posted to the kernel mailing lists, please 376 + use the lore.kernel.org redirector URL:: 377 377 378 - https://lore.kernel.org/r/email-message@id 378 + Link: https://lore.kernel.org/email-message-id@here 379 379 380 - The kernel.org redirector is considered a stable URL, unlike other email 381 - archives. 380 + This URL should be used when referring to relevant mailing list 381 + topics, related patch sets, or other notable discussion threads. 382 + A convenient way to associate ``Link:`` trailers with the commit 383 + message is to use markdown-like bracketed notation, for example:: 382 384 383 - Maintainers will add a Link tag referencing the email of the patch 384 - submission when they apply a patch to the tip tree. This tag is useful 385 - for later reference and is also used for commit notifications. 385 + A similar approach was attempted before as part of a different 386 + effort [1], but the initial implementation caused too many 387 + regressions [2], so it was backed out and reimplemented. 388 + 389 + Link: https://lore.kernel.org/some-msgid@here # [1] 390 + Link: https://bugzilla.example.org/bug/12345 # [2] 391 + 392 + You can also use ``Link:`` trailers to indicate the origin of the 393 + patch when applying it to your git tree. In that case, please use the 394 + dedicated ``patch.msgid.link`` domain instead of ``lore.kernel.org``. 395 + This practice makes it possible for automated tooling to identify 396 + which link to use to retrieve the original patch submission. For 397 + example:: 398 + 399 + Link: https://patch.msgid.link/patch-source-message-id@here 386 400 387 401 Please do not use combined tags, e.g. ``Reported-and-tested-by``, as 388 402 they just complicate automated extraction of tags.
+5 -10
Documentation/process/submitting-patches.rst
··· 119 119 120 120 When linking to mailing list archives, preferably use the lore.kernel.org 121 121 message archiver service. To create the link URL, use the contents of the 122 - ``Message-Id`` header of the message without the surrounding angle brackets. 122 + ``Message-ID`` header of the message without the surrounding angle brackets. 123 123 For example:: 124 124 125 - Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ 125 + Link: https://lore.kernel.org/30th.anniversary.repost@klaava.Helsinki.FI 126 126 127 127 Please check the link to make sure that it is actually working and points 128 128 to the relevant message. ··· 243 243 volume on that list has caused a number of developers to tune it out. Please 244 244 do not spam unrelated lists and unrelated people, though. 245 245 246 - Many kernel-related lists are hosted on vger.kernel.org; you can find a 247 - list of them at http://vger.kernel.org/vger-lists.html. There are 248 - kernel-related lists hosted elsewhere as well, though. 249 - 250 - Do not send more than 15 patches at once to the vger mailing lists!!! 246 + Many kernel-related lists are hosted at kernel.org; you can find a list 247 + of them at https://subspace.kernel.org. There are kernel-related lists 248 + hosted elsewhere as well, though. 251 249 252 250 Linus Torvalds is the final arbiter of all changes accepted into the 253 251 Linux kernel. His e-mail address is <torvalds@linux-foundation.org>. ··· 863 865 <http://www.kroah.com/log/linux/maintainer-05.html> 864 866 865 867 <http://www.kroah.com/log/linux/maintainer-06.html> 866 - 867 - NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! 868 - <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net> 869 868 870 869 Kernel Documentation/process/coding-style.rst 871 870
+2
Documentation/scheduler/sched-design-CFS.rst
··· 1 + .. _sched_design_CFS: 2 + 1 3 ============= 2 4 CFS Scheduler 3 5 =============
+1
Documentation/staging/index.rst
··· 8 8 9 9 crc32 10 10 lzo 11 + magic-number 11 12 remoteproc 12 13 rpmsg 13 14 speculation
+3 -3
Documentation/tools/rv/rv-mon.rst
··· 1 1 .. SPDX-License-Identifier: GPL-2.0 2 2 3 - ======= 4 - rv-list 5 - ======= 3 + ====== 4 + rv-mon 5 + ====== 6 6 ----------------------- 7 7 List available monitors 8 8 -----------------------
+44
Documentation/translations/it_IT/doc-guide/kernel-doc.rst
··· 370 370 */ 371 371 typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); 372 372 373 + Documentazione di macro simili a oggetti 374 + ---------------------------------------- 375 + 376 + Le macro simili a oggetti si distinguono dalle macro simili a funzione. Esse si 377 + distinguono in base al fatto che il nome della macro simile a funzione sia 378 + immediatamente seguito da una parentesi sinistra ('(') mentre in quelle simili a 379 + oggetti no. 380 + 381 + Le macro simili a funzioni sono gestite come funzioni da ``scripts/kernel-doc``. 382 + Possono avere un elenco di parametri. Le macro simili a oggetti non hanno un 383 + elenco di parametri. 384 + 385 + Il formato generale di un commento kernel-doc per una macro simile a oggetti è:: 386 + 387 + /** 388 + * define object_name - Brief description. 389 + * 390 + * Description of the object. 391 + */ 392 + 393 + Esempio:: 394 + 395 + /** 396 + * define MAX_ERRNO - maximum errno value that is supported 397 + * 398 + * Kernel pointers have redundant information, so we can use a 399 + * scheme where we can return either an error code or a normal 400 + * pointer with the same return value. 401 + */ 402 + #define MAX_ERRNO 4095 403 + 404 + Esempio:: 405 + 406 + /** 407 + * define DRM_GEM_VRAM_PLANE_HELPER_FUNCS - \ 408 + * Initializes struct drm_plane_helper_funcs for VRAM handling 409 + * 410 + * This macro initializes struct drm_plane_helper_funcs to use the 411 + * respective helper functions. 412 + */ 413 + #define DRM_GEM_VRAM_PLANE_HELPER_FUNCS \ 414 + .prepare_fb = drm_gem_vram_plane_helper_prepare_fb, \ 415 + .cleanup_fb = drm_gem_vram_plane_helper_cleanup_fb 416 + 373 417 Marcatori e riferimenti 374 418 ----------------------- 375 419
+1 -1
Documentation/translations/it_IT/doc-guide/parse-headers.rst
··· 63 63 *********** 64 64 65 65 Converte un file d'intestazione o un file sorgente C (C_FILE) in un testo 66 - ReStructuredText incluso mediante il blocco ..parsed-literal 66 + reStructuredText incluso mediante il blocco ..parsed-literal 67 67 con riferimenti alla documentazione che descrive l'API. Opzionalmente, 68 68 il programma accetta anche un altro file (EXCEPTIONS_FILE) che 69 69 descrive quali elementi debbano essere ignorati o il cui riferimento
+23 -4
Documentation/translations/it_IT/process/5.Posting.rst
··· 223 223 Fixes: 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID") 224 224 225 225 Un'altra etichetta viene usata per fornire collegamenti a pagine web contenenti 226 - maggiori informazioni, per esempio un rapporto circa il baco risolto dalla 227 - patch, oppure un documento con le specifiche implementate dalla patch:: 226 + maggiori informazioni, per esempio una discussione avvenuta precedentemente 227 + circa il baco risolto dalla patch, oppure un documento con le specifiche 228 + implementate dalla patch:: 228 229 229 230 Link: https://example.com/somewhere.html optional-other-stuff 230 231 ··· 234 233 alcuni strumenti come b4 or un *hook* git come quello descritto qui 235 234 'Documentation/translations/it_IT/maintainer/configure-git.rst' 236 235 237 - Un terzo tipo di etichetta viene usato per indicare chi ha contribuito allo 236 + 237 + Se il collegamento indirizza verso un rapporto su un baco risolto dalla patch, 238 + allora usate l'etichetta "Closes:":: 239 + 240 + Closes: https://example.com/issues/1234 optional-other-stuff 241 + 242 + Alcune piattaforme di tracciamento di bachi hanno la capacità di chiudere 243 + automaticamente il problema se l'etichetta è presente nel messaggio. Alcuni 244 + automatismi che monitorano la liste di discussione possono anche tracciare 245 + queste etichette e intraprendere azioni. Piattaforme private e URL invalidi sono 246 + proibiti. 247 + 248 + Un altro tipo di etichetta viene usato per indicare chi ha contribuito allo 238 249 sviluppo della patch. Tutte queste etichette seguono il formato:: 239 250 240 251 tag: Full Name <email address> optional-other-stuff ··· 280 267 - Reported-by: menziona l'utente che ha riportato il problema corretto da 281 268 questa patch; quest'etichetta viene usata per dare credito alle persone che 282 269 hanno verificato il codice e ci hanno fatto sapere quando le cose non 283 - funzionavano correttamente. Se esiste un rapporto disponibile sul web, allora 270 + funzionavano correttamente. Questa etichetta dovrebbe essere seguita da 271 + quella Closes: con un indirizzo al rapporto, a meno che questo non sia 272 + disponibile sul web. L'etichetta Link: può essere usata in alternativa a 273 + Closes: se la patch corregge solo in parte il problema riportato nel 274 + rapporto. 275 + 276 + Se esiste un rapporto disponibile sul web, allora 284 277 L'etichetta dovrebbe essere seguita da un collegamento al suddetto rapporto. 285 278 286 279 - Cc: la persona menzionata ha ricevuto una copia della patch ed ha avuto
+7
Documentation/translations/it_IT/process/6.Followthrough.rst
··· 60 60 stanno lavorando per la creazione del miglior kernel possibile; non 61 61 stanno cercando di creare un disagio ad aziende concorrenti. 62 62 63 + - Preparatevi a richieste apparentemente sciocche di modifiche allo stile di 64 + codifica e a richieste di trasferire parte del vostro codice in parti 65 + condivise del kernel. Uno dei compiti dei manutentori è quello di mantenere 66 + lo aspetto del codice. A volte questo significa che l'ingegnoso stratagemma 67 + nel vostro driver per aggirare un problema deve diventare una caratteristica 68 + generalizzata del kernel pronta per essere riutilizzata. 69 + 63 70 Quello che si sta cercando di dire è che, quando i revisori vi inviano degli 64 71 appunti dovete fare attenzione alle osservazioni tecniche che vi stanno 65 72 facendo. Non lasciate che il loro modo di esprimersi o il vostro orgoglio
+1 -1
Documentation/translations/it_IT/process/7.AdvancedTopics.rst
··· 200 200 accetta e di valore, se porta ad avere un codice migliore nel kernel. 201 201 202 202 Non esistono requisiti particolarmente stringenti per l'uso di etichette come 203 - ``Reviewd-by``. Tuttavia, perché la revisione sia efficace ci si aspetta un 203 + ``Reviewed-by``. Tuttavia, perché la revisione sia efficace ci si aspetta un 204 204 qualche tipo di messaggio che dica "ho verificato A, B e C nel codice che è 205 205 appena stato inviato e mi sembra tutto in ordine". Inoltre, questo permette ai 206 206 manutentori di prendere conoscenza circa una revisione avvenuta per davvero.
+2 -2
Documentation/translations/it_IT/process/changes.rst
··· 33 33 Programma Versione minima Comando per verificare la versione 34 34 ====================== ================= ======================================== 35 35 GNU C 5.1 gcc --version 36 - Clang/LLVM (optional) 11.0.0 clang --version 37 - Rust (opzionale) 1.74.1 rustc --version 36 + Clang/LLVM (optional) 13.0.0 clang --version 37 + Rust (opzionale) 1.76.0 rustc --version 38 38 bindgen (opzionale) 0.65.1 bindgen --version 39 39 GNU make 3.81 make --version 40 40 bash 4.2 bash --version
+1 -1
Documentation/translations/it_IT/process/clang-format.rst
··· 1 1 .. include:: ../disclaimer-ita.rst 2 2 3 - :Original: :ref:`Documentation/process/clang-format.rst <clangformat>` 3 + :Original: :ref:`Documentation/dev-tools/clang-format.rst <clangformat>` 4 4 :Translator: Federico Vaga <federico.vaga@vaga.pv.it> 5 5 6 6 .. _it_clangformat:
+1 -1
Documentation/translations/it_IT/process/index.rst
··· 107 107 108 108 magic-number 109 109 clang-format 110 - ../riscv/patch-acceptance 110 + ../arch/riscv/patch-acceptance 111 111 112 112 .. only:: subproject and html 113 113
+1 -1
Documentation/translations/it_IT/process/magic-number.rst
··· 1 1 .. include:: ../disclaimer-ita.rst 2 2 3 - :Original: :ref:`Documentation/process/magic-number.rst <magicnumbers>` 3 + :Original: :ref:`Documentation/staging/magic-number.rst <magicnumbers>` 4 4 :Translator: Federico Vaga <federico.vaga@vaga.pv.it> 5 5 6 6 .. _it_magicnumbers:
+174 -148
Documentation/translations/it_IT/process/stable-kernel-rules.rst
··· 11 11 Regole sul tipo di patch che vengono o non vengono accettate nei sorgenti 12 12 "-stable": 13 13 14 - - Ovviamente dev'essere corretta e verificata. 15 - - Non dev'essere più grande di 100 righe, incluso il contesto. 16 - - Deve correggere una cosa sola. 17 - - Deve correggere un baco vero che sta disturbando gli utenti (non cose del 18 - tipo "Questo potrebbe essere un problema ..."). 19 - - Deve correggere un problema di compilazione (ma non per cose già segnate 20 - con CONFIG_BROKEN), un kernel oops, un blocco, una corruzione di dati, 21 - un vero problema di sicurezza, o problemi del tipo "oh, questo non va bene". 22 - In pratica, qualcosa di critico. 23 - - Problemi importanti riportati dagli utenti di una distribuzione potrebbero 24 - essere considerati se correggono importanti problemi di prestazioni o di 25 - interattività. Dato che questi problemi non sono così ovvi e la loro 26 - correzione ha un'alta probabilità d'introdurre una regressione, dovrebbero 27 - essere sottomessi solo dal manutentore della distribuzione includendo un 28 - link, se esiste, ad un rapporto su bugzilla, e informazioni aggiuntive 29 - sull'impatto che ha sugli utenti. 30 - - Non deve correggere problemi relativi a una "teorica sezione critica", 31 - a meno che non venga fornita anche una spiegazione su come questa si 32 - possa verificare. 33 - - Non deve includere alcuna correzione "banale" (correzioni grammaticali, 34 - pulizia dagli spazi bianchi, eccetera). 35 - - Deve rispettare le regole scritte in 36 - :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>` 37 - - Questa patch o una equivalente deve esistere già nei sorgenti principali di 38 - Linux 14 + - Questa patch o una equivalente deve esistere già nei sorgenti principali di 15 + Linux (upstream) 16 + - Ovviamente dev'essere corretta e verificata. 17 + - Non dev'essere più grande di 100 righe, incluso il contesto. 18 + - Deve rispettare le regole scritte in 19 + :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>` 20 + - Deve correggere un vero baco che causi problemi agli utenti oppure aggiunge 21 + un nuovo identificatore di dispositivo. Maggiori dettagli per il primo caso: 39 22 23 + - Corregge un problema come un oops, un blocco, una corruzione di dati, un 24 + vero problema di sicurezza, una stranezza hardware, un problema di 25 + compilazione (ma non per cose già segnate con CONFIG_BROKEN), o problemi 26 + del tipo "oh, questo non va bene". 27 + - Problemi importanti riportati dagli utenti di una distribuzione potrebbero 28 + essere considerati se correggono importanti problemi di prestazioni o di 29 + interattività. Dato che questi problemi non sono così ovvi e la loro 30 + correzione ha un'alta probabilità d'introdurre una regressione, 31 + dovrebbero essere sottomessi solo dal manutentore della distribuzione 32 + includendo un link, se esiste, ad un rapporto su bugzilla, e informazioni 33 + aggiuntive sull'impatto che ha sugli utenti. 34 + - Non si accettano cose del tipo "Questo potrebbe essere un problema ..." 35 + come una teorica sezione critica, senza aver fornito anche una spiegazione 36 + su come il baco possa essere sfruttato. 37 + - Non deve includere alcuna correzione "banale" (correzioni grammaticali, 38 + pulizia dagli spazi bianchi, eccetera). 40 39 41 40 Procedura per sottomettere patch per i sorgenti -stable 42 41 ------------------------------------------------------- ··· 45 46 di revisione -stable, ma dovrebbe seguire le procedure descritte in 46 47 :ref:`Documentation/translations/it_IT/process/security-bugs.rst <it_securitybugs>`. 47 48 48 - Per tutte le altre sottomissioni, scegliere una delle seguenti procedure 49 - ------------------------------------------------------------------------ 49 + Ci sono tre opzioni per inviare una modifica per i sorgenti -stable: 50 + 51 + 1. Aggiungi un'etichetta 'stable' alla descrizione della patch al momento della 52 + sottomissione per l'inclusione nei sorgenti principali. 53 + 2. Chiedere alla squadra "stable" di prendere una patch già applicata sui 54 + sorgenti principali 55 + 3. Sottomettere una patch alla squadra "stable" equivalente ad una modifica già 56 + fatta sui sorgenti principali. 57 + 58 + Le seguenti sezioni descrivono con maggiori dettagli ognuna di queste opzioni 59 + 60 + L':ref:`it_option_1` è **fortemente** raccomandata; è il modo più facile e 61 + usato. L':ref:`it_option_2` si usa quando al momento della sottomissione non si 62 + era pensato di riportare la modifica su versioni precedenti. 63 + L':ref:`it_option_3` è un'alternativa ai due metodi precedenti quando la patch 64 + nei sorgenti principali ha bisogno di aggiustamenti per essere applicata su 65 + versioni precedenti (per esempio a causa di cambiamenti dell'API). 66 + 67 + Quando si utilizza l'opzione 2 o 3 è possibile chiedere che la modifica sia 68 + inclusa in specifiche versioni stabili. In tal caso, assicurarsi che la correzione 69 + o una equivalente sia applicabile, o già presente in tutti i sorgenti 70 + stabili più recenti ancora supportati. Questo ha lo scopo di prevenire 71 + regressioni che gli utenti potrebbero incontrare in seguito durante 72 + l'aggiornamento, se ad esempio una correzione per 5.19-rc1 venisse 73 + riportata a 5.10.y, ma non a 5.15.y. 50 74 51 75 .. _it_option_1: 52 76 53 77 Opzione 1 54 78 ********* 55 79 56 - Per far sì che una patch venga automaticamente inclusa nei sorgenti stabili, 57 - aggiungete l'etichetta 80 + Aggiungete la seguente etichetta nell'area delle firme per far sì che una patch 81 + che state inviando per l'inclusione nei sorgenti principali venga presa 82 + automaticamente anche per quelli stabili:: 58 83 59 - .. code-block:: none 84 + Cc: stable@vger.kernel.org 60 85 61 - Cc: stable@vger.kernel.org 86 + Invece, usate ``Cc: stable@vger.kernel.org`` quando state inviando correzioni 87 + per vulnerabilità non ancora di pubblico dominio: questo riduce il rischio di 88 + esporre accidentalmente al pubblico la correzione quando si usa 'git 89 + send-email', perché i messaggi inviati a quell'indirizzo non vengono inviati da 90 + nessuna parte. 62 91 63 - nell'area dedicata alla firme. Una volta che la patch è stata inclusa, verrà 64 - applicata anche sui sorgenti stabili senza che l'autore o il manutentore 65 - del sottosistema debba fare qualcosa. 92 + Una volta che la patch è stata inclusa, verrà applicata anche sui sorgenti 93 + stabili senza che l'autore o il manutentore del sottosistema debba fare 94 + qualcosa. 95 + 96 + Per lasciare una nota per la squadra "stable", usate commenti in linea in stile 97 + shell (leggere oltre per maggiori dettagli). 98 + 99 + * Specificate i prerequisiti per le patch aggiuntive:: 100 + 101 + Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle 102 + Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle 103 + Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic 104 + Cc: <stable@vger.kernel.org> # 3.3.x 105 + Signed-off-by: Ingo Molnar <mingo@elte.hu> 106 + 107 + La sequenza di etichette ha il seguente significato:: 108 + 109 + git cherry-pick a1f84a3 110 + git cherry-pick 1b9508f 111 + git cherry-pick fd21073 112 + git cherry-pick <this commit> 113 + 114 + Notate che per una serie di patch non dovere elencare come necessarie tutte 115 + le patch della serie stessa. Per esempio se avete la seguente serie:: 116 + 117 + patch1 118 + patch2 119 + 120 + dove patch2 dipende da patch1, non dovete elencare patch1 come requisito per 121 + patch2 se avete già menzionato patch1 per l'inclusione in "stable" 122 + 123 + * Evidenziate le patch che hanno dei requisiti circa la versione del kernel:: 124 + 125 + Cc: <stable@vger.kernel.org> # 3.3.x 126 + 127 + L'etichetta ha il seguente significato:: 128 + 129 + git cherry-pick <this commit> 130 + 131 + per ogni sorgente "-stable" che inizia con la versione indicata. 132 + 133 + Notate che queste etichette non sono necessarie se la squadre "stable" può 134 + dedurre la versione dalle etichette Fixes: 135 + 136 + * Ritardare l'inclusione di patch:: 137 + Cc: <stable@vger.kernel.org> # after -rc3 138 + 139 + * Evidenziare problemi noti:: 140 + 141 + Cc: <stable@vger.kernel.org> # see patch description, needs adjustments for <= 6.3 142 + 143 + Esiste un'ulteriore variante per l'etichetta "stable" che permette di comunicare 144 + allo strumento di *backporting* di ignorare un cambiamento:: 145 + 146 + Cc: <stable+noautosel@kernel.org> # reason goes here, and must be present 147 + 66 148 67 149 .. _it_option_2: 68 150 69 151 Opzione 2 70 152 ********* 71 153 72 - Dopo che la patch è stata inclusa nei sorgenti Linux, inviate una mail a 154 + Se la patch è già stata inclusa nei sorgenti Linux, inviate una mail a 73 155 stable@vger.kernel.org includendo: il titolo della patch, l'identificativo 74 - del commit, il perché pensate che debba essere applicata, e in quale versione 156 + del commit, il perché pensate che debba essere applicata, e in quali versioni 75 157 del kernel la vorreste vedere. 76 158 77 159 .. _it_option_3: ··· 160 80 Opzione 3 161 81 ********* 162 82 163 - Inviata la patch, dopo aver verificato che rispetta le regole descritte in 164 - precedenza, a stable@vger.kernel.org. Dovete annotare nel changelog 165 - l'identificativo del commit nei sorgenti principali, così come la versione 166 - del kernel nel quale vorreste vedere la patch. 167 - 168 - L':ref:`it_option_1` è fortemente raccomandata; è il modo più facile e usato. 169 - L':ref:`it_option_2` e l':ref:`it_option_3` sono più utili quando, al momento 170 - dell'inclusione dei sorgenti principali, si ritiene che non debbano essere 171 - incluse anche in quelli stabili (per esempio, perché si crede che si dovrebbero 172 - fare più verifiche per eventuali regressioni). L':ref:`it_option_3` è 173 - particolarmente utile se una patch dev'essere riportata su una versione 174 - precedente (per esempio la patch richiede modifiche a causa di cambiamenti di 175 - API). 176 - 177 - Notate che per l':ref:`it_option_3`, se la patch è diversa da quella nei 178 - sorgenti principali (per esempio perché è stato necessario un lavoro di 179 - adattamento) allora dev'essere ben documentata e giustificata nella descrizione 180 - della patch. 181 - 182 - L'identificativo del commit nei sorgenti principali dev'essere indicato sopra 183 - al messaggio della patch, così: 184 - 185 - .. code-block:: none 83 + Dopo aver verificato che rispetta le regole descritte in precedenza, inviata la 84 + patch a stable@vger.kernel.org facendo anche menzione delle versioni nella quale 85 + si vorrebbe applicarla. Nel farlo, dovete annotare nel changelog 86 + l'identificativo del commit nei sorgenti principali, così come la versione del 87 + kernel nel quale vorreste vedere la patch.:: 186 88 187 89 commit <sha1> upstream. 188 90 189 - o in alternativa: 190 - 191 - .. code-block:: none 91 + o in alternativa:: 192 92 193 93 [ Upstream commit <sha1> ] 194 94 195 - In aggiunta, alcune patch inviate attraverso l':ref:`it_option_1` potrebbero 196 - dipendere da altre che devo essere incluse. Questa situazione può essere 197 - indicata nel seguente modo nell'area dedicata alle firme: 95 + Se la patch inviata devia rispetto all'originale presente nei sorgenti 96 + principali (per esempio per adattarsi ad un cambiamento di API), allora questo 97 + dev'essere giustificato e dettagliato in modo chiaro nella descrizione. 198 98 199 - .. code-block:: none 99 + Dopo la sottomissione 100 + --------------------- 200 101 201 - Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle 202 - Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle 203 - Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic 204 - Cc: <stable@vger.kernel.org> # 3.3.x 205 - Signed-off-by: Ingo Molnar <mingo@elte.hu> 102 + Il mittente riceverà un ACK quando la patch è stata accettata e messa in coda, 103 + oppure un NAK se la patch è stata rigettata. La risposta potrebbe richiedere 104 + alcuni giorni in funzione dei piani dei membri della squadra "stable", 206 105 207 - La sequenza di etichette ha il seguente significato: 208 - 209 - .. code-block:: none 210 - 211 - git cherry-pick a1f84a3 212 - git cherry-pick 1b9508f 213 - git cherry-pick fd21073 214 - git cherry-pick <this commit> 215 - 216 - Inoltre, alcune patch potrebbero avere dei requisiti circa la versione del 217 - kernel. Questo può essere indicato usando il seguente formato nell'area 218 - dedicata alle firme: 219 - 220 - .. code-block:: none 221 - 222 - Cc: <stable@vger.kernel.org> # 3.3.x 223 - 224 - L'etichetta ha il seguente significato: 225 - 226 - .. code-block:: none 227 - 228 - git cherry-pick <this commit> 229 - 230 - per ogni sorgente "-stable" che inizia con la versione indicata. 231 - 232 - Dopo la sottomissione: 233 - 234 - - Il mittente riceverà un ACK quando la patch è stata accettata e messa in 235 - coda, oppure un NAK se la patch è stata rigettata. A seconda degli impegni 236 - degli sviluppatori, questa risposta potrebbe richiedere alcuni giorni. 237 - - Se accettata, la patch verrà aggiunta alla coda -stable per essere 238 - revisionata dal altri sviluppatori e dal principale manutentore del 239 - sottosistema. 240 - 106 + Se accettata, la patch verrà aggiunta alla coda -stable per essere revisionata 107 + dal altri sviluppatori e dal principale manutentore del sottosistema. 241 108 242 109 Ciclo di una revisione 243 110 ---------------------- 244 111 245 - - Quando i manutentori -stable decidono di fare un ciclo di revisione, le 246 - patch vengono mandate al comitato per la revisione, ai manutentori soggetti 247 - alle modifiche delle patch (a meno che il mittente non sia anche il 248 - manutentore di quell'area del kernel) e in CC: alla lista di discussione 249 - linux-kernel. 250 - - La commissione per la revisione ha 48 ore per dare il proprio ACK o NACK 251 - alle patch. 252 - - Se una patch viene rigettata da un membro della commissione, o un membro 253 - della lista linux-kernel obietta la bontà della patch, sollevando problemi 254 - che i manutentori ed i membri non avevano compreso, allora la patch verrà 255 - rimossa dalla coda. 256 - - Le patch che hanno ricevuto un ACK verranno inviate nuovamente come parte di 257 - un rilascio candidato (-rc) al fine di essere verificate dagli sviluppatori e 258 - dai testatori. 259 - - Solitamente si pubblica solo una -rc, tuttavia se si riscontrano problemi 260 - importanti, alcune patch potrebbero essere modificate o essere scartate, 261 - oppure nuove patch potrebbero essere messe in coda. Dunque, verranno pubblicate 262 - nuove -rc e così via finché non si ritiene che non vi siano più problemi. 263 - - Si può rispondere ad una -rc scrivendo sulla lista di discussione un'email 264 - con l'etichetta "Tested-by:". Questa etichetta verrà raccolta ed aggiunta al 265 - commit rilascio. 266 - - Alla fine del ciclo di revisione il nuovo rilascio -stable conterrà tutte le 267 - patch che erano in coda e sono state verificate. 268 - - Le patch di sicurezza verranno accettate nei sorgenti -stable direttamente 269 - dalla squadra per la sicurezza del kernel, e non passerà per il normale 270 - ciclo di revisione. Contattate la suddetta squadra per maggiori dettagli 271 - su questa procedura. 112 + - Quando i manutentori -stable decidono di fare un ciclo di revisione, le 113 + patch vengono mandate al comitato per la revisione, ai manutentori soggetti 114 + alle modifiche delle patch (a meno che il mittente non sia anche il 115 + manutentore di quell'area del kernel) e in CC: alla lista di discussione 116 + linux-kernel. 117 + - La commissione per la revisione ha 48 ore per dare il proprio ACK o NACK 118 + alle patch. 119 + - Se una patch viene rigettata da un membro della commissione, o un membro 120 + della lista linux-kernel obietta la bontà della patch, sollevando problemi 121 + che i manutentori ed i membri non avevano compreso, allora la patch verrà 122 + rimossa dalla coda. 123 + - Le patch che hanno ricevuto un ACK verranno inviate nuovamente come parte di 124 + un rilascio candidato (-rc) al fine di essere verificate dagli sviluppatori e 125 + dai testatori. 126 + - Solitamente si pubblica solo una -rc, tuttavia se si riscontrano problemi 127 + importanti, alcune patch potrebbero essere modificate o essere scartate, 128 + oppure nuove patch potrebbero essere messe in coda. Dunque, verranno pubblicate 129 + nuove -rc e così via finché non si ritiene che non vi siano più problemi. 130 + - Si può rispondere ad una -rc scrivendo sulla lista di discussione un'email 131 + con l'etichetta "Tested-by:". Questa etichetta verrà raccolta ed aggiunta al 132 + commit rilascio. 133 + - Alla fine del ciclo di revisione il nuovo rilascio -stable conterrà tutte le 134 + patch che erano in coda e sono state verificate. 135 + - Le patch di sicurezza verranno accettate nei sorgenti -stable direttamente 136 + dalla squadra per la sicurezza del kernel, e non passerà per il normale 137 + ciclo di revisione. Contattate la suddetta squadra per maggiori dettagli 138 + su questa procedura. 272 139 273 140 Sorgenti 274 141 -------- 275 142 276 - - La coda delle patch, sia quelle già applicate che in fase di revisione, 277 - possono essere trovate al seguente indirizzo: 143 + - La coda delle patch, sia quelle già applicate che in fase di revisione, 144 + possono essere trovate al seguente indirizzo: 278 145 279 - https://git.kernel.org/pub/scm/linux/kernel/git/stable/stable-queue.git 146 + https://git.kernel.org/pub/scm/linux/kernel/git/stable/stable-queue.git 280 147 281 - - Il rilascio definitivo, e marchiato, di tutti i kernel stabili può essere 282 - trovato in rami distinti per versione al seguente indirizzo: 148 + - Il rilascio definitivo, e marchiato, di tutti i kernel stabili può essere 149 + trovato in rami distinti per versione al seguente indirizzo: 283 150 284 - https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git 151 + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git 285 152 286 - - I rilasci candidati di tutti i kernel stabili possono essere trovati al 287 - seguente indirizzo: 153 + - I rilasci candidati di tutti i kernel stabili possono essere trovati al 154 + seguente indirizzo: 288 155 289 156 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable-rc.git/ 290 157 291 - 292 - .. warning:: 293 - I sorgenti -stable-rc sono un'istantanea dei sorgenti stable-queue e 294 - subirà frequenti modifiche, dunque verrà anche trapiantato spesso. 295 - Dovrebbe essere usato solo allo scopo di verifica (per esempio in un 296 - sistema di CI) 158 + .. warning:: 159 + I sorgenti -stable-rc sono un'istantanea dei sorgenti stable-queue e 160 + subirà frequenti modifiche, dunque verrà anche trapiantato spesso. 161 + Dovrebbe essere usato solo allo scopo di verifica (per esempio in un 162 + sistema di CI) 297 163 298 164 Comitato per la revisione 299 165 ------------------------- 300 166 301 - - Questo comitato è fatto di sviluppatori del kernel che si sono offerti 302 - volontari per questo lavoro, e pochi altri che non sono proprio volontari. 167 + - Questo comitato è fatto di sviluppatori del kernel che si sono offerti 168 + volontari per questo lavoro, e pochi altri che non sono proprio volontari.
+109 -26
Documentation/translations/it_IT/process/submitting-patches.rst
··· 106 106 xyzzy to do frotz", come se steste dando ordini al codice di cambiare il suo 107 107 comportamento. 108 108 109 + Se volete far riferimento a uno specifico commit, non usate solo 110 + l'identificativo SHA-1. Per cortesia, aggiungete anche la breve riga 111 + riassuntiva del commit per rendere la chiaro ai revisori l'oggetto. 112 + Per esempio:: 113 + 114 + Commit e21d2170f36602ae2708 ("video: remove unnecessary 115 + platform_set_drvdata()") removed the unnecessary 116 + platform_set_drvdata(), but left the variable "dev" unused, 117 + delete it. 118 + 119 + Dovreste anche assicurarvi di usare almeno i primi 12 caratteri 120 + dell'identificativo SHA-1. Il repositorio del kernel ha *molti* oggetti e 121 + questo rende possibile la collisione fra due identificativi con pochi 122 + caratteri. Tenete ben presente che anche se oggi non ci sono collisioni con il 123 + vostro identificativo a 6 caratteri, potrebbero essercene fra 5 anni da oggi. 124 + 109 125 Se ci sono delle discussioni, o altre informazioni d'interesse, che fanno 110 126 riferimento alla patch, allora aggiungete l'etichetta 'Link:' per farvi 111 - riferimento. Per esempio, se la vostra patch corregge un baco potete aggiungere 127 + riferimento. Se la patch è il risultato di una discussione avvenuta 128 + precedentemente o di un documento sul presente sul web, allora fatevi 129 + riferimento. 130 + 131 + Per esempio, se la vostra patch corregge un baco potete aggiungere 112 132 quest'etichetta per fare riferimento ad un rapporto su una lista di discussione 113 133 o un *bug tracker*. Un altro esempio; potete usare quest'etichetta per far 114 134 riferimento ad una discussione precedentemente avvenuta su una lista di ··· 149 129 accedere alle fonti esterne. Inoltre, riassumente i punti più salienti che hanno 150 130 condotto all'invio della patch. 151 131 152 - Se volete far riferimento a uno specifico commit, non usate solo 153 - l'identificativo SHA-1. Per cortesia, aggiungete anche la breve riga 154 - riassuntiva del commit per rendere la chiaro ai revisori l'oggetto. 155 - Per esempio:: 132 + Se il collegamento indirizza verso un rapporto su un baco risolto dalla patch, 133 + allora usate l'etichetta "Closes:":: 156 134 157 - Commit e21d2170f36602ae2708 ("video: remove unnecessary 158 - platform_set_drvdata()") removed the unnecessary 159 - platform_set_drvdata(), but left the variable "dev" unused, 160 - delete it. 135 + Closes: https://example.com/issues/1234 optional-other-stuff 161 136 162 - Dovreste anche assicurarvi di usare almeno i primi 12 caratteri 163 - dell'identificativo SHA-1. Il repositorio del kernel ha *molti* oggetti e 164 - questo rende possibile la collisione fra due identificativi con pochi 165 - caratteri. Tenete ben presente che anche se oggi non ci sono collisioni con il 166 - vostro identificativo a 6 caratteri, potrebbero essercene fra 5 anni da oggi. 137 + Alcune piattaforme di tracciamento di bachi hanno la capacità di chiudere 138 + automaticamente il problema se l'etichetta è presente nel messaggio. Alcuni 139 + automatismi che monitorano la liste di discussione possono anche tracciare 140 + queste etichette e intraprendere azioni. Piattaforme private e URL invalidi sono 141 + proibiti. 167 142 168 143 Se la vostra patch corregge un baco in un commit specifico, per esempio avete 169 144 trovato un problema usando ``git bisect``, per favore usate l'etichetta ··· 252 237 5) Selezionate i destinatari della vostra patch 253 238 ----------------------------------------------- 254 239 255 - Dovreste sempre inviare una copia della patch ai manutentori dei sottosistemi 256 - interessati dalle modifiche; date un'occhiata al file MAINTAINERS e alla storia 257 - delle revisioni per scoprire chi si occupa del codice. Lo script 258 - scripts/get_maintainer.pl può esservi d'aiuto (passategli il percorso alle 259 - vostre patch). Se non riuscite a trovare un manutentore per il sottosistema su 260 - cui state lavorando, allora Andrew Morton (akpm@linux-foundation.org) sarà la 261 - vostra ultima possibilità. 240 + Dovreste sempre inviare una copia della patch ai manutentori e alle liste di 241 + discussione dei sottosistemi interessati dalle modifiche; date un'occhiata al 242 + file MAINTAINERS e alla storia delle revisioni per scoprire chi si occupa del 243 + codice. Lo script scripts/get_maintainer.pl può esservi d'aiuto (passategli il 244 + percorso alle vostre patch). Se non riuscite a trovare un manutentore per il 245 + sottosistema su cui state lavorando, allora Andrew Morton 246 + (akpm@linux-foundation.org) sarà la vostra ultima possibilità. 247 + 248 + La lista linux-kernel@vger.kernel.org dovrebbe essere usata per l'invio di tutte 249 + le patch, ma il volume ha raggiunto un livello tale d'aver spinto alcuni 250 + sviluppatori a non seguirla più. Dunque, per favore, evitate di inviare messaggi 251 + scorrelati al tema della lista o a persone che non dovrebbero essere 252 + interessate all'argomento. 262 253 263 254 Normalmente, dovreste anche scegliere una lista di discussione a cui inviare la 264 255 vostra serie di patch. La lista di discussione linux-kernel@vger.kernel.org ··· 364 343 evidenziato. Quando inviate una versione successiva ricordatevi di aggiungere un 365 344 ``patch changelog`` alla email di intestazione o ad ogni singola patch spiegando 366 345 le differenze rispetto a sottomissioni precedenti (vedere 367 - :ref:`it_the_canonical_patch_format`). 346 + :ref:`it_the_canonical_patch_format`). Aggiungete a CC tutte le persone che 347 + vi hanno fornito dei commenti per notificarle di eventuali nuove versioni. 368 348 369 349 Leggete Documentation/translations/it_IT/process/email-clients.rst per 370 350 le raccomandazioni sui programmi di posta elettronica e l'etichetta da usare ··· 407 385 I revisori sono persone occupate e potrebbero non ricevere la vostra patch 408 386 immediatamente. 409 387 410 - Un tempo, le patch erano solite scomparire nel vuoto senza alcun commento, 411 - ma ora il processo di sviluppo funziona meglio. Dovreste ricevere commenti 412 - in una settimana o poco più; se questo non dovesse accadere, assicuratevi di 413 - aver inviato le patch correttamente. Aspettate almeno una settimana prima di 388 + Un tempo, le patch erano solite scomparire nel vuoto senza alcun commento, ma 389 + ora il processo di sviluppo funziona meglio. Dovreste ricevere commenti in poche 390 + settimane (tipicamente 2 o 3); se questo non dovesse accadere, assicuratevi di 391 + aver inviato le patch correttamente. Aspettate almeno una settimana prima di 414 392 rinviare le modifiche o sollecitare i revisori - probabilmente anche di più 415 393 durante la finestra d'integrazione. 416 394 ··· 574 552 Rammentate che se il baco è stato riportato in privato, dovrete chiedere il 575 553 permesso prima di poter utilizzare l'etichetta Reported-by. Questa etichetta va 576 554 usata per i bachi, dunque non usatela per richieste di nuove funzionalità. 555 + Questa etichetta dovrebbe essere seguita da quella Closes: con un indirizzo al 556 + rapporto, a meno che questo non sia disponibile sul web. L'etichetta Link: può 557 + essere usata in alternativa a Closes: se la patch corregge solo in parte il 558 + problema riportato nel rapporto. 577 559 578 560 L'etichetta Tested-by: indica che la patch è stata verificata con successo 579 561 (su un qualche sistema) dalla persona citata. Questa etichetta informa i ··· 833 807 è utile, potete usare https://lore.kernel.org/ per ottenere i collegamenti 834 808 ad una versione precedente di una serie di patch (per esempio, potete usarlo 835 809 per l'email introduttiva alla serie). 810 + 811 + Fornire informazioni circa i sorgenti 812 + ------------------------------------- 813 + 814 + Quando gli altri sviluppatori ricevono le vostre patch e iniziano il processo di 815 + revisione, è assolutamente necessario che sappiano qual è il commit/ramo di base 816 + su cui si base il vostro lavoro: considerate l'enorme quantità di sorgenti dei 817 + manutentori presenti al giorno d'oggi. Si noti ancora una volta la voce **T:** 818 + nel file MAINTAINERS spiegato sopra. 819 + 820 + Questo è ancora più importante per i processi automatizzati di CI che tentano di 821 + eseguire una serie di test per stabilire la qualità del codice prima che il 822 + manutentore inizi la revisione. 823 + 824 + Se si usa ``git format-patch`` per generare le patch, si possono includere 825 + automaticamente le informazioni sull'albero di base nell'invio usando il flag 826 + ``--base``. Il modo più semplice e comodo di usare questa opzione è con i rami 827 + topici:: 828 + 829 + $ git checkout -t -b my-topical-branch master 830 + Branch 'my-topical-branch' set up to track local branch 'master'. 831 + Switched to a new branch 'my-topical-branch' 832 + 833 + [perform your edits and commits] 834 + 835 + $ git format-patch --base=auto --cover-letter -o outgoing/ master 836 + outgoing/0000-cover-letter.patch 837 + outgoing/0001-First-Commit.patch 838 + outgoing/... 839 + 840 + Aprendo ``outgoing/0000-cover-letter.patch`` per la modifica, si noterà 841 + che ha ``base-commit:`` in fondo, questo fornisce al revisore e agli 842 + strumenti CI informazioni sufficienti per eseguire correttamente ``git am`` 843 + senza preoccuparsi dei conflitti:: 844 + 845 + $ git checkout -b patch-review [base-commit-id] 846 + Switched to a new branch 'patch-review' 847 + $ git am patches.mbox 848 + Applying: First Commit 849 + Applying: ... 850 + 851 + Consultate ``man git-format-patch`` per maggiori informazioni circa questa 852 + opzione. 853 + 854 + .. note:: 855 + 856 + L'opzione ``--base`` fu introdotta con git versione 2.9.0 857 + 858 + Se non si usa git per produrre le patch, si può comunque includere 859 + ``base-commit`` per indicare l'hash del commit dei sorgenti su cui si basa il 860 + lavoro. Dovreste aggiungerlo nella lettera di accompagnamento o nella prima 861 + patch della serie e dovrebbe essere collocato sotto la riga ``---`` o in fondo a 862 + tutti gli altri contenuti, subito prima della vostra firma e-mail. 863 + 864 + Assicuratevi che il commit si basi su sorgenti ufficiali del 865 + manutentore/mainline e non su sorgenti interni, accessibile solo a voi, 866 + altrimenti sarebbe inutile. 836 867 837 868 Riferimenti 838 869 -----------
+22 -2
Documentation/translations/it_IT/riscv/patch-acceptance.rst Documentation/translations/it_IT/arch/riscv/patch-acceptance.rst
··· 1 - .. include:: ../disclaimer-ita.rst 1 + .. include:: ../../disclaimer-ita.rst 2 2 3 - :Original: :doc:`../../../arch/riscv/patch-acceptance` 3 + :Original: :doc:`../../../../arch/riscv/patch-acceptance` 4 4 :Translator: Federico Vaga <federico.vaga@vaga.pv.it> 5 5 6 6 arch/riscv linee guida alla manutenzione per gli sviluppatori ··· 21 21 sperimentale. Desideriamo estendere questi stessi principi al codice 22 22 relativo all'architettura RISC-V che verrà accettato per l'inclusione 23 23 nel kernel. 24 + 25 + Patchwork 26 + --------- 27 + 28 + RISC-V ha un'istanza di patchwork dov'è possibile controllare lo stato delle patch: 29 + 30 + https://patchwork.kernel.org/project/linux-riscv/list/ 31 + 32 + Se la vostra patch non appare nella vista predefinita, i manutentori di RISC-V 33 + hanno probabilmente richiesto delle modifiche o si aspettano che venga applicata 34 + a un altro albero. 35 + 36 + Il processo automatico viene eseguito su questa istanza di patchwork, costruendo 37 + e collaudando le patch man mano che arrivano. Il processo applica le patch al 38 + riferimento HEAD corrente dei rami `for-next` e `fixes` dei sorgenti RISC-V, 39 + questo a seconda che la patch sia stata o meno individuata come correzione. In 40 + caso contrario, utilizzerà il ramo `master` di RISC-V. L'esatto commit a cui è 41 + stata applicata una serie di patch sarà annotato su patchwork. È improbabile che 42 + vengano applicate Le patch che non passano i controlli, nella maggior parte dei 43 + casi dovranno essere ripresentate. 24 44 25 45 In aggiunta alla lista delle verifiche da fare prima di inviare una patch 26 46 -------------------------------------------------------------------------
+1
Documentation/translations/sp_SP/index.rst
··· 78 78 79 79 process/index 80 80 wrappers/memory-barriers 81 + scheduler/index
+1 -1
Documentation/translations/sp_SP/process/coding-style.rst
··· 754 754 de estilo del código, errores tipográficos y posibles mejoras. También es 755 755 útil para ordenar ``#includes``, para alinear variables/macros, para 756 756 redistribuir texto y otras tareas similares. Vea el archivo 757 - :ref:`Documentation/process/clang-format.rst <clangformat>` para más 757 + :ref:`Documentation/dev-tools/clang-format.rst <clangformat>` para más 758 758 detalles. 759 759 760 760 10) Archivos de configuración de Kconfig
+1
Documentation/translations/sp_SP/process/index.rst
··· 29 29 submit-checklist 30 30 howto 31 31 development-process 32 + maintainer-kvm-x86
+1 -1
Documentation/translations/sp_SP/process/magic-number.rst
··· 1 1 .. include:: ../disclaimer-sp.rst 2 2 3 - :Original: :ref:`Documentation/process/magic-number.rst <magicnumbers>` 3 + :Original: :ref:`Documentation/staging/magic-number.rst <magicnumbers>` 4 4 :Translator: Carlos Bilbao <carlos.bilbao.osdev@gmail.com> 5 5 6 6 .. _sp_magicnumbers:
+465
Documentation/translations/sp_SP/process/maintainer-kvm-x86.rst
··· 1 + .. include:: ../disclaimer-sp.rst 2 + 3 + :Original: Documentation/process/maintainer-kvm-x86.rst 4 + :Translator: Juan Embid <jembid@ucm.es> 5 + 6 + KVM x86 7 + ======= 8 + 9 + Prólogo 10 + -------- 11 + KVM se esfuerza por ser una comunidad acogedora; las contribuciones de los 12 + recién llegados son valoradas e incentivadas. Por favor, no se desanime ni 13 + se sienta intimidado por la extensión de este documento y las numerosas 14 + normas/directrices que contiene. Todos cometemos errores y todos hemos sido 15 + principiantes en algún momento. Mientras haga un esfuerzo honesto por 16 + seguir las directrices de KVM x86, sea receptivo a los comentarios, y 17 + aprenda de los errores que cometa, será recibido con los brazos abiertos, 18 + no con antorchas y horcas. 19 + 20 + TL;DR 21 + ----- 22 + Las pruebas son obligatorias. Sea coherente con los estilos y patrones 23 + establecidos. 24 + 25 + Árboles 26 + ------- 27 + KVM x86 se encuentra actualmente en un período de transición de ser parte 28 + del árbol principal de KVM, a ser "sólo otra rama de KVM". Como tal, KVM 29 + x86 está dividido entre el árbol principal de KVM, 30 + ``git.kernel.org/pub/scm/virt/kvm/kvm.git``, y un árbol específico de KVM 31 + x86, ``github.com/kvm-x86/linux.git``. 32 + 33 + Por lo general, las correcciones para el ciclo en curso se aplican 34 + directamente al árbol principal de KVM, mientras que todo el desarrollo 35 + para el siguiente ciclo se dirige a través del árbol de KVM x86. En el 36 + improbable caso de que una corrección para el ciclo actual se dirija a 37 + través del árbol KVM x86, se aplicará a la rama ``fixes`` antes de llegar 38 + al árbol KVM principal. 39 + 40 + Tenga en cuenta que se espera que este periodo de transición dure bastante 41 + tiempo, es decir, que será el statu quo en un futuro previsible. 42 + 43 + Ramas 44 + ~~~~~ 45 + El árbol de KVM x86 está organizado en múltiples ramas por temas. El 46 + propósito de utilizar ramas temáticas más específicas es facilitar el 47 + control de un área de desarrollo, y para limitar los daños colaterales de 48 + errores humanos y/o commits con errores, por ejemplo, borrar el commit HEAD 49 + de una rama temática no tiene impacto en los hashes SHA1 de otros commit 50 + en en camino, y tener que rechazar una solicitud de pull debido a errores 51 + retrasa sólo esa rama temática. 52 + 53 + Todas las ramas temáticas, excepto ``next`` y ``fixes``, se agrupan en 54 + ``next`` a través de un Cthulhu merge en función de las necesidades, es 55 + decir, cuando se actualiza una rama temática. Como resultado, los push 56 + forzados a ``next`` son comunes. 57 + 58 + Ciclo de Vida 59 + ~~~~~~~~~~~~~ 60 + Las correcciones dirigidas a la versión actual, también conocida como 61 + mainline, suelen aplicarse directamente al árbol principal de KVM, es 62 + decir, no pasan por el árbol x86 de KVM. 63 + 64 + Los cambios dirigidos a la siguiente versión se dirigen a través del árbol 65 + KVM x86. Se envían pull requests (de KVM x86 a KVM main) para cada rama 66 + temática de KVM x86, normalmente la semana antes de que Linus abra la 67 + ventana de fusión, por ejemplo, la semana siguiente a rc7 para las 68 + versiones "normales". Si todo va bien, las ramas temáticas son subidas en 69 + el pull request principal de KVM enviado durante la ventana de fusión de 70 + Linus. 71 + 72 + El árbol de KVM x86 no tiene su propia ventana de fusión oficial, pero hay 73 + un cierre suave alrededor de rc5 para nuevas características, y un cierre 74 + suave alrededor de rc6 para correcciones (para la próxima versión; fíjese 75 + más arriba para las correcciones dirigidas a la versión actual). 76 + 77 + Cronología 78 + ~~~~~~~~~~ 79 + Normalmente, los envíos se revisan y aplican en orden FIFO, con cierto 80 + margen de maniobra en función del tamaño de la serie, los parches que están 81 + "calientes en caché", etc. Correcciones, especialmente para la versión 82 + actual y/o árboles estables, consiguen saltar la cola. Los parches que se 83 + lleven a través de un árbol que no sea KVM (la mayoría de las veces a 84 + través del árbol de consejos) y/o que tengan otros acks/revisiones también 85 + saltan la cola hasta cierto punto. 86 + 87 + Tenga en cuenta que la mayor parte de la revisión se realiza entre rc1 y 88 + rc6, más o menos. El periodo entre la rc6 y la siguiente rc1 se utiliza 89 + para ponerse al día en otras tareas, es decir, la falta de envíos durante 90 + este periodo no es inusual. 91 + 92 + Los pings para obtener una actualización del estado son bienvenidos, pero 93 + tenga en cuenta el calendario del ciclo de publicación actual y tenga 94 + expectativas realistas. Si está haciendo ping para la aceptación, es decir, 95 + no sólo para obtener comentarios o una actualización, por favor haga todo 96 + lo posible, dentro de lo razonable, para asegurarse de que sus parches 97 + están listos para ser fusionados. Los pings sobre series que rompen la 98 + compilación o fallan en las pruebas provocan el descontento de los 99 + mantenedores. 100 + 101 + Desarrollo 102 + ----------- 103 + 104 + Árbol base/Rama 105 + ~~~~~~~~~~~~~~~ 106 + Las correcciones dirigidas a la versión actual, también conocida como 107 + mainline, deben basarse en 108 + ``git://git.kernel.org/pub/scm/virt/kvm/kvm.git master``. Tenga en cuenta 109 + que las correcciones no garantizan automáticamente la inclusión en la 110 + versión actual. No hay una regla única, pero normalmente sólo las 111 + correcciones de errores urgentes, críticos y/o introducidos en la versión 112 + actual deberían incluirse en la versión actual. 113 + 114 + Todo lo demás debería basarse en ``kvm-x86/next``, es decir, no hay 115 + necesidad de seleccionar una rama temática específica como base. Si hay 116 + conflictos y/o dependencias entre ramas, es trabajo del mantenedor 117 + resolverlos. 118 + 119 + La única excepción al uso de ``kvm-x86/next`` como base es si un 120 + parche/serie es una serie multi-arquitectura, es decir, tiene 121 + modificaciones no triviales en el código común de KVM y/o tiene cambios más 122 + que superficiales en el código de otras arquitecturas. Los parches/series 123 + multi-arquitectura deberían basarse en un punto común y estable en la 124 + historia de KVM, por ejemplo, la versión candidata en la que se basa 125 + ``kvm-x86 next``. Si no está seguro de si un parche/serie es realmente 126 + multiarquitectura, sea precavido y trátelo como multiarquitectura, es 127 + decir, utilice una base común. 128 + 129 + Estilo del codigo 130 + ~~~~~~~~~~~~~~~~~~~~~~ 131 + Cuando se trata de estilo, nomenclatura, patrones, etc., la coherencia es 132 + la prioridad número uno en KVM x86. Si todo lo demás falla, haga coincidir 133 + lo que ya existe. 134 + 135 + Con algunas advertencias que se enumeran a continuación, siga las 136 + recomendaciones de los responsables del árbol de consejos 137 + :ref:`maintainer-tip-coding-style`, ya que los parches/series a menudo 138 + tocan tanto archivos x86 KVM como no KVM, es decir, llaman la atención de 139 + los mantenedores de KVM *y* del árbol de consejos. 140 + 141 + El uso del abeto inverso, también conocido como árbol de Navidad inverso o 142 + árbol XMAS inverso, para las declaraciones de variables no es estrictamente 143 + necesario, aunque es preferible. 144 + 145 + Excepto para unos pocos apuntes especiales, no utilice comentarios 146 + kernel-doc para las funciones. La gran mayoría de las funciones "públicas" 147 + de KVM no son realmente públicas, ya que están destinadas únicamente al 148 + consumo interno de KVM (hay planes para privatizar las cabeceras y 149 + exportaciones de KVM para reforzar esto). 150 + 151 + Comentarios 152 + ~~~~~~~~~~~ 153 + Escriba los comentarios en modo imperativo y evite los pronombres. Utilice 154 + los comentarios para ofrecer una visión general de alto nivel del código 155 + y/o para explicar por qué el código hace lo que hace. No reitere lo que el 156 + código hace literalmente; deje que el código hable por sí mismo. Si el 157 + propio código es inescrutable, los comentarios no servirán de nada. 158 + 159 + Referencias SDM y APM 160 + ~~~~~~~~~~~~~~~~~~~~~~ 161 + Gran parte de la base de código de KVM está directamente vinculada al 162 + comportamiento de la arquitectura definido en El Manual de Desarrollo de 163 + Software (SDM) de Intel y el Manual del Programador de Arquitectura (APM) 164 + de AMD. El uso de "SDM de Intel" y "APM de AMD", o incluso sólo "SDM" o 165 + "APM", sin contexto adicional es correcto. 166 + 167 + No haga referencia a secciones específicas, tablas, figuras, etc. por su 168 + número, especialmente en los comentarios. En su lugar, si es necesario 169 + (véase más abajo), copie y pegue el fragmento correspondiente y haga 170 + referencia a las secciones/tablas/figuras por su nombre. Los diseños del 171 + SDM y el APM cambian constantemente, por lo que los números/etiquetas no 172 + son estables. 173 + 174 + En general, no haga referencia explícita ni copie-pegue del SDM o APM en 175 + los comentarios. Con pocas excepciones, KVM *debe* respetar el 176 + comportamiento de la arquitectura, por lo que está implícito que el 177 + comportamiento de KVM está emulando el comportamiento de SDM y/o APM. Tenga 178 + en cuenta que hacer referencia al SDM/APM en los registros de cambios para 179 + justificar el cambio y proporcionar contexto es perfectamente correcto y 180 + recomendable. 181 + 182 + Shortlog 183 + ~~~~~~~~ 184 + El formato de prefijo más recomendable es ``KVM: <topic>:``, donde 185 + ``<topic>`` es uno de los siguientes:: 186 + 187 + - x86 188 + - x86/mmu 189 + - x86/pmu 190 + - x86/xen 191 + - autocomprobaciones 192 + - SVM 193 + - nSVM 194 + - VMX 195 + - nVMX 196 + 197 + **¡NO use x86/kvm!** ``x86/kvm`` se usa exclusivamente para cambios de 198 + Linux virtualizado por KVM, es decir, para arch/x86/kernel/kvm.c. No use 199 + nombres de archivos o archivos completos como prefijo de asunto/shortlog. 200 + 201 + Tenga en cuenta que esto no coincide con las ramas temáticas (las ramas 202 + temáticas se preocupan mucho más por los conflictos de código). 203 + 204 + Todos los nombres distinguen entre mayúsculas y minúsculas. ``KVM: x86:`` 205 + es correcto, ``kvm: vmx:`` no lo es. 206 + 207 + Escriba en mayúsculas la primera palabra de la descripción condensada del 208 + parche, pero omita la puntuación final. Por ejemplo:: 209 + 210 + KVM: x86: Corregir una desviación de puntero nulo en function_xyz() 211 + 212 + no:: 213 + 214 + kvm: x86: corregir una desviación de puntero nulo en function_xyz. 215 + 216 + Si un parche afecta a varios temas, recorra el árbol conceptual hasta 217 + encontrar el primer padre común (que suele ser simplemente ``x86``). En 218 + caso de duda, ``git log path/to/file`` debería proporcionar una pista 219 + razonable. 220 + 221 + De vez en cuando surgen nuevos temas, pero le rogamos que inicie un debate 222 + en la lista si desea proponer la introducción de un nuevo tema, es decir, 223 + no se ande con rodeos. 224 + 225 + Consulte :ref:`the_canonical_patch_format` para obtener más información, 226 + con una enmienda: no trate el límite de 70-75 caracteres como un límite 227 + absoluto y duro. En su lugar, utilice 75 caracteres como límite firme, pero 228 + no duro, y 80 caracteres como límite duro. Es decir, deje que el registro 229 + corto sobrepase en algunos caracteres el límite estándar si tiene una buena 230 + razón para hacerlo. 231 + 232 + Registro de cambios 233 + ~~~~~~~~~~~~~~~~~~~ 234 + Y lo que es más importante, escriba los registros de cambios en modo 235 + imperativo y evite los pronombres. 236 + 237 + Consulte :ref:`describe_changes` para obtener más información, con una 238 + recomendación: comience con un breve resumen de los cambios reales y 239 + continúe con el contexto y los antecedentes. Nota. Este orden entra en 240 + conflicto directo con el enfoque preferido del árbol de sugerencias. Por 241 + favor, siga el estilo preferido del árbol de sugerencias cuando envíe 242 + parches. que se dirigen principalmente a código arch/x86 que _NO_ es código 243 + KVM. 244 + 245 + KVM x86 prefiere indicar lo que hace un parche antes de entrar en detalles 246 + por varias razones. En primer lugar, el código que realmente se está 247 + cambiando es posiblemente la información más importante, por lo que esa 248 + información debe ser fácil de encontrar. Changelogs que entierran el "qué 249 + está cambiando realmente" en una sola línea después de 3+ párrafos de fondo 250 + hacen muy difícil encontrar esa información. 251 + 252 + Para la revisión inicial, se podría argumentar que "lo que está roto" es 253 + más importante, pero para hojear los registros y la arqueología git, los 254 + detalles escabrosos importan cada vez menos. Por ejemplo, al hacer una 255 + serie de "git blame", los detalles de cada cambio a lo largo del camino son 256 + inútiles, los detalles sólo importan para el culpable. Proporcionar el "qué 257 + ha cambiado" facilita determinar rápidamente si una confirmación puede ser 258 + de interés o no. 259 + 260 + Otra ventaja de decir primero "qué cambia" es que casi siempre es posible 261 + decir "qué cambia" en una sola frase. A la inversa, todo menos los errores 262 + más simples requieren varias frases o párrafos para describir el problema. 263 + Si tanto "qué está cambiando" como "cuál es el fallo" son muy breves, el 264 + orden no importa. Pero si uno es más corto (casi siempre el "qué está 265 + cambiando"), entonces cubrir el más corto primero es ventajoso porque es 266 + menos inconveniente para los lectores/revisores que tienen una preferencia 267 + estricta de orden. Por ejemplo, tener que saltarse una frase para llegar al 268 + contexto es menos doloroso que tener que saltarse tres párrafos para llegar 269 + a "lo que cambia". 270 + 271 + Arreglos 272 + ~~~~~~~~ 273 + Si un cambio corrige un error de KVM/kernel, añada una etiqueta Fixes: 274 + incluso si el cambio no necesita ser retroportado a kernels estables, e 275 + incluso si el cambio corrige un error en una versión anterior. 276 + 277 + Por el contrario, si es necesario hacer una corrección, etiquete 278 + explícitamente el parche con "Cc: stable@vger.kernel" (aunque no es 279 + necesario que el correo electrónico incluya Cc: stable); KVM x86 opta por 280 + excluirse del backporting Correcciones: por defecto. Algunos parches 281 + seleccionados automáticamente se retroportan, pero requieren la aprobación 282 + explícita de los mantenedores (busque MANUALSEL). 283 + 284 + Referencias a Funciones 285 + ~~~~~~~~~~~~~~~~~~~~~~~ 286 + Cuando se mencione una función en un comentario, registro de cambios o 287 + registro abreviado (o en cualquier otro lugar), utilice el formato 288 + ``nombre_de_la_función()``. Los paréntesis proporcionan contexto y 289 + desambiguan la referencia. 290 + 291 + Pruebas 292 + ~~~~~~~ 293 + Como mínimo, *todos* los parches de una serie deben construirse limpiamente 294 + para KVM_INTEL=m KVM_AMD=m, y KVM_WERROR=y. Construir todas las 295 + combinaciones posibles de Kconfigs no es factible, pero cuantas más mejor. 296 + KVM_SMM, KVM_XEN, PROVE_LOCKING, y X86_64 son particularmente interesantes. 297 + 298 + También es obligatorio ejecutar las autopruebas y las pruebas unitarias de 299 + KVM (y, como es obvio, las pruebas deben pasar). La única excepción es para 300 + los cambios que tienen una probabilidad insignificante de afectar al 301 + comportamiento en tiempo de ejecución, por ejemplo, parches que sólo 302 + modificar los comentarios. Siempre que sea posible y pertinente, se 303 + recomienda encarecidamente realizar pruebas tanto en Intel como en AMD. Se 304 + recomienda arrancar una máquina virtual real, pero no es obligatorio. 305 + 306 + Para cambios que afecten al código de paginación en la sombra de KVM, es 307 + obligatorio ejecutar con TDP (EPT/NPT) deshabilitado. Para cambios que 308 + afecten al código MMU común de KVM, se recomienda encarecidamente ejecutar 309 + con TDP deshabilitado. Para todos los demás cambios, si el código que se 310 + está modificando depende de y/o interactúa con un parámetro del módulo, es 311 + obligatorio realizar pruebas con la configuración correspondiente. 312 + 313 + Tenga en cuenta que las autopruebas de KVM y las pruebas de unidad de KVM 314 + tienen fallos conocidos. Si sospecha que un fallo no se debe a sus cambios, 315 + verifique que el *exactamente el mismo* fallo se produce con y sin sus 316 + cambios. 317 + 318 + Los cambios que afecten a la documentación de texto reestructurado, es 319 + decir, a los archivos .rst, deben generar htmldocs de forma limpia, es 320 + decir, sin advertencias ni errores. 321 + 322 + Si no puede probar completamente un cambio, por ejemplo, por falta de 323 + hardware, indique claramente qué nivel de pruebas ha podido realizar, por 324 + ejemplo, en la carta de presentación. 325 + 326 + Novedades 327 + ~~~~~~~~~ 328 + Con una excepción, las nuevas características *deben* venir con cobertura 329 + de pruebas. Las pruebas específicas de KVM no son estrictamente necesarias, 330 + por ejemplo, si la cobertura se proporciona mediante la ejecución de una 331 + prueba de VM huésped suficientemente habilitada, o ejecutando una 332 + autoprueba de kernel relacionada en una VM, pero en todos los casos se 333 + prefieren las pruebas KVM dedicadas. Los casos de prueba negativos en 334 + particular son obligatorios para la habilitación de nuevas características 335 + de hardware, ya que los flujos de errores y excepciones rara vez se 336 + ejercitan simplemente ejecutando una VM. 337 + 338 + La única excepción a esta regla es si KVM está simplemente anunciando 339 + soporte para un a través de KVM_GET_SUPPORTED_CPUID, es decir, para 340 + instrucciones/funciones que KVM no puede impedir que utilice una VM y 341 + para las que no existe una verdadera habilitación. 342 + 343 + Tenga en cuenta que "nuevas características" no significa sólo "nuevas 344 + características de hardware". Las nuevas funcionalidades que no puedan ser 345 + validadas usando las pruebas existentes de KVM y/o las pruebas unitarias de 346 + KVM deben venir con pruebas. 347 + 348 + Es más que bienvenido el envío de nuevos desarrollos de características sin 349 + pruebas para obtener un feedback temprano, pero tales envíos deben ser 350 + etiquetados como RFC, y la carta de presentación debe indicar claramente 351 + qué tipo de feedback se solicita/espera. No abuse del proceso de RFC; las 352 + RFC no suelen recibir una revisión en profundidad. 353 + 354 + Corrección de Errores 355 + ~~~~~~~~~~~~~~~~~~~~~ 356 + Salvo en el caso de fallos "obvios" detectados por inspección, las 357 + correcciones deben ir acompañadas de un reproductor del fallo corregido. En 358 + muchos casos, el reproductor está implícito, por ejemplo, para errores de 359 + compilación y fallos de prueba, pero debe quedar claro para lectores qué es 360 + lo que no funciona y cómo verificar la solución. Se concede cierto margen a 361 + los errores detectados mediante cargas de trabajo/pruebas no públicas, pero 362 + se recomienda encarecidamente que se faciliten pruebas de regresión para 363 + dichos errores. 364 + 365 + En general, las pruebas de regresión son preferibles para cualquier fallo 366 + que no sea trivial de encontrar. Por ejemplo, incluso si el error fue 367 + encontrado originalmente por un fuzzer como syzkaller, una prueba de 368 + regresión dirigida puede estar justificada si el error requiere golpear una 369 + condición de carrera de tipo uno en un millón. 370 + 371 + Recuerde que los fallos de KVM rara vez son urgentes *y* no triviales de 372 + reproducir. Pregúntate si un fallo es realmente el fin del mundo antes de 373 + publicar una corrección sin un reproductor. 374 + 375 + Publicación 376 + ----------- 377 + 378 + Enlaces 379 + ~~~~~~~ 380 + No haga referencia explícita a informes de errores, versiones anteriores de 381 + un parche/serie, etc. mediante cabeceras ``In-Reply-To:``. Usar 382 + ``In-Reply-To:`` se convierte en un lío para grandes series y/o cuando el 383 + número de versiones es alto, y ``In-Reply-To:`` es inútil para cualquiera 384 + que no tenga el mensaje original, por ejemplo, si alguien no recibió un Cc 385 + en el informe de error o si la lista de destinatarios cambia entre 386 + versiones. 387 + 388 + Para enlazar con un informe de error, una versión anterior o cualquier cosa 389 + de interés, utiliza enlaces lore. Para hacer referencia a versiones 390 + anteriores, en general no incluya un Enlace: en el registro de cambios, ya 391 + que no hay necesidad de registrar la historia en git, es decir, ponga el 392 + enlace en la carta de presentación o en la sección que git ignora. 393 + Proporcione un Enlace: formal para los informes de errores y/o discusiones 394 + que condujeron al parche. El contexto de por qué se hizo un cambio es muy 395 + valioso para futuros lectores. 396 + 397 + Basado en Git 398 + ~~~~~~~~~~~~~ 399 + Si utilizas la versión 2.9.0 o posterior de git (Googlers, ¡os incluimos a 400 + todos!), utilice ``git format-patch`` con el indicador ``--base`` para 401 + incluir automáticamente la información del árbol base en los parches 402 + generados. 403 + 404 + Tenga en cuenta que ``--base=auto`` funciona como se espera si y sólo si el 405 + upstream de una rama se establece en la rama temática base, por ejemplo, 406 + hará lo incorrecto si su upstream se establece en su repositorio personal 407 + con fines de copia de seguridad. Una solución "automática" alternativa es 408 + derivar los nombres de tus ramas de desarrollo basándose en su KVM x86, e 409 + introdúzcalo en ``--base``. Por ejemplo, ``x86/pmu/mi_nombre_de_rama``, y 410 + luego escribir un pequeño wrapper para extraer ``pmu`` del nombre de la 411 + rama actual para obtener ``--base=x/pmu``, donde ``x`` es el nombre que su 412 + repositorio utiliza para rastrear el remoto KVM x86. 413 + 414 + Tests de Co-Publicación 415 + ~~~~~~~~~~~~~~~~~~~~~~~ 416 + Las autopruebas de KVM asociadas a cambios de KVM, por ejemplo, pruebas de 417 + regresión para correcciones de errores, deben publicarse junto con los 418 + cambios de KVM como una única serie. Se aplicarán las reglas estándar del 419 + núcleo para la bisección, es decir, los cambios de KVM que provoquen fallos 420 + en las pruebas se ordenarán después de las actualizaciones de las 421 + autopruebas, y viceversa. Las pruebas que fallan debido a errores de KVM 422 + deben ordenarse después de las correcciones de KVM. 423 + 424 + KVM-unit-tests debería *siempre* publicarse por separado. Las herramientas, 425 + por ejemplo b4 am, no saben que KVM-unit-tests es un repositorio separado y 426 + se confunden cuando los parches de una serie se aplican en diferentes 427 + árboles. Para vincular los parches de KVM-unit-tests a Parches KVM, primero 428 + publique los cambios KVM y luego proporcione un enlace lore Link: al 429 + parche/serie KVM en el parche(s) KVM-unit-tests. 430 + 431 + Notificaciones 432 + ~~~~~~~~~~~~~~ 433 + Cuando se acepte oficialmente un parche/serie, se enviará un correo 434 + electrónico de notificación en respuesta a la publicación original (carta 435 + de presentación para series de varios parches). La notificación incluirá el 436 + árbol y la rama temática, junto con los SHA1 de los commits de los parches 437 + aplicados. 438 + 439 + Si se aplica un subconjunto de parches, se indicará claramente en la 440 + notificación. A menos que se indique lo contrario, se sobreentiende que 441 + todos los parches del Las series que no han sido aceptadas necesitan más 442 + trabajo y deben presentarse en una nueva versión. 443 + 444 + Si por alguna razón se retira un parche después de haber sido aceptado 445 + oficialmente, se enviará una respuesta al correo electrónico de 446 + notificación explicando por qué se ha retirado el parche, así como los 447 + pasos siguientes. 448 + 449 + Estabilidad SHA1 450 + ~~~~~~~~~~~~~~~~ 451 + Los SHA1 no son 100% estables hasta que llegan al árbol de Linus. Un SHA1 452 + es *normalmente* estable una vez que se ha enviado una notificación, pero 453 + ocurren cosas. En la mayoría de los casos, se proporcionará una 454 + actualización del correo electrónico de notificación si se aplica un SHA1 455 + del parche. Sin embargo, en algunos escenarios, por ejemplo, si todas las 456 + ramas de KVM x86 necesitan ser rebasadas, no se darán notificaciones 457 + individuales. 458 + 459 + Vulnerabilidades 460 + ~~~~~~~~~~~~~~~~ 461 + Los fallos que pueden ser explotados por la VM (el "guest") para atacar al 462 + host (kernel o espacio de usuario), o que pueden ser explotados por una VM 463 + anidada a *su* host (L2 atacando a L1), son de particular interés para KVM. 464 + Por favor, siga el protocolo para :ref:`securitybugs` si sospecha que un 465 + fallo puede provocar una filtración de datos, etc.
+8
Documentation/translations/sp_SP/scheduler/index.rst
··· 1 + .. include:: ../disclaimer-sp.rst 2 + 3 + .. _sp_scheduler_index: 4 + 5 + .. toctree:: 6 + :maxdepth: 1 7 + 8 + sched-design-CFS
+277
Documentation/translations/sp_SP/scheduler/sched-design-CFS.rst
··· 1 + .. include:: ../disclaimer-sp.rst 2 + 3 + :Original: :ref:`Documentation/scheduler/sched-design-CFS.rst <sched_design_CFS>` 4 + :Translator: Sergio González Collado <sergio.collado@gmail.com> 5 + 6 + .. _sp_sched_desing_CFS: 7 + 8 + ==================== 9 + Gestor de tareas CFS 10 + ==================== 11 + 12 + 1. VISIÓN GENERAL 13 + ================== 14 + 15 + CFS viene de las siglas en inglés de "Gestor de tareas totalmente justo" 16 + ("Completely Fair Scheduler"), y es el nuevo gestor de tareas de escritorio 17 + implementado por Ingo Molnar e integrado en Linux 2.6.23. Es el sustituto de 18 + el previo gestor de tareas SCHED_OTHER. 19 + 20 + Nota: El planificador EEVDF fue incorporado más recientemente al kernel. 21 + 22 + El 80% del diseño de CFS puede ser resumido en una única frase: CFS 23 + básicamente modela una "CPU ideal, precisa y multi-tarea" sobre hardware 24 + real. 25 + 26 + "una CPU multitarea ideal" es una CPU (inexistente :-)) que tiene un 100% 27 + de potencia y que puede ejecutar cualquier tarea exactamente a la misma 28 + velocidad, en paralelo, y cada una a 1/n velocidad. Por ejemplo, si hay dos 29 + tareas ejecutándose, entonces cada una usa un 50% de la potencia --- es decir, 30 + como si se ejecutaran en paralelo. 31 + 32 + En hardware real, se puede ejecutar una única tarea a la vez, así que 33 + se ha usado el concepto de "tiempo de ejecución virtual". El tiempo 34 + de ejecución virtual de una tarea específica cuando la siguiente porción 35 + de ejecución podría empezar en la CPU ideal multi-tarea descrita anteriormente. 36 + En la práctica, el tiempo de ejecución virtual de una tarea es el 37 + tiempo de ejecución real normalizado con respecto al número total de 38 + tareas ejecutándose. 39 + 40 + 41 + 2. UNOS CUANTOS DETALLES DE IMPLEMENTACIÓN 42 + =========================================== 43 + 44 + En CFS, el tiempo de ejecución virtual se expresa y se monitoriza por 45 + cada tarea, en su valor de p->se.vruntime (en unidades de nanosegundos). 46 + De este modo, es posible temporizar con precisión y medir el "tiempo 47 + de CPU esperado" que una tarea debería tener. 48 + 49 + Un pequeño detalle: en hardware "ideal", en cualquier momento todas las 50 + tareas pueden tener el mismo valor de p->se.vruntime --- i.e., tareas 51 + se podrían ejecutar simultáneamente y ninguna tarea podría escaparse del 52 + "balance" de la partición "ideal" del tiempo compartido de la CPU. 53 + 54 + La lógica de elección del tareas de CFS se basa en el valor de p->se.vruntime 55 + y por tanto es muy sencilla: siempre intenta ejecutar la tarea con el valor 56 + p->se.vruntime más pequeño (i.e., la tarea que se ha ejecutado menos hasta el 57 + momento). CFS siempre intenta dividir el espacio de tiempo entre tareas 58 + en ejecución tan próximo a la "ejecución multitarea ideal del hardware" como 59 + sea posible. 60 + 61 + El resto del diseño de CFS simplemente se escapa de este simple concepto, 62 + con unos cuantos añadidos como los niveles "nice" ("nice" significa "amable" 63 + en inglés), multi-tarea y varias variantes del algoritmo para identificar 64 + tareas "durmiendo". 65 + 66 + 67 + 3. EL ÁRBOL ROJO-NEGRO 68 + ======================= 69 + 70 + El diseño de CFS es bastante radical: no utiliza las antiguas estructuras 71 + de datos para las colas de ejecución (en inglés "runqueues"), pero usa una 72 + estructura de árbol rojo-negro (en inglés "red-black tree") ordenado cronológicamente 73 + para construir un línea de ejecución en el futuro, y por eso no tiene ningún 74 + artificio de "cambio de tareas" (algo que previamente era usado por el gestor 75 + anterior y RSDL/SD). 76 + 77 + CFS también mantiene el valor de rq->cfs.min_vruntime, el cual crece 78 + monotónicamente siguiendo el valor más pequeño de vruntime de entre todas 79 + las tareas en la cola de ejecución. La cantidad total de trabajo realizado 80 + por el sistema es monitorizado usado min_vruntime; este valor es usado 81 + para situar las nuevas tareas en la parte izquierda del árbol tanto 82 + como sea posible. 83 + 84 + El valor total de tareas ejecutándose en la cola de ejecución es 85 + contabilizado mediante el valor rq->cfs.load, el cual es la suma de los 86 + de esas tareas que están en la cola de ejecución. 87 + 88 + CFS mantiene un árbol rojo-negro cronológicamente ordenado, donde todas las 89 + tareas que pueden ser ejecutadas están ordenadas por su valor de 90 + p->se.vruntime. CFS selecciona la tarea más hacia la izquierda de este 91 + árbol y la mantiene. Según el sistema continúa, las tareas ejecutadas 92 + se ponen en este árbol más y más hacia la derecha --- lentamente pero 93 + de forma continuada dando una oportunidad a cada tarea de ser la que 94 + está "la más hacia la izquierda" y por tanto obtener la CPU una cantidad 95 + determinista de tiempo. 96 + 97 + Resumiendo, CFS funciona así: ejecuta una tarea un tiempo, y cuando la 98 + tarea se gestiona (o sucede un tic del gestor de tareas) se considera 99 + que el tiempo de uso de la CPU se ha completado, y se añade a 100 + p->se.vruntime. Una vez p->se.vruntime ha aumentado lo suficiente como 101 + para que otra tarea sea "la tarea más hacia la izquierda" del árbol 102 + rojo-negro ordenado cronológicamente esta mantienen (más una cierta pequeña 103 + cantidad de distancia relativa a la tarea más hacia la izquierda para 104 + que no se sobre-reserven tareas y perjudique a la cache), entonces la 105 + nueva tarea "que está a la izquierda del todo", es la que se elige 106 + para que se ejecute, y la tarea en ejecución es interrumpida. 107 + 108 + 4. ALGUNAS CARACTERÍSTICAS DE CFS 109 + ================================== 110 + 111 + CFS usa una granularidad de nanosegundos y no depende de ningún 112 + jiffie o detalles como HZ. De este modo, el gestor de tareas CFS no tiene 113 + noción de "ventanas de tiempo" de la forma en que tenía el gestor de 114 + tareas previo, y tampoco tiene heurísticos. Únicamente hay un parámetro 115 + central ajustable (se ha de cambiar en CONFIG_SCHED_DEBUG): 116 + 117 + /sys/kernel/debug/sched/base_slice_ns 118 + 119 + El cual puede ser usado para afinar desde el gestor de tareas del "escritorio" 120 + (i.e., bajas latencias) hacia cargas de "servidor" (i.e., bueno con 121 + procesamientos). Su valor por defecto es adecuado para tareas de escritorio. 122 + SCHED_BATCH también es gestionado por el gestor de tareas CFS. 123 + 124 + Debido a su diseño, el gestor de tareas CFS no es proclive a ninguno de los 125 + ataques que existen a día de hoy contra los heurísticos del gestor de tareas: 126 + fiftyp.c, thud.c, chew.c, ring-test.c, massive_intr.c todos trabajan 127 + correctamente y no tienen impacto en la interacción y se comportan de la forma 128 + esperada. 129 + 130 + El gestor de tareas CFS tiene una gestión mucho más firme de los niveles 131 + "nice" y SCHED_BATCH que los previos gestores de tareas: ambos tipos de 132 + tareas están aisladas de forma más eficiente. 133 + 134 + El balanceo de tareas SMP ha sido rehecho/mejorado: el avance por las 135 + colas de ejecución de tareas ha desaparecido del código de balanceo de 136 + carga, y ahora se usan iteradores en la gestión de módulos. El balanceo 137 + del código ha sido simplificado como resultado esto. 138 + 139 + 5. Políticas de gestión de tareas 140 + ================================== 141 + 142 + CFS implementa tres políticas de gestión de tareas: 143 + 144 + - SCHED_NORMAL (tradicionalmente llamada SCHED_OTHER): Gestión de 145 + tareas que se usan para tareas normales. 146 + 147 + - SCHED_BATCH: No interrumpe tareas tan a menudo como las tareas 148 + normales harían, por eso permite a las tareas ejecutarse durante 149 + ventanas de tiempo mayores y hace un uso más efectivo de las 150 + caches pero al coste de la interactividad. Esto es adecuado 151 + para trabajos de procesado de datos. 152 + 153 + - SCHED_IDLE: Esta política es más débil incluso que nice 19, pero 154 + no es un gestor "idle" para evitar caer en el problema de la 155 + inversión de prioridades que causaría un bloqueo de la máquina 156 + (deadlock). 157 + 158 + SCHED_FIFO/_RR se implementan en sched/rt.c y son específicos de 159 + POSIX. 160 + 161 + El comando chrt de util-linux-ng 2.13.1.1. puede asignar cualquiera de 162 + estas políticas excepto SCHED_IDLE. 163 + 164 + 165 + 6. CLASES DE GESTIÓN 166 + ===================== 167 + 168 + El nuevo gestor de tareas CFS ha sido diseñado de tal modo para incluir 169 + "clases de gestión", una jerarquía ampliable de módulos que pueden tener 170 + distintas políticas de gestión de tareas. Estos módulos encapsulan los 171 + detalles de las politicas de gestión y son manejadas por el núcleo del 172 + gestor de tareas sin que este tenga que presuponer mucho sobre estas clases. 173 + 174 + sched/fair.c implementa el gestor de tareas CFS descrito antes. 175 + 176 + sched/rt.c implementa la semántica de SCHED_FIFO y SCHED_RR, de una forma 177 + más sencilla que el gestor de tareas anterior. Usa 100 colas de ejecución 178 + (por todos los 100 niveles de prioridad RT, en vez de las 140 que necesitaba 179 + el gestor de tareas anterior) y no necesita las listas de expiración. 180 + 181 + Las clases de gestión de tareas son implementadas por medio de la estructura 182 + sched_class, la cual tiene llamadas a las funciones que deben de llamarse 183 + cuando quiera que ocurra un evento interesante. 184 + 185 + Esta es la lista parcial de llamadas: 186 + 187 + - enqueue_task(...) 188 + 189 + Llamada cuando una tarea entra en el estado de lista para ejecución. 190 + Pone la entidad a ser gestionada (la tarea) en el árbol rojo-negro 191 + e incrementa la variable nr_running. 192 + 193 + - dequeue_task(...) 194 + 195 + Cuando una tarea deja de ser ejecutable, esta función se llama para 196 + mantener a la entidad gestionada fuera del árbol rojo-negor. Esto 197 + decrementa la variable nr_running. 198 + 199 + - yield_task(...) 200 + 201 + Esta función es básicamente desencolar, seguido por encolar, a menos que 202 + sysctl compat_yield esté activado; en ese caso, sitúa la entidad a gestionar 203 + en la parte más hacia la derecha del árbol rojo-negro. 204 + 205 + - check_preempt_curr(...) 206 + 207 + Esta función comprueba si una tarea que ha entrado en el estado de 208 + poder ser ejecutada, podría reemplazar a la tarea que actualmente 209 + se esté ejecutando. 210 + 211 + - pick_next_task(...) 212 + 213 + Esta función elige la tarea más apropiada para ser ejecutada a continuación. 214 + 215 + - set_curr_task(...) 216 + 217 + Esta función se llama cuando una tarea cambia su clase de gestión o 218 + cambia su grupo de tareas. 219 + 220 + - task_tick(...) 221 + 222 + Esta función es llamada la mayoría de las veces desde la función de tiempo 223 + tick; esto puede llevar a un cambio de procesos. Esto dirige el reemplazo 224 + de las tareas. 225 + 226 + 227 + 7. EXTENSIONES DE GRUPOS PARA CFS 228 + ================================== 229 + 230 + Normalmente, el gestor de tareas gestiona tareas individuales e intenta 231 + proporcionar una cantidad justa de CPU a cada tarea. Algunas veces, puede 232 + ser deseable agrupar las tareas y proporcionarles una cantidad justa 233 + de tiempo de CPU a cada una de las tareas de ese grupo. Por ejemplo, 234 + podría ser deseable que primero se proporcione una cantidad justa de 235 + tiempo de CPU a cada usuario del sistema y después a cada tarea 236 + que pertenezca a un usuario. 237 + 238 + CONFIG_CGROUP_SCHED destaca en conseguir exactamente eso. Permite a las 239 + tareas ser agrupadas y divide el tiempo de CPU de forma just entre esos 240 + grupos. 241 + 242 + CONFIG_RT_GROUP_SCHED permite agrupar tareas de tiempo real (i.e., 243 + SCHED_FIFO y SCHED_RR). 244 + 245 + CONFIG_FAIR_GROUP_SCHED permite agrupar tareas de CFS (i.e., SCHED_NORMAL y 246 + SCHED_BATCH). 247 + 248 + Estas opciones necesitan CONFIG_CGROUPS para ser definidas, y permitir 249 + al administrador crear grupos arbitrarios de tareas, usando el pseudo 250 + sistema de archivos "cgroup". Vease la documentación para más información 251 + sobre este sistema de archivos: Documentation/admin-guide/cgroup-v1/cgroups.rst 252 + 253 + Cuando CONFIG_FAIR_GROUP_SCHED es definido, un archivo 254 + "cpu.shares" es creado por cada grupo creado usado en el pseudo 255 + sistema de archivos. Véanse por ejemplo los pasos a continuación 256 + para crear grupos de tareas y modificar cuanto comparten de la CPU 257 + usando el pseudo sistema de archivos "cgroup" :: 258 + 259 + # mount -t tmpfs cgroup_root /sys/fs/cgroup 260 + # mkdir /sys/fs/cgroup/cpu 261 + # mount -t cgroup -ocpu none /sys/fs/cgroup/cpu 262 + # cd /sys/fs/cgroup/cpu 263 + 264 + # mkdir multimedia # crear un grupo de tareas "multimedia" 265 + # mkdir browser # crear un grupo de tareas "browser" 266 + 267 + # #Configurar el grupo multimedia para tener el doble de tiempo de CPU 268 + # #que el grupo browser 269 + 270 + # echo 2048 > multimedia/cpu.shares 271 + # echo 1024 > browser/cpu.shares 272 + 273 + # firefox & # Lanzar firefox y moverlo al grupo "browser" 274 + # echo <firefox_pid> > browser/tasks 275 + 276 + # #Lanzar gmplayer (o su programa favorito de reproducción de películas) 277 + # echo <movie_player_pid> > multimedia/tasks
+1 -1
Documentation/translations/zh_CN/admin-guide/index.rst
··· 68 68 cpu-load 69 69 cputopology 70 70 lockup-watchdogs 71 + numastat 71 72 unicode 72 73 sysrq 73 74 mm/index ··· 110 109 * module-signing 111 110 * mono 112 111 * namespaces/index 113 - * numastat 114 112 * parport 115 113 * perf-security 116 114 * pm/index
+48
Documentation/translations/zh_CN/admin-guide/numastat.rst
··· 1 + .. SPDX-License-Identifier: GPL-2.0 2 + .. include:: ../disclaimer-zh_CN.rst 3 + 4 + :Original: Documentation/admin-guide/numastat.rst 5 + :Translator: Tao Zou <wodemia@linux.alibaba.com> 6 + 7 + 8 + ======================= 9 + Numa策略命中/未命中统计 10 + ======================= 11 + 12 + /sys/devices/system/node/node*/numastat 13 + 14 + 所有数据的单位都是页面。巨页有独立的计数器。 15 + 16 + numa_hit、numa_miss和numa_foreign计数器反映了进程是否能够在他们偏好的节点上分配内存。 17 + 如果进程成功在偏好的节点上分配内存则在偏好的节点上增加numa_hit计数，否则在偏好的节点上增 18 + 加numa_foreign计数同时在实际内存分配的节点上增加numa_miss计数。 19 + 20 + 通常，偏好的节点是进程运行所在的CPU的本地节点，但是一些限制可以改变这一行为，比如内存策略， 21 + 因此同样有两个基于CPU本地节点的计数器。local_node和numa_hit类似，当在CPU所在的节点上分 22 + 配内存时增加local_node计数，other_node和numa_miss类似，当在CPU所在节点之外的其他节点 23 + 上成功分配内存时增加other_node计数。需要注意，没有和numa_foreign对应的计数器。 24 + 25 + 更多细节内容: 26 + 27 + =============== ============================================================ 28 + numa_hit 一个进程想要从本节点分配内存并且成功。 29 + 30 + numa_miss 一个进程想要从其他节点分配内存但是最终在本节点完成内存分配。 31 + 32 + numa_foreign 一个进程想要在本节点分配内存但是最终在其他节点完成内存分配。 33 + 34 + local_node 一个进程运行在本节点的CPU上并且从本节点上获得了内存。 35 + 36 + other_node 一个进程运行在其他节点的CPU上但是在本节点上获得了内存。 37 + 38 + interleave_hit 内存交叉分配策略下想要从本节点分配内存并且成功。 39 + =============== ============================================================ 40 + 41 + 你可以使用numactl软件包（http://oss.sgi.com/projects/libnuma/）中的numastat工具 42 + 来辅助阅读。需要注意，numastat工具目前只在有少量CPU的机器上运行良好。 43 + 44 + 需要注意，在包含无内存节点（一个节点有CPUs但是没有内存）的系统中numa_hit、numa_miss和 45 + numa_foreign统计数据会被严重曲解。在当前的内核实现中，如果一个进程偏好一个无内存节点（即 46 + 进程正在该节点的一个本地CPU上运行），实际上会从距离最近的有内存节点中挑选一个作为偏好节点。 47 + 结果会导致相应的内存分配不会增加无内存节点上的numa_foreign计数器，并且会扭曲最近节点上的 48 + numa_hit、numa_miss和numa_foreign统计数据。
+4
Documentation/translations/zh_CN/dev-tools/gdb-kernel-debugging.rst
··· 34 34 但这通常仅在不依赖内核模块时才有效。有关此模式的更多详细信息，请参阅QEMU文档。 35 35 在这种情况下，如果架构支持KASLR，应该在禁用CONFIG_RANDOMIZE_BASE的情况下构建内核。 36 36 37 + - 构建gdb脚本（适用于内核v5.1版本及以上） 38 + 39 + make scripts_gdb 40 + 37 41 - 启用QEMU/KVM的gdb stub，可以通过如下方式实现 38 42 39 43 - 在VM启动时，通过在QEMU命令行中添加“-s”参数
+5 -1
Documentation/translations/zh_CN/dev-tools/index.rst
··· 20 20 21 21 testing-overview 22 22 sparse 23 + kcov 23 24 gcov 24 25 kasan 25 - kcov 26 26 ubsan 27 27 kmemleak 28 28 gdb-kernel-debugging 29 29 30 30 Todolist: 31 31 32 + - checkpatch 32 33 - coccinelle 34 + - kmsan 33 35 - kcsan 34 36 - kfence 35 37 - kgdb 36 38 - kselftest 37 39 - kunit/index 40 + - ktap 41 + - checkuapi
+18
Documentation/translations/zh_CN/dev-tools/kasan.rst
··· 235 235 通用KASAN还报告两个辅助调用堆栈跟踪。这些堆栈跟踪指向代码中与对象交互但不直接 236 236 出现在错误访问堆栈跟踪中的位置。目前，这包括 call_rcu() 和排队的工作队列。 237 237 238 + CONFIG_KASAN_EXTRA_INFO 239 + ~~~~~~~~~~~~~~~~~~~~~~~ 240 + 241 + 启用 CONFIG_KASAN_EXTRA_INFO 选项允许 KASAN 记录和报告更多信息。目前支持的 242 + 额外信息包括分配和释放时的 CPU 编号和时间戳。更多的信息可以帮助找到内核错误的原因， 243 + 并将错误与其他系统事件关联起来，但代价是用额外的内存来记录更多信息（有关更多 244 + 开销的细节，请参见 CONFIG_KASAN_EXTRA_INFO 选项的帮助文本）。 245 + 246 + 以下为 CONFIG_KASAN_EXTRA_INFO 开启后的报告（仅显示不同部分）:: 247 + 248 + ================================================================== 249 + ... 250 + Allocated by task 134 on cpu 5 at 229.133855s: 251 + ... 252 + Freed by task 136 on cpu 3 at 230.199335s: 253 + ... 254 + ================================================================== 255 + 238 256 实施细则 239 257 -------- 240 258
+2
Documentation/translations/zh_CN/dev-tools/testing-overview.rst
··· 99 99 参阅 Documentation/dev-tools/kfence.rst 100 100 * lockdep是一个锁定正确性检测器。参阅 101 101 Documentation/locking/lockdep-design.rst 102 + * 运行时确认（Runtime Verification）支持检查给定子系统的特定行为。参阅 103 + Documentation/trace/rv/runtime-verification.rst。 102 104 * 除此以外，在内核中还有一些其它的调试工具，大多数能在 103 105 lib/Kconfig.debug 中找到。 104 106
+1 -1
Documentation/translations/zh_CN/driver-api/index.rst
··· 23 23 24 24 gpio/index 25 25 io_ordering 26 + phy/index 26 27 27 28 Todolist: 28 29 ··· 104 103 * parport-lowlevel 105 104 * pps 106 105 * ptp 107 - * phy/index 108 106 * pwm 109 107 * pldmfw/index 110 108 * rfkill
+20
Documentation/translations/zh_CN/driver-api/phy/index.rst
··· 1 + .. SPDX-License-Identifier: GPL-2.0 2 + 3 + ============ 4 + PHY 通用框架 5 + ============ 6 + 7 + .. toctree:: 8 + 9 + phy 10 + 11 + Todolist: 12 + 13 + * samsung-usb2 14 + 15 + .. only:: subproject and html 16 + 17 + Indices 18 + ======= 19 + 20 + * :ref:`genindex`
+212
Documentation/translations/zh_CN/driver-api/phy/phy.rst
··· 1 + .. SPDX-License-Identifier: GPL-2.0 2 + .. include:: ../../disclaimer-zh_CN.rst 3 + 4 + :Original: Documentation/driver-api/phy/phy.rst 5 + 6 + :翻译: 7 + 8 + 司延腾 Yanteng Si <siyanteng@loongson.cn> 9 + 10 + ========= 11 + PHY子系统 12 + ========= 13 + 14 + :作者: Kishon Vijay Abraham I <kishon@ti.com> 15 + 16 + 本文档解释了 PHY 的通用框架和提供的API，以及使用方法。 17 + 18 + 简介 19 + ==== 20 + 21 + *PHY* 是物理层的缩写，它被用来把设备连接到一个物理媒介，例如USB控制器 22 + 有一个提供序列化、反序列化、编码、解码和负责获取所需的数据传输速率的 PHY。 23 + 注意，有些USB控制器内嵌了 PHY 的功能，其它的则使用了一个外置的PHY，此外 24 + 使用 PHY 的设备还有无线网、以太网、SATA等（控制器）。 25 + 26 + 创建这个框架的目的是将遍布 Linux 内核的 PHY 驱动程序融入到 drivers/phy， 27 + 以增加代码的可复用性，进而提高代码的可维护性。 28 + 29 + 该框架仅适用于使用外部 PHY（PHY 功能未嵌入控制器内）的设备。 30 + 31 + 注册/注销PHY provider 32 + ===================== 33 + 34 + PHY provider是指实现一个或多个 PHY 实例的实体。对于 PHY provider 仅 35 + 实现单个 PHY 实例的简单情况，框架在 of_phy_simple_xlate 中提供其自己 36 + 的 of_xlate 实现。如果 PHY provider 实现多个实例，则应提供其自己的 37 + of_xlate 实现。of_xlate 仅用于 dt 启动情况。 38 + 39 + :: 40 + 41 + #define of_phy_provider_register(dev, xlate) \ 42 + __of_phy_provider_register((dev), NULL, THIS_MODULE, (xlate)) 43 + 44 + #define devm_of_phy_provider_register(dev, xlate) \ 45 + __devm_of_phy_provider_register((dev), NULL, THIS_MODULE, 46 + (xlate)) 47 + 48 + of_phy_provider_register 和 devm_of_phy_provider_register 宏 49 + 可用于注册 phy_provider，它以 device 和 of_xlate 作为参数。对于 dt 50 + 启动情况，所有 PHY provider 都应使用上述两个宏之一来注册 PHY provider。 51 + 52 + 与 PHY provider 关联的设备树节点通常包含一组子节点，每个子节点代表一个 53 + PHY。某些绑定可能会为了上下文和可扩展性将子节点嵌套在特别的层级中，在这种 54 + 情况下，可以使用低级别的 of_phy_provider_register_full() 和 55 + devm_of_phy_provider_register_full() 宏来覆盖包含子节点的节点。 56 + 57 + :: 58 + 59 + #define of_phy_provider_register_full(dev, children, xlate) \ 60 + __of_phy_provider_register(dev, children, THIS_MODULE, xlate) 61 + 62 + #define devm_of_phy_provider_register_full(dev, children, xlate) \ 63 + __devm_of_phy_provider_register_full(dev, children, 64 + THIS_MODULE, xlate) 65 + 66 + void devm_of_phy_provider_unregister(struct device *dev, 67 + struct phy_provider *phy_provider); 68 + void of_phy_provider_unregister(struct phy_provider *phy_provider); 69 + 70 + devm_of_phy_provider_unregister 和 of_phy_provider_unregister 71 + 可以被用来注销PHY. 72 + 73 + 创建PHY 74 + ======= 75 + 76 + PHY 驱动程序应创建 PHY，以便其他外围（芯片）控制器能够使用它。PHY 框架 77 + 提供了 2 个 API 来创建 PHY。 78 + 79 + :: 80 + 81 + struct phy *phy_create(struct device *dev, struct device_node *node, 82 + const struct phy_ops *ops); 83 + struct phy *devm_phy_create(struct device *dev, 84 + struct device_node *node, 85 + const struct phy_ops *ops); 86 + 87 + PHY 驱动程序可以使用上述两个 API 之一，通过传递设备指针和 phy_ops 88 + 来创建 PHY。 89 + 90 + phy_ops 是一组用于执行 PHY 操作（例如 init、exit、power_on 和 91 + power_off）的函数指针。 92 + 93 + 在 phy_ops 中，PHY provider驱动程序在创建 PHY 后使用 phy_set_drvdata() 94 + 设置私有数据，使用 phy_get_drvdata() 获取私有数据。 95 + 96 + 获取对 PHY 的引用 97 + ================= 98 + 99 + 控制器必须先获取对 PHY 的引用，然后才能使用 PHY。此框架提供以下 API 100 + 来获取对 PHY 的引用。 101 + 102 + :: 103 + 104 + struct phy *phy_get(struct device *dev, const char *string); 105 + struct phy *devm_phy_get(struct device *dev, const char *string); 106 + struct phy *devm_phy_optional_get(struct device *dev, 107 + const char *string); 108 + struct phy *devm_of_phy_get(struct device *dev, struct device_node *np, 109 + const char *con_id); 110 + struct phy *devm_of_phy_optional_get(struct device *dev, 111 + struct device_node *np, 112 + const char *con_id); 113 + struct phy *devm_of_phy_get_by_index(struct device *dev, 114 + struct device_node *np, 115 + int index); 116 + 117 + phy_get、devm_phy_get 和 devm_phy_optional_get 可用于在 dt 118 + 启动的情况下获取 PHY，字符串参数应包含 dt 数据中给出的 phy 名称，在 119 + 非 dt 启动的情况下，它应包含 PHY 的标签。两个 devm_phy_get 在成功 120 + 获取 PHY 后使用 devres 将设备与 PHY 关联。在驱动程序分离时，将在 121 + devres 数据上调用 release 函数并释放 devres 数据。当 phy 是可选 122 + 的时，应使用 _optional_get 变体。这些函数永远不会返回 -ENODEV，而 123 + 是在找不到 phy 时返回 NULL。一些通用驱动程序（例如 ehci）可能使用 124 + 多个 phy。在这种情况下，devm_of_phy_get 或 devm_of_phy_get_by_index 125 + 用于根据名称或索引获取 phy 引用。 126 + 127 + 需要注意的是，NULL 是有效的 phy 引用。NULL phy 上的所有 phy 使用 128 + 者调用都将成为 NOP。也就是说释放调用，当应用于 NULL phy 时，release 129 + 调用、phy_init()/phy_exit() 调用、phy_power_on()/phy_power_off() 130 + 调用都是 NOP。NULL phy 在处理可选的 phy 设备中很有用。 131 + 132 + API的调用顺序 133 + ============= 134 + 135 + 通常，调用顺序应该是:: 136 + 137 + [devm_][of_]phy_get() 138 + phy_init() 139 + phy_power_on() 140 + [phy_set_mode[_ext]()] 141 + ... 142 + phy_power_off() 143 + phy_exit() 144 + [[of_]phy_put()] 145 + 146 + 一些PHY驱动可能没有实现 :c:func:`phy_init` 或 :c:func:`phy_power_on`, 147 + 但是控制器应该总是调用这些函数以兼容其它PHY，有些PHY可能要求 148 + :c:func:`phy_set_mode <phy_set_mode_ext>` 而其他 PHY 可能使用 149 + 默认模式（通常通过设备树或其他固件配置）。出于兼容性考虑，如果您知道将 150 + 使用哪种模式，则应始终调用此函数。通常，应在 :c:func:`phy_power_on` 151 + 之后调用此函数，尽管某些 PHY 驱动程序可能随时允许调用它。 152 + 153 + 释放对 PHY 的引用 154 + ================= 155 + 156 + 当控制器不再需要 PHY 时，它必须使用上一节中提到的 API 释放对已获得 157 + 的 PHY 的引用。PHY 框架提供了 2 个 API 来释放对 PHY 的引用。 158 + 159 + :: 160 + 161 + void phy_put(struct phy *phy); 162 + void devm_phy_put(struct device *dev, struct phy *phy); 163 + 164 + 这两个 API 都用于释放对 PHY 的引用，并且 devm_phy_put 会销毁与此 165 + PHY 关联的设备资源。 166 + 167 + 销毁 PHY 168 + ======== 169 + 170 + 当创建 PHY 的驱动程序被卸载时，它应该使用以下 2 个 API 之一销毁其创 171 + 建的 PHY:: 172 + 173 + void phy_destroy(struct phy *phy); 174 + void devm_phy_destroy(struct device *dev, struct phy *phy); 175 + 176 + 这两个 API 都会销毁 PHY，并且 devm_phy_destroy 会销毁与此 PHY 关 177 + 联的 devres。 178 + 179 + PM Runtime 180 + ========== 181 + 182 + 这个子系统启用了pm runtime。 所以，在创建PHY 时，将调用此子系统创建的 183 + phy 设备的 pm_runtime_enable 函数，在销毁 PHY 时，将调用 184 + pm_runtime_disable。请注意，此子系统创建的 phy 设备将是调用 phy_create 185 + （PHY provider 设备）的设备的子设备。 186 + 187 + 因此，由于父子关系，此子系统创建的 phy_device 的 pm_runtime_get_sync 188 + 调用 PHY provider 设备的 pm_runtime_get_sync。还应注意， 189 + phy_power_on 和 phy_power_off 分别执行 phy_pm_runtime_get_sync 和 190 + phy_pm_runtime_put。有导出的 API，如 phy_pm_runtime_get、 191 + phy_pm_runtime_get_sync、phy_pm_runtime_put、phy_pm_runtime_put_sync、 192 + phy_pm_runtime_allow 和 phy_pm_runtime_forbid，用于执行 PM 操作。 193 + 194 + PHY映射 195 + ======= 196 + 197 + 为了在没有 DeviceTree 帮助的情况下获取对 PHY 的引用，框架提供了可与 198 + clkdev 进行比较的查找，允许将 clk 结构体绑定到设备。当 struct phy 的 199 + 句柄已存在时，可以在运行时进行查找。 200 + 201 + 该框架提供以下 API 用于注册和注销查找:: 202 + 203 + int phy_create_lookup(struct phy *phy, const char *con_id, 204 + const char *dev_id); 205 + void phy_remove_lookup(struct phy *phy, const char *con_id, 206 + const char *dev_id); 207 + 208 + DeviceTree绑定 209 + ============== 210 + 211 + PHY dt 绑定的文档可以在以下位置找到 @ 212 + Documentation/devicetree/bindings/phy/phy-bindings.txt
+1 -1
Documentation/translations/zh_CN/process/4.Coding.rst
··· 54 54 注意您还可以使用 ``clang-format`` 工具来帮助您处理这些规则，快速自动重新格式 55 55 化部分代码，和审阅完整的文件以发现代码样式错误、拼写错误和可能的改进。它还 56 56 可以方便地排序 ``#includes`` 、对齐变量/宏、重排文本和其他类似任务。有关详细 57 - 信息，请参阅文档 :ref:`Documentation/process/clang-format.rst <clangformat>` 57 + 信息，请参阅文档 :ref:`Documentation/dev-tools/clang-format.rst <clangformat>` 58 58 59 59 抽象层 60 60 ******
+1 -1
Documentation/translations/zh_CN/process/coding-style.rst
··· 654 654 请注意，您还可以使用 ``clang-format`` 工具帮助您处理这些规则，快速自动重新格 655 655 式化部分代码，并审阅整个文件以发现代码风格错误、打字错误和可能的改进。它还可 656 656 以方便地排序 ``#include`` ，对齐变量/宏，重排文本和其他类似任务。 657 - 详见 Documentation/process/clang-format.rst 。 657 + 详见 Documentation/dev-tools/clang-format.rst 。 658 658 659 659 660 660 10) Kconfig 配置文件
+1 -1
Documentation/translations/zh_CN/process/index.rst
··· 64 64 management-style 65 65 stable-kernel-rules 66 66 submit-checklist 67 + researcher-guidelines 67 68 68 69 TODOLIST: 69 70 ··· 72 71 * kernel-docs 73 72 * deprecated 74 73 * maintainers 75 - * researcher-guidelines 76 74 * contribution-maturity-model 77 75 78 76
+1 -1
Documentation/translations/zh_CN/process/magic-number.rst
··· 1 1 .. include:: ../disclaimer-zh_CN.rst 2 2 3 - :Original: Documentation/process/magic-number.rst 3 + :Original: Documentation/staging/magic-number.rst 4 4 5 5 :翻译: 6 6
+129
Documentation/translations/zh_CN/process/researcher-guidelines.rst
··· 1 + .. SPDX-License-Identifier: GPL-2.0-or-later 2 + 3 + .. include:: ../disclaimer-zh_CN.rst 4 + 5 + .. _cn_researcherguidelines: 6 + 7 + :Original: Documentation/process/researcher-guidelines.rst 8 + 9 + :译者: 10 + - 慕冬亮 Dongliang Mu <dzm91@hust.edu.cn> 11 + 12 + 研究人员指南 13 + +++++++++++++++++++++ 14 + 15 + Linux 内核社区欢迎对 Linux 内核及其开发过程中涉及的活动与任何其他副产品 16 + 进行透明的研究。Linux 从这种研究中受益匪浅，其多方面均由某种形式的研究所推动。 17 + 18 + 社区非常感谢研究人员在公开研究结果之前能分享初步发现，特别是涉及安全的研究。 19 + 早期参与有助于提高研究质量并使 Linux 受益。无论如何，推荐研究人员与社区分享 20 + 已发表研究的开放访问副本。 21 + 22 + 本文旨在澄清研究开展过程中 Linux 内核社区认可与不认可的一些做法。至少，这类 23 + 研究及相关活动应遵循标准的研究伦理规则。有关研究伦理、技术伦理以及开发者社区 24 + 研究的更多背景信息，请查阅： 25 + 26 + * `研究伦理史 <https://www.unlv.edu/research/ORI-HSR/history-ethics>`_ 27 + * `IEEE 伦理 <https://www.ieee.org/about/ethics/index.html>`_ 28 + * `开发者和研究人员对开源项目实验伦理的看法 <https://arxiv.org/pdf/2112.13217.pdf>`_ 29 + 30 + Linux 内核社区期望与项目互动的每个人都是真诚地为了使 Linux 变得更好。 31 + 对 Linux 内核社区产生的任何公开可用的成果（包括但不限于源代码）的研究 32 + 是受欢迎的，对开发者的研究如若要开展，则必须要明确说明，获得（开发者）同意。 33 + 34 + 完全基于公开可用资源（包括公共邮件列表的帖子和公开代码库的提交）的被动研究 35 + 显然是允许的。不过，和任何研究一样，仍需遵循标准伦理。 36 + 37 + 然而，针对开发者行为的主动研究必须在获得相关开发者的明确同意和完全披露的情况下进行。 38 + 未经同意，不得与开发者互动或对其进行实验；这也是标准的研究伦理。 39 + 40 + 调查 41 + ======= 42 + 43 + 研究通常采用调查问卷的形式发送给维护者或贡献者。然而，内核社区通常从这些调查问卷中获益 44 + 甚少。内核开发过程之所以有效，是因为每个开发者都从中受益，即使与目标不同的人一起工作。 45 + 而回应调查则是对繁忙开发者的单向需求，对他们自己或整个内核社区没有相应的好处。因此， 46 + 这种研究方法不被鼓励。 47 + 48 + 内核社区成员已经收到过多的电子邮件，可能会将调查请求视为对他们时间的又一要求。发送 49 + 此类请求会剥夺社区宝贵的贡献者时间，且不太可能产生有统计意义的回应。 50 + 51 + 作为替代，研究人员应考虑参加开发者活动，举办研讨会来介绍研究项目及其对参与者的益处， 52 + 并直接与社区互动。该方式获得的信息将比电子邮件调查问卷丰富得多，且社区也能从中学习 53 + 到您的见解。 54 + 55 + 补丁 56 + ======= 57 + 58 + 澄清：向开发者发送补丁**是**与他们互动，但他们已经同意接收**善意贡献**。故意发送有缺陷/ 59 + 有漏洞的补丁或在讨论中提供误导信息是不被同意的。这种交流会对开发者造成损害 60 + （例如，消耗时间、精力和士气），并通过破坏整个开发者社区对贡献者（及其所在组织） 61 + 的信任而损害项目，削弱为贡献者提供建设性反馈的努力，并使最终用户面临软件缺陷的风险。 62 + 63 + 研究人员参与 Linux 本身的开发与其他人一样受到欢迎和鼓励。研究 Linux 代码是常见 64 + 做法，尤其是在开发或运行可产生可操作结果的分析工具时。 65 + 66 + 在与开发者社区互动时，发送补丁历来是产生影响的最佳方式。Linux 已经有很多已知的 67 + 漏洞 -- 更有帮助的是经过审核的修复。在贡献之前，请仔细阅读相关文档： 68 + 69 + * Documentation/process/development-process.rst 70 + * Documentation/process/submitting-patches.rst 71 + * Documentation/admin-guide/reporting-issues.rst 72 + * Documentation/process/security-bugs.rst 73 + 74 + 然后发送补丁（包括所有如下详细信息的提交日志）并跟进其他开发者的任何反馈。 75 + 76 + 当发送因研究而产生的补丁时，提交日志应至少包含以下详细信息，以便开发者有适当的上下文 77 + 来理解贡献。回答： 78 + 79 + * 找到了什么具体问题？ 80 + * 在运行系统上如何触发这个问题？ 81 + * 遇到这个问题对系统会有什么影响？ 82 + * 如何发现这个问题？具体包括任何测试、静态或动态分析程序及其他用于执行工作的工具或方法的详细信息。 83 + * 在哪个版本的 Linux 上发现了这个问题？强烈推荐使用最新的发布版本或最近的 linux-next 分支（参见 Documentation/process/howto.rst）。 84 + * 进行了哪些更改来修复这个问题，为什么认为这些更改是正确的？ 85 + * 如何进行构建测试和运行时测试？ 86 + * 此更改修复了哪个先前的提交？这应该在 "Fixes:" 标签中，如文档所述。 87 + * 还有谁审查了这个补丁？这应该在适当的 "Reviewed-by:" 标签中注明；见下文。 88 + 89 + 例如:: 90 + 91 + From: Author <author@email> 92 + Subject: [PATCH] drivers/foo_bar: Add missing kfree() 93 + 94 + The error path in foo_bar driver does not correctly free the allocated 95 + struct foo_bar_info. This can happen if the attached foo_bar device 96 + rejects the initialization packets sent during foo_bar_probe(). This 97 + would result in a 64 byte slab memory leak once per device attach, 98 + wasting memory resources over time. 99 + 100 + This flaw was found using an experimental static analysis tool we are 101 + developing, LeakMagic[1], which reported the following warning when 102 + analyzing the v5.15 kernel release: 103 + 104 + path/to/foo_bar.c:187: missing kfree() call? 105 + 106 + Add the missing kfree() to the error path. No other references to 107 + this memory exist outside the probe function, so this is the only 108 + place it can be freed. 109 + 110 + x86_64 and arm64 defconfig builds with CONFIG_FOO_BAR=y using GCC 111 + 11.2 show no new warnings, and LeakMagic no longer warns about this 112 + code path. As we don't have a FooBar device to test with, no runtime 113 + testing was able to be performed. 114 + 115 + [1] https://url/to/leakmagic/details 116 + 117 + Reported-by: Researcher <researcher@email> 118 + Fixes: aaaabbbbccccdddd ("Introduce support for FooBar") 119 + Signed-off-by: Author <author@email> 120 + Reviewed-by: Reviewer <reviewer@email> 121 + 122 + 如果您是第一次参与贡献，建议在补丁在发布到公共列表前请其他人私下进行审核。（如果明确 123 + 告诉您补丁需要更仔细的内部审查，则这是必需的。）这些人预计会在最终的补丁中包含他们的 124 + "Reviewed-by" 标签。找到熟悉 Linux 贡献的其他开发者，特别是您自己组织内的开发者， 125 + 并在将补丁发送到公共邮件列表前请他们帮助审核，往往会显著提高补丁的质量，从而减少 126 + 其他开发者的负担。 127 + 128 + 如果你找不到人内部审核补丁且需要帮助找到这样的人，或者如果您对本文档和开发者社区的期望 129 + 有任何其他问题，请联系技术咨询委员会私有邮件列表：<tech-board@groups.linuxfoundation.org>。
+1 -1
Documentation/translations/zh_CN/virt/guest-halt-polling.rst
··· 76 76 77 77 默认值: Y 78 78 79 - 模块参数可以从Debugfs文件中设置，在:: 79 + 模块参数可以从sysfs文件中设置，在:: 80 80 81 81 /sys/module/haltpoll/parameters/ 82 82
+1 -1
Documentation/translations/zh_TW/process/4.Coding.rst
··· 57 57 注意您還可以使用 ``clang-format`` 工具來幫助您處理這些規則，快速自動重新格式 58 58 化部分代碼，和審閱完整的文件以發現代碼樣式錯誤、拼寫錯誤和可能的改進。它還 59 59 可以方便地排序 ``#includes`` 、對齊變量/宏、重排文本和其他類似任務。有關詳細 60 - 信息，請參閱文檔 :ref:`Documentation/process/clang-format.rst <clangformat>` 60 + 信息，請參閱文檔 :ref:`Documentation/dev-tools/clang-format.rst <clangformat>` 61 61 62 62 抽象層 63 63 ******
+1 -1
Documentation/translations/zh_TW/process/coding-style.rst
··· 657 657 請注意，您還可以使用 ``clang-format`` 工具幫助您處理這些規則，快速自動重新格 658 658 式化部分代碼，並審閱整個文件以發現代碼風格錯誤、打字錯誤和可能的改進。它還可 659 659 以方便地排序 ``#include`` ，對齊變量/宏，重排文本和其他類似任務。 660 - 詳見 Documentation/process/clang-format.rst 。 660 + 詳見 Documentation/dev-tools/clang-format.rst 。 661 661 662 662 663 663 10) Kconfig 配置文件
+1 -1
Documentation/translations/zh_TW/process/magic-number.rst
··· 4 4 5 5 .. include:: ../disclaimer-zh_TW.rst 6 6 7 - :Original: :ref:`Documentation/process/magic-number.rst <magicnumbers>` 7 + :Original: :ref:`Documentation/staging/magic-number.rst <magicnumbers>` 8 8 9 9 如果想評論或更新本文的內容，請直接發信到LKML。如果你使用英文交流有困難的話，也可 10 10 以向中文版維護者求助。如果本翻譯更新不及時或者翻譯存在問題，請聯繫中文版維護者::
+2
Documentation/userspace-api/ioctl/ioctl-number.rst
··· 97 97 '%' 00-0F include/uapi/linux/stm.h System Trace Module subsystem 98 98 <mailto:alexander.shishkin@linux.intel.com> 99 99 '&' 00-07 drivers/firewire/nosy-user.h 100 + '*' 00-1F uapi/linux/user_events.h User Events Subsystem 101 + <mailto:linux-trace-kernel@vger.kernel.org> 100 102 '1' 00-1F linux/timepps.h PPS kit from Ulrich Windl 101 103 <ftp://ftp.de.kernel.org/pub/linux/daemons/ntp/PPS/> 102 104 '2' 01-04 linux/i2o.h
+203
scripts/checktransupdate.py
··· 1 + #!/usr/bin/env python3 2 + # SPDX-License-Identifier: GPL-2.0 3 + 4 + """ 5 + This script helps track the translation status of the documentation 6 + in different locales, e.g., zh_CN. More specially, it uses `git log` 7 + commit to find the latest english commit from the translation commit 8 + (order by author date) and the latest english commits from HEAD. If 9 + differences occur, report the file and commits that need to be updated. 10 + 11 + The usage is as follows: 12 + - ./scripts/checktransupdate.py -l zh_CN 13 + This will print all the files that need to be updated in the zh_CN locale. 14 + - ./scripts/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst 15 + This will only print the status of the specified file. 16 + 17 + The output is something like: 18 + Documentation/translations/zh_CN/dev-tools/testing-overview.rst (1 commits) 19 + commit 42fb9cfd5b18 ("Documentation: dev-tools: Add link to RV docs") 20 + """ 21 + 22 + import os 23 + from argparse import ArgumentParser, BooleanOptionalAction 24 + from datetime import datetime 25 + 26 + flag_p_c = False 27 + flag_p_uf = False 28 + flag_debug = False 29 + 30 + 31 + def dprint(*args, **kwargs): 32 + if flag_debug: 33 + print("[DEBUG] ", end="") 34 + print(*args, **kwargs) 35 + 36 + 37 + def get_origin_path(file_path): 38 + paths = file_path.split("/") 39 + tidx = paths.index("translations") 40 + opaths = paths[:tidx] 41 + opaths += paths[tidx + 2 :] 42 + return "/".join(opaths) 43 + 44 + 45 + def get_latest_commit_from(file_path, commit): 46 + command = "git log --pretty=format:%H%n%aD%n%cD%n%n%B {} -1 -- {}".format( 47 + commit, file_path 48 + ) 49 + dprint(command) 50 + pipe = os.popen(command) 51 + result = pipe.read() 52 + result = result.split("\n") 53 + if len(result) <= 1: 54 + return None 55 + 56 + dprint("Result: {}".format(result[0])) 57 + 58 + return { 59 + "hash": result[0], 60 + "author_date": datetime.strptime(result[1], "%a, %d %b %Y %H:%M:%S %z"), 61 + "commit_date": datetime.strptime(result[2], "%a, %d %b %Y %H:%M:%S %z"), 62 + "message": result[4:], 63 + } 64 + 65 + 66 + def get_origin_from_trans(origin_path, t_from_head): 67 + o_from_t = get_latest_commit_from(origin_path, t_from_head["hash"]) 68 + while o_from_t is not None and o_from_t["author_date"] > t_from_head["author_date"]: 69 + o_from_t = get_latest_commit_from(origin_path, o_from_t["hash"] + "^") 70 + if o_from_t is not None: 71 + dprint("tracked origin commit id: {}".format(o_from_t["hash"])) 72 + return o_from_t 73 + 74 + 75 + def get_commits_count_between(opath, commit1, commit2): 76 + command = "git log --pretty=format:%H {}...{} -- {}".format(commit1, commit2, opath) 77 + dprint(command) 78 + pipe = os.popen(command) 79 + result = pipe.read().split("\n") 80 + # filter out empty lines 81 + result = list(filter(lambda x: x != "", result)) 82 + return result 83 + 84 + 85 + def pretty_output(commit): 86 + command = "git log --pretty='format:%h (\"%s\")' -1 {}".format(commit) 87 + dprint(command) 88 + pipe = os.popen(command) 89 + return pipe.read() 90 + 91 + 92 + def check_per_file(file_path): 93 + opath = get_origin_path(file_path) 94 + 95 + if not os.path.isfile(opath): 96 + dprint("Error: Cannot find the origin path for {}".format(file_path)) 97 + return 98 + 99 + o_from_head = get_latest_commit_from(opath, "HEAD") 100 + t_from_head = get_latest_commit_from(file_path, "HEAD") 101 + 102 + if o_from_head is None or t_from_head is None: 103 + print("Error: Cannot find the latest commit for {}".format(file_path)) 104 + return 105 + 106 + o_from_t = get_origin_from_trans(opath, t_from_head) 107 + 108 + if o_from_t is None: 109 + print("Error: Cannot find the latest origin commit for {}".format(file_path)) 110 + return 111 + 112 + if o_from_head["hash"] == o_from_t["hash"]: 113 + if flag_p_uf: 114 + print("No update needed for {}".format(file_path)) 115 + return 116 + else: 117 + print("{}".format(file_path), end="\t") 118 + commits = get_commits_count_between( 119 + opath, o_from_t["hash"], o_from_head["hash"] 120 + ) 121 + print("({} commits)".format(len(commits))) 122 + if flag_p_c: 123 + for commit in commits: 124 + msg = pretty_output(commit) 125 + if "Merge tag" not in msg: 126 + print("commit", msg) 127 + 128 + 129 + def main(): 130 + script_path = os.path.dirname(os.path.abspath(__file__)) 131 + linux_path = os.path.join(script_path, "..") 132 + 133 + parser = ArgumentParser(description="Check the translation update") 134 + parser.add_argument( 135 + "-l", 136 + "--locale", 137 + help="Locale to check when files are not specified", 138 + ) 139 + parser.add_argument( 140 + "--print-commits", 141 + action=BooleanOptionalAction, 142 + default=True, 143 + help="Print commits between the origin and the translation", 144 + ) 145 + 146 + parser.add_argument( 147 + "--print-updated-files", 148 + action=BooleanOptionalAction, 149 + default=False, 150 + help="Print files that do no need to be updated", 151 + ) 152 + 153 + parser.add_argument( 154 + "--debug", 155 + action=BooleanOptionalAction, 156 + help="Print debug information", 157 + default=False, 158 + ) 159 + 160 + parser.add_argument( 161 + "files", nargs="*", help="Files to check, if not specified, check all files" 162 + ) 163 + args = parser.parse_args() 164 + 165 + global flag_p_c, flag_p_uf, flag_debug 166 + flag_p_c = args.print_commits 167 + flag_p_uf = args.print_updated_files 168 + flag_debug = args.debug 169 + 170 + # get files related to linux path 171 + files = args.files 172 + if len(files) == 0: 173 + if args.locale is not None: 174 + files = ( 175 + os.popen( 176 + "find {}/Documentation/translations/{} -type f".format( 177 + linux_path, args.locale 178 + ) 179 + ) 180 + .read() 181 + .split("\n") 182 + ) 183 + else: 184 + files = ( 185 + os.popen( 186 + "find {}/Documentation/translations -type f".format(linux_path) 187 + ) 188 + .read() 189 + .split("\n") 190 + ) 191 + 192 + files = list(filter(lambda x: x != "", files)) 193 + files = list(map(lambda x: os.path.relpath(os.path.abspath(x), linux_path), files)) 194 + 195 + # cd to linux root directory 196 + os.chdir(linux_path) 197 + 198 + for file in files: 199 + check_per_file(file) 200 + 201 + 202 + if __name__ == "__main__": 203 + main()