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

Pull documentation updates from Jonathan Corbet: "It has been a not-too-busy cycle for docs; here's the highlights: - A (hopefully) consensus change to our LLM-attribution requirements, removing the specific model name from the Assisted-by tag - A couple of new realtime documents - Various docs-build-system fixes - Ongoing work with the Chinese, Portuguese, and Japanese translations ...and lots of typo fixes, grammar tweaks, etc" * tag 'docs-7.3' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux: (85 commits) Doc: admin-guide: pm: Remove unnecessary backticks and fix a spell Documentation: Extend the real-time hardware bits with some firmware bits docs: pt_BR: Reorganize process/index.rst to follow english structure docs: conf.py: fix the 'utf-8' typo doc tools: fix 'path' typos Documentation: real-time: Add kernel configuration guide docs: python: abi_regex: convert adjacent index placeholders docs: python: abi_regex: catch the right exception for a bad regex docs: sphinx-build-wrapper: include localversion in kernel version string Documentation: html: adjust sidebar section titles styling Documentation: html: show sections in the sidebar checkpatch.pl: adapt to new Assisted-by: format MAINTAINERS: update Traditional Chinese documentation maintainers docs: pt_BR: process: Translate CVE documentation docs: pt_BR: translate the management-style.rst to Brazilian Portuguese docs: xforms_lists: support DEFINE_IDTENTRY_IRQ() coding-assistants: simplify attribution docs: translations: pt_BR: translate email-clients.rst docs: pt_BR: process: Translate the security-bugs.rst doc:it_IT: align doc-guide translation ...

Linus Torvalds committed 2 months ago

Commit 72fdff12 parents 9d2ed02 791e42085 files · +8019 −604Browse files

Unified · Split

85 files

CREDITS +4 −0
Documentation/ABI/README +1 −1
Documentation/ABI/testing/sysfs-edac-memory-repair +1 −1
Documentation/admin-guide/kernel-parameters.txt +15 −19
Documentation/admin-guide/media/bttv.rst +1 −1
Documentation/admin-guide/mm/pagemap.rst +4 −4
Documentation/admin-guide/pm/amd-pstate.rst +1 −1
Documentation/conf.py +3 −3
Documentation/core-api/SMP.rst +11 −0
Documentation/core-api/dma-api.rst +1 −1
Documentation/core-api/errseq.rst +1 −1
Documentation/core-api/index.rst +1 −0
Documentation/core-api/list.rst +1 −1
Documentation/core-api/min_heap.rst +0 −13
Documentation/core-api/packing.rst +2 −2
Documentation/core-api/real-time/hardware.rst +104 −0
Documentation/core-api/real-time/index.rst +1 −0
Documentation/core-api/real-time/kernel-configuration.rst +307 −0
Documentation/dev-tools/container.rst +3 −3
Documentation/driver-api/ipmi.rst +1 −1
Documentation/driver-api/usb/writing_usb_driver.rst +0 −3
Documentation/filesystems/overlayfs.rst +1 −2
Documentation/filesystems/proc.rst +1 −1
Documentation/index.rst +8 −0
Documentation/kernel-hacking/locking.rst +4 −4
Documentation/process/coding-assistants.rst +6 −6
Documentation/process/generated-content.rst +7 −0
Documentation/process/submitting-patches.rst +6 −8
Documentation/scheduler/sched-energy.rst +1 −1
Documentation/scheduler/sched-pelt.c +2 −1
Documentation/sphinx-static/custom.css +15 −9
Documentation/sphinx/maintainers_include.py +5 −2
Documentation/translations/it_IT/doc-guide/checktransupdate.rst +59 −0
Documentation/translations/it_IT/doc-guide/contributing.rst +319 −0
Documentation/translations/it_IT/doc-guide/index.rst +3 −10
Documentation/translations/it_IT/doc-guide/kernel-doc.rst +69 −19
Documentation/translations/it_IT/doc-guide/maintainer-profile.rst +60 −0
Documentation/translations/it_IT/doc-guide/parse-headers.rst +110 −110
Documentation/translations/it_IT/doc-guide/sphinx.rst +137 −41
Documentation/translations/it_IT/process/changes.rst +73 −45
Documentation/translations/ja_JP/process/submitting-patches.rst +152 −75
Documentation/translations/pt_BR/index.rst +1 −12
Documentation/translations/pt_BR/process/4.Coding.rst +440 −0
Documentation/translations/pt_BR/process/5.Posting.rst +376 −0
Documentation/translations/pt_BR/process/6.Followthrough.rst +220 −0
Documentation/translations/pt_BR/process/7.AdvancedTopics.rst +201 −0
Documentation/translations/pt_BR/process/8.Conclusion.rst +73 −0
Documentation/translations/pt_BR/process/adding-syscalls.rst +700 −0
Documentation/translations/pt_BR/process/applying-patches.rst +447 −0
Documentation/translations/pt_BR/process/backporting.rst +598 −0
Documentation/translations/pt_BR/process/botching-up-ioctls.rst +256 −0
Documentation/translations/pt_BR/process/code-of-conduct-interpretation.rst +257 −0
Documentation/translations/pt_BR/process/code-of-conduct.rst +88 −0
Documentation/translations/pt_BR/process/contribution-maturity-model.rst +111 −0
Documentation/translations/pt_BR/process/cve.rst +125 −0
Documentation/translations/pt_BR/process/deprecated.rst +422 −0
Documentation/translations/pt_BR/process/development-process.rst +5 −0
Documentation/translations/pt_BR/process/email-clients.rst +368 −0
Documentation/translations/pt_BR/process/index.rst +102 −0
Documentation/translations/pt_BR/process/kernel-driver-statement.rst +205 −0
Documentation/translations/pt_BR/process/maintainer-netdev.rst +16 −7
Documentation/translations/pt_BR/process/management-style.rst +265 −0
Documentation/translations/pt_BR/process/security-bugs.rst +368 −0
Documentation/translations/pt_BR/process/submit-checklist.rst +145 −0
Documentation/translations/zh_CN/accounting/psi.rst +1 −1
Documentation/translations/zh_CN/admin-guide/index.rst +152 −50
Documentation/translations/zh_CN/admin-guide/module-signing.rst +250 −0
Documentation/translations/zh_CN/dev-tools/kasan.rst +1 −1
Documentation/translations/zh_CN/how-to.rst +100 −49
Documentation/translations/zh_CN/rust/arch-support.rst +1 −0
Documentation/translations/zh_CN/rust/general-information.rst +79 −3
Documentation/translations/zh_CN/rust/quick-start.rst +19 −29
Documentation/translations/zh_CN/rust/testing.rst +4 −0
Documentation/translations/zh_CN/scheduler/sched-energy.rst +1 −1
Documentation/translations/zh_CN/security/self-protection.rst +1 −1
Documentation/translations/zh_TW/process/stable-api-nonsense.rst +31 −31
MAINTAINERS +4 −3
README +9 −9
scripts/checkpatch.pl +4 −3
tools/docs/documentation-file-ref-check +1 −1
tools/docs/sphinx-build-wrapper +11 −2
tools/lib/python/abi/abi_regex.py +5 −6
tools/lib/python/kdoc/kdoc_output.py +1 −1
tools/lib/python/kdoc/kdoc_parser.py +53 −5
tools/lib/python/kdoc/xforms_lists.py +1 −0

CREDITS+4−0

@@ -1821,6 +1821,10 @@ S: Am Strand 5 · 1820 unmodified lines
1821	S: D-19063 Schwerin	1821	S: D-19063 Schwerin
1822	S: Germany	1822	S: Germany
1823		1823
		1824	N: Haowen Hu
		1825	E: srcres258@furdevs.cn
		1826	D: Traditional Chinese (zh_TW) documentation translation and maintenance
		1827
1824	N: Jan Hubicka	1828	N: Jan Hubicka
1825	E: hubicka@freesoft.cz	1829	E: hubicka@freesoft.cz
1826	E: hubicka@suse.cz	1830	E: hubicka@suse.cz

Documentation/ABI/README+1−1

@@ -62,7 +62,7 @@ Users: All users of this interface who wish to be notified when · 61 unmodified lines
62		62
63		63
64	Note:	64	Note:
65	The fields should be use a simple notation, compatible with ReST markup.	65	The fields should use a simple notation, compatible with ReST markup.
66	Also, the file should not have a top-level index, like::	66	Also, the file should not have a top-level index, like::
67		67
68	===	68	===

Documentation/ABI/testing/sysfs-edac-memory-repair+1−1

@@ -160,7 +160,7 @@ Description: · 159 unmodified lines
160	in trace events, such as CXL DRAM and CXL general media	160	in trace events, such as CXL DRAM and CXL general media
161	error records of CXL memory devices.	161	error records of CXL memory devices.
162		162
163	When readng back these attributes, it returns the current	163	When reading back these attributes, it returns the current
164	value of memory requested to be repaired.	164	value of memory requested to be repaired.
165		165
166	bank_group - The bank group of the memory to repair.	166	bank_group - The bank group of the memory to repair.

Documentation/admin-guide/kernel-parameters.txt+15−19

 			on all PCI bridges while in the EFI boot stub
 	efi_no_storage_paranoia [EFI,X86,EARLY]
-			Using this parameter you can use more than 50% of
+			The kernel reserves 5KB of EFI variable storage for
-			your efi variable storage. Use this parameter only if
+			safety, because some UEFI implementation may fail to
-			you are really sure that your UEFI does sane gc and
+			boot if there's insufficient space in the EFI variable
-			fulfills the spec otherwise your board may brick.
+			storage.
+			Using this parameter, you can use the 5KB reservation
+			in the EFI variable storage.
+			However, Use this parameter only if you are really
+			sure that your UEFI does sane gc and fulfills the spec
+			otherwise your board may brick.
 	efivar_ssdt=	[EFI; X86] Name of an EFI variable that contains an SSDT
 			that is to be dynamically loaded by Linux. If there are
 	reboot=		[KNL]
 			Format (x86 or x86_64):
 				[w[arm] | c[old] | h[ard] | s[oft] | g[pio]] | d[efault] \
-				[[,]s[mp]#### \
+				[[,]s[mp]####] \
 				[[,]b[ios] | a[cpi] | k[bd] | t[riple] | e[fi] | p[ci]] \
-				[[,]f[orce]
+				[[,]f[orce]]
 			Where reboot_mode is one of warm (soft) or cold (hard) or gpio
 					(prefix with 'panic_' to set mode for panic
 					reboot only),
 			xtime_lock contention on larger systems, and/or RCU lock
 			contention on all systems with CONFIG_MAXSMP set.
 			Format: { "0" | "1" }
-			0 -- disable. (may be 1 via CONFIG_CMDLINE="skew_tick=1"
+			0 -- disable. (may be 1 via CONFIG_CMDLINE="skew_tick=1")
 			1 -- enable.
 			Note: increases power consumption, thus should only be
 			enabled if running jitter sensitive (HPC/RT) workloads.
 			apic=verbose is specified.
 			Example: apic=debug show_lapic=all
-	slab_debug[=options[,slabs][;[options[,slabs]]...]	[MM]
+	slab_debug[=options[,slabs][;[options[,slabs]]...]]	[MM]
 			Enabling slab_debug allows one to determine the
 			culprit if slab objects become corrupted. Enabling
 			slab_debug can create guard zones around objects and
 			take as long as they take.  Specifying 300,000
 			for this value provides a 5-minute timeout.
-	smsc-ircc2.nopnp	[HW] Don't use PNP to discover SMC devices
-	smsc-ircc2.ircc_cfg=	[HW] Device configuration I/O port
-	smsc-ircc2.ircc_sir=	[HW] SIR base I/O port
-	smsc-ircc2.ircc_fir=	[HW] FIR base I/O port
-	smsc-ircc2.ircc_irq=	[HW] IRQ line
-	smsc-ircc2.ircc_dma=	[HW] DMA channel
-	smsc-ircc2.ircc_transceiver= [HW] Transceiver type:
-				0: Toshiba Satellite 1800 (GP data pin select)
-				1: Fast pin select (default)
-				2: ATC IRMode
 	smt=		[KNL,MIPS,S390,EARLY] Set the maximum number of threads
 			(logical CPUs) to use per physical CPU on systems
 			capable of symmetric multithreading (SMT). Will

Documentation/admin-guide/media/bttv.rst+1−1

@@ -1239,7 +1239,7 @@ Models: · 1238 unmodified lines
1239	- Galaxis DVB Card C CI	1239	- Galaxis DVB Card C CI
1240	- Galaxis DVB Card S	1240	- Galaxis DVB Card S
1241	- Galaxis DVB Card C	1241	- Galaxis DVB Card C
1242	- Galaxis plug.in S [neuer Name: Galaxis DVB Card S CI	1242	- Galaxis plug.in S [new Name: Galaxis DVB Card S CI]
1243		1243
1244	Hauppauge	1244	Hauppauge
1245	~~~~~~~~~	1245	~~~~~~~~~

Documentation/admin-guide/mm/pagemap.rst+4−4

@@ -67,7 +67,7 @@ number of times a page is mapped. · 66 unmodified lines
67	* ``/proc/kpageflags``. This file contains a 64-bit set of flags for each	67	* ``/proc/kpageflags``. This file contains a 64-bit set of flags for each
68	page, indexed by PFN.	68	page, indexed by PFN.
69		69
70	The flags are (from ``fs/proc/page.c``, above kpageflags_read):	70	The flags are (from ``include/uapi/linux/kernel-page-flags.h``):
71		71
72	0. LOCKED	72	0. LOCKED
73	1. ERROR	73	1. ERROR
@@ -264,7 +264,7 @@ The ``struct pm_scan_arg`` is used as the argument of the IOCTL. · 190 unmodified lines
264	provided or not.	264	provided or not.
265	3. The range is specified through ``start`` and ``end``.	265	3. The range is specified through ``start`` and ``end``.
266	4. The walk can abort before visiting the complete range such as the user buffer	266	4. The walk can abort before visiting the complete range such as the user buffer
267	can get full etc. The walk ending address is specified in``end_walk``.	267	can get full etc. The walk ending address is specified in ``walk_end``.
268	5. The output buffer of ``struct page_region`` array and size is specified in	268	5. The output buffer of ``struct page_region`` array and size is specified in
269	``vec`` and ``vec_len``.	269	``vec`` and ``vec_len``.
270	6. The optional maximum requested pages are specified in the ``max_pages``.	270	6. The optional maximum requested pages are specified in the ``max_pages``.
@@ -275,7 +275,7 @@ Find pages which have been written and WP them as well:: · 4 unmodified lines
275		275
276	struct pm_scan_arg arg = {	276	struct pm_scan_arg arg = {
277	.size = sizeof(arg),	277	.size = sizeof(arg),
278	.flags = PM_SCAN_CHECK_WPASYNC \| PM_SCAN_CHECK_WPASYNC,	278	.flags = PM_SCAN_WP_MATCHING \| PM_SCAN_CHECK_WPASYNC,
279	..	279	..
280	.category_mask = PAGE_IS_WRITTEN,	280	.category_mask = PAGE_IS_WRITTEN,
281	.return_mask = PAGE_IS_WRITTEN,	281	.return_mask = PAGE_IS_WRITTEN,
@@ -288,7 +288,7 @@ present or huge:: · 6 unmodified lines
288	.size = sizeof(arg),	288	.size = sizeof(arg),
289	.flags = 0,	289	.flags = 0,
290	..	290	..
291	.category_mask = PAGE_IS_WRITTEN \| PAGE_IS_SWAPPED,	291	.category_mask = PAGE_IS_WRITTEN \| PAGE_IS_FILE,
292	.category_inverted = PAGE_IS_SWAPPED,	292	.category_inverted = PAGE_IS_SWAPPED,
293	.category_anyof_mask = PAGE_IS_PRESENT \| PAGE_IS_HUGE,	293	.category_anyof_mask = PAGE_IS_PRESENT \| PAGE_IS_HUGE,
294	.return_mask = PAGE_IS_WRITTEN \| PAGE_IS_SWAPPED \|	294	.return_mask = PAGE_IS_WRITTEN \| PAGE_IS_SWAPPED \|

Documentation/admin-guide/pm/amd-pstate.rst+1−1

@@ -471,7 +471,7 @@ update the core ranking and set the cpu's priority. · 470 unmodified lines
471	Kernel Parameters	471	Kernel Parameters
472	-----------------	472	-----------------
473		473
474	``amd-pstate`` peferred core`` has two states: enable and disable.	474	``amd-pstate`` preferred core has two states: enable and disable.
475	Enable/disable states can be chosen by different kernel parameters.	475	Enable/disable states can be chosen by different kernel parameters.
476	Default enable ``amd-pstate`` preferred core.	476	Default enable ``amd-pstate`` preferred core.
477		477

Documentation/conf.py+3−3

@@ -61,12 +61,12 @@ manpages_url = 'https://man7.org/linux/man-pages/man{section}/{page}.{section}.h · 60 unmodified lines
61		61
62	def config_init(app, config):	62	def config_init(app, config):
63	"""	63	"""
64	Initialize path-dependent variabled	64	Initialize path-dependent variables
65		65
66	On Sphinx, all directories are relative to what it is passed as	66	On Sphinx, all directories are relative to what it is passed as
67	SOURCEDIR parameter for sphinx-build. Due to that, all patterns	67	SOURCEDIR parameter for sphinx-build. Due to that, all patterns
68	that have directory names on it need to be dynamically set, after	68	that have directory names on it need to be dynamically set, after
69	converting them to a relative patch.	69	converting them to a relative path.
70		70
71	As Sphinx doesn't include any patterns outside SOURCEDIR, we should	71	As Sphinx doesn't include any patterns outside SOURCEDIR, we should
72	exclude relative patterns that start with "../".	72	exclude relative patterns that start with "../".
@@ -287,7 +287,7 @@ author = "The kernel development community" · 214 unmodified lines
287	try:	287	try:
288	makefile_version = None	288	makefile_version = None
289	makefile_patchlevel = None	289	makefile_patchlevel = None
290	with open("../Makefile", encoding="utf=8") as fp:	290	with open("../Makefile", encoding="utf-8") as fp:
291	for line in fp:	291	for line in fp:
292	key, val = [x.strip() for x in line.split("=", 2)]	292	key, val = [x.strip() for x in line.split("=", 2)]
293	if key == "VERSION":	293	if key == "VERSION":

Documentation/core-api/SMP.rst+11−0

@@ -0,0 +1,11 @@
	1	.. SPDX-License-Identifier: GPL-2.0+
	2
	3	==============
	4	SMP primitives
	5	==============
	6
	7	.. kernel-doc:: include/linux/smp.h
	8	:internal:
	9
	10	.. kernel-doc:: kernel/smp.c
	11	:export:

Documentation/core-api/dma-api.rst+1−1

@@ -508,7 +508,7 @@ call to dma_iova_try_alloc. This can be useful in the unmap path. · 507 unmodified lines
508		508
509	Is used to link ranges to the IOVA previously allocated. The start of all	509	Is used to link ranges to the IOVA previously allocated. The start of all
510	but the first call to dma_iova_link for a given state must be aligned	510	but the first call to dma_iova_link for a given state must be aligned
511	to the DMA merge boundary returned by ``dma_get_merge_boundary())``, and	511	to the DMA merge boundary returned by ``dma_get_merge_boundary()``, and
512	the size of all but the last range must be aligned to the DMA merge boundary	512	the size of all but the last range must be aligned to the DMA merge boundary
513	as well.	513	as well.
514		514

Documentation/core-api/errseq.rst+1−1

@@ -143,7 +143,7 @@ Because of this, it's often advantageous to first do an errseq_check to · 142 unmodified lines
143	see if anything has changed, and only later do an	143	see if anything has changed, and only later do an
144	errseq_check_and_advance after taking the lock. e.g.::	144	errseq_check_and_advance after taking the lock. e.g.::
145		145
146	if (errseq_check(&wd.wd_err, READ_ONCE(su.s_wd_err)) {	146	if (errseq_check(&wd.wd_err, READ_ONCE(su.s_wd_err))) {
147	/* su.s_wd_err is protected by s_wd_err_lock */	147	/* su.s_wd_err is protected by s_wd_err_lock */
148	spin_lock(&su.s_wd_err_lock);	148	spin_lock(&su.s_wd_err_lock);
149	err = errseq_check_and_advance(&wd.wd_err, &su.s_wd_err);	149	err = errseq_check_and_advance(&wd.wd_err, &su.s_wd_err);

Documentation/core-api/index.rst+1−0

@@ -81,6 +81,7 @@ Documentation/locking/index.rst for more related documentation. · 80 unmodified lines
81	padata	81	padata
82	../RCU/index	82	../RCU/index
83	wrappers/memory-barriers.rst	83	wrappers/memory-barriers.rst
		84	SMP
84		85
85	Low-level hardware management	86	Low-level hardware management
86	=============================	87	=============================

Documentation/core-api/list.rst+1−1

@@ -458,7 +458,7 @@ The list_move() and list_move_tail() functions can be used to move an entry · 457 unmodified lines
458	from one list to another, to either the start or end respectively.	458	from one list to another, to either the start or end respectively.
459		459
460	In the following example, we'll assume we start with two lists ("clowns" and	460	In the following example, we'll assume we start with two lists ("clowns" and
461	"sidewalk" in the following initial state "State 0"::	461	"sidewalk") in the following initial state "State 0"::
462		462
463	.----------------------------------------------------------------.	463	.----------------------------------------------------------------.
464	v \|	464	v \|

Documentation/core-api/min_heap.rst+0−13

@@ -240,19 +240,6 @@ This macro returns `true` if the heap is full, otherwise `false`. · 239 unmodified lines
240		240
241	Inline Version: min_heap_full_inline(heap)	241	Inline Version: min_heap_full_inline(heap)
242		242
243	- min_heap_empty(heap): Checks whether the heap is empty.
244	Complexity: O(1).
245
246	.. code-block:: c
247
248	bool empty = min_heap_empty(heap);
249
250	- `heap`: A pointer to the min-heap to check.
251
252	This macro returns `true` if the heap is empty, otherwise `false`.
253
254	Inline Version: min_heap_empty_inline(heap)
255
256	Example Usage	243	Example Usage
257	=============	244	=============
258		245

Documentation/core-api/packing.rst+2−2

@@ -330,7 +330,7 @@ Here is an example of how to use the fields APIs: · 329 unmodified lines
330		330
331	void unpack_your_data(const packed_buf_t buf, struct data unpacked)	331	void unpack_your_data(const packed_buf_t buf, struct data unpacked)
332	{	332	{
333	BUILD_BUG_ON(sizeof(*buf) != SIZE;	333	BUILD_BUG_ON(sizeof(*buf) != SIZE);
334		334
335	unpack_fields(buf, sizeof(*buf), unpacked, fields,	335	unpack_fields(buf, sizeof(*buf), unpacked, fields,
336	QUIRK_LITTLE_ENDIAN);	336	QUIRK_LITTLE_ENDIAN);
@@ -338,7 +338,7 @@ Here is an example of how to use the fields APIs: · 1 unmodified line
338		338
339	void pack_your_data(const struct data unpacked, packed_buf_t buf)	339	void pack_your_data(const struct data unpacked, packed_buf_t buf)
340	{	340	{
341	BUILD_BUG_ON(sizeof(*buf) != SIZE;	341	BUILD_BUG_ON(sizeof(*buf) != SIZE);
342		342
343	pack_fields(buf, sizeof(*buf), unpacked, fields,	343	pack_fields(buf, sizeof(*buf), unpacked, fields,
344	QUIRK_LITTLE_ENDIAN);	344	QUIRK_LITTLE_ENDIAN);

Documentation/core-api/real-time/hardware.rst+104−0

@@ -130,3 +130,107 @@ https://github.com/Linutronix/RTC-Testbench. · 129 unmodified lines
130	The goal of this project is to validate real-time network communication. It can	130	The goal of this project is to validate real-time network communication. It can
131	be thought of as a "cyclictest" for networking and also serves as a starting	131	be thought of as a "cyclictest" for networking and also serves as a starting
132	point for application development.	132	point for application development.
		133
		134	Firmware
		135	--------
		136
		137	The firmware often plays a significant role in system operation because it can
		138	perform tasks that the kernel cannot directly access, and in some cases it can
		139	even preempt or intercept the kernel.
		140
		141	A common example of firmware assisting the kernel is when it provides a generic
		142	interface to a resource. Instead of accessing an RTC chip through an I2C host
		143	controller, the kernel may query the firmware for the current time, and the
		144	firmware then accesses the RTC behind the scenes.
		145
		146	Firmware can also intercept kernel execution by providing services that
		147	temporarily take control of the system. One example is memory scrubbing, where
		148	the firmware periodically pauses the kernel, reads back portions of system
		149	memory, and then returns control. During this time, the kernel is effectively
		150	interrupted.
		151	In contrast, some systems provide hardware-based memory scrubbing, which
		152	operates independently of firmware or software. See
		153	Documentation/edac/scrub.rst for details.
		154
		155	If the kernel is intercepted for longer periods then these periods can be made
		156	visible with the hardware latency detector. See
		157	Documentation/trace/hwlat_detector.rst.
		158
		159	The kernel can also be intercepted in response to specific events, such as
		160	overheating. In this case, the firmware may throttle the CPU or shut it down
		161	immediately to prevent hardware damage.
		162
		163	Unless the firmware is well documented, it should be thoroughly tested to
		164	uncover any unexpected behaviour.
		165
		166	EFI
		167	~~~~
		168
		169	EFI provides runtime services that act as a communication interface between the
		170	firmware and the operating system. One such service is reading and writing EFI
		171	variables, which are used, for example, to determine the boot source.
		172
		173	Invoking a runtime service may require the architecture to disable kernel
		174	preemption or interrupts during the call. This means the duration of a service
		175	invocation directly affects the system’s observable latency. There is also
		176	nothing that prevents a service call from disabling interrupts internally while
		177	it runs.
		178
		179	For these reasons, EFI runtime services are disabled by default on a PREEMPT_RT
		180	kernel. They can still be enabled at boot time or via a Kconfig option if
		181	required.
		182	The native EFI runtime service implementation (where both the EFI service and
		183	the kernel are either 32-bit or 64-bit executables) uses a wrapper mechanism
		184	that invokes the service through a dedicated workqueue. This workqueue is named
		185	efi_runtime, and it can be restricted to a housekeeping CPU using the
		186	``/sys/devices/virtual/workqueue/efi_runtime/cpumask`` sysfs file. Assigning it
		187	to a housekeeping CPU ensures that potentially long service invocations do not
		188	impact the real-time workload which is restricted to other CPUs.
		189
		190	It must also be verified that the runtime services behave as expected. Some
		191	implementations on the x86 architecture pause all other CPUs while one CPU
		192	performs the service call. In such cases, the interruption affects all CPUs,
		193	and restricting the workqueue to a single CPU provides no benefit.
		194
		195	OP-TEE (ARM)
		196	~~~~~~~~~~~~
		197
		198	Execution flows from the normal world (Linux) into the secure world (OP-TEE)
		199	through the secure monitor at EL3. The transition is initiated by the `smc`
		200	(Secure Monitor Call) opcode or the `hvc` (Hypervisor Call) opcode together
		201	with a function identifier. The calling convention defines two types of calls:
		202	yielding calls and fast calls:
		203
		204	- A yielding call unmasks interrupts before handling the requested service,
		205	allowing normal world interrupts to occur.
		206	- A fast call handles the requested service atomically, without allowing
		207	interrupts from either the normal world or the secure world.
		208
		209	In addition, the secure world (EL3 and OP-TEE) can receive interrupts routed to
		210	the secure world. While a secure world interrupt is being serviced,
		211	normal world interrupts are masked and cannot preempt the operation.
		212
		213	The transition from normal world to secure monitor to OP-TEE and back introduces
		214	additional latency due to world switching and context save/restore. This
		215	overhead is typically a few microseconds and usually remains within the noise
		216	floor.
		217
		218	It is worth noting that the normal world cannot mask secure interrupts, while
		219	the secure world can mask normal-world interrupts during execution. How OP-TEE
		220	affects real-time workloads depends on whether secure interrupts are enabled
		221	and which OP-TEE services are invoked.
		222
		223	A practical concern is any fast call that runs longer than expected, for
		224	example a function that occasionally performs a long-running cryptographic
		225	computation. Another example that may block in an unexpected way are OP-TEE
		226	drivers that issue RPC requests. An OP-TEE service in the secure world (RPMB
		227	for instance) may need to issue a request back to the normal world (the Linux
		228	driver) in order to complete the operation. While Linux remains preemptible,
		229	the thread that issued the request stays blocked until the RPC completes and
		230	the secure function call returns.
		231
		232	The TF-A project provides documentation on interrupt management:
		233	https://trustedfirmware-a.readthedocs.io/en/latest/design/interrupt-framework-design.html#interrupt-management-framework
		234
		235	The OP-TEE project provides documentation on how interrupts are handled:
		236	https://optee.readthedocs.io/en/latest/architecture/core.html#interrupt-handling

Documentation/core-api/real-time/index.rst+1−0

@@ -15,3 +15,4 @@ the required changes compared to a non-PREEMPT_RT configuration. · 14 unmodified lines
15	differences	15	differences
16	hardware	16	hardware
17	architecture-porting	17	architecture-porting
		18	kernel-configuration

Documentation/core-api/real-time/kernel-configuration.rst+307−0

@@ -0,0 +1,307 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	==============================
	4	Real-Time Kernel configuration
	5	==============================
	6
	7	.. contents:: Table of Contents
	8	:depth: 3
	9	:local:
	10
	11	Introduction
	12	============
	13
	14	This document lists the kernel configuration options that might affect a
	15	real-time kernel's worst-case latency. It is intended for system integrators.
	16
	17	Configuration options
	18	=====================
	19
	20	.. Please keep the configuration listings alphabetically ordered
	21
	22	CPU frequency governors
	23	-----------------------
	24
	25	``CONFIG_CPU_FREQ``
	26	^^^^^^^^^^^^^^^^^^^
	27
	28	:Expectation: enabled
	29	:Severity: high
	30
	31	The CPU frequency scaling subsystem ensures that the processor can operate at
	32	its maximum supported frequency. While, in general, bootloaders are tasked
	33	with setting the CPU clock to the highest speed on boot, some do not. It is
	34	thus desirable to keep this option enabled.
	35
	36	.. caution::
	37
	38	A real-time kernel is not about being "as fast as possible", however
	39	real-time requirements may demand that the CPU is clocked at a particular
	40	speed.
	41
	42	``CONFIG_CPU_FREQ_DEFAULT_GOV_PERFORMANCE``
	43	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
	44
	45	:Expectation: enabled
	46	:Severity: high
	47
	48	Real-Time workloads expect a fixed CPU frequency during execution. Using the
	49	performance governor is an easy way to achieve that purely from kernel
	50	configuration.
	51
	52	This is not an absolute rule. Some setups might prefer to clock the CPU to
	53	lower speeds due to thermal packaging or other requirements. The key is that
	54	the CPU frequency remains constant once set.
	55
	56	Non-performance CPU frequency governors
	57	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
	58
	59	:Expectation: disabled
	60	:Severity: medium
	61
	62	To ensure reproducible system latency measurements, disable the
	63	non-``PERFORMANCE`` CPU frequency governors whenever possible. This avoids
	64	the risk of unknown userspace tasks implicitly or explicitly setting a
	65	different CPU frequency governor, and thereby changing latency behavior while
	66	the system is running.
	67
	68	If disabling other frequency governors is not an option, use a governor that
	69	keeps the CPU frequency fixed. For example,
	70	``CONFIG_CPU_FREQ_DEFAULT_GOV_USERSPACE`` can be enabled when userspace is
	71	responsible for setting a stable frequency during system initialization.
	72
	73	If a low CPU frequency is desired, then
	74	``CONFIG_CPU_FREQ_DEFAULT_GOV_POWERSAVE`` can be set.
	75
	76	The ``ONDEMAND`` governor should not be enabled on a real-time system. Its
	77	frequency changes depend on workload behavior and can significantly harm
	78	determinism.
	79
	80	For more information, see Documentation/admin-guide/pm/cpufreq.rst
	81
	82	``CONFIG_CPU_IDLE``
	83	-------------------
	84
	85	:Expectation: enabled
	86	:Severity: info
	87
	88	CPU idle states (C-states) allow the processor to enter low-power modes during
	89	periods of inactivity. Very-low CPU idle states may require flushing the CPU
	90	caches and lowering or disabling the clocking. This can lower power
	91	consumption, but it also increases the entry and exit latency from such
	92	states.
	93
	94	While disabling this option eliminates cpuidle-related latencies, doing so can
	95	significantly impact hardware longevity, warranty, and thermal behavior.
	96	Users should cap the maximum C-state to C1 instead. For ACPI platforms, this
	97	can be achieved by using the boot parameter [1]_::
	98
	99	processor.max_cstate=1
	100
	101	Higher C-states can be acceptable depending on the user workload's latency
	102	requirements. For ACPI-based platforms, use the ``cpupower idle-info``
	103	command to inspect the available idle states.
	104
	105	For more information, please see:
	106
	107	- ``linux/tools/power/cpupower``
	108	- Documentation/admin-guide/pm/cpuidle.rst
	109	- Documentation/admin-guide/pm/index.rst
	110
	111	``CONFIG_DRM``
	112	--------------
	113
	114	:Expectation: disabled
	115	:Severity: info
	116
	117	GPU-accelerated workloads can share system resources with the CPU, including
	118	last-level cache (LLC) and memory bandwidth. Modern integrated GPUs optimize
	119	graphics performance at the expense of CPU determinism.
	120
	121	Examples of affected platforms:
	122
	123	- Intel processors with integrated graphics (Gen9 and later)
	124	- AMD APUs with Radeon Graphics
	125	- Xilinx Zynq UltraScale+ MPSoC EG/EV series
	126
	127	If graphics workloads must run alongside real-time tasks, users must conduct
	128	thorough stress testing using tools like ``glmark2`` while measuring the
	129	overall system latency.
	130
	131	For more information, please check:
	132
	133	- Documentation/core-api/real-time/hardware.rst ("Regarding hardware" section)
	134	- Documentation/filesystems/resctrl.rst
	135	- `Real-Time and Graphics: A Contradiction? <https://web.archive.org/web/20221025085614/https://linutronix.de/PDF/Realtime_and_graphics-acontradiction2021.pdf>`_
	136
	137	``CONFIG_EFI_DISABLE_RUNTIME``
	138	------------------------------
	139
	140	:Expectation: enabled
	141	:Severity: medium
	142
	143	EFI is the standard boot and firmware interface for multiple architectures.
	144	EFI runtime services provide callback functions to be called from the kernel;
	145	e.g., as utilized by (``CONFIG_EFI_VARS*``) or (``CONFIG_RTC_DRV_EFI``). For
	146	the former, the kernel calls into EFI to update the EFI variables.
	147
	148	Calling into EFI means invoking firmware callbacks. During such invocations,
	149	the system might not be able to react to interrupts and will thus not be able
	150	to perform a context switch. This can cause significant latency spikes for
	151	the real-time system.
	152
	153	``CONFIG_PREEMPT_RT`` enables this option by default. If this option is
	154	manually disabled at build time, the following boot parameter [1]_ may be used
	155	to disable EFI runtime at boot up::
	156
	157	efi=noruntime
	158
	159	Alternatively, confine EFI runtime service calls to a housekeeping CPU by
	160	restricting the ``efi_runtime`` workqueue CPU affinity. For example, set that
	161	workqueue's affinity to CPU #0 and pin your RT tasks to a different CPU range.
	162	See Documentation/core-api/workqueue.rst
	163
	164	``CONFIG_NO_HZ`` / ``CONFIG_NO_HZ_FULL``
	165	----------------------------------------
	166
	167	:Expectation: disabled
	168	:Severity: medium
	169
	170	Tickless operation can increase kernel-to-userspace transition latency due to
	171	the extra accounting and state book-keeping.
	172
	173	Guidance by real-time workload type:
	174
	175	- For periodic workloads; e.g., control loops executing every 100 µs, avoid
	176	``NO_HZ`` modes. Consistent kernel ticks are preferable.
	177
	178	- For computation-intensive workloads; e.g. extended userspace execution,
	179	``NO_HZ_FULL`` may be beneficial. In such cases, users should offload the
	180	kernel housekeeping to dedicated CPUs and isolate compute cores.
	181
	182	See also Documentation/timers/no_hz.rst
	183
	184	``CONFIG_PREEMPT_RT``
	185	---------------------
	186
	187	:Expectation: enabled
	188	:Severity: fatal
	189
	190	This option must be enabled, or the resulting kernel will not be fully
	191	preemptible and real-time capable.
	192
	193	``CONFIG_TRACING`` (and tracing options)
	194	----------------------------------------
	195
	196	:Expectation: enabled
	197	:Severity: info
	198
	199	Shipping kernels with tracing support enabled (but not actively running) is
	200	highly recommended. This will allow the users to extract more information if
	201	latency problems arise. Nonetheless, some tracers do incur latency overhead
	202	just by being enabled.
	203
	204	.. caution::
	205
	206	Users should not make use of tracers or trace events during production
	207	real-time kernel operation as they can add considerable overhead and degrade
	208	the system's latency.
	209
	210	``CONFIG_IRQSOFF_TRACER`` and ``CONFIG_PREEMPT_TRACER``
	211	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
	212
	213	:Expectation: disabled
	214	:Severity: high
	215
	216	These tracers do incur measurable latency overhead even when tracing is not
	217	currently active.
	218
	219	Kernel Debug Options
	220	====================
	221
	222	Most kernel debug options add runtime overhead that increases the worst-case
	223	latency.
	224
	225	.. caution::
	226
	227	During development and early testing, users are encouraged to run their
	228	real-time workloads and peripherals with lockdep (:ref:`lockdep`) and other
	229	kernel debug options enabled, for a considerable amount of time. Such
	230	workloads might trigger kernel code paths that were not triggered during the
	231	internal Linux real-time kernel development, thus helping to uncover locking
	232	and other types of kernel bugs.
	233
	234	``CONFIG_DEBUG_ATOMIC_SLEEP``
	235	-----------------------------
	236
	237	:Expectation: allowed
	238
	239	This sanity check catches common kernel programming errors with a tolerable
	240	latency cost. It also increases overall scheduling as each ``might_sleep()``
	241	can lead to a context switch.
	242
	243	``CONFIG_DEBUG_BUGVERBOSE`` and ``CONFIG_DEBUG_INFO*``
	244	------------------------------------------------------
	245
	246	:Expectation: allowed
	247
	248	These options increase the kernel image size but have no latency impact. They
	249	are also essential for meaningful BUG logs, crash dumps, and profiling.
	250
	251	``CONFIG_DEBUG_FS``
	252	-------------------
	253
	254	:Expectation: allowed
	255
	256	This is safe to include in real-time kernels, *provided that debugfs is not
	257	accessed during production runtime*.
	258
	259	``CONFIG_DEBUG_KERNEL``
	260	-----------------------
	261
	262	:Expectation: allowed
	263
	264	Meta-option which allows debug features to be enabled. It has no runtime
	265	impact, but beware of any debug features that it may have implicitly enabled.
	266
	267	``CONFIG_LOCKUP_DETECTOR``
	268	--------------------------
	269
	270	:Expectation: disabled
	271	:Severity: high
	272
	273	The lockup detector creates kernel timer callbacks that execute every few
	274	seconds, in hard-IRQ context, even on real-time kernels. These periodic
	275	interrupts can cause latency spikes.
	276
	277	Users should use hardware watchdogs instead, which will provide a similar
	278	functionality without the software-induced latency.
	279
	280	.. _lockdep:
	281
	282	``CONFIG_PROVE_LOCKING``
	283	------------------------
	284
	285	:Expectation: disabled
	286	:Severity: high
	287
	288	Proving the correctness of all kernel locking adds substantial overhead and
	289	significantly increases worst-case latency.
	290
	291	Summary
	292	=======
	293
	294	There is no "one size fits all" solution for configuring a real-time Linux
	295	system. Beginning with the system real-time requirements, integrators must
	296	consider the features and functions of the system's hardware, kernel, and
	297	userspace. All such components must be properly configured in order to
	298	establish and constrain the system's maximum latency.
	299
	300	With that in mind, any incorrect real-time kernel configuration could cause a
	301	new maximum latency that shows up at the wrong time and is catastrophic for
	302	the real-time system's latency.
	303
	304	References
	305	==========
	306
	307	.. [1] See Documentation/admin-guide/kernel-parameters.rst

Documentation/dev-tools/container.rst+3−3

@@ -40,7 +40,7 @@ Available options: · 39 unmodified lines
40		40
41	``-r, --runtime RUNTIME``	41	``-r, --runtime RUNTIME``
42		42
43	Container runtime name. Supported runtimes: ``docker``, ``podman``.	43	Container runtime name. Supported runtimes: ``podman``, ``docker``.
44		44
45	If not specified, the first one found on the system will be used	45	If not specified, the first one found on the system will be used
46	i.e. Podman if present, otherwise Docker.	46	i.e. Podman if present, otherwise Docker.
@@ -75,8 +75,8 @@ working directory and adjust the user and group id as needed. · 28 unmodified lines
75		75
76	The container image which would typically include a compiler toolchain is	76	The container image which would typically include a compiler toolchain is
77	provided by the user and selected via the ``-i`` option. The container runtime	77	provided by the user and selected via the ``-i`` option. The container runtime
78	can be selected with the ``-r`` option, which can be either ``docker`` or	78	can be selected with the ``-r`` option, which can be either ``podman`` or
79	``podman``. If none is specified, the first one found on the system will be	79	``docker``. If none is specified, the first one found on the system will be
80	used while giving priority to Podman. Support for other runtimes may be added	80	used while giving priority to Podman. Support for other runtimes may be added
81	later depending on their popularity among users.	81	later depending on their popularity among users.
82		82

Documentation/driver-api/ipmi.rst+1−1

@@ -280,7 +280,7 @@ Creating the User · 279 unmodified lines
280	To use the message handler, you must first create a user using	280	To use the message handler, you must first create a user using
281	ipmi_create_user. The interface number specifies which SMI you want	281	ipmi_create_user. The interface number specifies which SMI you want
282	to connect to, and you must supply callback functions to be called	282	to connect to, and you must supply callback functions to be called
283	when data comes in. This also allows to you pass in a piece of data,	283	when data comes in. This also allows you to pass in a piece of data,
284	the handler_data, that will be passed back to you on all calls.	284	the handler_data, that will be passed back to you on all calls.
285		285
286	Once you are done, call ipmi_destroy_user() to get rid of the user.	286	Once you are done, call ipmi_destroy_user() to get rid of the user.

Documentation/driver-api/usb/writing_usb_driver.rst+0−3

@@ -322,7 +322,4 @@ http://linux-hotplug.sourceforge.net/ · 321 unmodified lines
322	linux-usb Mailing List Archives:	322	linux-usb Mailing List Archives:
323	https://lore.kernel.org/linux-usb/	323	https://lore.kernel.org/linux-usb/
324		324
325	Programming Guide for Linux USB Device Drivers:
326	https://lmu.web.psi.ch/docu/manuals/software_manuals/linux_sl/usb_linux_programming_guide.pdf
327
328	USB Home Page: https://www.usb.org	325	USB Home Page: https://www.usb.org

Documentation/filesystems/overlayfs.rst+1−2

@@ -123,8 +123,7 @@ At mount time, the two directories given as mount options "lowerdir" and · 122 unmodified lines
123	mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,\	123	mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,\
124	workdir=/work /merged	124	workdir=/work /merged
125		125
126	The "workdir" needs to be an empty directory on the same filesystem	126	The "workdir" needs to be a directory on the same filesystem as upperdir.
127	as upperdir.
128		127
129	Then whenever a lookup is requested in such a merged directory, the	128	Then whenever a lookup is requested in such a merged directory, the
130	lookup is performed in each actual directory and the combined result	129	lookup is performed in each actual directory and the combined result

Documentation/filesystems/proc.rst+1−1

@@ -513,7 +513,7 @@ In some kernel configurations, the semantics of pages part of a larger · 512 unmodified lines
513	allocation (e.g., THP) can differ: a page is accounted as "private" if all	513	allocation (e.g., THP) can differ: a page is accounted as "private" if all
514	pages part of the corresponding large allocation are certainly mapped in the	514	pages part of the corresponding large allocation are certainly mapped in the
515	same process, even if the page is mapped multiple times in that process. A	515	same process, even if the page is mapped multiple times in that process. A
516	page is accounted as "shared" if any page page of the larger allocation	516	page is accounted as "shared" if any page of the larger allocation
517	is maybe mapped in a different process. In some cases, a large allocation	517	is maybe mapped in a different process. In some cases, a large allocation
518	might be treated as "maybe mapped by multiple processes" even though this	518	might be treated as "maybe mapped by multiple processes" even though this
519	is no longer the case.	519	is no longer the case.

Documentation/index.rst+8−0

 .. toctree::
    :maxdepth: 1
+   :caption: Working with the development community
    Development process <process/development-process>
    Submitting patches <process/submitting-patches>
 .. toctree::
    :maxdepth: 1
+   :caption: Internal API manuals
    Core API <core-api/index>
    Driver APIs <driver-api/index>
 .. toctree::
    :maxdepth: 1
+   :caption: Development tools and processes
    Licensing rules <process/license-rules>
    Writing documentation <doc-guide/index>
 .. toctree::
    :maxdepth: 1
+   :caption: User-oriented documentation
    Administration <admin-guide/index>
    Build system <kbuild/index>
 .. toctree::
    :maxdepth: 1
+   :caption: Firmware-related documentation
    Firmware <firmware-guide/index>
    Firmware and Devicetree <devicetree/index>
 .. toctree::
    :maxdepth: 2
+   :caption: Architecture-specific documentation
    CPU architectures <arch/index>
 .. toctree::
    :maxdepth: 1
+   :caption: Other documentation
    Unsorted documentation <staging/index>
 .. toctree::
    :maxdepth: 2
+   :caption: Translations
    Translations <translations/index>

Documentation/kernel-hacking/locking.rst+4−4

@@ -471,7 +471,7 @@ to protect the cache and all the objects within it. Here's the code:: · 470 unmodified lines
471	obj = __cache_find(id);	471	obj = __cache_find(id);
472	if (obj) {	472	if (obj) {
473	ret = 0;	473	ret = 0;
474	strcpy(name, obj->name);	474	strscpy(name, obj->name);
475	}	475	}
476	mutex_unlock(&cache_lock);	476	mutex_unlock(&cache_lock);
477	return ret;	477	return ret;
@@ -553,7 +553,7 @@ which are taken away, and the ``+`` are lines which are added. · 75 unmodified lines
553	obj = __cache_find(id);	553	obj = __cache_find(id);
554	if (obj) {	554	if (obj) {
555	ret = 0;	555	ret = 0;
556	strcpy(name, obj->name);	556	strscpy(name, obj->name);
557	}	557	}
558	- mutex_unlock(&cache_lock);	558	- mutex_unlock(&cache_lock);
559	+ spin_unlock_irqrestore(&cache_lock, flags);	559	+ spin_unlock_irqrestore(&cache_lock, flags);
@@ -676,7 +676,7 @@ Here is the code:: · 116 unmodified lines
676	obj = __cache_find(id);	676	obj = __cache_find(id);
677	- if (obj) {	677	- if (obj) {
678	- ret = 0;	678	- ret = 0;
679	- strcpy(name, obj->name);	679	- strscpy(name, obj->name);
680	- }	680	- }
681	+ if (obj)	681	+ if (obj)
682	+ __object_get(obj);	682	+ __object_get(obj);
@@ -1317,7 +1317,7 @@ from user context, and can sleep. · 634 unmodified lines
1317		1317
1318	- put_user()	1318	- put_user()
1319		1319
1320	- kmalloc(GP_KERNEL) <kmalloc>`	1320	- kmalloc(GFP_KERNEL) <kmalloc>
1321		1321
1322	- mutex_lock_interruptible() and	1322	- mutex_lock_interruptible() and
1323	mutex_lock()	1323	mutex_lock()

Documentation/process/coding-assistants.rst+6−6

 * Documentation/process/coding-style.rst
 * Documentation/process/submitting-patches.rst
+For guidelines on content generated by AI coding assistants see:
+* Documentation/process/generated-content.rst
 Licensing and Legal Requirements
 ================================
 helps track the evolving role of AI in the development process.
 Contributions should include an Assisted-by tag in the following format::
-  Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2]
+  Assisted-by: LLM [TOOL1] [TOOL2]
-Where:
-* ``AGENT_NAME`` is the name of the AI tool or framework
-* ``MODEL_VERSION`` is the specific model version used
 * ``[TOOL1] [TOOL2]`` are optional specialized analysis tools used
   (e.g., coccinelle, sparse, smatch, clang-tidy)
 Example::
-  Assisted-by: Claude:claude-3-opus coccinelle sparse
+  Assisted-by: LLM coccinelle sparse
 Procedure for finding and fixing bugs
 =====================================

Documentation/process/generated-content.rst+7−0

@@ -107,3 +107,10 @@ the resulting changes. · 106 unmodified lines
107		107
108	If you do so anyway, maintainers are entitled to reject your series	108	If you do so anyway, maintainers are entitled to reject your series
109	without detailed review.	109	without detailed review.
		110
		111	References
		112	==========
		113
		114	For specific guidelines on AI coding assistants, see:
		115
		116	* Documentation/process/coding-assistants.rst

Documentation/process/submitting-patches.rst+6−8

 The sign-off is a simple line at the end of the explanation for the
 patch, which certifies that you wrote it or otherwise have the right to
 pass it on as an open-source patch.  The rules are pretty simple: if you
-can certify the below:
+can certify the below::
-Developer's Certificate of Origin 1.1
+        Developer's Certificate of Origin 1.1
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-By making a contribution to this project, I certify that:
+        By making a contribution to this project, I certify that:
         (a) The contribution was created in whole or in part by me and I
             have the right to submit it under the open source license
 future patches, and ensures credit for the testers.
 Reviewed-by:, instead, indicates that the patch has been reviewed and found
-acceptable according to the Reviewer's Statement:
+acceptable according to the Reviewer's Statement::
-Reviewer's statement of oversight
+	Reviewer's statement of oversight
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-By offering my Reviewed-by: tag, I state that:
+	By offering my Reviewed-by: tag, I state that:
 	 (a) I have carried out a technical review of this patch to
 	     evaluate its appropriateness and readiness for inclusion into

Documentation/scheduler/sched-energy.rst+1−1

@@ -141,7 +141,7 @@ in its previous activation. · 140 unmodified lines
141	find_energy_efficient_cpu() uses compute_energy() to estimate what will be the	141	find_energy_efficient_cpu() uses compute_energy() to estimate what will be the
142	energy consumed by the system if the waking task was migrated. compute_energy()	142	energy consumed by the system if the waking task was migrated. compute_energy()
143	looks at the current utilization landscape of the CPUs and adjusts it to	143	looks at the current utilization landscape of the CPUs and adjusts it to
144	'simulate' the task migration. The EM framework provides the em_pd_energy() API	144	'simulate' the task migration. The EM framework provides the em_cpu_energy() API
145	which computes the expected energy consumption of each performance domain for	145	which computes the expected energy consumption of each performance domain for
146	the given utilization landscape.	146	the given utilization landscape.
147		147

Documentation/scheduler/sched-pelt.c+2−1

@@ -25,7 +25,8 @@ void calc_runnable_avg_yN_inv(void) · 24 unmodified lines
25	for (i = 0; i < HALFLIFE; i++) {	25	for (i = 0; i < HALFLIFE; i++) {
26	x = ((1UL<<32)-1)*pow(y, i);	26	x = ((1UL<<32)-1)*pow(y, i);
27		27
28	if (i % 6 == 0) printf("\n\t");	28	if (i % 6 == 0)
		29	printf("\n\t");
29	printf("0x%8x, ", x);	30	printf("0x%8x, ", x);
30	}	31	}
31	printf("\n};\n\n");	32	printf("\n};\n\n");

Documentation/sphinx-static/custom.css+15−9

  * CSS tweaks for the Alabaster theme
  */
+div.body {  max-width: 120em; }
 /* Shrink the headers a bit */
 div.body h1 { font-size: 180%; }
 div.body h2 { font-size: 150%; }
 div.kerneltoc { background-color: #eeeeee; }
 div.kerneltoc li.current ul { background-color: white; }
+/*
+ * Hide toctree captions on the welcome page, they should only be shown in the
+ * sidebar.
+ */
+section#the-linux-kernel-documentation p.caption { display: none; }
+/*
+ * Make section titles bold in the sidebar, and decrease their bottom margin to
+ * group them with their subsections.
+ */
+div.sphinxsidebar p.caption { font-weight: bold; margin-bottom: 0; }
+div.sphinxsidebar p.caption + ul { margin-top: 0; }
 /*
  * The CSS magic to toggle the contents on small screens.
  */
     background: #dddddd;
 }
-/*
- * Let long inline literals in paragraph text wrap as needed to prevent
- * overflow.
- */
-code.docutils.literal span.pre {
-    white-space: normal;
-    overflow-wrap: anywhere;
-}
 /* Let rendered reference links in tables wrap when needed. */
 div.body table.docutils a.reference {
     overflow-wrap: anywhere;

Documentation/sphinx/maintainers_include.py+5−2

                     html = KERNELDOC_URL + ename + ".html"
                     entries[entry] = f'`{ename} <{html}>`_'
                 else:
-                    entries[entry] = f':doc:`{ename} </{entry}>`'
+                    entries[entry] = f'/{entry}'
         return entries
                 output += f"- {name}: {entry}\n"
                 self.warning(f"{profile}: Invalid 'P' tag: {entry}\n")
             else:
-                output += f"- {entry}\n"
+                if not name:
+                    name = entry
+                output += f"- :doc:`{name} <{entry}>`\n"
         #
         # Create a hidden TOC table with all profiles. That allows adding

Documentation/translations/it_IT/doc-guide/checktransupdate.rst+59−0

@@ -0,0 +1,59 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	.. include:: ../disclaimer-ita.rst
	4
	5	Verificare la necessità di aggiornare le traduzioni
	6	===================================================
	7
	8	Questo script aiuta a tracciare lo stato delle traduzioni della
	9	documentazione nelle diverse lingue, ovvero se la documentazione è
	10	allineata con la controparte inglese.
	11
	12	Come funziona
	13	-------------
	14
	15	Lo script usa il comando ``git log`` per individuare l'ultimo commit in inglese
	16	a partire dal commit della traduzione (in ordine di data dell'autore) e gli
	17	ultimi commit in inglese a partire da HEAD. Se emergono delle differenze, il
	18	file viene considerato non aggiornato, e vengono quindi raccolti e segnalati i
	19	commit che necessitano di un aggiornamento.
	20
	21	Funzionalità implementate
	22
	23	- verifica di tutti i file in una determinata lingua
	24	- verifica di un singolo file o di un insieme di file
	25	- opzioni per modificare il formato dell'output
	26	- tracciamento dello stato di traduzione dei file che non hanno alcuna
	27	traduzione
	28
	29	Utilizzo
	30	--------
	31
	32	::
	33
	34	tools/docs/checktransupdate.py --help
	35
	36	Fate riferimento all'output del messaggio d'aiuto per i dettagli sull'utilizzo.
	37
	38	Esempi
	39
	40	- ``tools/docs/checktransupdate.py -l zh_CN``
	41	Questo stamperà tutti i file che necessitano di un aggiornamento nella
	42	lingua zh_CN.
	43	- ``tools/docs/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst``
	44	Questo stamperà solamente lo stato del file specificato.
	45
	46	L'output sarà quindi qualcosa del genere:
	47
	48	::
	49
	50	Documentation/dev-tools/kfence.rst
	51	No translation in the locale of zh_CN
	52
	53	Documentation/translations/zh_CN/dev-tools/testing-overview.rst
	54	commit 42fb9cfd5b18 ("Documentation: dev-tools: Add link to RV docs")
	55	1 commits needs resolving in total
	56
	57	Funzionalità ancora da implementare
	58
	59	- specificare cartelle in aggiunta ai singoli file

Documentation/translations/it_IT/doc-guide/contributing.rst+319−0

@@ -0,0 +1,319 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	.. include:: ../disclaimer-ita.rst
	4
	5	Come contribuire al miglioramento della documentazione del kernel
	6	=================================================================
	7
	8	La documentazione è una parte importante di ogni progetto di sviluppo
	9	software. Una buona documentazione aiuta ad attirare nuovi sviluppatori e
	10	permette a quelli già presenti di lavorare in modo più efficace. Senza una
	11	documentazione di qualità, si spreca molto tempo nel decifrare il codice a
	12	ritroso e si commettono errori altrimenti evitabili.
	13
	14	Sfortunatamente, al momento la documentazione del kernel è ben lontana da
	15	quello che dovrebbe essere per sostenere un progetto di queste dimensioni e
	16	importanza.
	17
	18	Questa guida è per chi vuole contribuire a migliorare questa situazione. I
	19	miglioramenti alla documentazione del kernel possono essere fatti da
	20	sviluppatori con diversi livelli di esperienza; sono un modo relativamente
	21	semplice per imparare il processo di sviluppo del kernel in generale e
	22	trovare il proprio posto nella comunità. Quello che segue è, per la maggior
	23	parte, l'elenco dei compiti che il manutentore della documentazione ritiene
	24	più urgenti.
	25
	26	Le cose da fare nella documentazione
	27	------------------------------------
	28
	29	C'è un elenco infinito di compiti da svolgere per portare la nostra
	30	documentazione al livello in cui dovrebbe essere. Questo elenco contiene
	31	alcuni punti importanti, ma è lungi dall'essere esaustivo; se trovate un
	32	modo diverso per migliorare la documentazione, non esitate!
	33
	34	Correzione degli avvisi
	35	~~~~~~~~~~~~~~~~~~~~~~~
	36
	37	Al momento, la generazione della documentazione produce un numero
	38	incredibile di avvisi. Quando ce ne sono così tanti, è come se non ce ne
	39	fosse nessuno: le persone li ignorano e non si accorgeranno mai quando il
	40	loro lavoro ne aggiunge di nuovi. Per questo motivo, eliminare gli avvisi è
	41	uno dei compiti a più alta priorità nell'elenco delle cose da fare per la
	42	documentazione. Il compito in sé è ragionevolmente semplice, ma va
	43	affrontato nel modo giusto per avere successo.
	44
	45	Gli avvisi emessi da un compilatore per il codice C possono spesso essere
	46	scartati come falsi positivi, portando a patch il cui unico scopo è zittire
	47	il compilatore. Gli avvisi generati dalla documentazione, invece, indicano
	48	quasi sempre un problema reale; farli sparire richiede di comprendere il
	49	problema e correggerlo alla radice. Per questo motivo, le patch che
	50	correggono avvisi nella documentazione non dovrebbero limitarsi a dire "fix
	51	a warning" nel titolo del changelog; dovrebbero invece indicare il problema
	52	reale che è stato corretto.
	53
	54	Un altro punto importante è che gli avvisi nella documentazione sono spesso
	55	generati da problemi nei commenti kerneldoc all'interno del codice C. Anche se
	56	il manutentore della documentazione apprezza l'essere messo in copia sulle
	57	correzioni di questo tipo, in realtà spesso rivolgersi al sottosistema di
	58	documentazione non è il modo migliore di apportare queste modifiche; queste
	59	dovrebbero invece essere inviate al manutentore del sottosistema in questione.
	60
	61	Per esempio, in una generazione della documentazione ho preso, quasi a
	62	caso, un paio di avvisi::
	63
	64	./drivers/devfreq/devfreq.c:1818: warning: bad line:
	65	- Resource-managed devfreq_register_notifier()
	66	./drivers/devfreq/devfreq.c:1854: warning: bad line:
	67	- Resource-managed devfreq_unregister_notifier()
	68
	69	(Le righe sono state divise per essere più leggibili).
	70
	71	Una rapida occhiata al file sorgente indicato sopra ha rivelato un paio di
	72	commenti kerneldoc con questo aspetto::
	73
	74	/**
	75	* devm_devfreq_register_notifier()
	76	- Resource-managed devfreq_register_notifier()
	77	* @dev: The devfreq user device. (parent of devfreq)
	78	* @devfreq: The devfreq object.
	79	* @nb: The notifier block to be unregistered.
	80	* @list: DEVFREQ_TRANSITION_NOTIFIER.
	81	*/
	82
	83	Il problema è l'asterisco mancante, che confonde l'idea semplicistica che il
	84	sistema di generazione abbia idea di come debba essere fatto un blocco di
	85	commento C. Questo problema era presente fin da quando quel commento venne
	86	aggiunto nel 2016, quindi da diversi anni. Correggerlo è stata solo questione di
	87	aggiungere gli asterischi mancanti. Una rapida occhiata alla cronologia di quel
	88	file ha mostrato quale fosse il formato usuale per la riga dell'oggetto, e
	89	``scripts/get_maintainer.pl`` mi ha detto chi dovesse riceverla (basta passare
	90	il percorso delle vostre patch come argomento a scripts/get_maintainer.pl). La
	91	patch risultante era questa::
	92
	93	[PATCH] PM / devfreq: Fix two malformed kerneldoc comments
	94
	95	Two kerneldoc comments in devfreq.c fail to adhere to the required format,
	96	resulting in these doc-build warnings:
	97
	98	./drivers/devfreq/devfreq.c:1818: warning: bad line:
	99	- Resource-managed devfreq_register_notifier()
	100	./drivers/devfreq/devfreq.c:1854: warning: bad line:
	101	- Resource-managed devfreq_unregister_notifier()
	102
	103	Add a couple of missing asterisks and make kerneldoc a little happier.
	104
	105	Signed-off-by: Jonathan Corbet <corbet@lwn.net>
	106	---
	107	drivers/devfreq/devfreq.c \| 4 ++--
	108	1 file changed, 2 insertions(+), 2 deletions(-)
	109
	110	diff --git a/drivers/devfreq/devfreq.c b/drivers/devfreq/devfreq.c
	111	index 57f6944d65a6..00c9b80b3d33 100644
	112	--- a/drivers/devfreq/devfreq.c
	113	+++ b/drivers/devfreq/devfreq.c
	114	@@ -1814,7 +1814,7 @@ static void devm_devfreq_notifier_release(struct device dev, void res)
	115
	116	/**
	117	* devm_devfreq_register_notifier()
	118	- - Resource-managed devfreq_register_notifier()
	119	+ * - Resource-managed devfreq_register_notifier()
	120	* @dev: The devfreq user device. (parent of devfreq)
	121	* @devfreq: The devfreq object.
	122	* @nb: The notifier block to be unregistered.
	123	@@ -1850,7 +1850,7 @@ EXPORT_SYMBOL(devm_devfreq_register_notifier);
	124
	125	/**
	126	* devm_devfreq_unregister_notifier()
	127	- - Resource-managed devfreq_unregister_notifier()
	128	+ * - Resource-managed devfreq_unregister_notifier()
	129	* @dev: The devfreq user device. (parent of devfreq)
	130	* @devfreq: The devfreq object.
	131	* @nb: The notifier block to be unregistered.
	132	--
	133	2.24.1
	134
	135	L'intero procedimento ha richiesto solo pochi minuti. Naturalmente, ho poi
	136	scoperto che qualcun altro l'aveva già corretto in un altro albero,
	137	mettendo in luce un'altra lezione: controllate sempre linux-next per
	138	vedere se un problema è già stato risolto prima di mettervici sopra.
	139
	140	Altre correzioni richiederanno più tempo, specialmente quelle relative ai
	141	campi di una struttura o ai parametri di una funzione privi di
	142	documentazione. In questi casi, è necessario capire quale sia il ruolo di
	143	questi campi o parametri e descriverli correttamente. Nel complesso, questo
	144	compito diventa un po' tedioso a volte, ma è molto importante. Se riusciamo
	145	davvero ad eliminare gli avvisi dalla generazione della documentazione,
	146	allora potremo iniziare a pretendere che gli sviluppatori evitino di
	147	aggiungerne di nuovi.
	148
	149	Oltre ai normali avvisi durante la generazione della documentazione, potete
	150	ottenerne di più eseguendo ``make refcheckdocs`` per trovare riferimenti a file
	151	di documentazione inesistenti.
	152
	153	Commenti kerneldoc dimenticati
	154	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	155
	156	Gli sviluppatori sono incoraggiati a scrivere commenti kerneldoc per il
	157	loro codice, ma molti di questi commenti non vengono mai inclusi nella
	158	generazione della documentazione. Questo rende tale informazione più
	159	difficile da trovare e, per esempio, impedisce a Sphinx di generare
	160	collegamenti verso quella documentazione. Aggiungere le direttive
	161	``kernel-doc`` alla documentazione per includere quei commenti può aiutare
	162	la comunità a ottenere il pieno valore del lavoro speso per crearli.
	163
	164	Lo strumento ``tools/docs/find-unused-docs.sh`` può essere usato per
	165	trovare questi commenti dimenticati.
	166
	167	Da notare che il valore maggiore deriva dall'includere la documentazione
	168	per le funzioni e le strutture dati esportate. Molti sottosistemi hanno
	169	anche commenti kerneldoc per uso interno; questi non dovrebbero essere
	170	inclusi nella generazione della documentazione a meno che non vengano
	171	posti in un documento specificamente rivolto agli sviluppatori che
	172	lavorano all'interno del sottosistema in questione.
	173
	174
	175	Correzione dei refusi
	176	~~~~~~~~~~~~~~~~~~~~~
	177
	178	Correggere errori di battitura o di formattazione nella documentazione è
	179	un modo rapido per imparare come creare e inviare patch, ed è un servizio
	180	utile. Sono sempre disposto ad accettare questo tipo di patch. Detto
	181	questo, una volta che ne avete corretti alcuni, considerate di passare a
	182	compiti più avanzati, lasciando qualche refuso per il prossimo principiante
	183	che vorrà occuparsene.
	184
	185	Da notare che alcune cose non sono refusi e non dovrebbero essere
	186	"corrette":
	187
	188	- Sia la grafia americana che quella britannica dell'inglese sono
	189	ammesse nella documentazione del kernel. Non c'è bisogno di sostituire
	190	l'una con l'altra.
	191
	192	- La questione se un punto debba essere seguito da uno o due spazi non
	193	va dibattuta nel contesto della documentazione del kernel. Anche
	194	altri argomenti di legittimo disaccordo, come la "virgola di Oxford",
	195	non sono pertinenti qui.
	196
	197	Come per qualsiasi patch a qualsiasi progetto, considerate se la vostra
	198	modifica sta davvero migliorando le cose.
	199
	200	Documentazione datata
	201	~~~~~~~~~~~~~~~~~~~~~
	202
	203	Parte della documentazione del kernel è attuale, mantenuta e utile.
	204	Un'altra parte... non lo è. Documentazione impolverata, vecchia e
	205	imprecisa può fuorviare i lettori e gettare discredito sulla nostra
	206	documentazione nel suo complesso. Qualsiasi cosa si possa fare per
	207	affrontare questi problemi è più che benvenuta.
	208
	209	Ogni volta che lavorate su un documento, considerate se è attuale, se ha
	210	bisogno di essere aggiornato, o se forse dovrebbe essere rimosso del
	211	tutto. Ci sono alcuni segnali d'allarme a cui potete prestare attenzione:
	212
	213	- Riferimenti a kernel della serie 2.x
	214	- Rimandi a repositori su SourceForge
	215	- Nella cronologia, negli ultimi anni, solo correzioni di refusi
	216	- Discussioni su modi di lavorare precedenti a Git
	217
	218	La cosa migliore da fare, ovviamente, sarebbe portare la documentazione a
	219	essere attuale, aggiungendo qualsiasi informazione necessaria. Un lavoro
	220	simile spesso richiede la collaborazione di sviluppatori che conoscono bene
	221	il sottosistema in questione. Gli sviluppatori, quando viene chiesto loro
	222	gentilmente, e quando le loro risposte vengono ascoltate e messe in
	223	pratica, sono spesso più che disposti a collaborare con chi lavora per
	224	migliorare la documentazione.
	225
	226	Alcuni documenti sono senza speranza; a volte troviamo documenti che fanno
	227	riferimento a codice rimosso dal kernel molto tempo fa, per esempio. C'è
	228	una sorprendente resistenza a rimuovere la documentazione obsoleta, ma
	229	dovremmo farlo comunque. Il materiale superfluo nella nostra documentazione
	230	non è d'aiuto a nessuno.
	231
	232	Nei casi in cui, forse, ci sono informazioni utili in un documento
	233	gravemente datato, e non siete in grado di aggiornarlo, la cosa migliore
	234	da fare potrebbe essere aggiungere un avviso all'inizio. Si raccomanda il
	235	seguente testo::
	236
	237	.. warning ::
	238	This document is outdated and in need of attention. Please use
	239	this information with caution, and please consider sending patches
	240	to update it.
	241
	242	In questo modo, almeno i nostri pazientissimi lettori sono stati avvisati
	243	che il documento potrebbe portarli fuori strada.
	244
	245	Coerenza della documentazione
	246	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	247
	248	I veterani di qui ricorderanno i libri su Linux che comparvero sugli
	249	scaffali negli anni '90. Erano semplicemente raccolte di file di
	250	documentazione racimolati da varie fonti in rete. I libri sono (per lo
	251	più) migliorati da allora, ma la documentazione del kernel è ancora per lo
	252	più costruita su quel modello. Sono migliaia di file, quasi ognuno dei
	253	quali è stato scritto in isolamento da tutti gli altri. Non abbiamo un
	254	corpo coerente di documentazione del kernel; abbiamo migliaia di documenti
	255	individuali.
	256
	257	Abbiamo cercato di migliorare la situazione creando un insieme di "libri"
	258	che raggruppano la documentazione per specifici lettori. Questi
	259	includono:
	260
	261	- Documentation/admin-guide/index.rst
	262	- Documentation/core-api/index.rst
	263	- Documentation/driver-api/index.rst
	264	- Documentation/userspace-api/index.rst
	265
	266	Così come questo libro sulla documentazione stessa.
	267
	268	Spostare i documenti nei libri appropriati è un compito importante e deve
	269	continuare. Ci sono, tuttavia, un paio di sfide associate a questo lavoro.
	270	Spostare i file della documentazione, nel breve termine, infastidisce chi vi
	271	lavora; comprensibilmente, non sono entusiasti di questi cambiamenti. Di solito
	272	li si può convincere a spostarli una volta; tuttavia, non vogliamo continuare a
	273	spostarli in giro.
	274
	275	Anche quando tutti i documenti sono al posto giusto, però, siamo solo
	276	riusciti a trasformare un grande cumulo in un gruppo di cumuli più
	277	piccoli. Il lavoro di cercare di tessere insieme tutti quei documenti in
	278	un unico insieme non è ancora iniziato. Se avete idee brillanti su come
	279	potremmo procedere su questo fronte, saremmo più che felici di sentirle.
	280
	281	Miglioramenti al foglio di stile
	282	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	283
	284	Con l'adozione di Sphinx abbiamo un output HTML dall'aspetto molto più gradevole
	285	di quanto avessimo un tempo. Ma è ancora migliorabile; Donald Knuth e Edward
	286	Tufte non ne sarebbero impressionati. Questo richiede di modificare i nostri
	287	fogli di stile per creare un output tipograficamente più solido, accessibile e
	288	leggibile.
	289
	290	Attenzione: se vi assumete questo compito, vi state addentrando nel
	291	classico territorio del "bikeshed". Aspettatevi molte opinioni e
	292	discussioni anche per cambiamenti relativamente ovvi. Questa è, ahimè, la
	293	natura del mondo in cui viviamo.
	294
	295	Generazione di PDF senza LaTeX
	296	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	297
	298	Questo è un compito decisamente non banale per qualcuno con molto tempo a
	299	disposizione e competenze in Python. La catena di strumenti di Sphinx è
	300	relativamente piccola e ben contenuta; è facile da aggiungere a un sistema
	301	di sviluppo. Ma generare output in PDF o EPUB richiede l'installazione di
	302	LaTeX, che non è affatto piccolo o ben contenuto. Sarebbe una bella cosa
	303	da eliminare.
	304
	305	La speranza originale era di usare lo strumento rst2pdf (https://rst2pdf.org/)
	306	per la generazione dei PDF, ma si è scoperto che non era all'altezza del
	307	compito. Il lavoro di sviluppo su rst2pdf sembra però essere ripreso di recente,
	308	il che è un segno di speranza. Se uno sviluppatore adeguatamente motivato lo
	309	migliorasse per far funzionare rst2pdf con la documentazione del kernel, il
	310	mondo gli sarebbe eternamente grato.
	311
	312	Scrivere più documentazione
	313	~~~~~~~~~~~~~~~~~~~~~~~~~~~
	314
	315	Naturalmente, ci sono vaste parti del kernel che sono gravemente prive di
	316	documentazione. Se avete la conoscenza per documentare uno specifico
	317	sottosistema del kernel e il desiderio di farlo, non esitate a scrivere e
	318	inviare il lavoro al kernel. Un numero incalcolabile di
	319	sviluppatori e utenti del kernel vi ringrazierà.

Documentation/translations/it_IT/doc-guide/index.rst+3−10

@@ -1,8 +1,5 @@
1	.. include:: ../disclaimer-ita.rst	1	.. include:: ../disclaimer-ita.rst
2		2
3	.. note:: Per leggere la documentazione originale in inglese:
4	:ref:`Documentation/doc-guide/index.rst <doc_guide>`
5
6	.. _it_doc_guide:	3	.. _it_doc_guide:
7		4
8	==========================================	5	==========================================
@@ -15,10 +12,6 @@ Come scrivere la documentazione del kernel · 6 unmodified lines
15	sphinx	12	sphinx
16	kernel-doc	13	kernel-doc
17	parse-headers	14	parse-headers
18		15	contributing
19	.. only:: subproject and html	16	maintainer-profile
20		17	checktransupdate
21	Indices
22	=======
23
24	* :ref:`genindex`

Documentation/translations/it_IT/doc-guide/kernel-doc.rst+69−19

 .. include:: ../disclaimer-ita.rst
-.. note:: Per leggere la documentazione originale in inglese:
-	  :ref:`Documentation/doc-guide/index.rst <doc_guide>`
 .. title:: Commenti in kernel-doc
-.. _it_kernel_doc:
 =================================
 Scrivere i commenti in kernel-doc
 =================================
 	tools/docs/kernel-doc -v -none drivers/foo/bar.c
-Il formato della documentazione è verificato della procedura di generazione
+Il formato della documentazione dei file ``.c`` è verificato anche dalla
-del kernel quando viene richiesto di effettuare dei controlli extra con GCC::
+procedura di generazione del kernel quando viene richiesto di effettuare dei
+controlli extra con GCC::
 	make W=n
+Tuttavia, il comando precedente non verifica i file d'intestazione. Questi
+devono essere controllati separatamente utilizzando ``kernel-doc``.
 Documentare le funzioni
 ------------------------
 ~~~~~~~~~~~~~~~~~
 Il valore di ritorno, se c'è, viene descritto in una sezione dedicata di nome
-``Return``.
+``Return`` (o ``Returns``).
 .. note::
 Documentare strutture, unioni ed enumerazioni
 ---------------------------------------------
-Generalmente il formato di un commento kernel-doc per struct, union ed enum è::
+Generalmente il formato di un commento kernel-doc per ``struct``, ``union``
+ed ``enum`` è::
   /**
    * struct struct_name - Brief description.
 il marcatore di un commento ``/*``. Opzionalmente, possono includere commenti
 fra ``:`` e il marcatore di fine commento ``*/``.
+Quando ``private:`` viene usata su strutture annidate, si propaga solo alle
+strutture/unioni interne.
 Esempio::
   /**
         union {
           struct {
             int memb1;
+            /* private: nasconde memb2 dalla documentazione */
             int memb2;
-        }
+          };
+          /* Qui torna tutto pubblico, l'ambito private è terminato */
           struct {
             void *memb3;
             int memb4;
-          }
+          };
-        }
+        };
         union {
           struct {
             int memb1;
    * Description of the type.
    *
    * Context: Locking context.
-   * Return: Meaning of the return value.
+   * Returns: Meaning of the return value.
    */
    typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
+Documentazione delle variabili
+-------------------------------
+Generalmente il formato di un commento kernel-doc per una variabile è
+il seguente::
+  /**
+   * var var_name - Brief description.
+   *
+   * Description of the var_name variable.
+   */
+   extern int var_name;
 Documentazione di macro simili a oggetti
 ----------------------------------------
 ``%CONST``
   Il nome di una costante (nessun riferimento, solo formattazione)
+  Esempi::
+    %0    %NULL    %-1    %-EFAULT    %-EINVAL    %-ENOMEM
 ````literal````
   Un blocco di testo che deve essere riportato così com'è. La rappresentazione
   finale utilizzerà caratteri a ``spaziatura fissa``.
   See :c:func:`my custom link text for function foo <foo>`.
   See :c:type:`my custom link text for struct bar <bar>`.
+Per ulteriori dettagli, consultate la documentazione del `dominio Sphinx per
+il C`_.
+.. note::
+   Le variabili non vengono automaticamente collegate tramite riferimenti
+   incrociati. Per queste, dovete aggiungere esplicitamente un riferimento
+   incrociato del dominio C.
 Commenti per una documentazione generale
 ----------------------------------------
 Al fine d'avere il codice ed i commenti nello stesso file, potete includere
 dei blocchi di documentazione kernel-doc con un formato libero invece
-che nel formato specifico per funzioni, strutture, unioni, enumerati o tipi
+che nel formato specifico per funzioni, strutture, unioni, enumerati, tipi
-di dato. Per esempio, questo tipo di commento potrebbe essere usato per la
+di dato o variabili. Per esempio, questo tipo di commento potrebbe essere
-spiegazione delle operazioni di un driver o di una libreria
+usato per la spiegazione delle operazioni di un driver o di una libreria
 Questo s'ottiene utilizzando la parola chiave ``DOC:`` a cui viene associato
 un titolo.
   Include la documentazione per ogni *function* e *type*  in *source*.
   Se non vengono esplicitamente specificate le funzioni da includere, allora
   verranno incluse tutte quelle disponibili in *source*.
+  *type* può essere un identificatore di tipo ``struct``, ``union``,
+  ``enum``, ``typedef`` o ``var``.
   Esempi::
 Come utilizzare kernel-doc per generare pagine man
 --------------------------------------------------
-Se volete utilizzare kernel-doc solo per generare delle pagine man, potete
+Per generare le pagine man di tutti i file che contengono marcatori
-farlo direttamente dai sorgenti del kernel::
+kernel-doc, eseguite::
+  $ make mandocs
+Oppure, chiamando direttamente ``script-build-wrapper``::
+  $ ./tools/docs/sphinx-build-wrapper mandocs
+Il risultato sarà disponibile nella cartella ``/man`` dentro la cartella
+di output (predefinita: ``Documentation/output``).
+Opzionalmente, è possibile generare un sottoinsieme di pagine man usando
+SPHINXDIRS:
+  $ make SPHINXDIRS=driver-api/media mandocs
+.. note::
-  $ tools/docs/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man
+   Quando si usa SPHINXDIRS={subdir}, verranno generate le pagine man solo
+   per i file che si trovano esplicitamente all'interno di un file
+   ``Documentation/{subdir}/.../*.rst``.

Documentation/translations/it_IT/doc-guide/maintainer-profile.rst+60−0

@@ -0,0 +1,60 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	.. include:: ../disclaimer-ita.rst
	4
	5	Profilo del manutentore del sottosistema di documentazione
	6	==========================================================
	7
	8	Il "sottosistema" della documentazione è il punto di coordinamento
	9	centrale per la documentazione del kernel e la relativa infrastruttura.
	10	Copre la gerarchia sotto Documentation/ (con l'eccezione di
	11	Documentation/devicetree), diverse utilità sotto scripts/ e, almeno in
	12	parte, LICENSES/.
	13
	14	Vale la pena notare, però, che i confini di questo sottosistema sono più sfumati
	15	del normale. Molti altri manutentori di sottosistemi preferiscono mantenere il
	16	controllo di alcune parti di Documentation/, e molti altri ancora vi applicano
	17	liberamente delle modifiche quando è conveniente. Oltre a ciò, buona parte della
	18	documentazione del kernel si trova nel codice sorgente sotto forma di commenti
	19	kerneldoc; questi sono solitamente (ma non sempre) mantenuti dal manutentore del
	20	sottosistema pertinente.
	21
	22	La lista di discussione per la documentazione è linux-doc@vger.kernel.org.
	23	Le patch dovrebbero essere inviate contro l'albero docs-next quando
	24	possibile.
	25
	26	Aggiunta alla checklist di invio
	27	--------------------------------
	28
	29	Quando si apportano modifiche alla documentazione, dovreste generare
	30	effettivamente la documentazione e assicurarvi che non siano stati
	31	introdotti nuovi errori o avvisi. Generare i documenti in HTML e osservare
	32	il risultato aiuterà a evitare fraintendimenti spiacevoli su come le cose
	33	verranno rappresentate.
	34
	35	Tutta la nuova documentazione (incluse le aggiunte a documenti esistenti)
	36	dovrebbe idealmente giustificare, da qualche parte nel changelog, chi sia
	37	il pubblico a cui è destinata; in questo modo, ci assicuriamo che la
	38	documentazione finisca nel posto giusto. Alcune categorie possibili
	39	sono: sviluppatori del kernel (esperti o principianti), programmatori
	40	dello spazio utente, utenti finali e/o amministratori di sistema, e
	41	distributori.
	42
	43	Date chiave del ciclo
	44	---------------------
	45
	46	Le patch possono essere inviate in qualsiasi momento, ma la risposta sarà
	47	più lenta del solito durante la finestra d'integrazione. L'albero della
	48	documentazione tende a chiudersi tardi, prima dell'apertura della finestra
	49	d'integrazione, poiché il rischio di regressioni dovute a patch sulla
	50	documentazione è basso.
	51
	52	Cadenza di revisione
	53	--------------------
	54
	55	Sono (Jonathan Corbet) l'unico manutentore del sottosistema di documentazione, e
	56	svolgo questo lavoro nel mio tempo libero, quindi la risposta alle patch sarà a
	57	volte lenta. Cerco sempre di inviare una notifica quando una patch viene
	58	integrata (o quando decido che non può esserlo). Non esitate a inviare un
	59	sollecito se non avete ricevuto risposta entro una settimana dall'invio di una
	60	patch.

Documentation/translations/it_IT/doc-guide/parse-headers.rst+110−110

@@ -1,195 +1,195 @@
1	.. include:: ../disclaimer-ita.rst	1	.. include:: ../disclaimer-ita.rst
2		2
3	:Original: Documentation/doc-guide/index.rst	3	=====================================
4		4	Includere i file di intestazione uAPI
5	=========================================	5	=====================================
6	Includere gli i file di intestazione uAPI
7	=========================================
8		6
9	Qualche volta è utile includere dei file di intestazione e degli esempi di codice C	7	Qualche volta è utile includere dei file di intestazione e degli esempi di codice C
10	al fine di descrivere l'API per lo spazio utente e per generare dei riferimenti	8	al fine di descrivere l'API per lo spazio utente e per generare dei riferimenti
11	fra il codice e la documentazione. Aggiungere i riferimenti ai file dell'API	9	fra il codice e la documentazione. Aggiungere i riferimenti ai file dell'API
12	dello spazio utente ha ulteriori vantaggi: Sphinx genererà dei messaggi	10	dello spazio utente ha un ulteriore vantaggio: Sphinx genererà dei messaggi
13	d'avviso se un simbolo non viene trovato nella documentazione. Questo permette	11	d'avviso se un simbolo non viene trovato nella documentazione. Questo permette
14	di mantenere allineate la documentazione della uAPI (API spazio utente)	12	di mantenere allineate la documentazione della uAPI (API spazio utente)
15	con le modifiche del kernel.	13	con le modifiche del kernel.
16	Il programma :ref:`parse_headers.py <it_parse_headers>` genera questi riferimenti.	14	Il programma :ref:`parse_headers.py <it_parse_headers>` genera questi
17	Esso dev'essere invocato attraverso un Makefile, mentre si genera la	15	riferimenti. Esso dev'essere invocato attraverso un Makefile, mentre si genera
18	documentazione. Per avere un esempio su come utilizzarlo all'interno del kernel	16	la documentazione. Per avere un esempio su come utilizzarlo all'interno del
19	consultate ``Documentation/userspace-api/media/Makefile``.	17	kernel consultate ``Documentation/userspace-api/media/Makefile``.
20		18
21	.. _it_parse_headers:	19	.. _it_parse_headers:
22		20
23	parse_headers.py	21	tools/docs/parse_headers.py
24	^^^^^^^^^^^^^^^^	22	^^^^^^^^^^^^^^^^^^^^^^^^^^^
25		23
26	NOME	24	NOME
27	****	25	****
28		26
		27	parse_headers.py - analizza un file C al fine di identificare funzioni,
		28	strutture, enumerati e definizioni, e creare riferimenti per un libro Sphinx.
29		29
30	parse_headers.py - analizza i file C al fine di identificare funzioni,	30	USO
31	strutture, enumerati e definizioni, e creare riferimenti per Sphinx	31	***
32		32
33	SINTASSI	33	parse-headers.py [-h] [-d] [-t] ``FILE_IN`` ``FILE_OUT`` ``FILE_RULES``
34	********
35		34
		35	SINOSSI
		36	*******
36		37
37	\ parse_headers.py\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]	38	Converte un file d'intestazione o un file sorgente C ``FILE_IN`` in un testo
		39	ReStructured Text incluso mediante il blocco ..parsed-literal con riferimenti
		40	alla documentazione che descrive l'API. Accetta opzionalmente un file
		41	``FILE_RULES`` che descrive quali elementi debbano essere ignorati o il cui
		42	riferimento debba puntare ad un tipo/nome diverso da quello predefinito.
38		43
39	Dove <options> può essere: --debug, --usage o --help.	44	Il file generato viene scritto in ``FILE_OUT``.
40		45
		46	Il programma è capace di identificare ``define``, ``struct``, ``typedef``,
		47	``enum`` e ``symbol`` di un enumerato, creando i riferimenti per ognuno di
		48	loro.
41		49
42	OPZIONI	50	Inoltre, esso è capace di distinguere le ``#define`` utilizzate per
43	*******	51	specificare le macro specifiche di Linux usate per definire gli ``ioctl``.
44		52
		53	Il file ``FILE_RULES``, opzionale, contiene un insieme di regole come le
		54	seguenti::
45		55
		56	ignore ioctl VIDIOC_ENUM_FMT
		57	replace ioctl VIDIOC_DQBUF vidioc_qbuf
		58	replace define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ :c:type:`v4l2_event_motion_det`
46		59
47	\ --debug\	60	ARGOMENTI POSIZIONALI
		61	*********************
48		62
49	Lo script viene messo in modalità verbosa, utile per il debugging.	63	``FILE_IN``
		64	File C d'ingresso
50		65
		66	``FILE_OUT``
		67	File RST generato
51		68
52	\ --usage\	69	``FILE_RULES``
		70	File delle eccezioni (opzionale)
53		71
54	Mostra un messaggio d'aiuto breve e termina.	72	OPZIONI
55		73	*******
56
57	\ --help\
58		74
59	Mostra un messaggio d'aiuto dettagliato e termina.	75	``-h``, ``--help``
		76	mostra un messaggio d'aiuto e termina
		77	``-d``, ``--debug``
		78	aumenta il livello di debug. Può essere usato più volte
		79	``-t``, ``--toc``
		80	invece di un blocco letterale, genera nel file RST una tabella
		81	dell'indice (TOC)
60		82
61		83
62	DESCRIZIONE	84	DESCRIZIONE
63	***********	85	***********
64		86
65	Converte un file d'intestazione o un file sorgente C (C_FILE) in un testo	87	Crea, a partire da ``FILE_IN``, una versione arricchita di un file
66	reStructuredText incluso mediante il blocco ..parsed-literal	88	d'intestazione del kernel con collegamenti incrociati verso ogni tipo di
67	con riferimenti alla documentazione che descrive l'API. Opzionalmente,	89	struttura dati C, formattandola con la notazione reStructuredText, sia
68	il programma accetta anche un altro file (EXCEPTIONS_FILE) che	90	come blocco letterale che come tabella dell'indice.
69	descrive quali elementi debbano essere ignorati o il cui riferimento
70	deve puntare ad elemento diverso dal predefinito.
71
72	Il file generato sarà disponibile in (OUT_FILE).
73
74	Il programma è capace di identificare define, funzioni, strutture,
75	tipi di dato, enumerati e valori di enumerati, e di creare i riferimenti
76	per ognuno di loro. Inoltre, esso è capace di distinguere le #define
77	utilizzate per specificare i comandi ioctl di Linux.
78
79	Il file EXCEPTIONS_FILE contiene due tipi di dichiarazioni:
80	\ ignore\ o \ replace\ .
81
82	La sintassi per ignore è:
83
84	ignore \ tipo\ \ nome\
85
86	La dichiarazione \ ignore\ significa che non verrà generato alcun
87	riferimento per il simbolo \ name\ di tipo \ tipo\ .
88		91
		92	Accetta opzionalmente un file ``FILE_RULES`` che descrive quali elementi
		93	debbano essere ignorati o il cui riferimento debba puntare ad un valore
		94	diverso da quello predefinito, e che può opzionalmente definire lo spazio
		95	dei nomi C da utilizzare.
89		96
90	La sintassi per replace è:	97	Ha lo scopo di permettere una documentazione più completa, in cui i file
		98	d'intestazione della uAPI creino collegamenti incrociati verso il codice.
91		99
92	replace \ tipo\ \ nome\ \ nuovo_valore\	100	Il file generato viene scritto in ``FILE_OUT``.
93		101
94	La dichiarazione \ replace\ significa che verrà generato un	102	Il file ``FILE_RULES`` può contenere tre tipi di dichiarazioni:
95	riferimento per il simbolo \ name\ di tipo \ tipo\ , ma, invece	103	ignore, replace e namespace.
96	di utilizzare il valore predefinito, verrà utilizzato il valore
97	\ nuovo_valore\ .
98		104
99	Per entrambe le dichiarazioni, il \ tipo\ può essere uno dei seguenti:	105	Per impostazione predefinita, vengono create regole per tutti i simboli e
		106	le definizioni, ma è anche possibile fornire un file di eccezioni. Questo
		107	file contiene un insieme di regole che seguono la sintassi descritta di
		108	seguito:
100		109
		110	1. Regole ignore:
101		111
102	\ ioctl\	112	ignore tipo simbolo
103		113
104	La dichiarazione ignore o replace verrà applicata su definizioni di ioctl	114	Rimuove il simbolo dalla generazione dei riferimenti.
105	come la seguente:
106		115
107	#define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register)	116	2. Regole replace:
108		117
		118	replace tipo vecchio_simbolo nuovo_riferimento
109		119
		120	Sostituisce vecchio_simbolo con nuovo_riferimento.
		121	nuovo_riferimento può essere:
110		122
111	\ define\	123	- un semplice nome di simbolo;
		124	- un riferimento Sphinx completo.
112		125
113	La dichiarazione ignore o replace verrà applicata su una qualsiasi #define	126	3. Regole namespace
114	trovata in C_FILE.
115		127
		128	namespace spazio_dei_nomi
116		129
		130	Imposta lo spazio_dei_nomi C da utilizzare durante la generazione dei
		131	riferimenti incrociati. Può essere sovrascritto dalle regole replace.
117		132
118	\ typedef\	133	Nelle regole ignore e replace, tipo può essere:
119		134
120	La dichiarazione ignore o replace verrà applicata ad una dichiarazione typedef	135	- ioctl:
121	in C_FILE.	136	per le definizioni della forma ``_IO*``, per esempio le definizioni
		137	di ioctl
122		138
		139	- define:
		140	per le altre definizioni
123		141
		142	- symbol:
		143	per i simboli definiti all'interno di enumerati;
124		144
125	\ struct\	145	- typedef:
		146	per i typedef;
126		147
127	La dichiarazione ignore o replace verrà applicata ai nomi di strutture	148	- enum:
128	in C_FILE.	149	per il nome di un enumerato non anonimo;
129		150
130		151	- struct:
131		152	per le strutture.
132	\ enum\
133
134	La dichiarazione ignore o replace verrà applicata ai nomi di enumerati
135	in C_FILE.
136
137
138
139	\ symbol\
140
141	La dichiarazione ignore o replace verrà applicata ai nomi di valori di
142	enumerati in C_FILE.
143
144	Per le dichiarazioni di tipo replace, il campo \ new_value\ utilizzerà
145	automaticamente i riferimenti :c:type: per \ typedef\ , \ enum\ e
146	\ struct\. Invece, utilizzerà :ref: per \ ioctl\ , \ define\ e
147	\ symbol\. Il tipo di riferimento può essere definito esplicitamente
148	nella dichiarazione stessa.
149		153
150		154
151	ESEMPI	155	ESEMPI
152	******	156	******
153		157
		158	- Ignora una definizione ``_VIDEODEV2_H`` in ``FILE_IN``::
154		159
155	ignore define _VIDEODEV2_H	160	ignore define _VIDEODEV2_H
156
157
158	Ignora una definizione #define _VIDEODEV2_H nel file C_FILE.
159
160	ignore symbol PRIVATE
161		161
		162	- In una struttura dati come questo enumerato::
162		163
163	In un enumerato come il seguente:	164	enum foo { BAR1, BAR2, PRIVATE };
164		165
165	enum foo { BAR1, BAR2, PRIVATE };	166	Non genererà alcun riferimento incrociato per ``PRIVATE``::
166		167
167	Non genererà alcun riferimento per \ PRIVATE\ .	168	ignore symbol PRIVATE
168		169
169	replace symbol BAR1 :c:type:\`foo\`	170	Nello stesso enumerato, invece di creare un riferimento incrociato per
170	replace symbol BAR2 :c:type:\`foo\`	171	ogni simbolo, si può far si che tutti puntino al tipo C ``enum foo``::
171		172
		173	replace symbol BAR1 :c:type:\`foo\`
		174	replace symbol BAR2 :c:type:\`foo\`
172		175
173	In un enumerato come il seguente:
174		176
175	enum foo { BAR1, BAR2, PRIVATE };	177	- Usa lo spazio dei nomi C ``MC`` per tutti i simboli in ``FILE_IN``::
176
177	Genererà un riferimento ai valori BAR1 e BAR2 dal simbolo foo nel dominio C.
178		178
		179	namespace MC
179		180
180	BUGS	181	BUGS
181	****	182	****
182		183
183	Riferire ogni malfunzionamento a Mauro Carvalho Chehab <mchehab@s-opensource.com>	184	Segnalate qualsiasi malfunzionamento a Mauro Carvalho Chehab
184		185	<mchehab@kernel.org>
185		186
186	COPYRIGHT	187	COPYRIGHT
187	*********	188	*********
188		189
		190	Copyright (c) 2016, 2025 di Mauro Carvalho Chehab <mchehab+huawei@kernel.org>.
189		191
190	Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.	192	Licenza GPLv2: GNU GPL versione 2 <https://gnu.org/licenses/gpl.html>.
191
192	Licenza GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>.
193		193
194	Questo è software libero: siete liberi di cambiarlo e ridistribuirlo.	194	Questo è software libero: siete liberi di cambiarlo e ridistribuirlo.
195	Non c'è alcuna garanzia, nei limiti permessi dalla legge.	195	Non c'è alcuna garanzia, nei limiti permessi dalla legge.

Documentation/translations/it_IT/doc-guide/sphinx.rst+137−41

@@ -1,8 +1,5 @@
1	.. include:: ../disclaimer-ita.rst	1	.. include:: ../disclaimer-ita.rst
2		2
3	.. note:: Per leggere la documentazione originale in inglese:
4	:ref:`Documentation/doc-guide/index.rst <doc_guide>`
5
6	.. _it_sphinxdoc:	3	.. _it_sphinxdoc:
7		4
8	=============================================	5	=============================================
@@ -36,7 +33,7 @@ Installazione Sphinx · 27 unmodified lines
36	====================	33	====================
37		34
38	I marcatori ReST utilizzati nei file in Documentation/ sono pensati per essere	35	I marcatori ReST utilizzati nei file in Documentation/ sono pensati per essere
39	processati da ``Sphinx`` nella versione 1.7 o superiore.	36	processati da ``Sphinx`` nella versione 3.4.3 o superiore.
40		37
41	Esiste uno script che verifica i requisiti Sphinx. Per ulteriori dettagli	38	Esiste uno script che verifica i requisiti Sphinx. Per ulteriori dettagli
42	consultate :ref:`it_sphinx-pre-install`.	39	consultate :ref:`it_sphinx-pre-install`.
@@ -52,24 +49,14 @@ vi raccomandiamo di installare Sphinx dentro ad un ambiente virtuale usando · 9 unmodified lines
52	``virtualenv-3`` o ``virtualenv`` a seconda di come Python 3 è stato	49	``virtualenv-3`` o ``virtualenv`` a seconda di come Python 3 è stato
53	pacchettizzato dalla vostra distribuzione.	50	pacchettizzato dalla vostra distribuzione.
54		51
55	.. note::	52	Riassumendo, se volete installare l'ultima versione di Sphinx, dovete
56		53	eseguire::
57	#) Viene raccomandato l'uso del tema RTD per la documentazione in HTML.
58	A seconda della versione di Sphinx, potrebbe essere necessaria
59	l'installazione tramite il comando ``pip install sphinx_rtd_theme``.
60
61	#) Alcune pagine ReST contengono delle formule matematiche. A causa del
62	modo in cui Sphinx funziona, queste espressioni sono scritte
63	utilizzando LaTeX. Per una corretta interpretazione, è necessario aver
64	installato texlive con i pacchetti amdfonts e amsmath.
65
66	Riassumendo, se volete installare la versione 2.4.4 di Sphinx dovete eseguire::
67		54
68	$ virtualenv sphinx_2.4.4	55	$ virtualenv sphinx_latest
69	$ . sphinx_2.4.4/bin/activate	56	$ . sphinx_latest/bin/activate
70	(sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt	57	(sphinx_latest) $ pip install -r Documentation/sphinx/requirements.txt
71		58
72	Dopo aver eseguito ``. sphinx_2.4.4/bin/activate``, il prompt cambierà per	59	Dopo aver eseguito ``. sphinx_latest/bin/activate``, il prompt cambierà per
73	indicare che state usando il nuovo ambiente. Se aprite un nuova sessione,	60	indicare che state usando il nuovo ambiente. Se aprite un nuova sessione,
74	prima di generare la documentazione, dovrete rieseguire questo comando per	61	prima di generare la documentazione, dovrete rieseguire questo comando per
75	rientrare nell'ambiente virtuale.	62	rientrare nell'ambiente virtuale.
@@ -99,6 +86,27 @@ Per alcune distribuzioni Linux potrebbe essere necessario installare · 23 unmodified lines
99	anche una serie di pacchetti ``texlive`` in modo da fornire il supporto	86	anche una serie di pacchetti ``texlive`` in modo da fornire il supporto
100	minimo per il funzionamento di ``XeLaTeX``.	87	minimo per il funzionamento di ``XeLaTeX``.
101		88
		89	Espressioni matematiche in HTML
		90	-------------------------------
		91
		92	Alcune pagine ReST contengono delle formule matematiche. Per come funziona
		93	Sphinx, queste espressioni sono scritte utilizzando la notazione LaTeX. Esistono
		94	due opzioni per far si che Sphinx rappresenti le espressioni matematiche
		95	nell'output HTML. La prima è un'estensione chiamata `imgmath`_ che converte le
		96	espressioni matematiche in immagini e le integra nelle pagine HTML. L'altra è
		97	un'estensione chiamata `mathjax`_ che delega la rappresentazione delle formule
		98	matematiche ai browser web capaci di eseguire JavaScript. La prima era l'unica
		99	opzione per la documentazione del kernel precedente alla versione 6.1 e richiede
		100	diversi pacchetti texlive, fra cui amsfonts e amsmath.
		101
		102	A partire dalla versione 6.1 del kernel, le pagine HTML con espressioni
		103	matematiche possono essere generate senza dover installare alcun pacchetto
		104	texlive. Per maggiori informazioni consultate `Scelta della libreria per le
		105	formule matematiche`_.
		106
		107	.. _imgmath: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.imgmath
		108	.. _mathjax: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax
		109
102	.. _it_sphinx-pre-install:	110	.. _it_sphinx-pre-install:
103		111
104	Verificare le dipendenze Sphinx	112	Verificare le dipendenze Sphinx
@@ -136,6 +144,30 @@ Questo script ha i seguenti parametri: · 31 unmodified lines
136	Utilizza l'ambiente predefinito dal sistema operativo invece che	144	Utilizza l'ambiente predefinito dal sistema operativo invece che
137	l'ambiente virtuale per Python;	145	l'ambiente virtuale per Python;
138		146
		147	Installare la versione minima di Sphinx
		148	---------------------------------------
		149
		150	Quando si modifica il sistema di generazione di Sphinx, è importante
		151	assicurarsi che la versione minima sia ancora supportata. Al giorno d'oggi,
		152	sta diventando sempre più difficile farlo sulle distribuzioni moderne, dato
		153	che non è possibile installarla con Python 3.13 e versioni successive.
		154
		155	Potete verificare la versione minima di Python supportata, così come
		156	definita in Documentation/process/changes.rst, creando un venv con quella
		157	versione e installando i requisiti minimi con::
		158
		159	/usr/bin/python3.9 -m venv sphinx_min
		160	. sphinx_min/bin/activate
		161	pip install -r Documentation/sphinx/min_requirements.txt
		162
		163	Un test più completo può essere eseguito utilizzando:
		164
		165	tools/docs/test_doc_build.py
		166
		167	Questo script crea un venv Python per ogni versione supportata, generando
		168	facoltativamente la documentazione per un intervallo di versioni di
		169	Sphinx.
		170
139		171
140	Generazione della documentazione Sphinx	172	Generazione della documentazione Sphinx
141	=======================================	173	=======================================
@@ -143,39 +175,82 @@ Generazione della documentazione Sphinx · 1 unmodified line
143	Per generare la documentazione in formato HTML o PDF si eseguono i rispettivi	175	Per generare la documentazione in formato HTML o PDF si eseguono i rispettivi
144	comandi ``make htmldocs`` o ``make pdfdocs``. Esistono anche altri formati	176	comandi ``make htmldocs`` o ``make pdfdocs``. Esistono anche altri formati
145	in cui è possibile generare la documentazione; per maggiori informazioni	177	in cui è possibile generare la documentazione; per maggiori informazioni
146	potere eseguire il comando ``make help``.	178	potete eseguire il comando ``make help``.
147	La documentazione così generata sarà disponibile nella sottocartella	179	La documentazione così generata sarà disponibile nella sottocartella
148	``Documentation/output``.	180	``Documentation/output``.
149		181
150	Ovviamente, per generare la documentazione, Sphinx (``sphinx-build``)	182	Ovviamente, per generare la documentazione, Sphinx (``sphinx-build``)
151	dev'essere installato. Se disponibile, il tema Read the Docs per Sphinx	183	dev'essere installato. Per la documentazione in formato PDF, invece,
152	verrà utilizzato per ottenere una documentazione HTML più gradevole.	184	avrete bisogno di ``XeLaTeX`` e di ``convert(1)`` disponibile in
153	Per la documentazione in formato PDF, invece, avrete bisogno di ``XeLaTeX`	185	ImageMagick (https://www.imagemagick.org).\ [#ink]_ Tutti questi pacchetti
154	e di ``convert(1)`` disponibile in ImageMagick	186	sono ampiamente disponibili e pacchettizzati nelle distribuzioni.
155	(https://www.imagemagick.org). \ [#ink]_
156	Tipicamente, tutti questi pacchetti sono disponibili e pacchettizzati nelle
157	distribuzioni Linux.
158		187
159	Per poter passare ulteriori opzioni a Sphinx potete utilizzare la variabile	188	Per poter passare ulteriori opzioni a Sphinx potete utilizzare la variabile
160	make ``SPHINXOPTS``. Per esempio, se volete che Sphinx sia più verboso durante	189	make ``SPHINXOPTS``. Per esempio, se volete che Sphinx sia più prolisso
161	la generazione potete usare il seguente comando ``make SPHINXOPTS=-v htmldocs``.	190	durante la generazione potete usare il comando
		191	``make SPHINXOPTS=-v htmldocs``.
162		192
163	Potete anche personalizzare l'ouptut html passando un livello aggiuntivo	193	Potete anche personalizzare l'output html passando un livello aggiuntivo
164	DOCS_CSS usando la rispettiva variabile d'ambiente ``DOCS_CSS``.	194	DOCS_CSS usando la rispettiva variabile d'ambiente ``DOCS_CSS``.
165		195
166	La variable make ``SPHINXDIRS`` è utile quando si vuole generare solo una parte	196	Il tema di base per generare la documentazione HTML viene è "Alabaster"; questo
167	della documentazione. Per esempio, si possono generare solo di documenti in	197	tema è distribuito assieme a Sphinx e non necessita di un'installazione
168	``Documentation/doc-guide`` eseguendo ``make SPHINXDIRS=doc-guide htmldocs``. La	198	separata. Il tema di Sphinx può essere sostituito usando la variabile make
169	sezione dedicata alla documentazione di ``make help`` vi mostrerà quali sotto	199	``DOCS_THEME``.
170	cartelle potete specificare.	200
		201	.. note::
		202
		203	Alcuni potrebbero preferire il tema RTD per l'output in HTML. A seconda
		204	della versione di Sphinx, dev'essere installato separatamente, con il
		205	comando ``pip install sphinx_rtd_theme``.
		206
		207	Esiste un'altra variabile make, ``SPHINXDIRS``, utile quando si vuole
		208	generare, a scopo di test, solo una parte della documentazione. Per
		209	esempio, potete generare i documenti in ``Documentation/doc-guide``
		210	eseguendo ``make SPHINXDIRS=doc-guide htmldocs``. La sezione dedicata alla
		211	documentazione di ``make help`` vi mostrerà l'elenco delle sottocartelle
		212	che potete specificare.
171		213
172	Potete eliminare la documentazione generata tramite il comando	214	Potete eliminare la documentazione generata tramite il comando
173	``make cleandocs``.	215	``make cleandocs``.
174		216
175	.. [#ink] Avere installato anche ``inkscape(1)`` dal progetto Inkscape ()	217	.. [#ink] Avere installato anche ``inkscape(1)`` dal progetto Inkscape
176	potrebbe aumentare la qualità delle immagini che verranno integrate	218	(https://inkscape.org) potrebbe aumentare la qualità delle
177	nel documento PDF, specialmente per quando si usando rilasci del	219	immagini integrate nei documenti PDF, specialmente per i rilasci
178	kernel uguali o superiori a 5.18	220	del kernel dalla versione 5.18 in poi.
		221
		222	Scelta della libreria per le formule matematiche
		223	------------------------------------------------
		224
		225	A partire dalla versione 6.1 del kernel, mathjax funge da libreria di
		226	ripiego per le formule matematiche nell'output HTML.\ [#sph1_8]_
		227
		228	La libreria matematica viene scelta in base ai comandi disponibili, come
		229	mostrato di seguito:
		230
		231	.. table:: Scelta della libreria matematica per l'HTML
		232
		233	======== ================= ================
		234	Libreria Comandi richiesti Formato immagine
		235	======== ================= ================
		236	imgmath latex, dvipng PNG (raster)
		237	mathjax
		238	======== ================= ================
		239
		240	La scelta può essere sovrascritta impostando la variabile d'ambiente
		241	``SPHINX_IMGMATH`` come mostrato di seguito:
		242
		243	.. table:: Effetto dell'impostazione di ``SPHINX_IMGMATH``
		244
		245	====================== ========
		246	Impostazione Libreria
		247	====================== ========
		248	``SPHINX_IMGMATH=yes`` imgmath
		249	``SPHINX_IMGMATH=no`` mathjax
		250	====================== ========
		251
		252	.. [#sph1_8] La libreria di ripiego richiede Sphinx >=1.8.
		253
179		254
180	Scrivere la documentazione	255	Scrivere la documentazione
181	==========================	256	==========================
@@ -289,8 +364,19 @@ incrociato quando questa ha una voce nell'indice. Se trovate degli usi di · 107 unmodified lines
289	``c:func:`` nella documentazione del kernel, sentitevi liberi di rimuoverli.	364	``c:func:`` nella documentazione del kernel, sentitevi liberi di rimuoverli.
290		365
291		366
		367	Tabelle
		368	-------
		369
		370	Il formato reStructuredText offre diverse opzioni per la sintassi delle tabelle.
		371	Lo stile del kernel per le tabelle preferisce la sintassi delle *tabelle
		372	semplici* o delle tabelle a griglia. Per maggiori dettagli consultate il
		373	`manuale di riferimento reStructuredText per la sintassi delle tabelle`_.
		374
		375	.. _manuale di riferimento reStructuredText per la sintassi delle tabelle:
		376	https://docutils.sourceforge.io/docs/user/rst/quickref.html#tables
		377
292	Tabelle a liste	378	Tabelle a liste
293	---------------	379	~~~~~~~~~~~~~~~
294		380
295	Il formato ``list-table`` può essere utile per tutte quelle tabelle che non	381	Il formato ``list-table`` può essere utile per tutte quelle tabelle che non
296	possono essere facilmente scritte usando il formato ASCII-art di Sphinx. Però,	382	possono essere facilmente scritte usando il formato ASCII-art di Sphinx. Però,
@@ -403,6 +489,16 @@ percorso al documento. · 106 unmodified lines
403		489
404	Per informazioni riguardo ai riferimenti incrociati ai commenti	490	Per informazioni riguardo ai riferimenti incrociati ai commenti
405	kernel-doc per funzioni o tipi, consultate	491	kernel-doc per funzioni o tipi, consultate
		492	Documentation/translations/it_IT/doc-guide/kernel-doc.rst.
		493
		494	Riferimenti ai commit
		495	~~~~~~~~~~~~~~~~~~~~~
		496
		497	I riferimenti ai commit di git vengono trasformati automaticamente in
		498	collegamenti ipertestuali quando sono scritti in uno di questi formati::
		499
		500	commit 72bf4f1767f0
		501	commit 72bf4f1767f0 ("net: do not leave an empty skb in write queue")
406		502
407	.. _it_sphinx_kfigure:	503	.. _it_sphinx_kfigure:
408		504

Documentation/translations/it_IT/process/changes.rst+73−45

@@ -23,50 +23,53 @@ Requisiti minimi correnti · 22 unmodified lines
23		23
24	Prima di pensare d'avere trovato un baco, aggiornate i seguenti programmi	24	Prima di pensare d'avere trovato un baco, aggiornate i seguenti programmi
25	almeno alla versione indicata! Se non siete certi della versione che state	25	almeno alla versione indicata! Se non siete certi della versione che state
26	usando, il comando indicato dovrebbe dirvelo.	26	usando, il comando indicato dovrebbe dirvelo. Per avere una lista dei programmi
		27	sul vostro sistema, incluse le rispettive versioni, eseguite
		28	./scripts/ver_linux.
27		29
28	Questa lista presume che abbiate già un kernel Linux funzionante. In aggiunta,	30	Questa lista presume che abbiate già un kernel Linux funzionante. In aggiunta,
29	non tutti gli strumenti sono necessari ovunque; ovviamente, se non avete una	31	non tutti gli strumenti sono necessari ovunque; ovviamente, se non avete una
30	PC Card, per esempio, probabilmente non dovreste preoccuparvi di pcmciautils.	32	PC Card, per esempio, probabilmente non dovreste preoccuparvi di pcmciautils.
31		33
32	====================== ================= ========================================	34	====================== =============== ========================================
33	Programma Versione minima Comando per verificare la versione	35	Programma Versione minima Comando per verificare la versione
34	====================== ================= ========================================	36	====================== =============== ========================================
35	GNU C 8.1 gcc --version	37	bash 4.2 bash --version
36	Clang/LLVM (optional) 17.0.1 clang --version	38	bc 1.06.95 bc --version
37	Rust (opzionale) 1.78.0 rustc --version	39	bindgen (opzionale) 0.71.1 bindgen --version
38	bindgen (opzionale) 0.65.1 bindgen --version	40	binutils 2.30 ld -v
39	GNU make 4.0 make --version	41	bison 2.0 bison --version
40	bash 4.2 bash --version	42	btrfs-progs 0.18 btrfs --version
41	binutils 2.30 ld -v	43	Clang/LLVM (opzionale) 17.0.1 clang --version
42	flex 2.5.35 flex --version	44	e2fsprogs 1.41.4 e2fsck -V
43	bison 2.0 bison --version	45	flex 2.5.35 flex --version
44	pahole 1.16 pahole --version	46	gdb 7.2 gdb --version
45	util-linux 2.10o mount --version	47	GNU awk (opzionale) 5.1.0 gawk --version
46	kmod 13 depmod -V	48	GNU C 8.1 gcc --version
47	e2fsprogs 1.41.4 e2fsck -V	49	GNU make 4.0 make --version
48	jfsutils 1.1.3 fsck.jfs -V	50	GNU tar 1.28 tar --version
49	xfsprogs 2.6.0 xfs_db -V	51	GRUB 0.93 grub --version \|\| grub-install --version
50	squashfs-tools 4.0 mksquashfs -version	52	gtags (opzionale) 6.6.5 gtags --version
51	btrfs-progs 0.18 btrfsck	53	iptables 1.4.2 iptables -V
52	pcmciautils 004 pccardctl -V	54	jfsutils 1.1.3 fsck.jfs -V
53	quota-tools 3.09 quota -V	55	kmod 13 kmod -V
54	PPP 2.4.0 pppd --version	56	mcelog 0.6 mcelog --version
55	nfs-utils 1.0.5 showmount --version	57	mkimage (opzionale) 2017.01 mkimage --version
56	procps 3.2.0 ps --version	58	nfs-utils 1.0.5 showmount --version
57	udev 081 udevd --version	59	openssl & libcrypto 1.0.0 openssl version
58	grub 0.93 grub --version \|\| grub-install --version	60	pahole 1.26 pahole --version
59	mcelog 0.6 mcelog --version	61	pcmciautils 004 pccardctl -V
60	iptables 1.4.2 iptables -V	62	PPP 2.4.0 pppd --version
61	openssl & libcrypto 1.0.0 openssl version	63	procps 3.2.0 ps --version
62	bc 1.06.95 bc --version	64	Python 3.9.x python3 --version
63	Sphinx\ [#f1]_ 2.4.4 sphinx-build --version	65	quota-tools 3.09 quota -V
64	cpio any cpio --version	66	Rust (opzionale) 1.85.0 rustc --version
65	GNU tar 1.28 tar --version	67	Sphinx\ [#f1]_ 3.4.3 sphinx-build --version
66	gtags (opzionale) 6.6.5 gtags --version	68	squashfs-tools 4.0 mksquashfs -version
67	mkimage (opzionale) 2017.01 mkimage --version	69	udev 081 udevadm --version
68	Python (opzionale) 3.5.x python3 --version	70	util-linux 2.10o mount --version
69	====================== ================= ========================================	71	xfsprogs 2.6.0 xfs_db -V
		72	====================== =============== ========================================
70		73
71	.. [#f1] Sphinx è necessario solo per produrre la documentazione del Kernel	74	.. [#f1] Sphinx è necessario solo per produrre la documentazione del Kernel
72		75
@@ -144,7 +147,13 @@ pahole · 71 unmodified lines
144		147
145	Dalla versione 5.2, quando viene impostato CONFIG_DEBUG_INFO_BTF, il sistema di	148	Dalla versione 5.2, quando viene impostato CONFIG_DEBUG_INFO_BTF, il sistema di
146	compilazione genera BTF (BPF Type Format) a partire da DWARF per vmlinux. Più	149	compilazione genera BTF (BPF Type Format) a partire da DWARF per vmlinux. Più
147	tardi anche per i moduli. Questo richiede pahole v1.16 o successivo.	150	tardi anche per i moduli. Questo richiede pahole v1.22 o successivo.
		151
		152	Dalla versione 7.0, le kfunc annotate con KF_IMPLICIT_ARGS richiedono pahole
		153	v1.26 o successivo. Senza questa versione, tali kfunc avranno prototipi BTF
		154	errati in vmlinux, causando il fallimento del caricamento dei programmi BPF con
		155	l'errore "func_proto incompatible with vmlinux". Molte kfunc in sched_ext sono
		156	interessate da questo problema.
148		157
149	A seconda della distribuzione, lo si può trovare nei pacchetti 'dwarves' o	158	A seconda della distribuzione, lo si può trovare nei pacchetti 'dwarves' o
150	'pahole'. Oppure lo si può trovare qui: https://fedorapeople.org/~acme/dwarves/.	159	'pahole'. Oppure lo si può trovare qui: https://fedorapeople.org/~acme/dwarves/.
@@ -155,6 +164,14 @@ Perl · 4 unmodified lines
155	Per compilare il kernel vi servirà perl 5 e i seguenti moduli ``Getopt::Long``,	164	Per compilare il kernel vi servirà perl 5 e i seguenti moduli ``Getopt::Long``,
156	``Getopt::Std``, ``File::Basename``, e ``File::Find``.	165	``Getopt::Std``, ``File::Basename``, e ``File::Find``.
157		166
		167	Python
		168	------
		169
		170	Diverse opzioni di configurazione lo richiedono: è necessario per le
		171	configurazioni predefinite di arm/arm64, CONFIG_LTO_CLANG, alcune opzioni
		172	configurabili del DRM, lo strumento kernel-doc e la generazione della
		173	documentazione (Sphinx), e altro ancora.
		174
158	BC	175	BC
159	--	176	--
160		177
@@ -193,6 +210,12 @@ pacchetto ``u-boot-tools`` oppure può essere compilato dal codice sorgente di · 32 unmodified lines
193	U-Boot. Consultate le istruzioni	210	U-Boot. Consultate le istruzioni
194	https://docs.u-boot.org/en/latest/build/tools.html#building-tools-for-linux	211	https://docs.u-boot.org/en/latest/build/tools.html#building-tools-for-linux
195		212
		213	GNU AWK
		214	-------
		215
		216	GNU AWK è necessario se si vuole che la compilazione del kernel generi dati
		217	sugli intervalli di indirizzi per i moduli integrati
		218	(CONFIG_BUILTIN_MODULE_RANGES).
196		219
197	Strumenti di sistema	220	Strumenti di sistema
198	********************	221	********************
@@ -405,6 +428,16 @@ Clang/LLVM · 206 unmodified lines
405		428
406	- :ref:`Getting LLVM <getting_llvm>`.	429	- :ref:`Getting LLVM <getting_llvm>`.
407		430
		431	Rust
		432	----
		433
		434	- Documentation/rust/quick-start.rst.
		435
		436	bindgen
		437	-------
		438
		439	- Documentation/rust/quick-start.rst.
		440
408	Make	441	Make
409	----	442	----
410		443
@@ -507,11 +540,6 @@ mcelog · 96 unmodified lines
507		540
508	- <https://www.mcelog.org/>	541	- <https://www.mcelog.org/>
509		542
510	cpio
511	----
512
513	- <https://www.gnu.org/software/cpio/>
514
515	Rete	543	Rete
516	****	544	****
517		545

Documentation/translations/ja_JP/process/submitting-patches.rst+152−75

@@ -182,7 +182,7 @@ URL は禁止です。 · 181 unmodified lines
182	変更を分割する	182	変更を分割する
183	--------------	183	--------------
184		184
185	各論理的な変更は、個別のパッチに分けてください。	185	それぞれの\ 論理的な変更\ は、個別のパッチに分けてください。
186		186
187	たとえば、単一のドライバに対する変更にバグ修正と性能改善の	187	たとえば、単一のドライバに対する変更にバグ修正と性能改善の
188	両方が含まれるなら、それらは 2 つ以上のパッチに分けてください。	188	両方が含まれるなら、それらは 2 つ以上のパッチに分けてください。
@@ -208,7 +208,7 @@ URL は禁止です。 · 19 unmodified lines
208	ことがあります。途中でバグを持ち込めば、彼らに感謝されることは	208	ことがあります。途中でバグを持ち込めば、彼らに感謝されることは
209	ないでしょう。	209	ないでしょう。
210		210
211	パッチセットをこれ以上小さくできないなら、一度に投稿するのは	211	パッチセットをそれ以上小さくできないなら、一度に投稿するのは
212	15 個程度までにして、レビューと統合を待ってください。	212	15 個程度までにして、レビューと統合を待ってください。
213		213
214		214
@@ -220,18 +220,17 @@ Documentation/process/coding-style.rst を参照してください。 · 5 unmodified lines
220	これを怠ると、単にレビューアの時間を無駄にするだけでなく、	220	これを怠ると、単にレビューアの時間を無駄にするだけでなく、
221	パッチはおそらく読まれもせずに却下されます。	221	パッチはおそらく読まれもせずに却下されます。
222		222
223	大きな例外が 1 つあります。コードをあるファイルから別の	223	一つの重要な例外は、コードをあるファイルから別のファイルへ移動する場合です。
224	ファイルへ移動する場合です。このときは、コードを移動する	224	その際は、コードを移動するその同じパッチの中で、一切コードを変更しては
225	その同じパッチの中で、移動したコードを一切変更してはいけません。	225	いけません。これにより、コードの移動という行為と、コードの変更とが
226	そうすることで、コードの移動という行為と、あなたの変更とを	226	明確に区別されます。これは実際の差分のレビューを大いに助け、また、ツールを
227	明確に区別できます。これは実際の差分のレビューを大いに助け、	227	使ったコード変更の履歴の追跡を容易にします。
228	ツールがコード自体の履歴をより適切に追跡できるようにします。
229		228
230	提出前に、パッチスタイルチェッカー	229	提出前に、パッチスタイルチェッカー
231	(``scripts/checkpatch.pl``) でパッチを確認してください。	230	(``scripts/checkpatch.pl``) でパッチを確認してください。
232	ただし、スタイルチェッカーは指針として見るべきであり、	231	ただし、スタイルチェッカーは指針にすぎず、
233	人間の判断に取って代わるものではないことに注意してください。	232	人間の判断に取って代わるものではないことに注意してください。
234	違反があっても、その方がコードの見栄えがよいなら、	233	違反が指摘されるままのコードの方が見栄えがよいなら、おそらく
235	そのままにしておくのが最善でしょう。	234	そのままにしておくのが最善でしょう。
236		235
237	チェッカーは 3 つのレベルで報告します:	236	チェッカーは 3 つのレベルで報告します:
@@ -240,8 +239,7 @@ Documentation/process/coding-style.rst を参照してください。 · 2 unmodified lines
240	- WARNING: 慎重なレビューを要するもの	239	- WARNING: 慎重なレビューを要するもの
241	- CHECK: 検討を要するもの	240	- CHECK: 検討を要するもの
242		241
243	パッチに残した違反については、すべて理由を説明できなければ	242	パッチに違反を残す場合は、そのすべてを正当化できなければなりません。
244	なりません。
245		243
246		244
247	パッチの宛先を選択する	245	パッチの宛先を選択する
@@ -256,8 +254,8 @@ Documentation/process/coding-style.rst を参照してください。 · 8 unmodified lines
256	サブシステムのメンテナが見つからない場合は、Andrew Morton	254	サブシステムのメンテナが見つからない場合は、Andrew Morton
257	(akpm@linux-foundation.org) が最後の手段となるメンテナです。	255	(akpm@linux-foundation.org) が最後の手段となるメンテナです。
258		256
259	すべてのパッチでは、デフォルトで linux-kernel@vger.kernel.org を	257	すべてのパッチは、デフォルトで linux-kernel@vger.kernel.org にも
260	使うべきですが、このリストの流量が多いため、目を通さなくなった	258	送られるべきですが、このリストは流量が多く、目を通さなくなった
261	開発者も少なくありません。とはいえ、無関係なメーリングリストや	259	開発者も少なくありません。とはいえ、無関係なメーリングリストや
262	無関係な人々にスパムを送らないでください。	260	無関係な人々にスパムを送らないでください。
263		261
@@ -268,103 +266,104 @@ Documentation/process/coding-style.rst を参照してください。 · 4 unmodified lines
268	Linux カーネルに採用されるすべての変更の最終的な裁定者は	266	Linux カーネルに採用されるすべての変更の最終的な裁定者は
269	Linus Torvalds です。彼のメールアドレスは	267	Linus Torvalds です。彼のメールアドレスは
270	<torvalds@linux-foundation.org> です。Linus は大量のメールを	268	<torvalds@linux-foundation.org> です。Linus は大量のメールを
271	受け取っており、現時点では彼に直接届くパッチはごくわずかなので、	269	受け取っており、現時点では直接彼を経由するパッチはごくわずかなので、
272	通常は彼にメールを送ることを極力避けてください。	270	通常は彼にメールを送ることを極力\ 避けて\ ください。
273		271
274	悪用可能なセキュリティバグを修正するパッチがあるなら、	272	悪用可能なセキュリティバグを修正するパッチの場合は、
275	そのパッチを security@kernel.org に送ってください。深刻なバグに	273	それを security@kernel.org に送ってください。深刻なバグに
276	ついては、ディストリビュータがユーザーにパッチを配布できるよう、	274	ついては、ディストリビュータがユーザーにパッチを配布できるよう、
277	短期間の embargo が検討される場合があります。そのような場合、	275	短期間の秘匿措置 (訳註: embargo) が検討される可能性があります。
278	そのパッチを公開メーリングリストに送るべきではありません。	276	ですので、その種のパッチを公開メーリングリストに送らないでください。
279	Documentation/process/security-bugs.rst も参照してください。	277	Documentation/process/security-bugs.rst も参照してください。
280		278
281	リリース済みカーネルの深刻なバグを修正するパッチは、次のような行を	279	リリース済みカーネルの深刻なバグを修正するパッチは、次のような行を
282	パッチの sign-off 欄に入れることで、stable メンテナへ向けてください::	280	パッチの sign-off 欄に入れることで、stable メンテナに知らせてください。
		281	(メールの宛先ではないことに注意。) ::
283		282
284	Cc: stable@vger.kernel.org	283	Cc: stable@vger.kernel.org
285		284
286	これはメールの受信者ではないことに注意してください。また、	285	また、この文書に加えて Documentation/process/stable-kernel-rules.rst
287	この文書に加えて Documentation/process/stable-kernel-rules.rst も	286	も読んでください。
288	読んでください。
289		287
290	変更がユーザーランドとカーネルのインターフェースに影響する場合は、	288	変更がユーザーランドとカーネルのインターフェースに影響する場合は、
291	MAINTAINERS ファイルに記載されている MAN-PAGES メンテナに	289	MAINTAINERS ファイルに記載されている MAN-PAGES メンテナに
292	man-pages パッチ、少なくとも変更の通知を送って、情報が	290	マニュアルページのパッチ、もしくは少なくとも変更の通知を送って、情報が
293	マニュアルページに反映されるようにしてください。ユーザー空間 API の	291	そちらにも反映されるようにしてください。ユーザー空間 API の
294	変更は、linux-api@vger.kernel.org にも Cc してください。	292	変更は、linux-api@vger.kernel.org にも Cc してください。
295		293
296	MIME・リンク・圧縮・添付なし、プレーンテキストのみ	294	MIME・リンク・圧縮・添付なし、プレーンテキストのみ
297	----------------------------------------------------	295	----------------------------------------------------
298		296
299	Linus や他のカーネル開発者は、あなたが投稿する変更を読み、	297	Linus や他のカーネル開発者は、あなたが投稿する変更を読み、
300	コメントできる必要があります。カーネル開発者が標準的な	298	コメントできる必要があります。カーネル開発者にとって、コードの特定の
301	メールツールを使ってあなたの変更を「引用」し、コードの特定の	299	箇所について、標準的なメールツールを使ってあなたの変更を「引用」し、
302	箇所についてコメントできることが重要です。	300	コメントできることが重要です。
303		301
304	このため、すべてのパッチはメール本文中に ``inline`` で投稿すべきです。	302	このため、すべてのパッチはメール本文中に「インライン」で投稿すべきです。
305	これを行う最も簡単な方法は ``git send-email`` を使うことであり、	303	これを行う最も簡単な方法は ``git send-email`` を使うことであり、
306	強く推奨されます。``git send-email`` の対話型チュートリアルは	304	強く推奨されます。``git send-email`` の対話型チュートリアルは
307	https://git-send-email.io で利用できます。	305	https://git-send-email.io にあります。
308		306
309	``git send-email`` を使わないことを選ぶ場合:	307	``git send-email`` を使わない場合:
310		308
311	.. warning::	309	.. warning::
312		310
313	パッチをコピー＆ペーストする場合は、エディタの word-wrap によって	311	パッチをコピー＆ペーストする際に、エディタによる自動改行で
314	パッチが壊れないよう注意してください。	312	パッチが壊されないよう注意してください。
315		313
316	圧縮の有無にかかわらず、パッチを MIME 添付ファイルとして添付しては	314	圧縮の有無にかかわらず、パッチを MIME 添付ファイルとして添付しては
317	いけません。多くの一般的なメールアプリケーションは、MIME 添付	315	いけません。よく使われるメールアプリケーションの多くは、MIME 添付
318	ファイルを常にプレーンテキストとして送信するとは限らず、あなたの	316	ファイルをプレーンテキストとして送信するとは限らず、あなたのコードに
319	コードにコメントできなくなります。MIME 添付ファイルは Linus が	317	対するコメントを妨げます。MIME 添付ファイルは Linus (訳補: をはじめ
320	処理するのにも少し余分な時間がかかるため、MIME 添付された変更が	318	とする開発者）が処理するのに余分な手間がかかるため、MIME 添付すると
321	受け入れられる可能性を下げます。	319	その変更が受け入れられる可能性を下げることになります。
322		320
323	例外: メーラがパッチを壊してしまう場合は、誰かから MIME を使って	321	例外: パッチがメーラーによって壊されている場合に、MIME による再送
324	再送するよう求められることがあります。	322	を求められることがあります。
325		323
326	パッチを変更せずに送信するようメールクライアントを設定するための	324	改変なしにパッチを送信するためのメールクライアント設定のヒントは、
327	ヒントについては、Documentation/process/email-clients.rst を参照してください。	325	Documentation/process/email-clients.rst を参照してください。
328		326
329		327
330	レビューコメントに返答する	328	レビューコメントに応答する
331	--------------------------	329	--------------------------
332		330
333	あなたのパッチには、ほぼ確実に、パッチを改善する方法について	331	あなたのパッチには、ほぼ確実に、その改善に向けてレビューアから
334	レビューアからコメントが付きます。それは、あなたのメールへの返信という	332	コメントが付きます。それは、あなたのメールへの返信という
335	形で届きます。それらのコメントには必ず返答してください。レビューアを	333	形で届きます。それらのコメントには必ず応答してください。レビューアを
336	無視することは、こちらも無視されるためのよい方法です。コメントに	334	無視することは、あなたが無視されることにつながります。コメントに
337	答えるには、単にそのメールへ返信すれば構いません。コード変更に	335	答えるには、単にそのメールへ返信すればよいです。コード変更に
338	つながらないレビューコメントや質問であっても、次のレビューアが状況を	336	つながらないレビューコメントや質問であっても、次のレビューアが状況を
339	よりよく理解できるように、ほぼ確実にコメントまたは changelog エントリに	337	よりよく理解できるよう、多くの場合、コメントまたは changelog エントリ
340	反映すべきです。	338	として残すべきです。
341		339
342	どのような変更を行うのかをレビューアに必ず伝え、時間を割いてくれた	340	どのような変更を行うのかを忘れずにレビューアに伝えてください。そして
343	ことに感謝してください。コードレビューは疲れる、時間のかかる作業であり、	341	時間を割いてくれることへの感謝を忘れないでください。
344	レビューアが不機嫌になることもあります。そのような場合であっても、	342	コードレビューは疲れる、時間のかかる作業であり、
345	丁寧に返答し、指摘された問題に対応してください。次の版を送るときは、	343	ときにはレビューアが機嫌を損ねることもあります。そのような場合でも、
346	cover letter または個々のパッチに ``patch changelog`` を追加し、前回の	344	丁寧に応答し、指摘された問題に対応してください。次の版を送る際には、
		345	カバーレターまたは個々のパッチに ``patch changelog`` を追加し、前回の
347	投稿との差分を説明してください。詳細は原文の該当節	346	投稿との差分を説明してください。詳細は原文の該当節
348	("The canonical patch format") を参照してください。	347	("The canonical patch format") を参照してください。
349		348
350	.. TODO: Convert to file-local cross-reference when the destination is	349	.. TODO: Convert to file-local cross-reference when the destination is
351	translated.	350	translated.
352		351
353	あなたのパッチにコメントした人には、パッチの Cc リストに追加して、	352	あなたのパッチにコメントしてくれた人たちは、パッチの Cc リストに追加して
354	新しい版を知らせてください。	353	新しい版について知らせてください。
355		354
356	メールクライアントとメーリングリストでの作法についての推奨事項は、	355	メールクライアントとメーリングリストでの作法についての推奨事項は、
357	Documentation/process/email-clients.rst を参照してください。	356	Documentation/process/email-clients.rst を参照してください。
358		357
359	メール議論では不要な引用を削った interleaved replies を使う	358	要点に絞ったインライン返信での議論
360	------------------------------------------------------------	359	---------------------------------------
361		360
362	Linux カーネル開発の議論では、top-posting は強く非推奨とされています。	361	Linux カーネル開発の議論では、全文引用 (訳註: top-posting) は強く非推奨です。
363	Interleaved replies、または ``inline`` replies を使うと、会話の流れを	362	インライン返信 (訳註: interleaved reples or "inline" replies) を使うと、
364	ずっと追いやすくなります。詳細は次を参照してください:	363	会話の流れをずっと追いやすくなります。詳細は次を参照してください:
365	https://en.wikipedia.org/wiki/Posting_style#Interleaved_style	364	https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
366		365
367	メーリングリストでは、よく次のように引用されます::	366	これについて、メーリングリストでは、次の引用をしばしば目にします::
368		367
369	A: http://en.wikipedia.org/wiki/Top_post	368	A: http://en.wikipedia.org/wiki/Top_post
370	Q: Where do I find info about this thing called top-posting?	369	Q: Where do I find info about this thing called top-posting?
@@ -381,24 +380,102 @@ https://en.wikipedia.org/wiki/Posting_style#Interleaved_style · 10 unmodified lines
381	Q: Should I include quotations after my reply?	380	Q: Should I include quotations after my reply?
382		381
383		382
384	落胆しない、そして急がない	383	落胆しない - いらいらしない
385	--------------------------	384	---------------------------
386		385
387	変更を投稿した後は、辛抱強く待ってください。レビューアは忙しい人たちであり、	386	変更を投稿した後は、辛抱強く待ってください。レビューアは忙しい人たちであり、
388	あなたのパッチをすぐに見られるとは限りません。	387	あなたのパッチにすぐに取りかかれるとは限りません。
389		388
390	かつては、パッチが何のコメントもなく虚空へ消えていくこともありましたが、	389	かつては、パッチが何のコメントもなく虚空へ消えていくこともありましたが、
391	現在の開発プロセスはそれよりも円滑に機能しています。数週間以内、	390	現在の開発プロセスはそれよりも円滑に機能しています。数週間以内、
392	通常は 2〜3 週間以内にコメントを受け取るはずです。そうならない場合は、	391	通常は 2〜3 週間以内にコメントを受け取るはずです。そうならない場合は、
393	パッチを正しい場所へ送ったか確認してください。再投稿したりレビューアに	392	パッチを正しい場所へ送ったか確認してください。再投稿したりレビューアに
394	ping したりする前に、少なくとも 1 週間は待ってください。merge window の	393	ping したりする前に、少なくとも 1 週間は待ってください。マージ期間
395	ような忙しい時期には、さらに長く待つ方がよい場合もあります。	394	(訳註: merge window) のような忙しい時期には、さらに長く待ちましょう。
396		395
397	数週間後に、subject line に "RESEND" を追加して、パッチまたは	396	数週間後に、件名に "RESEND" を追加したパッチまたはパッチシリーズを
398	パッチシリーズを再送しても構いません::	397	再送することは構いません::
399		398
400	[PATCH Vx RESEND] sub/sys: Condensed patch summary	399	[PATCH Vx RESEND] sub/sys: Condensed patch summary
401		400
402	パッチまたはパッチシリーズの修正版を投稿する場合は、"RESEND" を	401	ただし、パッチまたはパッチシリーズの修正版を投稿する際には "RESEND"
403	追加しないでください。"RESEND" は、前回の投稿から一切変更していない	402	を追加しないでください。
404	パッチまたはパッチシリーズを再送する場合にのみ使います。	403	"RESEND" は、前回の投稿から一切変更のないパッチまたはパッチシリーズの
		404	再送だけに当てはまります。
		405
		406
		407	件名に PATCH を含める
		408	---------------------
		409
		410	Linus と linux-kernel メーリングリストには大量のメールが届くため、
		411	件名の先頭に ``[PATCH]`` を付けることが一般的な慣例となっています。
		412	これにより、Linus や他のカーネル開発者は、パッチとその他の議論を
		413	容易に区別できます。
		414
		415	``git send-email`` は、この指定を自動的に行います。
		416
		417
		418	作業への署名 - Developer's Certificate of Origin
		419	--------------------------------------------------
		420
		421	誰が何を行ったのかを追跡しやすくするため、特にパッチが複数階層の
		422	メンテナーを経由して最終的にカーネルへ取り込まれる場合に備えて、
		423	メールでやり取りされるパッチには sign-off の手続きが導入されています。
		424
		425	sign-off は、パッチの説明の末尾に追加する単純な一行です。これは、
		426	そのパッチを自分で作成したか、オープンソースのパッチとして提出する
		427	権利を持っていることを証明します。
		428
		429	.. note:: 【訳註】
		430
		431	``Signed-off-by`` によって同意する対象は、翻訳文ではなく、
		432	以下に示す英語原文の Developer's Certificate of Origin 1.1 です。
		433	DCO は法的な性質を持つ文書であるため、本文は翻訳せず、原文のまま
		434	掲載します。内容を確認する場合は、必ず英語原文を参照してください。
		435
		436	規則は単純で、以下を証明できる場合です::
		437
		438	Developer's Certificate of Origin 1.1
		439
		440	By making a contribution to this project, I certify that:
		441
		442	(a) The contribution was created in whole or in part by me and I
		443	have the right to submit it under the open source license
		444	indicated in the file; or
		445
		446	(b) The contribution is based upon previous work that, to the best
		447	of my knowledge, is covered under an appropriate open source
		448	license and I have the right under that license to submit that
		449	work with modifications, whether created in whole or in part
		450	by me, under the same open source license (unless I am
		451	permitted to submit under a different license), as indicated
		452	in the file; or
		453
		454	(c) The contribution was provided directly to me by some other
		455	person who certified (a), (b) or (c) and I have not modified
		456	it.
		457
		458	(d) I understand and agree that this project and the contribution
		459	are public and that a record of the contribution (including all
		460	personal information I submit with it, including my sign-off) is
		461	maintained indefinitely and may be redistributed consistent with
		462	this project or the open source license(s) involved.
		463
		464	上記を証明できる場合は、次のような行を追加します::
		465
		466	Signed-off-by: Random J Developer <random@developer.example.org>
		467
		468	既知の身元を使用してください。匿名での貢献は認められません。
		469	``git commit -s`` を使用すると、この行を自動的に追加できます。
		470
		471	revert にも ``Signed-off-by:`` を含める必要があります。
		472	``git revert -s`` を使用すると、自動的に追加できます。
		473
		474	末尾に追加のタグを付ける人もいます。現時点では無視されますが、
		475	社内手続きを示したり、sign-off に関する特記事項を記録したりするために
		476	使用できます。
		477
		478	作者の SoB に続く追加の SoB（``Signed-off-by:``）は、パッチの開発には
		479	関与せず、その取り扱いや転送を行った人によるものです。SoB の連鎖は、
		480	パッチがメンテナーを経て最終的に Linus へ届いた実際の経路を反映する
		481	必要があります。最初の SoB は、単独の主要作者であることを示します。

Documentation/translations/pt_BR/index.rst+1−12

@@ -66,15 +66,4 @@ kernel e sobre como ver seu trabalho integrado. · 65 unmodified lines
66	.. toctree::	66	.. toctree::
67	:maxdepth: 1	67	:maxdepth: 1
68		68
69	Introdução <process/1.Intro>	69	process/index
70	Guia do Processo de Desenvolvimento <process/development-process>
71	Index de documentos do Kernel <process/kernel-docs>
72	Regras de licenciamento <process/license-rules>
73	Como começar <process/howto>
74	Requisitos mínimos <process/changes>
75	Conclave (Continuidade do projeto) <process/conclave>
76	Manuais dos mantenedores <process/maintainer-handbooks>
77	Processo do subsistema de rede (netdev) <process/maintainer-netdev>
78	Processo do subsistema SoC <process/maintainer-soc>
79	Conformidade de DTS para SoC <process/maintainer-soc-clean-dts>
80	Processo do subsistema KVM x86 <process/maintainer-kvm-x86>

Documentation/translations/pt_BR/process/4.Coding.rst+440−0

@@ -0,0 +1,440 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	Escrever o código corretamente
	4	==============================
	5
	6	Embora haja muito o que se dizer sobre um processo de design sólido e orientado
	7	à comunidade, a prova de qualquer projeto de desenvolvimento de kernel está no
	8	código resultante. É o código que será examinado por outros desenvolvedores e
	9	mesclado (ou não) na árvore principal (mainline). Portanto, é a qualidade
	10	deste código que determinará o sucesso final do projeto.
	11
	12	Esta seção examinará o processo de codificação. Começaremos analisando uma série
	13	de maneiras pelas quais os desenvolvedores de kernel podem errar. Em seguida, o
	14	foco mudará para como fazer as coisas do jeito certo e as ferramentas que podem
	15	ajudar nessa busca.
	16
	17
	18	Armadilhas
	19	----------
	20
	21	Estilo de Codificação
	22	*********************
	23
	24	O kernel há muito possui um estilo de codificação padrão, descrito em
	25	:ref:`Documentation/process/coding-style.rst <codingstyle>`. Por grande parte
	26	desse tempo, as políticas descritas naquele arquivo eram consideradas, no
	27	máximo, como recomendações. Como resultado, há uma quantidade substancial
	28	de código no kernel que não cumpre as diretrizes de estilo de codificação.
	29	A presença desse código leva a dois riscos independentes para os
	30	desenvolvedores do kernel.
	31
	32	O primeiro deles é acreditar que os padrões de codificação do kernel não importam
	33	e não são exigidos. A verdade é que adicionar novo código ao kernel é muito
	34	difícil se esse código não estiver escrito de acordo com o padrão; muitos
	35	desenvolvedores solicitarão que o código seja reformatado antes mesmo de
	36	revisá-lo. Uma base de código tão grande quanto a do kernel exige certa
	37	uniformidade para tornar possível que os desenvolvedores entendam rapidamente
	38	qualquer parte dela. Portanto, não há mais espaço para códigos com formatações
	39	estranhas.
	40
	41	Ocasionalmente, o estilo de codificação do kernel entrará em conflito com o
	42	estilo exigido por um empregador. Nesses casos, o estilo do kernel terá que
	43	vencer para que o código possa ser mesclado. Colocar código no kernel significa
	44	abrir mão de um certo grau de controle de várias maneiras — incluindo o controle
	45	sobre como o código é formatado.
	46
	47	A outra armadilha é presumir que o código já presente no kernel necessita
	48	urgentemente de correções de estilo de codificação. Os desenvolvedores podem
	49	começar a gerar patches de reformatação como uma forma de ganhar familiaridade
	50	com o processo, ou como um meio de incluir seus nomes nos logs de alterações
	51	(changelogs) do kernel ou ambos. No entanto, patches puramente de estilo de
	52	codificação são vistos como ruído pela comunidade de desenvolvimento; eles tendem
	53	a receber uma recepção fria. Portanto, é melhor evitar esse tipo de patch. É
	54	natural corrigir o estilo de um trecho de código ao trabalhar nele por outros
	55	motivos, mas mudanças de estilo de codificação não devem ser feitas apenas por
	56	fazer.
	57
	58	O documento de estilo de codificação também não deve ser lido como uma lei
	59	absoluta que nunca pode ser transgredida. Se houver um bom motivo para ir contra
	60	o estilo (uma linha que se torna muito menos legível se for dividida para caber
	61	no limite de 80 colunas, por exemplo), simplesmente faça isso.
	62
	63	Note que você também pode usar a ferramenta ``clang-format`` para ajudá-lo com
	64	essas regras, para reformatar rapidamente partes do seu código de forma automática
	65	e para revisar arquivos completos a fim de identificar erros de estilo de
	66	codificação, erros de digitação e possíveis melhorias. Ela também é útil para
	67	ordenar ``#includes``, alinhar variáveis/macros, reajustar o fluxo de textos e
	68	outras tarefas semelhantes. Veja o arquivo
	69	:ref:`Documentation/dev-tools/clang-format.rst <clangformat>` para mais detalhes.
	70
	71	Algumas configurações básicas do editor, como indentação e fins de linha,
	72	serão definidas automaticamente se você estiver usando um editor compatível
	73	com o EditorConfig. Consulte o site oficial do EditorConfig para obter mais
	74	informações: https://editorconfig.org/
	75
	76	Camadas de Abstração
	77	********************
	78
	79	Os professores de Ciência da Computação ensinam os alunos a fazerem uso
	80	extensivo de camadas de abstração em nome da flexibilidade e da ocultação de
	81	informações. Certamente o kernel faz uso extensivo de abstração; nenhum
	82	projeto que envolva vários milhões de linhas de código poderia fazer o
	83	contrário e sobreviver. No entanto, a experiência tem mostrado que a
	84	abstração excessiva ou prematura pode ser tão prejudicial quanto a otimização
	85	prematura. A abstração deve ser usada até o nível necessário e não além.
	86
	87	Em um nível simples, considere uma função que possui um argumento que é
	88	sempre passado como zero por todos os chamadores. Alguém poderia manter esse
	89	argumento caso alguém eventualmente precise usar a flexibilidade extra que ele
	90	oferece. A essa altura, no entanto, as chances são grandes de que o código que
	91	implementa esse argumento extra tenha sido quebrado de alguma forma sutil que
	92	nunca foi percebida — porque ele nunca foi usado. Ou, quando surge a
	93	necessidade de flexibilidade extra, ela não ocorre de uma forma que corresponda
	94	à expectativa inicial do programador. Os desenvolvedores do kernel enviam
	95	patches rotineiramente para remover argumentos não utilizados; eles não devem,
	96	em geral, ser adicionados em primeiro lugar.
	97
	98	Camadas de abstração que ocultam o acesso ao hardware — frequentemente para
	99	permitir que a maior parte de um driver seja usada com múltiplos sistemas
	100	operacionais — são especialmente malvistas. Essas camadas obscurecem o código
	101	e podem impor uma penalidade de desempenho; elas não pertencem ao kernel
	102	Linux.
	103
	104	Por outro lado, se você se pegar copiando quantidades significativas de código
	105	de outro subsistema do kernel, é hora de perguntar se faria sentido, de fato,
	106	extrair parte desse código em uma biblioteca separada ou implementar essa
	107	funcionalidade em um nível superior. Não há valor em duplicar o mesmo código
	108	por todo o kernel.
	109
	110
	111	Uso de #ifdef e do pré-processador em geral
	112	*******************************************
	113
	114	O pré-processador C parece apresentar uma forte tentação para alguns
	115	programadores C, que o veem como uma forma de codificar eficientemente uma grande
	116	quantidade de flexibilidade em um arquivo-fonte. No entanto, o pré-processador
	117	não é C, e o uso pesado dele resulta em um código muito mais difícil de ser lido
	118	por outros e mais difícil para o compilador verificar a correção. O uso pesado
	119	do pré-processador é quase sempre um sinal de código que precisa de algum
	120	trabalho de limpeza.
	121
	122	A compilação condicional com #ifdef é, de fato, um recurso poderoso, e é
	123	utilizada dentro do kernel. Mas há pouco desejo de ver um código que seja
	124	salpicado liberalmente com blocos #ifdef. Como regra geral, o uso de #ifdef
	125	deve ser confinado a arquivos de cabeçalho (headers) sempre que possível. O
	126	código compilado condicionalmente pode ser confinado a funções que, se o código
	127	não estiver presente, simplesmente se tornam vazias. O compilador irá então,
	128	silenciosamente, otimizar e remover a chamada para a função vazia. O resultado
	129	é um código muito mais limpo e fácil de acompanhar.
	130
	131	As macros do pré-processador C apresentam uma série de riscos, incluindo a
	132	possível avaliação múltipla de expressões com efeitos colaterais e a falta de
	133	segurança de tipos. Se você se sentir tentado a definir uma macro, considere a
	134	criação de uma função inline em seu lugar. O código resultante será o mesmo,
	135	mas as funções inline são mais fáceis de ler, não avaliam seus argumentos
	136	múltiplas vezes e permitem que o compilador realize a checagem de tipos nos
	137	argumentos e no valor de retorno.
	138
	139
	140	Funções Inline
	141	**************
	142
	143	No entanto, as funções inline apresentam um perigo próprio. Os programadores
	144	podem ficar encantados com a eficiência percebida inerente a evitar uma chamada
	145	de função e encher um arquivo de código-fonte com funções inline. Essas
	146	funções, contudo, podem na verdade reduzir o desempenho. Como seu código é
	147	replicado em cada local de chamada, elas acabam inflando o tamanho do kernel
	148	compilado. Isso, por sua vez, cria pressão nos caches de memória do
	149	processador, o que pode desacelerar a execução drasticamente. As funções
	150	inline, como regra, devem ser bastante pequenas e relativamente raras. O custo
	151	de uma chamada de função, afinal de contas, não é tão alto; a criação de um
	152	grande número de funções inline é um exemplo clássico de otimização prematura.
	153
	154	Em geral, os programadores de kernel ignoram os efeitos de cache por sua própria
	155	conta e risco. O clássico compromisso entre tempo e espaço (tradeoff) ensinado
	156	nas aulas introdutórias de estruturas de dados frequentemente não se aplica ao
	157	hardware contemporâneo. Espaço é tempo, no sentido de que um programa maior
	158	será executado mais lentamente do que um que seja mais compacto.
	159
	160	Compiladores mais recentes desempenham um papel cada vez mais ativo em decidir
	161	se uma determinada função deve ou não ser realmente inline. Portanto, a inserção
	162	liberal da palavra-chave "inline" pode não apenas ser excessiva; ela também pode
	163	ser irrelevante.
	164
	165
	166	Mecanismo de Trava
	167	******************
	168
	169	Em maio de 2006, a pilha de rede "Devicescape" foi, com grande alarde, lançada
	170	sob a GPL e disponibilizada para inclusão no kernel mainline. Essa doação foi uma
	171	notícia bem-vinda; o suporte para redes sem fio no Linux era considerado abaixo do
	172	padrão, na melhor das hipóteses, e a pilha da Devicescape oferecia a promessa de
	173	corrigir essa situação. No entanto, esse código só entrou de fato no mainline em
	174	junho de 2007 (2.6.22). O que aconteceu?
	175
	176	Esse código mostrava vários sinais de ter sido desenvolvido a portas fechadas em
	177	ambiente corporativo. Mas um grande problema em particular era que ele não havia
	178	sido projetado para funcionar em sistemas multiprocessados. Antes que essa pilha
	179	de rede (agora chamada de mac80211) pudesse ser integrada, um esquema de locking
	180	(bloqueio) precisou ser adaptado a ela.
	181
	182	Era uma vez uma época em que o código do kernel Linux podia ser desenvolvido sem
	183	pensar nos problemas de concorrência apresentados por sistemas multiprocessados.
	184	Hoje, no entanto, este documento está sendo escrito em um laptop dual-core.
	185	Mesmo em sistemas com um único processador, o trabalho feito para melhorar a
	186	capacidade de resposta aumentará o nível de concorrência dentro do kernel. Os
	187	dias em que o código do kernel podia ser escrito sem pensar em locking ficaram
	188	há muito tempo no passado.
	189
	190	Qualquer recurso (estruturas de dados, registradores de hardware, etc.) que
	191	possa ser acessado concorrentemente por mais de uma linha de execução deve ser
	192	protegido por uma trava (lock). O novo código deve ser escrito com esse
	193	requisito em mente; adaptar o locking após o fato é uma tarefa consideravelmente
	194	mais difícil. Os desenvolvedores do kernel devem dedicar um tempo para
	195	compreender as primitivas de locking disponíveis bem o suficiente para escolher
	196	a ferramenta certa para o trabalho. Códigos que mostrem falta de atenção à
	197	concorrência terão um caminho difícil para entrar no mainline.
	198
	199
	200	Regressions
	201	***********
	202
	203	Um perigo final que vale a pena mencionar é este: pode ser tentador fazer uma
	204	alteração (que pode trazer grandes melhorias) que faça algo quebrar para os
	205	usuários existentes. Esse tipo de alteração é chamado de "regressão", e as
	206	regressões tornaram-se totalmente indesejadas no kernel mainline. Com poucas
	207	exceções, as alterações que causarem regressões serão revertidas se a regressão
	208	não puder ser corrigida em tempo hábil. É muito melhor evitar a regressão em
	209	primeiro lugar.
	210
	211	Muitas vezes argumenta-se que uma regressão pode ser justificada se ela fizer as
	212	coisas funcionarem para mais pessoas do que os problemas que ela cria. Por que
	213	não fazer uma alteração se ela trouxer uma nova funcionalidade para dez sistemas
	214	para cada um que ela quebrar? A melhor resposta para essa pergunta foi expressa
	215	por Linus em julho de 2007:
	216
	217	::
	218
	219	Portanto, nós não corrigimos bugs introduzindo novos problemas. Esse caminho
	220	leva à loucura, e ninguém nunca sabe se você está realmente fazendo algum
	221	progresso real. São dois passos para frente, um passo para trás, ou um passo
	222	para frente e dois passos para trás?
	223
	224	(https://lwn.net/Articles/243460/).
	225
	226	Um tipo de regressão especialmente indesejado é qualquer tipo de alteração na
	227	ABI do espaço do usuário (user-space ABI). Uma vez que uma interface tenha sido
	228	exportada para o espaço do usuário, ela deve receber suporte indefinidamente.
	229	Esse fato torna a criação de interfaces de espaço do usuário particularmente
	230	desafiadora: já que elas não podem ser alteradas de maneiras incompatíveis, elas
	231	devem ser feitas corretamente na primeira vez. Por essa razão, exige-se sempre
	232	muita reflexão, documentação clara e uma ampla revisão para as interfaces do
	233	espaço do usuário.
	234
	235
	236	Ferramentas de verificação de código
	237	------------------------------------
	238
	239	Por enquanto, pelo menos, a escrita de código livre de erros continua sendo um
	240	ideal que poucos de nós conseguem alcançar. O que podemos esperar fazer, no
	241	entanto, é capturar e corrigir o máximo possível desses erros antes que nosso
	242	código entre no kernel mainline. Para esse fim, os desenvolvedores do kernel
	243	reuniram um conjunto impressionante de ferramentas que podem capturar uma ampla
	244	variedade de problemas obscuros de forma automatizada. Qualquer problema
	245	capturado pelo computador é um problema que não afligirá um usuário mais tarde,
	246	portanto, é lógico que as ferramentas automatizadas devem ser usadas sempre que
	247	possível.
	248
	249	O primeiro passo é simplesmente prestar atenção aos avisos (warnings) produzidos
	250	com o compilador. As versões contemporâneas do gcc podem detectar (e alertar
	251	sobre) um grande número de erros potenciais. Com bastante frequência, esses
	252	avisos apontam para problemas reais. O código enviado para revisão deve, como
	253	regra, não produzir nenhum aviso do compilador. Ao silenciar os avisos, tome o
	254	cuidado de entender a real causa e tente evitar "correções" que façam o aviso
	255	desaparecer sem resolver a sua origem.
	256
	257	Note que nem todos os avisos do compilador ficam ativados por padrão. Compile o
	258	kernel com "make KCFLAGS=-W" para obter o conjunto completo.
	259
	260	O kernel fornece várias opções de configuração que ativam recursos de
	261	depuração; a maioria delas é encontrada no submanu "kernel hacking". Várias
	262	dessas opções devem ser ativadas para qualquer kernel usado para fins de
	263	desenvolvimento ou teste. Em particular, você deve ativar:
	264
	265	- FRAME_WARN para obter avisos sobre quadros de pilha (stack frames) maiores
	266	que um determinado valor. A saída gerada pode ser volumosa, mas não é
	267	necessário se preocupar com os avisos de outras partes do kernel.
	268
	269	- DEBUG_OBJECTS adicionará código para rastrear o tempo de vida de vários
	270	objetos criados pelo kernel e alertará quando as ações forem feitas fora de
	271	ordem. Se você estiver adicionando um subsistema que cria (e exporta) seus
	272	próprios objetos complexos, considere adicionar suporte à infraestrutura de
	273	depuração de objetos.
	274
	275	- DEBUG_SLAB pode encontrar uma variedade de erros de alocação e uso de
	276	memória; ele deve ser usado na maioria dos kernels de desenvolvimento.
	277
	278	- DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP e DEBUG_MUTEXES encontrarão uma série de
	279	erros comuns de locking (bloqueio).
	280
	281	Existem várias outras opções de depuração, algumas das quais serão discutidas
	282	abaixo. Algumas delas têm um impacto significativo no desempenho e não devem ser
	283	usadas o tempo todo. Mas um tempo gasto aprendendo as opções disponíveis
	284	provavelmente se pagará muitas vezes em pouco tempo.
	285
	286	Uma das ferramentas de depuração mais pesadas é o verificador de locking, ou
	287	"lockdep". Esta ferramenta rastreará a aquisição e a liberação de cada trava
	288	(spinlock ou mutex) no sistema, a ordem em que as travas são adquiridas umas em
	289	relação às outras, o ambiente de interrupção atual e muito mais. Ela pode,
	290	então, garantir que as travas sejam sempre adquiridas na mesma ordem, que as
	291	mesmas suposições de interrupção se apliquem em todas as situações e assim por
	292	diante. Em outras palavras, o lockdep pode encontrar uma série de cenários nos
	293	quais o sistema poderia, em raras ocasiões, entrar em deadlock. Esse tipo de
	294	problema pode ser doloroso (tanto para desenvolvedores quanto para usuários) em
	295	um sistema implantado; o lockdep permite que eles sejam encontrados de maneira
	296	automatizada e antecipada. Códigos com qualquer tipo de locking não trivial
	297	devem ser executados com o lockdep ativado antes de serem enviados para inclusão.
	298
	299	Como um programador de kernel diligente, você irá, sem dúvida, verificar o
	300	status de retorno de qualquer operação (como uma alocação de memória) que possa
	301	falhar. O fato, porém, é que os caminhos de recuperação de falha resultantes
	302	estão, provavelmente, completamente não testados. Código não testado tende a ser
	303	código quebrado; você poderia estar muito mais confiante em seu código se todos
	304	esses caminhos de tratamento de erros tivessem sido exercitados algumas vezes.
	305
	306	O kernel fornece um framework de injeção de falhas (fault injection) que pode
	307	fazer exatamente isso, especialmente onde alocações de memória estão
	308	envolvidas. Com a injeção de falhas ativada, uma porcentagem configurável das
	309	alocações de memória será forçada a falhar; essas falhas podem ser restritas a
	310	um intervalo específico de código. Executar o código com a injeção de falhas
	311	ativada permite ao programador ver como o código responde quando as coisas vão
	312	mal. Veja Documentation/fault-injection/fault-injection.rst para mais
	313	informações sobre como usar esse recurso.
	314
	315	Outros tipos de erros podem ser encontrados com a ferramenta de análise estática
	316	"sparse". Com o sparse, o programador pode ser alertado sobre confusões entre
	317	endereços do espaço do usuário e do espaço do kernel, mistura de quantidades
	318	big-endian e small-endian, a passagem de valores inteiros onde um conjunto de
	319	sinalizadores de bits (bit flags) é esperado, e assim por diante. O sparse deve
	320	ser instalado separadamente (ele pode ser encontrado em
	321	https://sparse.wiki.kernel.org/index.php/Main_Page se a sua distribuição não o
	322	incluir como pacote); ele pode então ser executado no código adicionando "C=1"
	323	ao seu comando make.
	324
	325	A ferramenta "Coccinelle" (http://coccinelle.lip6.fr/) é capaz de encontrar uma
	326	ampla variedade de potenciais problemas de codificação; ela também pode propor
	327	correções para esses problemas. Uma quantidade considerável de "patches
	328	semânticos" para o kernel foi empacotada sob o diretório scripts/coccinelle;
	329	executar "make coccicheck" passará por esses patches semânticos e relatará
	330	quaisquer problemas encontrados. Veja
	331	:ref:`Documentation/dev-tools/coccinelle.rst <devtools_coccinelle>`
	332	para mais informações.
	333
	334	Outros tipos de erros de portabilidade são encontrados mais facilmente ao
	335	compilar seu código para outras arquiteturas. Se você por acaso não tiver um
	336	sistema S/390 ou uma placa de desenvolvimento Blackfin à mão, ainda assim poderá
	337	realizar a etapa de compilação. Um grande conjunto de compiladores cruzados
	338	(cross-compilers) para sistemas x86 pode ser encontrado em:
	339
	340	https://www.kernel.org/pub/tools/crosstool/
	341
	342	Um tempo gasto instalando e usando esses compiladores ajudará a evitar
	343	constrangimentos mais tarde.
	344
	345
	346	Documentação
	347	-------------
	348
	349	A documentação frequentemente tem sido mais a exceção do que a regra no
	350	desenvolvimento do kernel. Mesmo assim, uma documentação adequada ajudará a
	351	facilitar a integração de novos códigos ao kernel, tornará a vida mais fácil para
	352	outros desenvolvedores e será útil para os seus usuários. Em muitos casos, a
	353	adição de documentação tornou-se essencialmente obrigatória.
	354
	355	A primeira parte da documentação de qualquer patch é o seu log de alterações
	356	(changelog) associado. As entradas do log devem descrever o problema que está
	357	sendo resolvido, a forma da solução, as pessoas que trabalharam no patch,
	358	quaisquer efeitos relevantes no desempenho e qualquer outra coisa que possa ser
	359	necessária para entender o patch. Certifique-se de que o changelog diga o
	360	porquê de o patch valer a pena ser aplicado; um número surpreendente de
	361	desenvolvedores falha em fornecer essa informação.
	362
	363	Qualquer código que adicione uma nova interface de espaço do usuário — incluindo
	364	novos arquivos sysfs ou /proc — deve incluir a documentação dessa interface, de
	365	modo a permitir que os desenvolvedores do espaço do usuário saibam com o que
	366	estão trabalhando. Veja Documentation/ABI/README para uma descrição de como essa
	367	documentação deve ser formatada e quais informações precisam ser fornecidas.
	368
	369	O arquivo :ref:`Documentation/admin-guide/kernel-parameters.rst
	370	<kernelparameters>` descreve todos os parâmetros de boot do kernel. Qualquer
	371	patch que adicione novos parâmetros deve adicionar as entradas apropriadas a
	372	este arquivo.
	373
	374	Quaisquer novas opções de configuração devem ser acompanhadas por um texto de
	375	ajuda que explique claramente as opções e quando o usuário pode querer
	376	selecioná-las.
	377
	378	As informações de API interna de muitos subsistemas são documentadas por meio de
	379	comentários com formatação especial; esses comentários podem ser extraídos e
	380	formatados de várias maneiras pelo script "kernel-doc". Se você estiver
	381	trabalhando em um subsistema que possui comentários kerneldoc, você deve
	382	mantê-los e adicioná-los, conforme apropriado, para funções disponíveis
	383	externamente. Mesmo em áreas que não tenham sido documentadas dessa forma, não há
	384	mal nenhum em adicionar comentários kerneldoc para o futuro; de fato, esta pode
	385	ser uma atividade útil para desenvolvedores iniciantes de kernel. O formato
	386	desses comentários, junto com algumas informações sobre como criar modelos de
	387	kerneldoc, pode ser encontrado em :ref:`Documentation/doc-guide/ <doc_guide>`.
	388
	389	Qualquer pessoa que leia uma quantidade significativa de código existente do
	390	kernel notará que, frequentemente, os comentários chamam a atenção por sua
	391	ausência. Mais uma vez, as expectativas para códigos novos são mais altas do que
	392	eram no passado; integrar código sem comentários será mais difícil. Dito isso,
	393	há pouco interesse em códigos comentados de forma prolixa. O código deve, por si
	394	só, ser legível, com os comentários explicando os aspectos mais sutis.
	395
	396	Certas coisas devem sempre ser comentadas. O uso de barreiras de memória
	397	(memory barriers) deve ser acompanhado por uma linha explicando por que a
	398	barreira é necessária. As regras de locking (bloqueio) para estruturas de dados
	399	geralmente precisam ser explicadas em algum lugar. Grandes estruturas de dados
	400	precisam de uma documentação abrangente em geral. Dependências não óbvias entre
	401	trechos distintos de código devem ser apontadas. Qualquer coisa que possa tentar
	402	um "faxineiro de código" (code janitor) a fazer uma "limpeza" incorreta precisa
	403	de um comentário dizendo por que foi feita daquela maneira. E assim por diante.
	404
	405
	406	Alterações de API interna
	407	-------------------------
	408
	409	A interface binária fornecida pelo kernel para o espaço do usuário não pode ser
	410	quebrada, exceto sob as circunstâncias mais graves. Por outro lado, as
	411	interfaces de programação internas do kernel são altamente fluidas e podem ser
	412	alteradas quando surgir a necessidade. Se você se encontrar tendo que criar uma
	413	gambiarra para contornar uma API do kernel, ou simplesmente deixando de usar uma
	414	funcionalidade específica porque ela não atende às suas necessidades, isso pode
	415	ser um sinal de que a API precisa mudar. Como desenvolvedor de kernel, você tem
	416	o poder de fazer tais alterações.
	417
	418	Existem, é claro, algumas pegadinhas. Alterações de API podem ser feitas, mas
	419	precisam ser bem justificadas. Portanto, qualquer patch que faça uma alteração de
	420	API interna deve ser acompanhado por uma descrição do que é a mudança e do porquê
	421	ela é necessária. Esse tipo de alteração também deve ser separado em um patch
	422	independente, em vez de ser enterrado dentro de um patch maior.
	423
	424	A outra pegadinha é que o desenvolvedor que altera uma API interna é geralmente
	425	encarregado da tarefa de corrigir qualquer código dentro da árvore do kernel que
	426	tenha sido quebrado pela mudança. Para uma função amplamente utilizada, esse
	427	dever pode levar a literalmente centenas ou milhares de alterações — muitas das
	428	quais provavelmente entrarão em conflito com o trabalho que está sendo feito por
	429	outros desenvolvedores. Desnecessário dizer que isso pode ser um grande
	430	trabalho, então é melhor ter certeza de que a justificativa é sólida. Note que
	431	a ferramenta Coccinelle pode ajudar com alterações de API de amplo alcance.
	432
	433	Ao fazer uma alteração incompatível de API, deve-se, sempre que possível,
	434	garantir que o código que não foi atualizado seja capturado pelo compilador.
	435	Isso ajudará você a ter certeza de que encontrou todos os usos dessa interface
	436	dentro da árvore (in-tree). Isso também alertará os desenvolvedores de códigos
	437	fora da árvore (out-of-tree) de que há uma mudança à qual eles precisam
	438	responder. Dar suporte a código fora da árvore não é algo com que os
	439	desenvolvedores do kernel precisem se preocupar, mas também não temos que
	440	tornar a vida dos desenvolvedores fora da árvore mais difícil do que precisa ser.

Documentation/translations/pt_BR/process/5.Posting.rst+376−0

@@ -0,0 +1,376 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	Enviando patches
	4	================
	5
	6	Cedo ou tarde, chega o momento em que seu trabalho está pronto para ser
	7	apresentado à comunidade para revisão e, eventualmente, inclusão no kernel
	8	mainline. Sem surpresa, a comunidade de desenvolvimento do kernel evoluiu um
	9	conjunto de convenções e procedimentos que são usados no envio de patches;
	10	segui-los tornará a vida muito mais fácil para todos os envolvidos. Este
	11	documento tentará cobrir essas expectativas em detalhes razoáveis; mais
	12	informações também podem ser encontradas nos arquivos
	13	:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
	14	e :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`.
	15
	16
	17	Quando enviar
	18	-------------
	19
	20	Existe uma tentação constante de evitar o envio de patches antes que eles
	21	estejam completamente "prontos". Para patches simples, isso não é um problema.
	22	No entanto, se o trabalho que está sendo feito for complexo, há muito a se
	23	ganhar obtendo feedback da comunidade antes que o trabalho esteja concluído.
	24	Portanto, você deve considerar o envio de trabalhos em andamento, ou até mesmo
	25	disponibilizar uma árvore git para que os desenvolvedores interessados possam
	26	acompanhar o seu trabalho a qualquer momento.
	27
	28	Ao enviar um código que ainda não é considerado pronto para inclusão, é uma boa
	29	ideia dizer isso no próprio envio. Mencione também qualquer trabalho importante
	30	que ainda precise ser feito e quaisquer problemas conhecidos. Menos pessoas vão
	31	olhar para patches que sabidamente estão "meio cozidos" (half-baked), mas aqueles
	32	que o fizerem virão com a ideia de que podem ajudá-lo a conduzir o trabalho na
	33	direção certa.
	34
	35
	36	Antes de criar patches
	37	----------------------
	38
	39	Há uma série de coisas que devem ser feitas antes de você considerar o envio
	40	de patches para la comunidade de desenvolvimento. Elas incluem:
	41
	42	- Teste o código tanto quanto puder. Faça uso das ferramentas de depuração
	43	do kernel, garanta que o kernel seja compilado com todas as combinações
	44	razoáveis de opções de configuração, use compiladores cruzados (cross-
	45	compilers) para compilar para diferentes arquiteturas, etc. Adicione testes,
	46	provavelmente usando um framework de testes existente como o KUnit, e
	47	inclua-os como um membro separado da sua série (veja a próxima seção para
	48	mais informações sobre séries de patches). Note que isso pode ser
	49	obrigatório ao afetar alguns subsistemas. Por exemplo, funções de biblioteca
	50	(localizadas sob lib/) são amplamente utilizadas em quase todos os lugares e
	51	espera-se que sejam testadas adequadamente.
	52
	53	- Certifique-se de que seu código esteja em conformidade com as diretrizes de
	54	estilo de codificação do kernel.
	55
	56	- Sua alteração tem implicações no desempenho? Se sim, você deve executar
	57	benchmarks mostrando qual é o impacto (ou benefício) da sua mudança; um
	58	resumo dos resultados deve ser incluído junto ao patch.
	59
	60	- Tenha certeza de que você tem o direito de enviar o código. Se este
	61	trabalho foi feito para um empregador, o empregador provavelmente tem direito
	62	sobre o trabalho e deve estar de acordo com a sua liberação sob a GPL.
	63
	64	Como regra geral, dedicar um pouco de reflexão extra antes de enviar o código
	65	quase sempre compensa o esforço em pouco tempo.
	66
	67
	68	Preparação de patches
	69	---------------------
	70
	71	A preparação de patches para envio pode dar uma quantidade surpreendente de
	72	trabalho, mas, mais uma vez, tentar economizar tempo aqui geralmente não é
	73	aconselhável, mesmo a curto prazo.
	74
	75	Os patches devem ser preparados contra uma versão específica do kernel. Como
	76	regra geral, um patch deve ser baseado no mainline atual encontrado na árvore
	77	git do Linus. Ao basear-se no mainline, comece a partir de um ponto de
	78	lançamento bem conhecido — um release estável ou -rc —, em vez de criar uma
	79	bifurcação (branch) a partir do mainline em um ponto arbitrário.
	80
	81	No entanto, pode tornar-se necessário criar versões contra a árvore -mm,
	82	linux-next ou a árvore de um subsistema, para facilitar testes e revisões mais
	83	amplos. Dependendo da área do seu patch e do que está acontecendo em outros
	84	lugares, basear um patch contra essas outras árvores pode exigir uma quantidade
	85	significativa de trabalho para resolver conflitos e lidar com mudanças de API.
	86
	87	Apenas as alterações mais simples devem ser formatadas como um único patch; tudo
	88	o mais deve ser feito como uma série lógica de mudanças. Dividir patches é uma
	89	arte; alguns desenvolvedores passam muito tempo descobrindo como fazer isso da
	90	maneira que a comunidade espera. Existem algumas regras práticas, no entanto,
	91	que podem ajudar consideravelmente:
	92
	93	- A série de patches que você envia quase certamente não será a série de
	94	alterações encontrada no seu sistema de controle de versão de trabalho. Em
	95	vez disso, as mudanças que você fez precisam ser consideradas em sua forma
	96	final e, então, divididas de maneiras que façam sentido. Os desenvolvedores
	97	estão interessados em alterações discretas e autocontidas, não no caminho
	98	que você percorreu para chegar a essas alterações.
	99
	100	- Cada alteração logicamente independente deve ser formatada como um patch separado.
	101	Essas alterações podem ser pequenas ("adicionar um campo a esta estrutura") ou
	102	grandes (adicionar um driver totalmente novo, por exemplo), mas devem ser
	103	conceitualmente pequenas e passíveis de uma descrição de uma única linha. Cada
	104	patch deve fazer uma alteração específica que possa ser revisada por si só e
	105	verificada para garantir que faz o que diz fazer.
	106
	107	- Como uma forma de reafirmar a diretriz acima: não misture diferentes tipos de
	108	alterações no mesmo patch. Se um único patch corrige uma falha crítica de
	109	segurança, reorganiza algumas estruturas e reformatará o código, há uma grande
	110	chance de que ele seja ignorado e a correção importante seja perdida.
	111
	112	- Cada patch deve resultar em um kernel que compile e funcione corretamente; se
	113	sua série de patches for interrompida no meio, o resultado ainda deve ser um
	114	kernel funcional. A aplicação parcial de uma série de patches é um cenário
	115	comum quando a ferramenta "git bisect" é usada para encontrar regressões; se o
	116	resultado for um kernel quebrado, você tornará a vida mais difícil para os
	117	desenvolvedores e usuários que estão engajados no nobre trabalho de rastrear
	118	problemas.
	119
	120	- No entanto, não exagere. Certa vez, um desenvolvedor enviou um conjunto de
	121	edições em um único arquivo como 500 patches separados — um ato que não o
	122	tornou a pessoa mais popular na lista de discussão do kernel. Um único patch
	123	pode ser razoavelmente grande, desde que ainda contenha uma única alteração
	124	lógica.
	125
	126	- Pode ser tentador adicionar toda uma nova infraestrutura com uma série de
	127	patches, mas deixar essa infraestrutura sem uso até que o patch final da série
	128	ative tudo. Essa tentação deve ser evitada, se possível; se essa série
	129	adicionar regressões, a bisseção (bisection) apontará o último patch como aquele
	130	que causou o problema, mesmo que o bug real esteja em outro lugar. Sempre que
	131	possível, um patch que adiciona código novo deve tornar esse código ativo
	132	imediatamente.
	133
	134	Trabalhar para criar a série de patches perfeita pode ser um processo
	135	frustrante, que exige bastante tempo e reflexão após o "trabalho real" ter sido
	136	concluído. Quando feito corretamente, no entanto, é um tempo bem gasto.
	137
	138
	139	Formatação de patches e logs de alterações
	140	------------------------------------------
	141
	142	Então agora você tem uma série perfeita de patches para enviar, mas o trabalho
	143	ainda não terminou. Cada patch precisa ser formatado em uma mensagem que comunique
	144	de forma rápida e clara o seu propósito para o resto do mundo. Para esse fim,
	145	cada patch será composto pelo seguinte:
	146
	147	- Uma linha "From" opcional que nomeia o autor do patch. Esta linha só é
	148	necessária se você estiver repassando o patch de outra pessoa via e-mail,
	149	mas nunca é demais adicioná-la em caso de dúvida.
	150
	151	- Uma descrição de uma única linha sobre o que o patch faz. Esta mensagem deve
	152	ser suficiente para que um leitor que a veja sem outro contexto consiga
	153	compreender o escopo do patch; esta é a linha que aparecerá nos logs de
	154	alterações (changelogs) de "forma curta". Esta mensagem geralmente é formatada
	155	com o nome do subsistema relevante primeiro, seguido pelo propósito do patch.
	156	Por exemplo:
	157
	158	::
	159
	160	gpio: fix build on CONFIG_GPIO_SYSFS=n
	161
	162	- Uma linha em branco seguida por uma descrição detalhada do conteúdo do
	163	patch. Esta descrição pode ser tão longa quanto necessário; ela deve dizer
	164	o que o patch faz e por que ele deve ser aplicado ao kernel.
	165
	166	- Uma ou mais linhas de marcadores (tags) com, no mínimo, uma linha
	167	"Signed-off-by:" do autor do patch. Os marcadores serão descritos em mais
	168	detalhes abaixo.
	169
	170	Os itens acima, juntos, formam o log de alterações (changelog) do patch. Escrever
	171	bons changelogs é uma arte crucial, mas frequentemente negligenciada; vale a
	172	pena dedicar mais um momento para discutir esse assunto. Ao escrever um
	173	changelog, você deve ter em mente que várias pessoas diferentes lerão suas
	174	palavras. Elas incluem mantenedores de subsistemas e revisores que precisam
	175	decidir se o patch deve ser incluído, distribuidores e outros mantenedores
	176	tentando decidir se um patch deve ser retroportado (backported) para outros
	177	kernels, caçadores de bugs se perguntando se o patch é responsável por um
	178	problema que estão perseguindo, usuários que querem saber como o kernel mudou e
	179	muito mais. Um bom changelog transmite a informação necessária para todas essas
	180	pessoas da maneira mais direta e concisa possível.
	181
	182	Para esse fim, a linha de resumo deve descrever os efeitos e a motivação da
	183	alteração o melhor possível, dada a restrição de uma única linha. A descrição
	184	detalhada pode então ampliar esses tópicos e fornecer qualquer informação
	185	adicional necessária. Se o patch corrige um bug, cite o commit que introduziu o
	186	bug, se possível (e, por favor, forneça tanto o ID do commit quanto o título ao
	187	citar commits). Se um problema estiver associado a uma saída específica de log
	188	ou do compilador, inclua essa saída para ajudar outras pessoas que buscam uma
	189	solução para o mesmo problema. Se a mudança tem o objetivo de dar suporte a
	190	outras alterações que virão em um patch posterior, informe isso. Se as APIs
	191	internas forem alteradas, detalhe essas mudanças e como outros desenvolvedores
	192	devem reagir. Em geral, quanto mais você puder se colocar no lugar de todos que
	193	lerão seu changelog, melhor será esse changelog (e o kernel como um todo).
	194
	195	Desnecessário dizer que o changelog deve ser o texto usado ao submeter (commit)
	196	a alteração em um sistema de controle de versão. Ele será seguido por:
	197
	198	- O patch em si, no formato de patch unificado ("-u"). O uso da opção "-p" no
	199	diff associará os nomes das funções às alterações, tornando o patch resultante
	200	mais fácil de ser lido por outras pessoas.
	201
	202	As tags já mencionadas brevemente acima são usados para fornecer
	203	informações sobre como o patch surgiu. Eles são descritos em detalhes no
	204	documento :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`;
	205	o que se segue aqui é um breve resumo.
	206
	207	Um marcador é usado para se referir a commits anteriores que introduziram os
	208	problemas corrigidos pelo patch::
	209
	210	Fixes: 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID")
	211
	212	Outro marcador é usado para vincular páginas da web com contextos ou detalhes
	213	adicionais, por exemplo, uma discussão anterior que levou ao patch ou um
	214	documento com uma especificação implementada pelo patch::
	215
	216	Link: https://example.com/somewhere.html optional-other-stuff
	217
	218	De acordo com as orientações do Pinguim-Chefe, um marcador Link
	219	só deve ser adicionado a um commit se ele levar a informações úteis que não
	220	são encontradas no próprio commit.
	221
	222	Se a URL apontar para um relatório de bug público que está sendo corrigido pelo
	223	patch, use o marcador "Closes:" em seu lugar::
	224
	225	Closes: https://example.com/issues/1234 optional-other-stuff
	226
	227	Alguns rastreadores de bugs têm a capacidade de fechar problemas de forma
	228	automática quando um commit com tal marcador é aplicado. Alguns bots que
	229	monitoram listas de discussão também podem rastrear esses marcadores e tomar certas
	230	ações. Rastreadores de bugs privados e URLs inválidas são proibidos.
	231
	232	Outro tipo de marcador é usado para documentar quem esteve envolvido no
	233	desenvolvimento do patch. Cada um deles usa este formato::
	234
	235	tag: Full Name <email address> optional-other-stuff
	236
	237	Os marcadores de uso comum são:
	238
	239	- Signed-off-by: esta é uma certificação do desenvolvedor de que ele ou ela
	240	tem o direito de enviar o patch para inclusão no kernel. É um acordo com o
	241	Developer's Certificate of Origin (Certificado de Origem do Desenvolvedor),
	242	cujo texto completo pode ser encontrado em
	243	:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
	244	Códigos sem um signoff adequado não podem ser mesclados (merged) no mainline.
	245
	246	- Co-developed-by: afirma que o patch foi criado em coautoria por vários
	247	desenvolvedores; é usado para dar atribuição aos coautores (além do autor
	248	atribuído pelo marcador From:) quando várias pessoas trabalham em um único
	249	patch. Cada Co-developed-by: deve ser imediatamente seguido por um
	250	Signed-off-by: do coautor associado. Detalhes e exemplos podem ser encontrados
	251	em :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
	252
	253	- Acked-by: indica o acordo de outro desenvolvedor (frequentemente um
	254	mantenedor do código relevante) de que o patch é apropriado para inclusão
	255	no kernel.
	256
	257	- Tested-by: afirma que a pessoa nomeada testou o patch e verificou que ele
	258	funciona.
	259
	260	- Reviewed-by: o desenvolvedor nomeado revisou o patch para verificar sua
	261	correção; veja a declaração do revisor em
	262	:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
	263	para mais detalhes.
	264
	265	- Reported-by: nomeia um usuário que relatou o problema que é corrigido por este
	266	patch; este marcador é usado para dar crédito às pessoas (frequentemente sub-
	267	valorizadas) que testam nosso código e nos informam quando as coisas não
	268	funcionam corretamente. Nota: este marcador deve ser seguido por um marcador
	269	Closes: apontando para o relato, a menos que o relato não esteja disponível na
	270	web. O marcador Link: pode ser usado em vez de Closes: se o patch corrigir
	271	apenas uma parte do(s) problema(s) relatado(s).
	272
	273	- A Suggested-by: este marcador indica que a ideia do patch foi sugerida pela
	274	pessoa nomeada e garante o crédito a ela pela ideia. Isso, espera-se, irá
	275	inspirá-la a nos ajudar novamente no futuro.
	276
	277	- Cc: a pessoa nomeada recebeu uma cópia do patch e teve a oportunidade de
	278	comentar sobre ele.
	279
	280	Tenha cuidado ao adicionar os marcadores mencionados acima aos seus patches, pois
	281	todos, exceto Cc:, Reported-by: e Suggested-by:, precisam de permissão explícita
	282	fontes da pessoa nomeada. Para esses três, a permissão implícita é suficiente se
	283	a pessoa contribuiu para o kernel Linux usando esse nome e endereço de e-mail de
	284	acordo com os arquivos do lore ou o histórico de commits — e, no caso de
	285	Reported-by: e Suggested-by:, se fizeram o relato ou a sugestão publicamente.
	286	Nota: o bugzilla.kernel.org é um local público nesse sentido, mas os endereços
	287	de e-mail usados lá são privados; portanto, não os exponha em marcadores, a menos
	288	que a pessoa os tenha usado em contribuições anteriores.
	289
	290
	291	Enviando o patch
	292	-----------------
	293
	294	Antes de enviar seus patches por e-mail, há algumas outras coisas com as quais
	295	você deve se preocupar:
	296
	297	- Você tem certeza de que seu cliente de e-mail não vai corromper os patches?
	298	Patches que sofreram alterações desnecessárias de espaço em branco ou quebra
	299	de linha causadas pelo cliente de e-mail não serão aplicados na outra ponta
	300	e, frequentemente, não serão examinados em detalhes. Se houver qualquer
	301	dúvida, envie o patch para você mesmo e certifique-se de que ele chegue intacto.
	302
	303	O documento :ref:`Documentation/process/email-clients.rst <email_clients>`
	304	possui algumas dicas úteis sobre como fazer clientes de e-mail específicos
	305	funcionarem para o envio de patches.
	306
	307	- Você tem certeza de que seu patch está livre de erros bobos? Você deve sempre
	308	passar os patches pelo scripts/checkpatch.pl e corrigir as reclamações que
	309	ele apresentar. Por favor, tenha em mente que o checkpatch.pl, embora seja a
	310	personificação de uma quantidade razoável de reflexão sobre como os patches do
	311	kernel devem parecer, não é mais inteligente que você. Se corrigir uma
	312	reclamação do checkpatch.pl piorar o código, não o faça.
	313
	314	Os patches devem sempre ser enviados como texto simples (plain text). Por favor,
	315	não os envie como anexos; isso torna muito mais difícil para os revisores citarem
	316	trechos do patch em suas respostas. Em vez disso, coloque o patch diretamente no
	317	corpo da sua mensagem.
	318
	319	Ao enviar patches por e-mail, é importante enviar cópias para qualquer pessoa
	320	que possa estar interessada neles. Ao contrário de alguns outros projetos, o
	321	kernel incentiva as pessoas a pecarem pelo excesso, enviando cópias demais; não
	322	assuma que as pessoas relevantes verão sua publicação nas listas de discussão. Em
	323	particular, as cópias devem ir para:
	324
	325	- O(s) mantenedor(es) do(s) subsistema(s) afetado(s). Como descrito antes, o
	326	arquivo MAINTAINERS é o primeiro lugar para procurar por essas pessoas.
	327
	328	- Outros desenvolvedores que estiveram trabalhando na mesma área — especialmente
	329	aqueles que possam estar trabalhando lá agora. Usar o git para ver quem mais
	330	modificou os arquivos nos quais você está trabalhando pode ser útil.
	331
	332	- Se você estiver respondendo a um relato de bug ou a uma solicitação de recurso
	333	(feature request), envie uma cópia também para o autor original.
	334
	335	- Envie uma cópia para a lista de discussão relevante ou, se nada mais se
	336	aplicar, para a lista linux-kernel.
	337
	338	- Se você estiver corrigindo um bug, pense se a correção deve ir para a próxima
	339	atualização estável (stable update). Se sim, stable@vger.kernel.org deve
	340	receber uma cópia do patch. Adicione também um "Cc: stable@vger.kernel.org"
	341	aos marcadores (tags) dentro do próprio patch; isso fará com que a equipe do
	342	stable receba uma notificação quando sua correção for integrada ao mainline.
	343
	344	Ao selecionar os destinatários para um patch, é bom ter uma ideia de quem você
	345	acha que eventualmente aceitará o patch e fará a mesclagem (merge). Embora seja
	346	possível enviar patches diretamente para Linus Torvalds e fazer com que ele os
	347	mescle, as coisas normalmente não são feitas dessa forma. Linus está ocupado, e
	348	existem mantenedores de subsistemas que vigiam partes específicas do kernel. Em
	349	geral, você desejará que esse mantenedor mescle seus patches. Se não houver um
	350	mantenedor óbvio, Andrew Morton costuma ser o destino de patch de último recurso.
	351
	352	Os patches precisam de boas linhas de assunto (subject lines). O formato canônico
	353	para a linha de um patch é algo como:
	354
	355	::
	356
	357
	358	[PATCH nn/mm] subsys: descrição de uma linha do patch
	359
	360	onde "nn" é o número ordinal do patch, "mm" é o número total de patches na
	361	série, e "subsys" é o nome do subsistema afetado. Claramente, nn/mm pode ser
	362	omitido no caso de um patch único e isolado (standalone).
	363
	364	Se você tiver uma série significativa de patches, é costumeiro enviar uma
	365	descrição introdutória como a parte zero. Essa convenção não é seguida
	366	universalmente, no entanto; se você a utilizar, lembre-se de que as informações
	367	da introdução não entram nos changelogs do kernel. Portanto, certifique-se de
	368	que os patches, em si, possuam informações completas em seus changelogs.
	369
	370	Em geral, a segunda parte e as subsequentes de um patch de múltiplas partes devem
	371	ser enviadas como uma resposta à primeira parte, de modo que todas formem uma
	372	única linha de discussão (thread) na ponta receptora. Ferramentas como o git e o
	373	quilt possuem comandos para enviar por e-mail um conjunto de patches com o
	374	encadeamento correto. Se você tiver uma série longa, contudo, e estiver usando o
	375	git, por favor, evite a opção --chain-reply-to para não criar um aninhamento
	376	excepcionalmente profundo.

Documentation/translations/pt_BR/process/6.Followthrough.rst+220−0

@@ -0,0 +1,220 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	Acompanhamento
	4	==============
	5
	6	Neste ponto, você seguiu as diretrizes apresentadas até aqui e, com a
	7	adição de suas próprias habilidades de engenharia, enviou uma série perfeita
	8	de patches. Um dos maiores erros que até mesmo desenvolvedores experientes
	9	do kernel podem cometer é concluir que o seu trabalho agora está concluído.
	10	Na verdade, o envio de patches indica uma transição para a próxima etapa
	11	do processo, possivelmente com uma quantidade considerável de trabalho
	12	ainda por fazer.
	13
	14	É raro um patch ser tão bom em seu primeiro envio que não haja margem para
	15	melhorias. O processo de desenvolvimento do kernel reconhece esse fato e,
	16	como resultado, é fortemente orientado para o aprimoramento do código
	17	enviado. Espera-se que você, como autor desse código, trabalhe junto à
	18	comunidade do kernel para garantir que seu código esteja de acordo com os
	19	padrões de qualidade do kernel. A falha em participar desse processo muito
	20	provavelmente impedirá a inclusão de seus patches na árvore principal
	21	(mainline).
	22
	23
	24	Trabalhando com revisores
	25	-------------------------
	26
	27	Um patch de qualquer relevância resultará em uma série de comentários de outros
	28	desenvolvedores à medida que eles revisam o código. Trabalhar com revisores
	29	pode ser, para muitos desenvolvedores, a parte mais intimidadora do processo
	30	de desenvolvimento do kernel. No entanto, a vida pode se tornar muito mais
	31	fácil se você mantiver algumas coisas em mente:
	32
	33	* Se você explicou bem o seu patch, os revisores entenderão o seu valor
	34	e o porquê de você ter tido o trabalho de escrevê-lo. Contudo, esse valor
	35	não os impedirá de fazer uma pergunta fundamental: como será manter um
	36	kernel com este código inserido nele daqui a cinco ou dez anos? Muitas das
	37	mudanças que podem lhe pedir para fazer — desde ajustes de estilo de código
	38	até reescritas substanciais — vêm do entendimento de que o Linux ainda estará
	39	por aqui e sob desenvolvimento daqui a uma década.
	40
	41	* A revisão de código é um trabalho árduo e uma ocupação relativamente
	42	ingrata; as pessoas lembram quem escreveu o código do kernel, mas há pouca
	43	fama duradoura para aqueles que o revisaram. Portanto, os revisores podem
	44	ficar ranzinzas, especialmente quando veem os mesmos erros sendo cometidos
	45	repetidamente. Se você receber uma revisão que pareça irritada, insultuosa
	46	ou abertamente ofensiva, resista ao impulso de responder à altura. A revisão
	47	de código diz respeito ao código, não às pessoas, e os revisores de código
	48	não estão atacando você pessoalmente.
	49
	50	* Da mesma forma, os revisores de código não estão tentando promover os
	51	interesses de seus empregadores em detrimento dos seus. Os desenvolvedores
	52	do kernel geralmente esperam continuar trabalhando no kernel daqui a muitos
	53	anos, mas entendem que seu empregador pode mudar. Quase sem exceção, eles
	54	estão verdadeiramente trabalhando em prol da criação do melhor kernel possível;
	55	eles não estão tentando causar desconforto aos concorrentes de seus empregadores.
	56
	57	* Esteja preparado para solicitações aparentemente tolas de mudanças no estilo
	58	de codificação e pedidos para refatorar parte do seu código em seções
	59	compartilhadas do kernel. Uma das funções dos mantenedores é manter as coisas
	60	com a mesma aparência. Às vezes, isso significa que aquele truque inteligente
	61	(clever hack) em seu driver para contornar um problema
	62
	63	Note que você não precisa concordar com todas as mudanças sugeridas pelos
	64	revisores. Se você acredita que o revisor entendeu mal o seu código, explique
	65	o que realmente está acontecendo. Se tiver uma objeção técnica a uma mudança
	66	sugerida, descreva-a e justifique a sua solução para o problema. Se as suas
	67	explicações fizerem sentido, o revisor as aceitará. Contudo, caso a sua
	68	explicação não seja persuasiva — especialmente se outros começarem a concordar
	69	com o revisor —, reserve um tempo para repensar as coisas. Pode ser fácil ficar
	70	ceguificado por sua própria solução para um problema, a ponto de não perceber
	71	que algo está fundamentalmente errado ou que, talvez, você não esteja sequer
	72	resolvendo o problema certo.
	73
	74	Andrew Morton sugeriu que todo comentário de revisão que não resulte em uma
	75	alteração de código deveria, em vez disso, resultar em um comentário adicional
	76	no próprio código; isso pode ajudar os futuros revisores a evitar as dúvidas
	77	que surgiram da primeira vez.
	78
	79	Um erro fatal é ignorar os comentários de revisão na esperança de que eles
	80	desapareçam. Eles não vão desaparecer. Se você reenviar o código sem ter
	81	respondido aos comentários que recebeu da vez anterior, é provável que descubra
	82	que os seus patches não vão a lugar nenhum.
	83
	84	Por falar em reenviar código: tenha em mente que os revisores não vão se
	85	lembrar de todos os detalhes do código que você enviou da última vez. Portanto,
	86	é sempre uma boa ideia lembrar os revisores dos problemas levantados
	87	anteriormente e de como você lidou com eles; o registro de alterações
	88	(changelog) do patch é um bom lugar para esse tipo de informação. Os revisores
	89	não deveriam ter que vasculhar os arquivos das listas de discussão para se
	90	familiarizarem com o que foi dito na última vez; se você ajudá-los a começar
	91	com o pé direito, eles estarão de melhor humor quando revisitarem o seu código.
	92
	93	E se você tentou fazer tudo certo e as coisas ainda não estão avançando? A
	94	maioria das divergências técnicas pode ser resolvida por meio de discussão,
	95	mas há momentos em que alguém simplesmente precisa tomar uma decisão. Se você
	96	acredita genuinamente que essa decisão está indo contra você de forma errada,
	97	você sempre pode tentar recorrer a uma instância superior. Até o momento em
	98	que este texto foi escrito, essa instância superior costuma ser Andrew Morton.
	99	Andrew goza de um enorme respeito na comunidade de desenvolvimento do kernel;
	100	ele frequentemente consegue destravar uma situação que parece desesperadoramente
	101	bloqueada. Recorrer a Andrew, no entanto, não deve ser feito de ânimo leve e nem
	102	antes que todas as outras alternativas tenham sido esgotadas. E tenha em mente,
	103	é claro, que ele também pode não concordar com você.
	104
	105	O que acontece a seguir
	106	-----------------------
	107
	108	Se um patch for considerado algo bom para ser adicionado ao kernel, e assim
	109	que a maioria dos problemas de revisão tiver sido resolvida, o próximo passo
	110	geralmente é a entrada na árvore de um mantenedor de subsistema. Como isso
	111	funciona varia de um subsistema para o outro; cada mantenedor tem sua própria
	112	maneira de fazer as coisas. Em particular, pode haver mais de uma árvore — uma,
	113	talvez, dedicada a patches planejados para a próxima janela de mesclagem
	114	(merge window), e outra para trabalhos de longo prazo.
	115
	116	Para patches que se aplicam a áreas para quais não há uma árvore de subsistema
	117	óbvia (patches de gerenciamento de memória, por exemplo), a árvore padrão
	118	geralmente acaba sendo a -mm. Patches que afetam múltiplos subsistemas
	119	também podem acabar passando pela árvore -mm.
	120
	121	A inclusão em uma árvore de subsistema pode trazer um nível mais alto de
	122	visibilidade para um patch. Agora, outros desenvolvedores que trabalham com
	123	aquela árvore receberão o patch por padrão. As árvores de subsistemas tipicamente
	124	alimentam a linux-next também, tornando seus conteúdos visíveis para a
	125	comunidade de desenvolvimento como um todo. Neste ponto, há uma boa chance de
	126	você receber mais comentários de um novo conjunto de revisores; esses
	127	comentários precisam ser respondidos da mesma forma que na rodada anterior.
	128
	129	O que também pode acontecer neste ponto, dependendo da natureza do seu patch,
	130	é surgirem conflitos com o trabalho que está sendo feito por outros. No pior
	131	dos casos, conflitos pesados de patches podem fazer com que alguns trabalhos
	132	sejam deixados em segundo plano, para que os patches restantes possam ser
	133	ajustados e mesclados. Outras vezes, a resolução de conflitos envolverá trabalhar
	134	junto a outros desenvolvedores e, possivelmente, mover alguns patches entre
	135	árvores para garantir que tudo se aplique de forma limpa. Este trabalho pode ser
	136	árduo, mas console-se com uma vantagem: antes do surgimento da árvore linux-next,
	137	esses conflitos frequentemente só apareciam durante a janela de mesclagem e
	138	tinham que ser resolvidos às pressas. Agora eles podem ser resolvidos com calma,
	139	antes que a janela de mesclagem se abra.
	140
	141	Um belo dia, se tudo correr bem, você fará login e verá que o seu patch foi
	142	mesclado ao kernel principal (mainline). Parabéns! No entanto, assim que a
	143	comemoração terminar (e você tiver se adicionado ao arquivo MAINTAINERS), vale
	144	a pena lembrar de um pequeno fato importante: o trabalho ainda não acabou. A
	145	mesclagem na árvore principal traz os seus próprios desafios.
	146
	147	Para começar, a visibilidade do seu patch aumentou ainda mais. Pode haver
	148	uma nova rodada de comentários de desenvolvedores que não estavam cientes do
	149	patch antes. Pode ser tentador ignorá-los, já que não há mais nenhuma dúvida
	150	sobre a mesclagem do seu código. No entanto, resista a essa tentação; você
	151	ainda precisa ser receptivo aos desenvolvedores que tiverem dúvidas ou
	152	sugestões.
	153
	154	Mais importante ainda: a inclusão na árvore principal coloca o seu código
	155	nas mãos de um grupo muito maior de testadores. Mesmo que você tenha contribuído
	156	com um driver para um hardware que ainda não está disponível, você se
	157	surpreenderá com a quantidade de pessoas que compilarão seu código em seus
	158	próprios kernels. E, logicamente, onde há testadores, haverá relatórios de
	159	erros (bug reports).
	160
	161	O pior tipo de relatório de erro são as regressões (regressions). Se o seu
	162	patch causar uma regressão, você descobrirá uma quantidade desconfortável de
	163	olhos voltados para você; as regressões precisam ser corrigidas o mais rápido
	164	possível. Se você não estiver disposto ou for incapaz de corrigir a regressão
	165	(e ninguém mais fizer isso por você), seu patch quase certamente será removido
	166	durante o período de estabilização. Além de anular todo o trabalho que você teve
	167	para colocar seu patch na árvore principal, ter um patch removido como resultado
	168	da falha em corrigir uma regressão pode muito bem tornar mais difícil para você
	169	mesclar trabalhos no futuro.
	170
	171	Depois que todas as regressões tiverem sido tratadas, pode haver outros erros
	172	comuns com os quais lidar. O período de estabilização é a sua melhor oportunidade
	173	para corrigir esses problemas e garantir que a estreia do seu código em um
	174	lançamento do kernel principal seja o mais sólida possível. Portanto, por favor,
	175	responda aos relatórios de erros e corrija os problemas, se for viável. É para
	176	isso que serve o período de estabilização; você pode começar a criar novos
	177	patches fantásticos assim que quaisquer problemas com os antigos tiverem sido
	178	resolvidos.
	179
	180	E não se esqueça de que existem outros marcos que também podem gerar relatórios
	181	de erros: o próximo lançamento estável da árvore principal, o momento em que
	182	distribuidores proeminentes adotarem uma versão do kernel que contenha o seu
	183	patch, etc. Continuar respondendo a esses relatórios é uma questão de orgulho
	184	básico pelo seu trabalho. Se isso não for motivação suficiente, contudo, também
	185	vale a pena considerar que a comunidade de desenvolvimento se lembra dos
	186	desenvolvedores que perdem o interesse em seu próprio código após a mesclagem.
	187	A próxima vez que você enviar um patch, eles o avaliarão sob a suposição de
	188	que você não estará por perto para mantê-lo depois.
	189
	190
	191	Outras coisas que podem acontecer
	192	---------------------------------
	193
	194	Um dia, você poderá abrir o seu cliente de e-mail e ver que alguém lhe enviou
	195	um patch para o seu código. Afinal, essa é uma das vantagens de ter o seu
	196	código disponível publicamente. Se você concordar com o patch, poderá encaminhá-lo
	197	para o mantenedor do subsistema (certifique-se de incluir uma linha ``From:``
	198	adequada para que a atribuição de autoria esteja correta e adicione a sua
	199	própria assinatura — signoff) ou enviar uma resposta com um ``Acked-by:``
	200	e deixar que o remetente original o envie para cima.
	201
	202	Se você não concordar com o patch, envie uma resposta educada explicando o
	203	motivo. Se possível, diga ao autor quais alterações precisam ser feitas para
	204	que o patch seja aceitável para você. Existe uma certa resistência em mesclar
	205	patches que sofrem oposição do autor e mantenedor do código, mas isso tem limite.
	206	Se você for visto como alguém que está bloqueando um bom trabalho sem necessidade,
	207	esses patches eventualmente seguirão outro fluxo ao seu redor e entrarão na
	208	árvore principal de qualquer maneira. No kernel do Linux, ninguém tem poder de
	209	veto absoluto sobre nenhum código. Exceto, talvez, o Linus.
	210
	211	Em ocasiões muito raras, você poderá ver algo completamente diferente: outro
	212	desenvolvedor envia uma solução diferente para o seu problema. Nesse ponto,
	213	as chances são de que um dos dois patches não seja mesclado, e o argumento
	214	"o meu chegou primeiro" não é considerado um argumento técnico convincente.
	215	Se o patch de outra pessoa deslocar o seu e entrar na árvore principal, existe
	216	realmente apenas uma maneira de responder: fique satisfeito pelo fato de o seu
	217	problema ter sido resolvido e siga adiante com o seu trabalho. Ter o próprio
	218	trabalho deixado de lado dessa maneira pode ser doloroso e desanimador, mas a
	219	comunidade se lembrará da sua reação muito depois de terem esquecido de quem
	220	foi o patch que realmente foi mesclado.

Documentation/translations/pt_BR/process/7.AdvancedTopics.rst+201−0

@@ -0,0 +1,201 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	Tópicos avançados
	4	=================
	5
	6	Neste ponto, esperamos que você já tenha uma boa noção de como funciona o
	7	processo de desenvolvimento. No entanto, ainda há mais a aprender! Esta seção
	8	cobrirá uma série de tópicos que podem ser úteis para desenvolvedores que
	9	desejam se tornar parte regular do processo de desenvolvimento do kernel Linux.
	10
	11	Gerenciamento de patches com o git
	12	----------------------------------
	13
	14	O uso de controle de versão distribuído para o kernel começou no início de
	15	2002, quando Linus começou a testar o aplicativo proprietário BitKeeper.
	16	Embora o BitKeeper fosse controverso, a abordagem de gerenciamento de versão
	17	de software que ele incorporava certamente não era. O controle de versão
	18	distribuído permitiu uma aceleração imediata do projeto de desenvolvimento do
	19	kernel. Atualmente, existem várias alternativas gratuitas ao BitKeeper. Para o
	20	bem ou para o mal, o projeto do kernel adotou o git como sua ferramenta de
	21	escolha.
	22
	23	Gerenciar patches com o git pode facilitar muito a vida do desenvolvedor,
	24	especialmente à medida que o volume desses patches cresce. O git também tem suas
	25	pontas soltas e apresenta certos riscos; é uma ferramenta jovem e poderosa que
	26	ainda está sendo refinada por seus desenvolvedores. Este documento não tentará
	27	ensinar o leitor a usar o git; isso seria material suficiente para um documento
	28	longo por si só. Em vez disso, o foco aqui será em como o git se encaixa
	29	especificamente no processo de desenvolvimento do kernel. Os desenvolvedores
	30	que desejam se atualizar com o git encontrarão mais informações em:
	31
	32	https://git-scm.com/
	33
	34	https://www.kernel.org/pub/software/scm/git/docs/user-manual.html
	35
	36	e em vários tutoriais encontrados na web.
	37
	38	A primeira ordem do dia é ler os sites acima e obter uma compreensão sólida de
	39	como o git funciona antes de tentar usá-lo para disponibilizar patches para
	40	outros. Um desenvolvedor que utiliza o git deve ser capaz de obter uma cópia do
	41	repositório principal, explorar o histórico de revisões, comitar alterações na
	42	árvore, usar branches, etc. A compreensão das ferramentas do git para a
	43	reescrita de histórico (como o rebase) também é útil. O git vem com sua própria
	44	terminologia e conceitos; um novo usuário do git deve saber sobre refs, remote
	45	branches, o index, fast-forward merges, pushes e pulls, detached HEADs, etc.
	46	Tudo isso pode ser um pouco intimidante no início, mas os conceitos não são tão
	47	difíceis de entender com um pouco de estudo.
	48
	49	Usar o git para gerar patches para submissão por e-mail pode ser um bom exercício
	50	enquanto você se atualiza.
	51
	52	Quando estiver pronto para começar a disponibilizar árvores git para que outros
	53	possam examinar, você, logicamente, precisará de um servidor a partir do qual um
	54	pull possa ser feito. Configurar um servidor desse tipo com o git-daemon é
	55	relativamente simples se você tiver um sistema acessível à internet. Caso
	56	contrário, sites de hospedagem públicos e gratuitos (o GitHub, por exemplo)
	57	estão começando a surgir na rede. Desenvolvedores estabelecidos podem obter uma
	58	conta no kernel.org, mas estas não são fáceis de conseguir; consulte
	59	https://kernel.org/faq/ para mais informações.
	60
	61	O fluxo de trabalho normal do git envolve o uso de muitas branches. Cada linha
	62	de desenvolvimento pode ser separada em uma "topic branch" distinta e mantida de
	63	forma independente. Branches no git são baratas, não há razão para não fazer um
	64	uso livre delas. E, em qualquer caso, você não deve fazer o seu desenvolvimento
	65	em nenhuma branch a partir da qual pretenda pedir para que outros deem pull.
	66	Branches disponíveis publicamente devem ser criadas com cuidado; mescle patches
	67	de branches de desenvolvimento quando eles estiverem em sua forma final e prontos
	68	para seguir em frente — não antes.
	69
	70	O git fornece algumas ferramentas poderosas que podem permitir que você
	71	reescreva o seu histórico de desenvolvimento. Um patch inconveniente (um que
	72	quebre o bisection, por exemplo, ou que tenha algum outro tipo de bug óbvio)
	73	pode ser corrigido localmente ou feito desaparecer completamente do histórico.
	74	Uma série de patches pode ser reescrita como se tivesse sido escrita no topo da
	75	linha principal de hoje, mesmo que você esteja trabalhando nela há meses. As
	76	alterações podem ser movidas de forma transparente de uma branch para outra. E
	77	assim por diante. O uso criterioso da capacidade do git de revisar o histórico
	78	pode ajudar na criação de conjuntos de patches limpos e com menos problemas.
	79
	80	O uso excessivo dessa capacidade pode levar a outros problemas, no entanto, além
	81	de uma simples obsessão pela criação do histórico de projeto perfeito. Reescrever
	82	o histórico reescreverá as alterações contidas nele, transformando uma árvore do
	83	kernel testada (assim se espera) em uma não testada. Mas, além disso, os
	84	desenvolvedores não podem colaborar facilmente se não tiverem uma visão
	85	compartilhada do histórico do projeto; se você reescrever o histórico que outros
	86	desenvolvedores já deram pull em seus repositórios, tornará a vida deles muito
	87	mais difícil. Portanto, uma regra prática simples se aplica aqui: o histórico
	88	que foi exportado para terceiros deve ser visto geralmente como imutável dali em
	89	diante.
	90
	91	Sendo assim, uma vez que você faz o push de um conjunto de alterações para o seu
	92	servidor disponível publicamente, essas alterações não devem ser reescritas. O
	93	git tentará aplicar essa regra se você tentar dar push em alterações que não
	94	resultem em um fast-forward merge (ou seja, alterações que não compartilham o
	95	mesmo histórico). É possível anular essa verificação, e pode haver momentos em
	96	que seja necessário reescrever uma árvore exportada. Mover changesets entre
	97	árvores para evitar conflitos na linux-next é um exemplo. No entanto, tais ações
	98	devem ser raras. Esta é uma das razões pelas quais o desenvolvimento deve ser
	99	feito em branches privadas (que podem ser reescritas, se necessário) e apenas
	100	movido para branches públicas quando estiver em um estado razoavelmente avançado.
	101
	102	À medida que a linha principal (ou outra árvore na qual um conjunto de
	103	alterações se baseia) avança, é tentador fazer o merge com essa árvore para
	104	permanecer na vanguarda. Para uma branch privada, o rebasing pode ser uma maneira
	105	fácil de acompanhar outra árvore, mas o rebasing não é uma opção uma vez que uma
	106	árvore é exportada para o mundo. Quando isso acontece, um merge completo deve
	107	ser feito. Fazer merges ocasionalmente faz todo o sentido, mas merges excessivamente
	108	frequentes podem poluir o histórico desnecessariamente. A técnica sugerida neste
	109	caso é fazer merges raramente, e geralmente apenas em release points específicos
	110	(como um lançamento -rc da linha principal). Se você estiver inseguro sobre
	111	mudanças específicas, sempre poderá realizar merges de teste em uma branch
	112	privada. A ferramenta "rerere" do git pode ser útil nessas situações; ela se
	113	lembra de como os conflitos de merge foram resolvidos para que você não precise
	114	fazer o mesmo trabalho duas vezes.
	115
	116	Uma das maiores reclamações recorrentes sobre ferramentas como o git é esta: o
	117	movimento em massa de patches de um repositório para outro torna fácil a
	118	inclusão de mudanças desaconselháveis que entram na linha principal abaixo do
	119	radar de revisão. Os desenvolvedores do kernel costumam ficar descontentes quando
	120	veem esse tipo de coisa acontecer; disponibilizar uma árvore git com patches não
	121	revisados ou fora do tópico pode afetar a sua capacidade de ter suas árvores
	122	puxadas no futuro. Citando Linus:
	123
	124	::
	125
	126	Você pode me enviar patches, mas para eu puxar um patch git de você, eu
	127	preciso saber que você sabe o que está fazendo, e preciso ser capaz de
	128	confiar nas coisas sem ter que ir lá e verificar cada mudança
	129	individualmente à mão.
	130
	131	(https://lwn.net/Articles/224135/).
	132
	133	Para evitar esse tipo de situação, certifique-se de que todos os patches
	134	dentro de uma determinada branch permaneçam estritamente alinhados ao tópico
	135	associado; uma branch de "correções de drivers" não deveria fazer alterações no
	136	código central de gerenciamento de memória. E, acima de tudo, não use uma árvore
	137	git para burlar o processo de revisão. Publique ocasionalmente um resumo da
	138	árvore na lista de discussão relevante e, quando for o momento certo, solicite
	139	que a árvore seja incluída na linux-next.
	140
	141	Se e quando outros começarem a enviar patches para inclusão em sua árvore, não
	142	se esqueça de revisá-los. Certifique-se também de manter as informações corretas
	143	de autoria; a ferramenta "am" do git faz o melhor que pode a esse respeito, mas
	144	você pode ter que adicionar uma linha "From:" ao patch se ele tiver sido
	145	retransmitido a você por terceiros.
	146
	147	Ao solicitar um pull, certifique-se de fornecer todas as informações
	148	relevantes: onde está a sua árvore, qual branch deve ser puxada e quais
	149	alterações resultarão do pull. O comando git request-pull pode ser útil a esse
	150	respeito; ele formatará a solicitação da maneira que outros desenvolvedores
	151	esperam e também verificará se você se lembrou de dar push nessas alterações
	152	para o servidor público.
	153
	154
	155	Revisão de patches
	156	------------------
	157
	158	Alguns leitores certamente objetarão a inclusão desta seção em "tópicos
	159	avançados" sob o argumento de que mesmo desenvolvedores iniciantes do kernel
	160	deveriam estar revisando patches. É certamente verdade que não há melhor maneira
	161	de aprender a programar no ambiente do kernel do que examinando o código
	162	postado por outros. Além disso, revisores estão sempre em falta; ao examinar o
	163	código, você pode fazer uma contribuição significativa para o processo como um
	164	todo.
	165
	166	Revisar código pode ser uma perspectiva intimidadora, especialmente para um novo
	167	desenvolvedor do kernel que pode se sentir nervoso em questionar — em público —
	168	um código que foi postado por aqueles com mais experiência. No entanto, mesmo o
	169	código escrito pelos desenvolvedores mais experientes pode ser aprimorado. Talvez
	170	o melhor conselho para revisores (todos os revisores) seja este: formule os
	171	comentários de revisão como perguntas em vez de críticas. Perguntar "como o lock
	172	é liberado neste caminho?" sempre funcionará melhor do que afirmar "o bloqueio
	173	aqui está errado."
	174
	175	Outra técnica útil em caso de desacordo é pedir que outros se manifestem. Se uma
	176	discussão chegar a um impasse após algumas trocas de mensagens, peça a opinião
	177	de outros revisores ou mantenedores. Frequentemente, aqueles que concordam com
	178	um revisor permanecem em silêncio, a menos que sejam solicitados. A opinião de
	179	múltiplas pessoas carrega exponencialmente mais peso.
	180
	181	Diferentes desenvolvedores revisarão o código sob diferentes pontos de vista.
	182	Alguns estão preocupados principalmente com o estilo de codificação e se as
	183	linhas de código possuem espaços em branco no final (trailing white space).
	184	Outros se concentrarão principalmente em saber se a alteração implementada pelo
	185	patch como um todo é algo bom para o kernel ou não. Ainda assim, outros buscarão
	186	por bloqueios problemáticos, uso excessivo de pilha (stack usage), possíveis
	187	problemas de segurança, duplicação de código encontrado em outros lugares,
	188	documentação adequada, efeitos adversos no desempenho, alterações na ABI do
	189	espaço do usuário (user-space ABI), etc. Todos os tipos de revisão, se levarem a
	190	um código melhor entrando no kernel, são bem-vindos e valem a pena.
	191
	192	Não há exigência estrita para o uso de tags específicas como ``Reviewed-by``. Na
	193	verdade, revisões em texto simples são mais informativas e incentivadas mesmo
	194	quando uma tag é fornecida, por exemplo: "Analisei os aspectos A, B e C deste
	195	envio e tudo me parece correto." Alguma forma de mensagem de revisão ou resposta
	196	é obviamente necessária, caso contrário, os mantenedores não saberão que o
	197	revisor sequer examinou o patch!
	198
	199	Por último, mas não menos importante, a revisão de patches pode se tornar um
	200	processo negativo, focado em apontar problemas. Por favor, reserve um elogio de
	201	vez em quando, particularmente para os novatos!

Documentation/translations/pt_BR/process/8.Conclusion.rst+73−0

@@ -0,0 +1,73 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	Para mais informações
	4	=====================
	5
	6	Há inúmeras fontes de informação sobre o desenvolvimento do kernel Linux e
	7	tópicos relacionados. A primeira delas sempre será o diretório Documentation
	8	encontrado na distribuição do código-fonte do kernel. Comece com o arquivo de
	9	nível superior :ref:`process/howto.rst <process_howto>`; leia também
	10	:ref:`process/submitting-patches.rst <submittingpatches>`. Muitas APIs internas
	11	do kernel são documentadas usando o mecanismo kerneldoc; "make htmldocs" ou
	12	"make pdfdocs" podem ser usados para gerar esses documentos em formato HTML ou
	13	PDF (embora a versão do TeX fornecida por algumas distribuições esbarre em
	14	limites internos e falhe em processar os documentos corretamente).
	15
	16	Vários sites discutem o desenvolvimento do kernel em todos os níveis de
	17	detalhes. O autor gostaria de sugerir humildemente o https://lwn.net/ como uma
	18	fonte; informações sobre muitos tópicos específicos do kernel podem ser
	19	encontradas através do índice do kernel do LWN em:
	20
	21	https://lwn.net/Kernel/Index/
	22
	23	Além disso, um recurso valioso para os desenvolvedores do kernel é:
	24	https://kernelnewbies.org/
	25
	26	E, claro, não se deve esquecer o https://kernel.org/, o local definitivo
	27	para informações sobre os lançamentos do kernel.
	28
	29	Há uma série de livros sobre o desenvolvimento do kernel:
	30
	31	Linux Device Drivers, 3rd Edition (Jonathan Corbet, Alessandro
	32	Rubini, and Greg Kroah-Hartman). Online at
	33	https://lwn.net/Kernel/LDD3/.
	34
	35	Linux Kernel Development (Robert Love).
	36
	37	Understanding the Linux Kernel (Daniel Bovet and Marco Cesati).
	38
	39	Todos esses livros, no entanto, sofrem de um defeito comum: eles tendem a estar
	40	um pouco obsoletos quando chegam às prateleiras, e já estão nelas há algum
	41	tempo. Ainda assim, há uma boa quantidade de informações úteis a serem
	42	encontradas ali.
	43
	44	A documentação para o git pode ser encontrada em:
	45
	46	https://www.kernel.org/pub/software/scm/git/docs/
	47
	48	https://www.kernel.org/pub/software/scm/git/docs/user-manual.html
	49
	50
	51	Conclusão
	52	=========
	53
	54	Parabéns a qualquer pessoa que tenha chegado ao fim deste documento longo e
	55	detalhado. Esperamos que ele tenha fornecido uma compreensão útil de como o
	56	kernel Linux é desenvolvido e de como você pode participar desse processo.
	57
	58	No fim das contas, é a participação que importa. Qualquer projeto de software
	59	de código aberto não é nada mais do que a soma do que seus colaboradores
	60	dedicam a ele. O kernel Linux progrediu tão rápido e tão bem porque foi ajudado
	61	por um grupo impressionantemente grande de desenvolvedores, todos trabalhando
	62	para torná-lo melhor. O kernel é um exemplo primordial do que pode ser feito
	63	quando milhares de pessoas trabalham juntas em direção a um objetivo comum.
	64
	65	O kernel, no entanto, sempre pode se beneficiar de uma base maior de
	66	desenvolvedores. Há sempre mais trabalho a fazer. Mas, de forma igualmente
	67	importante, a maioria dos outros participantes do ecossistema Linux pode se
	68	beneficiar ao contribuir para o kernel. Colocar o código na linha principal
	69	(mainline) é a chave para uma maior qualidade de código, menores custos de
	70	manutenção e distribuição, um nível mais alto de influência sobre a direção do
	71	desenvolvimento do kernel e muito mais. É uma situação em que todos os
	72	envolvidos ganham. Abra o seu editor e venha se juntar a nós; você será mais do
	73	que bem-vindo.

Documentation/translations/pt_BR/process/adding-syscalls.rst+700−0

@@ -0,0 +1,700 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	=======================================
	4	Adicionando uma Nova Chamada de Sistema
	5	=======================================
	6
	7	Este documento descreve o que está envolvido na adição de uma nova chamada de
	8	sistema (system call) ao kernel Linux, indo além dos conselhos normais de
	9	submissão em
	10	:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
	11
	12
	13	Alternativas às Chamadas de Sistema
	14	-----------------------------------
	15
	16	A primeira coisa a se considerar ao adicionar uma nova chamada de sistema é se
	17	uma das alternativas poderia ser mais adequada. Embora as chamadas de sistema
	18	sejam os pontos de interação mais tradicionais e óbvios entre o espaço do
	19	usuário (userspace) e o kernel, existem outras possibilidades -- escolha o que
	20	melhor se adapta à sua interface.
	21
	22	- Se as operações envolvidas puderem ser moldadas para se parecerem com um
	23	objeto do tipo arquivo, pode fazer mais sentido criar um novo sistema de
	24	arquivos ou dispositivo. Isso também torna mais fácil encapsular a nova
	25	funcionalidade em um módulo de kernel, em vez de exigir que ela seja
	26	incorporada ao kernel principal.
	27
	28	- Se a nova funcionalidade envolver operações em que o kernel notifica o
	29	espaço do usuário de que algo aconteceu, retornar um novo descritor de
	30	arquivo (file descriptor) para o objeto relevante permite que o espaço
	31	do usuário use ``poll``/``select``/``epoll`` para receber essa
	32	notificação.
	33	- No entanto, as operações que não se mapeiam para operações do tipo
	34	:manpage:`read(2)`/:manpage:`write(2)` precisam ser implementadas como
	35	requisições :manpage:`ioctl(2)`, o que pode levar a uma API um tanto
	36	quanto opaca.
	37
	38	- Se você estiver apenas expondo informações do sistema em tempo de execução,
	39	um novo nó no sysfs (veja ``Documentation/filesystems/sysfs.rst``) ou no
	40	sistema de arquivos ``/proc`` pode ser mais apropriado. No entanto, o acesso
	41	a esses mecanismos exige que o sistema de arquivos relevante esteja montado,
	42	o que pode não ser sempre o caso (por exemplo, em um ambiente com namespaces,
	43	sandboxed ou chrooted). Evite adicionar qualquer API ao debugfs, pois este
	44	não é considerado uma interface de "produção" para o espaço do usuário.
	45	- Se a operação for específica para um arquivo ou descritor de arquivo de um
	46	determinado objeto, então uma opção de comando adicional para :manpage:`fcntl(2)`
	47	pode ser mais adequada. Contudo, o :manpage:`fcntl(2)` é uma chamada de sistema
	48	de multiplexação que oculta muita complexidade, portanto, esta opção é melhor
	49	para quando a nova função for intimamente análoga à funcionalidade existente
	50	do :manpage:`fcntl(2)`, ou se a nova funcionalidade for muito simples (por
	51	exemplo, obter/definir uma flag simples relacionada a um descritor de arquivo).
	52	- Se a operação for específica para uma tarefa (task) ou processo específico,
	53	então uma opção de comando adicional para :manpage:`prctl(2)` pode ser mais
	54	apropriada. Assim como no caso do :manpage:`fcntl(2)`, esta chamada de sistema
	55	é um multiplexador complicado, sendo melhor reservá-la para análogos próximos
	56	de comandos ``prctl()`` existentes ou para obter/definir uma flag simples
	57	relacionada a um processo.
	58
	59
	60	Projetando a API: Planejando a Extensibilidade
	61	----------------------------------------------
	62
	63	Uma nova chamada de sistema faz parte da API do kernel e deve ser suportada
	64	indefinidamente. Sendo assim, é uma excelente ideia discutir explicitamente a
	65	interface na lista de discussão do kernel (LKML), e é crucial planejar extensões
	66	futuras para essa interface.
	67
	68	(A tabela de chamadas de sistema está repleta de exemplos históricos onde isso
	69	não foi feito, juntamente com as respectivas chamadas de sistema de acompanhamento
	70	-- ``eventfd``/``eventfd2``, ``dup2``/``dup3``, ``inotify_init``/``inotify_init1``,
	71	``pipe``/``pipe2``, ``renameat``/``renameat2`` -- portanto, aprenda com a história
	72	do kernel e planeje as extensões desde o início.)
	73
	74	Para chamadas de sistema mais simples que recebem apenas alguns argumentos, a
	75	maneira preferencial de permitir extensibilidade futura é incluir um argumento de
	76	flags na chamada de sistema. Para garantir que os programas do espaço do usuário
	77	possam usar flags de forma segura entre diferentes versões do kernel, verifique
	78	se o valor de flags contém qualquer flag desconhecida e rejeite a chamada de
	79	sistema (com ``EINVAL``) se contiver::
	80
	81	if (flags & ~(THING_FLAG1 \| THING_FLAG2 \| THING_FLAG3))
	82	return -EINVAL;
	83
	84	(Se nenhum valor de flag for utilizado ainda, verifique se o argumento de flags
	85	é zero.)
	86
	87	Para chamadas de sistema mais sofisticadas que envolvem um número maior de
	88	argumentos, prefere-se encapsular a maioria dos argumentos em uma estrutura
	89	(struct) que é passada por meio de um ponteiro. Esse tipo de estrutura pode
	90	lidar com extensões futuras incluindo um argumento de tamanho (size) na própria
	91	estrutura::
	92
	93	struct xyzzy_params {
	94	u32 size; /* o espaço do usuário define p->size = sizeof(struct xyzzy_params) */
	95	u32 param_1;
	96	u64 param_2;
	97	u64 param_3;
	98	};
	99
	100	Desde que qualquer campo adicionado subsequentemente, digamos ``param_4``, seja
	101	projetado de forma que um valor zero mantenha o comportamento anterior, isso
	102	permitirá lidar com a divergência de versões em ambas as direções:
	103
	104	- Para lidar com um programa de espaço do usuário mais novo chamando um kernel
	105	mais antigo, o código do kernel deve verificar se qualquer memória além do
	106	tamanho da estrutura que ele espera está zerada (efetivamente verificando
	107	se ``param_4 == 0``).
	108	- Para lidar com um programa de espaço do usuário mais antigo chamando um kernel
	109	mais novo, o código do kernel pode preencher com zero (zero-extend) a
	110	instância menor da estrutura (efetivamente definindo ``param_4 = 0``).
	111
	112	Veja :manpage:`perf_event_open(2)` e a função ``perf_copy_attr()`` (em
	113	``kernel/events/core.c``) para um exemplo desta abordagem.
	114
	115
	116	Projetando a API: Outras Considerações
	117	--------------------------------------
	118
	119	Se a sua nova chamada de sistema permitir que o espaço do usuário se refira a
	120	um objeto do kernel, ela deve usar um descritor de arquivo (file descriptor)
	121	como o handle (identificador) para esse objeto -- não invente um novo tipo de
	122	handle de objeto para o espaço do usuário quando o kernel já possui mecanismos
	123	e semânticas bem definidas para o uso de descritores de arquivo.
	124
	125	Se a sua nova chamada de sistema (2) de fato retornar un novo descritor de
	126	arquivo, então o argumento de flags deve incluir um valor que seja equivalente
	127	a definir ``O_CLOEXEC`` no novo FD. Isso torna possível para o espaço do usuário
	128	fechar a janela de tempo entre a chamada ``()`` e a execução de
	129	``fcntl(fd, F_SETFD, FD_CLOEXEC)``, onde um ``fork()`` e ``execve()`` inesperados
	130	em outra thread poderiam vazar um descritor para o programa executado. (Contudo,
	131	resista à tentação de reutilizar o valor real da constante ``O_CLOEXEC``, pois
	132	ela é específica de cada arquitetura e faz parte de um espaço de numeração de
	133	flags ``O_*`` que está bastante cheio.)
	134
	135	Se a sua chamada de sistema retornar um novo descritor de arquivo, você também
	136	deve considerar o que significa usar a família de chamadas de sistema
	137	:manpage:`poll(2)` nesse descritor de arquivo. Tornar um descritor de arquivo
	138	pronto para leitura ou escrita é a maneira normal de o kernel indicar ao espaço
	139	do usuário que um evento ocorreu no objeto correspondente do kernel.
	140
	141	Se a sua nova chamada de sistema (2) envolver um argumento de nome de arquivo
	142	(filename)::
	143
	144	int sys_xyzzy(const char __user *path, ..., unsigned int flags);
	145
	146	você também deve considerar se uma versão xyzzyat(2) seria mais apropriada::
	147
	148	int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags);
	149
	150	Isso permite maior flexibilidade para a forma como o espaço do usuário especifica
	151	o arquivo em questão; em particular, permite que o espaço do usuário solicite a
	152	funcionalidade para um descritor de arquivo já aberto usando a flag
	153	``AT_EMPTY_PATH``, fornecendo efetivamente uma operação fxyzzy(3) de graça::
	154
	155	- xyzzyat(AT_FDCWD, path, ..., 0) é equivalente a (path,...)
	156	- xyzzyat(fd, "", ..., AT_EMPTY_PATH) é equivalente a fxyzzy(fd, ...)
	157
	158	(Para mais detalhes sobre a justificativa das chamadas \*at(), veja a página de
	159	manual :manpage:`openat(2)`; para um exemplo de AT_EMPTY_PATH, veja a página de
	160	manual :manpage:`fstatat(2)`.)
	161
	162	Se a sua nova chamada de sistema (2) envolver um parâmetro que descreve um
	163	deslocamento (offset) dentro de um arquivo, mude o seu tipo para ``loff_t`` para
	164	que offsets de 64 bits possam ser suportados mesmo em arquiteturas de 32 bits.
	165
	166	Se a sua nova chamada de sistema (2) envolver funcionalidades privilegiadas,
	167	ela precisa ser governada pelo bit de capacidade (capability) do Linux apropriado
	168	(verificado com uma chamada a ``capable()``), conforme descrito na página de
	169	manual :manpage:`capabilities(7)`. Escolha um bit de capacidade existente que governe
	170	funcionalidades relacionadas, mas tente evitar combinar muitas funções que tenham
	171	apenas uma vaga relação sob o mesmo bit, pois isso vai contra o propósito das
	172	capabilities de dividir o poder do root. Em particular, evite adicionar novos
	173	usos para a capacidade ``CAP_SYS_ADMIN``, que já é excessivamente generalista.
	174
	175	Se a sua nova chamada de sistema (2) manipular um processo diferente do
	176	processo que a chamou, ela deve ser restrita (usando uma chamada a
	177	``ptrace_may_access()``) para que apenas um processo chamador com as mesmas
	178	permissões do processo alvo, ou com as capacidades necessárias, possa manipular
	179	o processo alvo.
	180
	181	Finalmente, esteja ciente de que algumas arquiteturas não-x86 lidam melhor se os
	182	parâmetros da chamada de sistema que são explicitamente de 64 bits caírem em
	183	argumentos de numeração ímpar (ou seja, parâmetro 1, 3, 5), para permitir o uso
	184	de pares contíguos de registradores de 32 bits. (Esta preocupação não se aplica
	185	se os argumentos fizerem parte de uma estrutura que é passada por meio de um
	186	ponteiro.)
	187
	188
	189	Propondo a API
	190	--------------
	191
	192	Para tornar as novas chamadas de sistema fáceis de revisar, é melhor dividir o
	193	conjunto de patches (patchset) em blocos separados. Estes devem incluir, pelo
	194	menos, os seguintes itens como commits distintos (cada um dos quais é descrito
	195	mais adiante):
	196
	197	- A implementação central da chamada de sistema, juntamente com protótipos,
	198	numeração genérica, alterações no Kconfig e a implementação de stub de realinhamento (fallback stub).
	199	- A fiação (wiring up) da nova chamada de sistema para uma arquitetura em
	200	particular, geralmente x86 (incluindo todas as variantes x86_64, x86_32 e x32).
	201	- Uma demonstração do uso da nova chamada de sistema no espaço do usuário por
	202	meio de um selftest em ``tools/testing/selftests/``.
	203	- Um rascunho da página de manual (man-page) para a nova chamada de sistema,
	204	seja como texto simples na carta de apresentação (cover letter) ou como um
	205	patch para o repositório (separado) de man-pages.
	206
	207	Novas propostas de chamadas de sistema, como qualquer alteração na API do
	208	kernel, devem sempre ser enviadas com cópia (cc'ed) para linux-api@vger.kernel.org.
	209
	210
	211	Implementação Genérica de Chamadas de Sistema
	212	---------------------------------------------
	213
	214	O ponto de entrada principal para a sua nova chamada de sistema (2) será chamado
	215	de ``sys_xyzzy()``, mas você deve adicionar esse ponto de entrada com a macro
	216	``SYSCALL_DEFINEn()`` apropriada, em vez de fazer isso explicitamente. O 'n'
	217	indica o número de argumentos da chamada de sistema, e a macro recebe o nome da
	218	chamada de sistema seguido pelos pares (tipo, nome) para os parâmetros como
	219	argumentos. O uso dessa macro permite que os metadados sobre a nova chamada de
	220	sistema fiquem disponíveis para outras ferramentas.
	221
	222	O novo ponto de entrada também precisa de um protótipo de função correspondente
	223	em ``include/linux/syscalls.h``, marcado como asmlinkage para corresponder à
	224	maneira como as chamadas de sistema são invocadas::
	225
	226	asmlinkage long sys_xyzzy(...);
	227
	228	Algumas arquiteturas (por exemplo, x86) possuem suas próprias tabelas de syscall
	229	específicas da arquitetura, mas várias outras arquiteturas compartilham uma tabela
	230	de syscall genérica. Adicione a sua nova chamada de sistema à lista genérica
	231	adicionando uma entrada na lista em ``include/uapi/asm-generic/unistd.h``::
	232
	233	#define __NR_xyzzy 292
	234	__SYSCALL(__NR_xyzzy, sys_xyzzy)
	235
	236	Atualize também a contagem de __NR_syscalls para refletir a chamada de sistema
	237	adicional, e observe que se múltiplas novas chamadas de sistema forem adicionadas
	238	na mesma janela de mesclagem (merge window), o número da sua nova syscall poderá
	239	ser ajustado para resolver conflitos.
	240
	241	O arquivo ``kernel/sys_ni.c`` fornece uma implementação de stub de fallback para
	242	cada chamada de sistema, retornando ``-ENOSYS``. Adicione a sua nova chamada de
	243	sistema aqui também::
	244
	245	COND_SYSCALL(sys_xyzzy);
	246
	247	A sua nova funcionalidade de kernel, e a chamada de sistema que a controla, deve
	248	normalmente ser opcional, portanto adicione uma opção ``CONFIG`` (tipicamente em
	249	``init/Kconfig``) para ela. Como de costume para novas opções ``CONFIG``:
	250
	251	- Inclua uma descrição da nova funcionalidade e da chamada de sistema controlada
	252	pela opção.
	253	- Faça a opção depender de EXPERT se ela deve ser ocultada dos usuários normais.
	254	- Faça com que quaisquer novos arquivos de código-fonte que implementem a função
	255	sejam dependentes da opção CONFIG no Makefile (por exemplo,
	256	``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.o``).
	257	- Verifique duas vezes se o kernel ainda compila com a nova opção CONFIG desativada.
	258
	259	Para resumir, você precisa de um commit que inclua:
	260
	261	- Opção ``CONFIG`` para a nova função, normalmente em ``init/Kconfig``
	262	- ``SYSCALL_DEFINEn(, ...)`` para o ponto de entrada
	263	- Protótipo correspondente em ``include/linux/syscalls.h``
	264	- Entrada na tabela genérica em ``include/uapi/asm-generic/unistd.h``
	265	- Stub de fallback em ``kernel/sys_ni.c``
	266
	267
	268	.. _pt_BR_syscall_generic_6_11:
	269
	270	Desde a versão 6.11
	271	~~~~~~~~~~~~~~~~~~~
	272
	273	A partir da versão 6.11 do kernel, a implementação de chamadas de sistema
	274	genéricas para as seguintes arquiteturas não requer mais modificações em
	275	``include/uapi/asm-generic/unistd.h``:
	276
	277	- arc
	278	- arm64
	279	- csky
	280	- hexagon
	281	- loongarch
	282	- nios2
	283	- openrisc
	284	- riscv
	285
	286	Em vez disso, você precisa atualizar ``scripts/syscall.tbl`` e, se aplicável,
	287	ajustar ``arch/*/kernel/Makefile.syscalls``.
	288
	289	Como o ``scripts/syscall.tbl`` serve como uma tabela de syscall comum para
	290	múltiplas arquiteturas, uma nova entrada é necessária nesta tabela::
	291
	292	468 common sys_xyzzy
	293
	294	Note que adicionar uma entrada ao ``scripts/syscall.tbl`` com a ABI "common"
	295	também afeta todas as arquiteturas que compartilham essa tabela. Para alterações
	296	mais limitadas ou específicas de uma arquitetura, considere usar uma ABI
	297	específica da arquitetura ou definir uma nova.
	298
	299	Se uma nova ABI, digamos ``xyz``, for introduzida, as atualizações
	300	correspondentes também devem ser feitas em ``arch/*/kernel/Makefile.syscalls``::
	301
	302	syscall_abis_{32,64} += xyz (...)
	303
	304	Para resumir, você precisa de um commit que inclua:
	305
	306	- Opção ``CONFIG`` para a nova função, normalmente em ``init/Kconfig``
	307	- ``SYSCALL_DEFINEn(, ...)`` para o ponto de entrada
	308	- Protótipo correspondente em ``include/linux/syscalls.h``
	309	- Nova entrada em ``scripts/syscall.tbl``
	310	- (Se necessário) Atualizações de Makefile em ``arch/*/kernel/Makefile.syscalls``
	311	- Stub de fallback em ``kernel/sys_ni.c``
	312
	313
	314	Implementação de Chamadas de Sistema em x86
	315	-------------------------------------------
	316
	317	Para interligar (wire up) a sua nova chamada de sistema nas plataformas x86, você
	318	precisa atualizar as tabelas mestras de syscall. Assumindo que a sua nova chamada
	319	de sistema não seja especial de alguma forma (veja abaixo), isso envolve uma
	320	entrada "common" (para x86_64 e x32) em
	321	``arch/x86/entry/syscalls/syscall_64.tbl``::
	322
	323	333 common sys_xyzzy
	324
	325	e uma entrada "i386" em ``arch/x86/entry/syscalls/syscall_32.tbl``::
	326
	327	380 i386 sys_xyzzy
	328
	329	Novamente, esses números estão sujeitos a alterações caso ocorram conflitos na
	330	janela de mesclagem (merge window) relevante.
	331
	332	Chamadas de Sistema de Compatibilidade (Genéricas)
	333	--------------------------------------------------
	334
	335	Para a maioria das chamadas de sistema, a mesma implementação de 64 bits pode
	336	ser invocada mesmo quando o programa do espaço do usuário é, ele próprio, de 32
	337	bits; mesmo se os parâmetros da chamada de sistema incluírem um ponteiro
	338	explícito, isso é tratado de forma transparente.
	339
	340	No entanto, existem algumas situações em que uma camada de compatibilidade
	341	(compatibility layer) é necessária para lidar com as diferenças de tamanho entre
	342	32 bits e 64 bits.
	343
	344	A primeira é se o kernel de 64 bits também suportar programas de espaço do
	345	usuário de 32 bits e, portanto, precisar analisar áreas de memória
	346	(``__user``) que poderiam conter valores de 32 bits ou 64 bits. Em particular,
	347	isso é necessário sempre que um argumento de chamada de sistema for:
	348
	349	- um ponteiro para um ponteiro
	350	- um ponteiro para uma struct que contém um ponteiro (por exemplo,
	351	``struct iovec __user *``)
	352	- um ponteiro para um tipo integral de tamanho variável (``time_t``,
	353	``off_t``, ``long``, ...)
	354	- um ponteiro para uma struct que contém um tipo integral de tamanho variável.
	355
	356	A segunda situação que requer uma camada de compatibilidade é se um dos
	357	argumentos da chamada de sistema tiver um tipo que é explicitamente de 64 bits,
	358	mesmo em uma arquitetura de 32 bits, por exemplo, ``loff_t`` ou ``__u64``. Neste
	359	caso, um valor que chega ao kernel de 64 bits vindo de uma aplicação de 32 bits
	360	será dividido em dois valores de 32 bits, que precisarão ser remontados na
	361	camada de compatibilidade.
	362
	363	(Note que um argumento de chamada de sistema que seja um ponteiro para um tipo
	364	explícito de 64 bits não precisa de uma camada de compatibilidade; por
	365	exemplo, os argumentos do :manpage:`splice(2)` do tipo ``loff_t __user *`` não
	366	disparam a necessidade de uma chamada de sistema ``compat_``.)
	367
	368	A versão de compatibilidade da chamada de sistema é chamada de
	369	``compat_sys_xyzzy()`` e é adicionada com a macro ``COMPAT_SYSCALL_DEFINEn()``,
	370	de forma análoga à macro SYSCALL_DEFINEn. Esta versão da implementação roda como
	371	parte de um kernel de 64 bits, mas espera receber valores de parâmetros de 32
	372	bits e faz o que for necessário para lidar com eles. (Tipicamente, a versão
	373	``compat_sys_`` converte os valores para versões de 64 bits e chama a versão
	374	``sys_``, ou ambas chamam uma função interna comum de implementação).
	375
	376	O ponto de entrada compat também precisa de um protótipo de função
	377	correspondente em ``include/linux/compat.h``, marcado como asmlinkage para
	378	corresponder à maneira como as chamadas de sistema são invocadas::
	379
	380	asmlinkage long compat_sys_xyzzy(...);
	381
	382	Se a chamada de sistema envolver uma estrutura cujo layout seja diferente em
	383	sistemas de 32 bits e 64 bits, digamos ``struct xyzzy_args``, então o arquivo de
	384	cabeçalho ``include/linux/compat.h`` também deve incluir uma versão compat da
	385	estrutura (``struct compat_xyzzy_args``), onde cada campo de tamanho variável
	386	tenha o tipo ``compat_`` correspondente ao tipo na ``struct xyzzy_args``. A
	387	rotina ``compat_sys_xyzzy()`` pode então usar essa estrutura ``compat_`` para
	388	analisar os argumentos vindos de uma invocação de 32 bits.
	389
	390	Por exemplo, se existirem os campos::
	391
	392	struct xyzzy_args {
	393	const char __user *ptr;
	394	__kernel_long_t varying_val;
	395	u64 fixed_val;
	396	/* ... */
	397	};
	398
	399	na struct xyzzy_args, então a struct compat_xyzzy_args teria::
	400
	401	struct compat_xyzzy_args {
	402	compat_uptr_t ptr;
	403	compat_long_t varying_val;
	404	u64 fixed_val;
	405	/* ... */
	406	};
	407
	408	A lista genérica de chamadas de sistema também precisa de ajustes para permitir
	409	a versão compat; a entrada em ``include/uapi/asm-generic/unistd.h`` deve usar
	410	``__SC_COMP`` em vez de ``__SYSCALL``::
	411
	412	#define __NR_xyzzy 292
	413	__SC_COMP(__NR_xyzzy, sys_xyzzy, compat_sys_xyzzy)
	414
	415	Para resumir, você precisa de:
	416
	417	- uma macro ``COMPAT_SYSCALL_DEFINEn(, ...)`` para o ponto de entrada compat
	418	- protótipo correspondente em ``include/linux/compat.h``
	419	- (se necessário) struct de mapeamento de 32 bits em ``include/linux/compat.h``
	420	- instância de ``__SC_COMP``, e não de ``__SYSCALL``, em
	421	``include/uapi/asm-generic/unistd.h``
	422
	423	Desde a versão 6.11
	424	~~~~~~~~~~~~~~~~~~~
	425
	426	Isso se aplica a todas as arquiteturas listadas em
	427	:ref:`Desde a versão 6.11<pt_BR_syscall_generic_6_11>` sob "Implementação Genérica de
	428	Chamadas de Sistema", exceto arm64. Veja
	429	:ref:`Chamadas de Sistema de Compatibilidade (arm64)<pt_BR_compat_arm64>` para mais
	430	informações.
	431
	432	Você precisa estender a entrada em ``scripts/syscall.tbl`` com uma coluna extra
	433	para indicar que um programa de espaço do usuário de 32 bits rodando em um
	434	kernel de 64 bits deve atingir o ponto de entrada compat::
	435
	436	468 common sys_xyzzy compat_sys_xyzzy
	437
	438	Para resumir, você precisa de:
	439
	440	- ``COMPAT_SYSCALL_DEFINEn(, ...)`` para o ponto de entrada compat
	441	- Protótipo correspondente em ``include/linux/compat.h``
	442	- Modificação da entrada em ``scripts/syscall.tbl`` para incluir uma coluna
	443	"compat" extra
	444	- (Se necessário) Struct de mapeamento de 32 bits em ``include/linux/compat.h``
	445
	446
	447	.. _pt_BR_compat_arm64:
	448
	449	Chamadas de Sistema de Compatibilidade (arm64)
	450	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
	451
	452	No arm64, existe uma tabela de syscall dedicada para chamadas de sistema de
	453	compatibilidade voltadas para o espaço do usuário de 32 bits (AArch32):
	454	``arch/arm64/tools/syscall_32.tbl``. Você precisa adicionar uma linha adicional
	455	a esta tabela especificando o ponto de entrada compat::
	456
	457	468 common sys_xyzzy compat_sys_xyzzy
	458
	459
	460	Chamadas de Sistema de Compatibilidade (x86)
	461	--------------------------------------------
	462
	463	Para interligar a arquitetura x86 de uma chamada de sistema com uma versão de
	464	compatibilidade, as entradas nas tabelas de syscall precisam ser ajustadas.
	465
	466	Primeiro, a entrada em ``arch/x86/entry/syscalls/syscall_32.tbl`` ganha uma
	467	coluna extra para indicar que um programa de espaço do usuário de 32 bits rodando
	468	em um kernel de 64 bits deve atingir o ponto de entrada compat::
	469
	470	380 i386 sys_xyzzy __ia32_compat_sys_xyzzy
	471
	472	Segundo, você precisa definir o que deve acontecer para a versão da ABI x32 da
	473	nova chamada de sistema. Há uma escolha aqui: o layout dos argumentos deve
	474	corresponder à versão de 64 bits ou à versão de 32 bits.
	475
	476	Se houver um ponteiro para um ponteiro envolvido, a decisão é fácil: x32 é
	477	ILP32 (inteiro, long e ponteiro possuem 32 bits), portanto o layout deve
	478	corresponder à versão de 32 bits, e a entrada em
	479	``arch/x86/entry/syscalls/syscall_64.tbl`` é dividida para que os programas x32
	480	atinjam o wrapper de compatibilidade::
	481
	482	333 64 sys_xyzzy
	483	...
	484	555 x32 __x32_compat_sys_xyzzy
	485
	486	Se não houver ponteiros envolvidos, então é preferível reutilizar a chamada de
	487	sistema de 64 bits para a ABI x32 (e, consequentemente, a entrada em
	488	``arch/x86/entry/syscalls/syscall_64.tbl`` permanece inalterada).
	489
	490	Em qualquer um dos casos, você deve verificar se os tipos envolvidos no layout
	491	dos seus argumentos de fato se mapeiam exatamente do x32 (-mx32) para os seus
	492	equivalentes de 32 bits (-m32) ou 64 bits (-m64).
	493
	494
	495	Chamadas de Sistema com Retorno para Outro Local
	496	------------------------------------------------
	497
	498	Para a maioria das chamadas de sistema (syscalls), assim que a execução é
	499	concluída, o programa do usuário continua exatamente de onde parou -- na
	500	próxima instrução, com a pilha idêntica e a maior parte dos registradores no
	501	mesmo estado de antes da chamada, além do mesmo espaço de memória virtual.
	502
	503	No entanto, algumas poucas chamadas de sistema agem de forma diferente. Elas
	504	podem retornar para um local distinto (``rt_sigreturn``), alterar o espaço de
	505	memória (``fork``/``vfork``/``clone``) ou até mesmo modificar a arquitetura
	506	(``execve``/``execveat``) do programa.
	507
	508	Para permitir isso, a implementação da chamada de sistema no kernel pode
	509	precisar salvar e restaurar registradores adicionais na pilha do kernel,
	510	garantindo controle total de onde e como a execução continuará após a syscall.
	511
	512	Isso é específico de cada arquitetura (arch-specific), mas tipicamente envolve
	513	a definição de pontos de entrada em assembly que salvam/restauram esses
	514	registradores adicionais e invocam o ponto de entrada real da chamada de
	515	sistema.
	516
	517	Para x86_64, isso é implementado como um ponto de entrada ``stub_xyzzy`` em
	518	``arch/x86/entry/entry_64.S``, e a entrada correspondente na tabela de syscalls
	519	(``arch/x86/entry/syscalls/syscall_64.tbl``) é ajustada para refletir::
	520
	521	333 common stub_xyzzy
	522
	523	O equivalente para programas de 32 bits executados em um kernel de 64 bits é
	524	normalmente chamado de ``stub32_xyzzy`` e implementado em
	525	``arch/x86/entry/entry_64_compat.S``, com o respectivo ajuste na tabela de
	526	syscalls em ``arch/x86/entry/syscalls/syscall_32.tbl``::
	527
	528	380 i386 sys_xyzzy stub32_xyzzy
	529
	530	Se a chamada de sistema precisar de uma camada de compatibilidade (como na
	531	seção anterior), a versão ``stub32_`` precisará chamar a versão
	532	``compat_sys_`` da chamada de sistema em vez da versão nativa de 64 bits. Além
	533	disso, se a implementação da ABI x32 não for compartilhada com a versão
	534	x86_64, sua tabela de syscalls também precisará invocar um stub que direcione
	535	para a versão ``compat_sys_``.
	536
	537	Por questões de integridade, também é recomendado configurar um mapeamento para
	538	que o User-Mode Linux (UML) continue funcionando -- sua tabela de syscalls fará
	539	referência a ``stub_xyzzy``, mas o build do UML não inclui a implementação de
	540	``arch/x86/entry/entry_64.S`` (já que o UML simula registradores, etc.). Corrigir
	541	isso é tão simples quanto adicionar um #define em
	542	``arch/x86/um/sys_call_table_64.c``::
	543
	544	#define stub_xyzzy sys_xyzzy
	545
	546
	547	Outros Detalhes
	548	---------------
	549
	550	A maior parte do kernel trata as chamadas de sistema de maneira genérica, mas
	551	há exceções ocasionais que podem precisar de atualização para a sua chamada
	552	de sistema específica.
	553
	554	O subsistema de auditoria (audit) é um desses casos especiais; ele inclui
	555	funções (específicas de cada arquitetura) que classificam alguns tipos
	556	especiais de chamada de sistema -- especificamente operações de abertura de
	557	arquivo (``open``/``openat``), execução de programa (``execve``/``exeveat``) ou
	558	multiplexador de socket (``socketcall``). Se a sua nova chamada de sistema for
	559	análoga a uma dessas, o sistema de auditoria deverá ser atualizado.
	560
	561	De forma mais geral, se existir uma chamada de sistema atual que seja análoga
	562	à sua nova chamada de sistema, vale a pena fazer um grep em todo o kernel pela
	563	chamada existente para verificar se não há outros casos especiais.
	564
	565
	566	Testes
	567	------
	568
	569	Uma nova chamada de sistema deve, obviamente, ser testada; também é útil
	570	fornecer aos revisores uma demonstração de como os programas do espaço do
	571	usuário (user space) usarão a chamada de sistema. Uma boa maneira de combinar
	572	esses objetivos é incluir um programa simples de autoteste em um novo diretório
	573	sob ``tools/testing/selftests/``.
	574
	575	Para uma nova chamada de sistema, obviamente não haverá uma função de wrapper
	576	na libc e, portanto, o teste precisará invocá-la usando ``syscall()``; além
	577	disso, se a chamada de sistema envolver uma nova estrutura visível para o
	578	espaço do usuário, o cabeçalho correspondente precisará ser instalado para
	579	compilar o teste.
	580
	581	Certifique-se de que o autoteste seja executado com sucesso em todas as
	582	arquiteturas suportadas. Por exemplo, verifique se ele funciona quando compitado
	583	como um programa ABI x86_64 (-m64), x86_32 (-m32) e x32 (-mx32).
	584
	585	Para testes mais extensos e minuciosos de novas funcionalidades, você também
	586	deve considerar a adição de testes ao Linux Test Project ou ao projeto
	587	xfstests para alterações relacionadas
	588
	589	Página de Manual (Man Page)
	590	---------------------------
	591
	592	Todas as novas chamadas de sistema devem vir acompanhadas de uma página de
	593	manual completa, idealmente usando a marcação groff, mas texto simples também
	594	é aceitável. Se o groff for utilizado, é útil incluir uma versão ASCII pré-
	595	renderizada da página de manual no e-mail de apresentação (cover letter) do
	596	conjunto de patches (patchset), para a conveniência dos revisores.
	597
	598	A página de manual deve ser enviada com cópia (cc) para
	599	linux-man@vger.kernel.org. Para mais detalhes, consulte
	600	https://www.kernel.org/doc/man-pages/patches.html
	601
	602
	603	Não invoque Chamadas de Sistema dentro do Kernel
	604	------------------------------------------------
	605
	606	As chamadas de sistema são, como mencionado acima, pontos de interação entre o
	607	espaço do usuário (userspace) e o kernel. Portanto, funções de chamada de
	608	sistema como ``sys_xyzzy()`` ou ``compat_sys_xyzzy()`` só devem ser chamadas a
	609	partir do espaço do usuário por meio da tabela de syscalls, e não de outros
	610	lugares do kernel. Se a funcionalidade da syscall for útil para ser utilizada
	611	dentro do kernel, precisar ser compartilhada entre uma syscall antiga e uma
	612	nova, ou precisar ser compartilhada entre uma syscall e sua variante de
	613	compatibilidade, ela deve ser implementada por meio de uma função auxiliadora
	614	("helper", como ``ksys_xyzzy()``). Essa função do kernel poderá então ser
	615	chamada dentro do stub da syscall (``sys_xyzzy()``), do stub da syscall de
	616	compatibilidade (``compat_sys_xyzzy()``) e/ou de outro código do kernel.
	617
	618	Pelo menos em x86 de 64 bits, será um requisito rígido a partir da versão v4.17
	619	em diante não chamar funções de chamadas de sistema no kernel. Essa arquitetura
	620	utiliza uma convenção de chamada diferente para chamadas de sistema na qual a
	621	``struct pt_regs`` é decodificada dinamicamente em um wrapper de syscall, que
	622	então repassa o processamento para a função real da syscall. Isso significa que
	623	apenas os parâmetros realmente necessários para uma syscall específica são
	624	passados durante a entrada da syscall, em vez de preencher seis registradores da
	625	CPU com conteúdos aleatórios do espaço do usuário o tempo todo (o que poderia
	626	causar problemas sérios no decorrer da cadeia de chamadas).
	627
	628	Além disso, as regras sobre como os dados podem ser acessados diferem entre os
	629	dados do kernel e os dados do usuário. Essa é outra razão pela qual chamar
	630	``sys_xyzzy()`` geralmente é uma má ideia.
	631
	632	Exceções a essa regra são permitidas apenas em substituições (overrides)
	633	específicas de cada arquitetura, wrappers de compatibilidade específicos de cada
	634	arquitetura ou outros códigos dentro do diretório arch/.
	635
	636	Referências e Fontes
	637	--------------------
	638
	639	- Artigo da LWN por Michael Kerrisk sobre o uso do argumento flags em chamadas
	640	de sistema:
	641	https://lwn.net/Articles/585415/
	642	- Artigo da LWN por Michael Kerrisk sobre como lidar com flags desconhecidas
	643	em uma chamada de sistema: https://lwn.net/Articles/588444/
	644	- Artigo da LWN por Jake Edge descrevendo restrições em argumentos de chamadas
	645	de sistema de 64 bits: https://lwn.net/Articles/311630/
	646	- Par de artigos da LWN por David Drysdale que descrevem detalhadamente os
	647	caminhos de implementação de chamadas de sistema para a v3.14:
	648
	649	- https://lwn.net/Articles/604287/
	650	- https://lwn.net/Articles/604515/
	651
	652	- Os requisitos específicos de arquitetura para chamadas de sistema são
	653	discutidos na página de manual :manpage:`syscall(2)`:
	654	http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES
	655	- E-mails compilados de Linus Torvalds discutindo os problemas com ``ioctl()``:
	656	https://yarchive.net/comp/linux/ioctl.html
	657	- "How to not invent kernel interfaces", Arnd Bergmann,
	658	https://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdf
	659	- Artigo da LWN por Michael Kerrisk sobre evitar novos usos de CAP_SYS_ADMIN:
	660	https://lwn.net/Articles/486306/
	661	- Recomendação de Andrew Morton para que todas as informações relacionadas a
	662	uma nova chamada de sistema venham na mesma thread de e-mail:
	663	https://lore.kernel.org/r/20140724144747.3041b208832bbdf9fbce5d96@linux-foundation.org
	664	- Recomendação de Michael Kerrisk para que uma nova chamada de sistema venha
	665	acompanhada de uma página de manual:
	666	https://lore.kernel.org/r/CAKgNAkgMA39AfoSoA5Pe1r9N+ZzfYQNvNPvcRN7tOvRb8+v06Q@mail.gmail.com
	667	- Sugestão de Thomas Gleixner para que a vinculação (wire-up) do x86 esteja em
	668	um commit separado:
	669	https://lore.kernel.org/r/alpine.DEB.2.11.1411191249560.3909@nanos
	670	- Sugestão de Greg Kroah-Hartman de que é bom que novas chamadas de sistema
	671	venham acompanhadas de uma página de manual e um autoteste:
	672	https://lore.kernel.org/r/20140320025530.GA25469@kroah.com
	673	- Discussão de Michael Kerrisk sobre uma nova chamada de sistema versus a
	674	extensão de :manpage:`prctl(2)`:
	675	https://lore.kernel.org/r/CAHO5Pa3F2MjfTtfNxa8LbnkeeU8=YJ+9tDqxZpw7Gz59E-4AUg@mail.gmail.com
	676	- Sugestão de Ingo Molnar de que as chamadas de sistema que envolvem múltiplos
	677	argumentos devem encapsular esses argumentos em uma struct, a qual inclua um
	678	campo de tamanho (size) para fins de extensibilidade futura:
	679	https://lore.kernel.org/r/20150730083831.GA22182@gmail.com
	680	- Excentricidades de numeração decorrentes do uso (e reuso) de flags do espaço
	681	de numeração O_*:
	682
	683	- commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness
	684	check")
	685	- commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc
	686	conflict")
	687	- commit bb458c644a59 ("Safer ABI for O_TMPFILE")
	688
	689	- Discussão de Matthew Wilcox sobre restrições em argumentos de 64 bits:
	690	https://lore.kernel.org/r/20081212152929.GM26095@parisc-linux.org
	691	- Recomendação de Greg Kroah-Hartman de que flags desconhecidas devem ser
	692	fiscalizadas/policiadas:
	693	https://lore.kernel.org/r/20140717193330.GB4703@kroah.com
	694	- Recomendação de Linus Torvalds de que as chamadas de sistema x32 devem
	695	preferir a compatibilidade com as versões de 64 bits em vez das versões de
	696	32 bits:
	697	https://lore.kernel.org/r/CA+55aFxfmwfB7jbbrXxa=K7VBYPfAvmu3XOkGrLbB1UFjX1+Ew@mail.gmail.com
	698	- Série de patches revisando a infraestrutura da tabela de chamadas de sistema
	699	para utilizar scripts/syscall.tbl em múltiplas arquiteturas:
	700	https://lore.kernel.org/lkml/20240704143611.2979589-1-arnd@kernel.org

Documentation/translations/pt_BR/process/applying-patches.rst+447−0

@@ -0,0 +1,447 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	Aplicando Patches ao Kernel Linux
	4	+++++++++++++++++++++++++++++++++
	5
	6	Autor Original:
	7	Jesper Juhl, Agosto de 2005
	8
	9	.. note::
	10
	11	Este documento está obsoleto. Na maioria dos casos, em vez de usar ``patch``
	12	manualmente, você quase certamente desejará considerar o uso do Git.
	13
	14	Uma pergunta feita com frequência na Linux Kernel Mailing List é como aplicar
	15	an patch ao kernel ou, mais especificamente, a qual kernel base um patch para
	16	uma das muitas árvores/branches deve ser aplicado. Esperamos que este documento
	17	explique isso a você.
	18
	19	Além de explicar como aplicar e reverter patches, uma breve descrição das
	20	diferentes árvores do kernel (e exemplos de como aplicar seus patches
	21	específicos) também é fornecida.
	22
	23
	24	O que é um Patch?
	25	=================
	26
	27	Um patch é um pequeno documento de texto que contém uma diferença (delta) de
	28	alterações entre duas versões diferentes de uma árvore de código-fonte. Os
	29	patches são criados com o programa ``diff``.
	30
	31	Para aplicar um patch corretamente, você precisa saber de qual base ele foi
	32	gerado e em qual nova versão o patch transformará a árvore de código-fonte.
	33	Ambas as informações devem estar presentes nos metadados do arquivo de patch
	34	ou ser possíveis de deduzir a partir do nome do arquivo.
	35
	36
	37	Como eu aplico ou reverto um patch?
	38	===================================
	39
	40	Você aplica um patch com o programa ``patch``. O programa patch lê um arquivo
	41	de diff (ou patch) e faz as alterações descritas nele na árvore de
	42	código-fonte.
	43
	44	Os patches para o kernel Linux são gerados relativamente ao diretório pai que
	45	contém o diretório do código-fonte do kernel.
	46
	47	Isso significa que os caminhos para os arquivos dentro do arquivo de patch
	48	contêm o nome dos diretórios do código-fonte do kernel contra os quais ele foi
	49	gerado (ou alguns outros nomes de diretório como "a/" e "b/").
	50
	51	Como é improvável que isso corresponda ao nome do diretório do código-fonte do
	52	kernel na sua máquina local (mas frequentemente é uma informação útil para ver
	53	contra qual versão um patch sem identificação foi gerado), você deve entrar no
	54	seu diretório de código-fonte do kernel e, em seguida, remover o primeiro
	55	elemento do caminho dos nomes de arquivos no arquivo de patch ao aplicá-lo (o
	56	argumento ``-p1`` para o ``patch`` faz isso).
	57
	58	Para reverter um patch aplicado anteriormente, use o argumento -R para o patch.
	59	Portanto, se você aplicou um patch desta forma::
	60
	61	patch -p1 < ../patch-x.y.z
	62
	63	Você pode revertê-lo (desfazê-lo) assim::
	64
	65	patch -R -p1 < ../patch-x.y.z
	66
	67
	68	Como eu passo um arquivo de patch/diff para o ``patch``?
	69	========================================================
	70
	71	Isso (como de costume no Linux e em outros sistemas operacionais do tipo UNIX)
	72	pode ser feito de várias maneiras diferentes.
	73
	74	Em todos os exemplos abaixo, eu passo o arquivo (em formato não compactado) para
	75	o patch via stdin usando a seguinte sintaxe::
	76
	77	patch -p1 < path/to/patch-x.y.z
	78
	79	Se você quer apenas ser capaz de seguir os exemplos abaixo e não deseja
	80	conhecer mais do que uma maneira de usar o patch, então você pode parar a
	81	leitura desta seção aqui.
	82
	83	O patch também pode receber o nome do arquivo a ser usado através do argumento
	84	-i, desta forma::
	85
	86	patch -p1 -i path/to/patch-x.y.z
	87
	88	Se o seu arquivo de patch estiver compactado com gzip ou xz e você não quiser
	89	descompactá-lo antes de aplicá-lo, você pode passá-lo para o patch desta outra
	90	forma::
	91
	92	xzcat path/to/patch-x.y.z.xz \| patch -p1
	93	bzcat path/to/patch-x.y.z.gz \| patch -p1
	94
	95	Se você deseja descompactar o arquivo de patch manualmente primeiro antes de
	96	aplicá-lo (o que presumo que você tenha feito nos exemplos abaixo), basta
	97	executar gunzip ou xz no arquivo -- desta forma::
	98
	99	gunzip patch-x.y.z.gz
	100	xz -d patch-x.y.z.xz
	101
	102	O que deixará você com um arquivo patch-x.y.z em texto puro que você pode
	103	passar para o patch via stdin ou pelo argumento ``-i``, conforme sua preferência.
	104
	105	Alguns outros argumentos úteis para o patch são ``-s``, que faz com que o patch
	106	seja silencioso (exceto por erros), o que é bom para evitar que erros sumam da
	107	tela rolando rápido demais; e ``--dry-run``, que faz com que o patch apenas
	108	imprima uma lista do que aconteceria, mas sem realizar nenhuma alteração de
	109	fato. Por fim, ``--verbose`` diz ao patch para imprimir mais informações sobre o
	110	trabalho que está sendo realizado.
	111
	112
	113	Erros comuns ao aplicar patches
	114	===============================
	115
	116	Quando o patch aplica um arquivo de patch, ele tenta verificar a integridade do
	117	arquivo de diferentes maneiras.
	118
	119	Verificar se o arquivo parece um arquivo de patch válido e checar se o código ao
	120	redor dos trechos sendo modificados corresponde ao contexto fornecido no patch
	121	são apenas duas das verificações básicas de integridade que o patch faz.
	122
	123	Se o patch encontrar algo que não pareça totalmente correto, ele tem duas
	124	opções. Ele pode se recusar a aplicar as alterações e abortar, ou pode tentar
	125	encontrar uma maneira de fazer o patch ser aplicado com algumas pequenas
	126	alterações.
	127
	128	Um exemplo de algo que não está "totalmente correto" e que o patch tentará
	129	corrigir é se todo o contexto coincidir, as linhas sendo alteradas coincidirem,
	130	mas os números das linhas forem diferentes. Isso pode acontecer, por exemplo, se
	131	o patch fizer uma alteração no meio do arquivo, mas, por algum motivo, algumas
	132	linhas tiverem sido adicionadas ou removidas perto do início do arquivo. Nesse
	133	caso, tudo parece correto, apenas mudou um pouco para cima ou para baixo, e o
	134	patch geralmente ajustará os números das linhas e aplicará o patch.
	135
	136	Sempre que o patch aplicar um patch que ele teve de modificar um pouco para
	137	fazer caber, ele avisará você dizendo que o patch foi aplicado com fuzz.
	138	Você deve ser cauteloso com tais alterações porque, embora o patch
	139	provavelmente tenha acertado, ele nem /sempre/ acerta, e o resultado às vezes
	140	será incorreto.
	141
	142	Quando o patch encontra uma alteração que não consegue corrigir com fuzz, ele a
	143	rejeita imediatamente e deixa um arquivo com a extensão ``.rej`` (um arquivo de
	144	rejeição). Você pode ler esse arquivo para ver exatamente qual alteração não
	145	pôde ser aplicada, para que possa corrigi-la manualmente, se desejar.
	146
	147	Se você não tem nenhum patch de terceiros aplicado ao seu código-fonte do
	148	kernel, mas apenas patches do kernel.org, e você aplica os patches na ordem
	149	correta, e não fez nenhuma modificação por conta própria nos arquivos de
	150	origem, então você nunca deveria ver uma mensagem de fuzz ou de rejeição (reject)
	151	do patch. Se você ainda assim vir tais mensagens, então há um alto risco de que
	152	sua árvore de código-fonte local ou o arquivo de patch estejam corrompidos de
	153	alguma forma. Nesse caso, você provavelmente deveria tentar baixar o patch
	154	novamente e, se as coisas ainda não estiverem certas, aconselha-se começar com
	155	uma árvore limpa baixada na íntegra do kernel.org.
	156
	157	Vamos examinar um pouco mais algumas das mensagens que o patch pode produzir.
	158
	159	Se o patch parar e apresentar um prompt ``File to patch:``, então o patch não
	160	conseguiu encontrar um arquivo para ser modificado. O mais provável é que você
	161	tenha esquecido de especificar -p1 ou esteja no diretório errado. Com menos
	162	frequência, você encontrará patches que precisam ser aplicados com ``-p0`` em
	163	vez de ``-p1`` (a leitura do arquivo de patch deve revelar se este é o caso -- se
	164	for, isso é um erro da pessoa que criou o patch, mas não é fatal).
	165
	166	Se você receber ``Hunk #2 succeeded at 1887 with fuzz 2 (offset 7 lines).`` ou
	167	uma mensagem semelhante a essa, significa que o patch teve que ajustar o local
	168	da alteração (neste exemplo, ele precisou se mover 7 linhas de onde esperava
	169	fazer a alteração para fazê-la caber).
	170
	171	O arquivo resultante pode ou não estar correto, dependendo do motivo pelo qual o
	172	arquivo estava diferente do esperado.
	173
	174	Isso geralmente acontece se você tentar aplicar un patch que foi gerado contra uma
	175	versão de kernel diferente daquela que você está tentando modificar.
	176
	177	Se você receber uma mensagem como ``Hunk #3 FAILED at 2387.``, significa que o
	178	patch não pôde ser aplicado corretamente e o programa patch não foi capaz de
	179	encontrar um caminho usando o fuzz. Isso gerará um arquivo ``.rej`` com a
	180	alteração que fez o patch falhar e também um arquivo ``.orig`` mostrando o
	181	conteúdo original que não pôde ser alterado.
	182
	183	Se você receber ``Reversed (or previously applied) patch detected! Assume -R? [n]``
	184	então o patch detectou que a alteração contida no patch parece já ter sido feita.
	185
	186	Se você realmente aplicou este patch anteriormente e apenas o reaplicou por erro,
	187	basta dizer [n]ão (n) e abortar este patch. Se você aplicou este patch
	188	anteriormente e realmente pretendia revertê-lo, mas esqueceu de especificar -R,
	189	você pode dizer [y]es (sim) aqui para fazer o patch revertê-lo para você.
	190
	191	Isso também pode acontecer se o criador do patch inverteu os diretórios de
	192	origem e destino ao criar o patch e, nesse caso, reverter o patch irá, na
	193	verdade, aplicá-lo.
	194
	195	Uma mensagem semelhante a ``patch: **** unexpected end of file in patch`` ou
	196	``patch unexpectedly ends in middle of line`` significa que o patch não conseguiu
	197	fazer sentido do arquivo que você passou para ele. Ou o seu download está
	198	quebrado, ou você tentou passar para o patch um arquivo de patch compactado sem
	199	descompactá-lo primeiro, ou o arquivo de patch que você está usando foi alterado
	200	por um cliente de e-mail ou agente de transferência de e-mail em algum lugar pelo
	201	caminho, por exemplo, dividindo uma linha longa em duas linhas. Frequentemente,
	202	esses avisos podem ser corrigidos facilmente juntando (concatenando) as duas
	203	linhas que foram divididas.
	204
	205	Como já mencionei acima, esses erros nunca deveriam acontecer se você aplicar um
	206	patch do kernel.org na versão correta de uma árvore de código-fonte não
	207	modificada. Portanto, se você obtiver esses erros com patches do kernel.org,
	208	você provavelmente deve assumir que o seu arquivo de patch ou a sua árvore está
	209	quebrada, e eu o aconselharia a recomeçar com um download limpo de uma árvore
	210	completa do kernel e do patch que deseja aplicar.
	211
	212	Existem alternativas ao ``patch``?
	213	==================================
	214
	215	Sim, existem alternativas.
	216
	217	Você pode usar o programa ``interdiff`` (http://cyberelk.net/tim/patchutils/) para
	218	gerar um patch que represente as diferenças entre dois patches e, em seguida,
	219	aplicar o resultado.
	220
	221	Isso permitirá que você passe de algo como 5.7.2 para 5.7.3 em um único
	222	passo. A flag -z do interdiff permite até mesmo passar patches em formato
	223	compactado com gzip ou bzip2 diretamente, sem o uso de zcat, bzcat ou
	224	descompactação manual.
	225
	226	Aqui está como você passaria de 5.7.2 para 5.7.3 em um único passo::
	227
	228	interdiff -z ../patch-5.7.2.gz ../patch-5.7.3.gz \| patch -p1
	229
	230	Embora o interdiff possa economizar um ou dois passos, geralmente recomenda-se
	231	realizar os passos adicionais, já que o interdiff pode errar em alguns casos.
	232
	233	Outra alternativa é o ``ketchup``, que é um script em python para download e
	234	aplicação automática de patches (https://www.selenic.com/ketchup/).
	235
	236	Outras ferramentas úteis são o diffstat, que mostra um resumo das alterações
	237	feitas por um patch; o lsdiff, que exibe uma lista curta dos arquivos afetados
	238	em um arquivo de patch, junto com (opcionalmente) os números das linhas de
	239	início de cada patch; e o grepdiff, que exibe uma lista dos arquivos modificados
	240	por um patch onde o patch contém uma determinada expressão regular.
	241
	242
	243	Onde posso baixar os patches?
	244	=============================
	245
	246	Os patches estão disponíveis em https://kernel.org/
	247	Os patches mais recentes estão vinculados na página principal, mas eles também
	248	possuem locais específicos.
	249
	250	Os patches 5.x.y (-stable) e 5.x residem em
	251
	252	https://www.kernel.org/pub/linux/kernel/v5.x/
	253
	254	Os patches incrementais 5.x.y residem em
	255
	256	https://www.kernel.org/pub/linux/kernel/v5.x/incr/
	257
	258	Os patches -rc não são armazenados no servidor web, mas são gerados sob
	259	demanda a partir de tags do git, tais como
	260
	261	https://git.kernel.org/torvalds/p/v5.1-rc1/v5.0
	262
	263	Os patches estáveis -rc residem em
	264
	265	https://www.kernel.org/pub/linux/kernel/v5.x/stable-review/
	266
	267
	268	Os kernels 5.x
	269	==============
	270
	271	Estes são os lançamentos estáveis base publicados por Linus. O lançamento com o
	272	número mais alto é o mais recente.
	273
	274	Se regressões ou outras falhas graves forem encontradas, um patch de correção
	275	-stable será lançado (veja abaixo) sobre esta base. Assim que um novo kernel
	276	base 5.x é lançado, um patch é disponibilizado contendo o delta entre o kernel
	277	5.x anterior e o novo.
	278
	279	Para aplicar um patch mudando da versão 5.6 para a 5.7, você faria o seguinte
	280	(note que tais patches NÃO se aplicam sobre kernels 5.x.y, mas sim sobre o
	281	kernel base 5.x -- se você precisar mudar de 5.x.y para 5.x+1, você deve
	282	primeiro reverter o patch do 5.x.y).
	283
	284	Aqui estão alguns exemplos::
	285
	286	# mudando de 5.6 para 5.7
	287
	288	$ cd ~/linux-5.6 # muda para o dir do fonte do kernel
	289	$ patch -p1 < ../patch-5.7 # aplica o patch do 5.7
	290	$ cd ..
	291	$ mv linux-5.6 linux-5.7 # renomeia o dir do fonte
	292
	293	# mudando de 5.6.1 para 5.7
	294
	295	$ cd ~/linux-5.6.1 # muda para o dir do fonte do kernel
	296	$ patch -p1 -R < ../patch-5.6.1 # reverte o patch do 5.6.1
	297	# o dir do fonte agora é o 5.6
	298	$ patch -p1 < ../patch-5.7 # aplica o novo patch do 5.7
	299	$ cd ..
	300	$ mv linux-5.6.1 linux-5.7 # renomeia o dir do fonte
	301
	302	Os kernels 5.x.y
	303	================
	304
	305	Kernels com versões de 3 dígitos são kernels -stable (estáveis). Eles contêm
	306	correções críticas relativamente pequenas para problemas de segurança ou
	307	regressões significativas descobertas em um determinado kernel 5.x.
	308
	309	Esta é a ramificação recomendada para usuários que desejam o kernel estável mais
	310	recente e não estão interessados em ajudar a testar versões de desenvolvimento
	311	ou experimentais.
	312
	313	Se nenhum kernel 5.x.y estiver disponível, então o kernel 5.x com o número mais
	314	alto será o atual kernel estável.
	315
	316	A equipe -stable fornece patches normais, bem como incrementais. Abaixo está
	317	como aplicar esses patches.
	318
	319	Patches normais
	320	~~~~~~~~~~~~~~~
	321
	322	Estes patches não são incrementais, o que significa que, por exemplo, o patch
	323	5.7.3 não se aplica sobre o código-fonte do kernel 5.7.2, mas sim sobre o
	324	código-fonte do kernel base 5.7.
	325
	326	Portanto, para aplicar o patch 5.7.3 ao seu código-fonte existente do kernel
	327	5.7.2, você deve primeiro remover o patch 5.7.2 (de modo que reste apenas o
	328	código-fonte do kernel base 5.7) e então aplicar o novo patch 5.7.3.
	329
	330	Aqui está um pequeno exemplo::
	331
	332	$ cd ~/linux-5.7.2 # muda para o dir do fonte do kernel
	333	$ patch -p1 -R < ../patch-5.7.2 # reverte o patch do 5.7.2
	334	$ patch -p1 < ../patch-5.7.3 # aplica o novo patch do 5.7.3
	335	$ cd ..
	336	$ mv linux-5.7.2 linux-5.7.3 # renomeia o dir do fonte do kernel
	337
	338	Patches incrementais
	339	~~~~~~~~~~~~~~~~~~~~
	340
	341	Os patches incrementais são diferentes: em vez de serem aplicados sobre o kernel
	342	base 5.x, eles são aplicados sobre o kernel estável anterior (5.x.y-1).
	343
	344	Aqui está o exemplo para aplicar estes::
	345
	346	$ cd ~/linux-5.7.2 # muda para o dir do fonte do kernel
	347	$ patch -p1 < ../patch-5.7.2-3 # aplica o novo patch do 5.7.3
	348	$ cd ..
	349	$ mv linux-5.7.2 linux-5.7.3 # renomeia o dir do fonte do kernel
	350
	351
	352	Os kernels -rc
	353	==============
	354
	355	Estes são os kernels candidatos a lançamento (release-candidate). São kernels
	356	de desenvolvimento publicados por Linus sempre que ele considera que a árvore
	357	atual do git (a ferramenta de gerenciamento de código-fonte do kernel) está em
	358	um estado razoavelmente íntegro e adequado para testes.
	359
	360	Estes kernels não são estáveis e você deve esperar quebras ocasionais se pretender
	361	executá-los. Esta é, no entanto, a mais estável das principais ramificações de
	362	desenvolvimento e é também o que eventualmente se tornará o próximo kernel
	363	estável, por isso é importante que seja testado pelo maior número possível de
	364	pessoas.
	365
	366	Esta é uma boa ramificação para pessoas que querem ajudar a testar kernels de
	367	desenvolvimento, mas não querem executar algumas das coisas realmente
	368	experimentais (essas pessoas devem ver as seções sobre os kernels -next e -mm
	369	abaixo).
	370
	371	Os patches -rc não são incrementais; eles se aplicam a um kernel base 5.x, assim
	372	como os patches 5.x.y descritos acima. A versão do kernel antes do sufixo -rcN
	373	indica a versão do kernel na qual este kernel -rc eventualmente se tornará.
	374
	375	Portanto, 5.8-rc5 significa que este é o quinto candidato a lançamento para o
	376	kernel 5.8 e o patch deve ser aplicado sobre o código-fonte do kernel 5.7.
	377
	378	Aqui estão 3 exemplos de como aplicar esses patches::
	379
	380	# primeiro, um exemplo de mudança do 5.7 para o 5.8-rc3
	381
	382	$ cd ~/linux-5.7 # muda para o dir do fonte do 5.7
	383	$ patch -p1 < ../patch-5.8-rc3 # aplica o patch do 5.8-rc3
	384	$ cd ..
	385	$ mv linux-5.7 linux-5.8-rc3 # renomeia o dir do fonte
	386
	387	# agora vamos mudar do 5.8-rc3 para o 5.8-rc5
	388
	389	$ cd ~/linux-5.8-rc3 # muda para o dir do 5.8-rc3
	390	$ patch -p1 -R < ../patch-5.8-rc3 # reverte o patch do 5.8-rc3
	391	$ patch -p1 < ../patch-5.8-rc5 # aplica o novo patch do 5.8-rc5
	392	$ cd ..
	393	$ mv linux-5.8-rc3 linux-5.8-rc5 # renomeia o dir do fonte
	394
	395	# por fim, vamos tentar mudar do 5.7.3 para o 5.8-rc5
	396
	397	$ cd ~/linux-5.7.3 # muda para o dir do fonte do kernel
	398	$ patch -p1 -R < ../patch-5.7.3 # reverte o patch do 5.7.3
	399	$ patch -p1 < ../patch-5.8-rc5 # aplica o novo patch do 5.8-rc5
	400	$ cd ..
	401	$ mv linux-5.7.3 linux-5.8-rc5 # renomeia o dir do fonte do kernel
	402
	403
	404	Os patches -mm e a árvore linux-next
	405	====================================
	406
	407	Os patches -mm são patches experimentais publicados por Andrew Morton.
	408
	409	No passado, a árvore -mm também era usada para testar patches de subsistemas,
	410	mas essa função agora é realizada por meio da árvore
	411	`linux-next` (https://www.kernel.org/doc/man-pages/linux-next.html).
	412	Os mantenedores de subsistemas enviam seus patches primeiro para a linux-next e,
	413	durante a janela de mesclagem (merge window), enviam-nos diretamente para Linus.
	414
	415	Os patches -mm servem como uma espécie de campo de testes para novos recursos e
	416	outros patches experimentais que não são mesclados por meio de uma árvore de
	417	subsistema. Assim que tais patches provam seu valor na -mm por um tempo, Andrew
	418	os envia para Linus para inclusão na linha principal (mainline).
	419
	420	A árvore linux-next é atualizada diariamente e inclui os patches -mm. Ambas
	421	estão em constante fluxo e contêm muitos recursos experimentais, uma grande
	422	quantidade de patches de depuração (debugging) não apropriados para a linha
	423	principal etc., sendo as mais experimentais das ramificações descritas neste
	424	documento.
	425
	426	Estes patches não são apropriados para uso em sistemas que devem ser estáveis e
	427	são mais arriscados de executar do que qualquer uma das outras ramificações
	428	(certifique-se de ter backups atualizados -- isso vale para qualquer kernel
	429	experimental, mas ainda mais para patches -mm ou ao usar um kernel da árvore
	430	linux-next).
	431
	432	O teste dos patches -mm e da linux-next é imensamente apreciado, pois todo o
	433	objetivo deles é eliminar regressões, travamentos (crashes), bugs de corrupção
	434	de dados, quebras de compilação (e qualquer outro bug em geral) antes que as
	435	alterações sejam mescladas na árvore principal do Linus, que é mais estável.
	436
	437	Mas os testadores da -mm e da linux-next devem estar cientes de que quebras são
	438	mais comuns do que em qualquer outra árvore.
	439
	440
	441	Isso conclui esta lista de explicações sobre as várias árvores do kernel.
	442	Espero que agora você tenha clareza sobre como aplicar os vários patches e
	443	ajudar a testar o kernel.
	444
	445	Agradecimentos a Randy Dunlap, Rolf Eike Beer, Linus Torvalds, Bodo Eggert,
	446	Johannes Stezenbach, Grant Coady, Pavel Machek e outros que posso ter esquecido
	447	por suas revisões e contribuições para este documento.

Documentation/translations/pt_BR/process/backporting.rst+598−0

@@ -0,0 +1,598 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	====================================
	4	Backporting e resolução de conflitos
	5	====================================
	6
	7	:Autor: Vegard Nossum <vegard.nossum@oracle.com>
	8
	9	.. contents::
	10	:local:
	11	:depth: 3
	12	:backlinks: none
	13
	14	Introdução
	15	==========
	16
	17	Alguns desenvolvedores podem nunca precisar lidar de fato com backporting de
	18	patches, mesclagem de ramificações (branches) ou resolução de conflitos em seu
	19	trabalho diário, portanto, quando um conflito de mesclagem aparece, pode ser
	20	assustador. Felizmente, resolver conflitos é uma habilidade como qualquer outra,
	21	e existem muitas técnicas úteis que você pode usar para tornar o processo mais
	22	suave e aumentar sua confiança no resultado.
	23
	24	Este documento tem como objetivo ser um guia abrangente e passo a passo para
	25	backporting e resolução de conflitos.
	26
	27	Aplicando o patch a uma árvore
	28	==============================
	29
	30	Às vezes, o patch que você está fazendo backport já existe como um commit do
	31	git, caso em que você apenas faz o cherry-pick dele diretamente usando
	32	``git cherry-pick``. No entanto, se o patch vier de um e-mail, como costuma
	33	acontecer no caso do kernel Linux, você precisará aplicá-lo a uma árvore usando
	34	``git am``.
	35
	36	Se você já usou o ``git am``, provavelmente já sabe que ele é bastante exigente
	37	sobre o patch ser aplicado perfeitamente à sua árvore de código-fonte. Na
	38	verdade, você provavelmente já teve pesadelos com arquivos ``.rej`` e tentando
	39	editar o patch para fazê-lo ser aplicado.
	40
	41	Recomenda-se fortemente, em vez disso, encontrar uma versão base apropriada onde
	42	o patch se aplique de forma limpa e então fazer o cherry-pick dele para a sua
	43	árvore de destino, pois isso fará com que o git exiba marcadores de conflito e
	44	permitirá que você resolva os conflitos com a ajuda do git e de quaisquer outras
	45	ferramentas de resolução de conflitos que preferir usar. Por exemplo, se você
	46	quiser aplicar um patch que acabou de chegar na LKML a um kernel estável mais
	47	antigo, você pode aplicá-lo ao kernel principal (mainline) mais recente e, em
	48	seguida, fazer o cherry-pick dele para a sua ramificação estável mais antiga.
	49
	50	Geralmente é melhor usar exatamente a mesma base a partir da qual o patch foi
	51	gerado, mas isso não importa tanto, desde que ele se aplique de forma limpa e
	52	não esteja muito longe da base original. O único problema ao aplicar o patch na
	53	base "errada" é que isso pode trazer mais alterações não relacionadas no
	54	contexto do diff ao fazer o cherry-pick dele para a ramificação mais antiga.
	55
	56	Um bom motivo para preferir o ``git cherry-pick`` em vez do ``git am`` é que o
	57	git conhece o histórico preciso de um commit existente, de modo que ele saberá
	58	quando o código foi movido de lugar e teve seus números de linha alterados; isso,
	59	por sua vez, torna menos provável que o patch seja aplicado no lugar errado (o
	60	que pode resultar em erros silenciosos ou conflitos confusos).
	61
	62	Se você estiver usando o `b4`_. e estiver aplicando o patch diretamente de um
	63	e-mail, você pode usar o ``b4 am`` com as opções ``-g``/``--guess-base`` e
	64	``-3``/``--prep-3way`` para fazer parte disso automaticamente (veja a
	65	`apresentação do b4`_ para mais informações). No entanto, o restante deste
	66	artigo assumirá que você está fazendo um ``git cherry-pick`` simples.
	67
	68	.. _b4: https://people.kernel.org/monsieuricon/introducing-b4-and-patch-attestation
	69	.. _apresentação do b4: https://youtu.be/mF10hgVIx9o?t=2996
	70
	71	Assim que tiver o patch no git, você pode prosseguir e fazer o cherry-pick dele
	72	em sua árvore de código-fonte. Não se esqueça de fazer o cherry-pick com ``-x``
	73	se quiser um registro por escrito de onde o patch veio!
	74
	75	Note que, se você estiver enviando um patch para a ramificação estável (stable),
	76	o formato é ligeiramente diferente; a primeira linha após a linha de assunto
	77	precisa ser::
	78
	79	commit <upstream commit> upstream
	80
	81	ou::
	82
	83	[ Upstream commit <upstream commit> ]
	84
	85	Resolvendo conflitos
	86	====================
	87
	88	Ih, rapaz; o cherry-pick falhou com uma mensagem vagamente ameaçadora::
	89
	90	CONFLICT (content): Merge conflict
	91
	92	O que fazer agora?
	93
	94	Em geral, os conflitos aparecem quando o contexto do patch (ou seja, as linhas
	95	que estão sendo alteradas e/ou as linhas que cercam as alterações) não
	96	corresponde ao que está na árvore à qual você está tentando aplicar o patch.
	97
	98	No caso de backports, o que provavelmente aconteceu foi que a ramificação
	99	(branch) a partir da qual você está fazendo o backport contém patches que não
	100	estão na ramificação para a qual você está fazendo o backport. No entanto, o
	101	inverso também é possível. Em qualquer caso, o resultado é um conflito que
	102	precisa ser resolvido.
	103
	104	Se a sua tentativa de cherry-pick falhar com um conflito, o git edita os
	105	arquivos automaticamente para incluir os chamados marcadores de conflito,
	106	mostrando onde está o conflito e como as duas ramificações divergiram. Resolver
	107	o conflito normalmente significa editar o resultado final de forma que ele leve
	108	em consideração esses outros commits.
	109
	110	A resolução do conflito pode ser feita manualmente em um editor de texto comum
	111	ou usando uma ferramenta dedicada de resolução de conflitos.
	112
	113	Muitas pessoas preferem usar seu editor de texto comum e editar o conflito
	114	diretamente, pois pode ser mais fácil entender o que você está fazendo e
	115	controlar o resultado final. Definitivamente, existem prós e contras em cada
	116	método, e às vezes há valor em usar ambos.
	117
	118	Não abordaremos o uso de ferramentas de mesclagem (merge tools) dedicadas aqui,
	119	além de fornecer algumas indicações de várias ferramentas que você poderia usar:
	120
	121	- `Modo Emacs Ediff <https://www.emacswiki.org/emacs/EdiffMode>`__
	122	- `vimdiff/gvimdiff <https://linux.die.net/man/1/vimdiff>`__
	123	- `KDiff3 <http://kdiff3.sourceforge.net/>`__
	124	- `TortoiseMerge <https://tortoisesvn.net/TortoiseMerge.html>`__
	125	- `Meld <https://meldmerge.org/help/>`__
	126	- `P4Merge <https://www.perforce.com/products/helix-core-apps/merge-diff-tool-p4merge>`__
	127	- `Beyond Compare <https://www.scootersoftware.com/>`__
	128	- `IntelliJ <https://www.jetbrains.com/help/idea/resolve-conflicts.html>`__
	129	- `VSCode <https://code.visualstudio.com/docs/editor/versioncontrol>`__
	130
	131	Para configurar o git para funcionar com elas, veja ``git mergetool --help`` ou
	132	a `documentação oficial do git-mergetool`_.
	133
	134	.. _documentação oficial do git-mergetool: https://git-scm.com/docs/git-mergetool
	135
	136	Patches pré-requisitos
	137	----------------------
	138
	139	A maioria dos conflitos acontece porque a ramificação para a qual você está
	140	fazendo o backport não possui alguns patches em comparação com a ramificação a
	141	partir da qual você está fazendo o backport. No caso mais geral (como a
	142	mesclagem de duas ramificações independentes), o desenvolvimento poderia ter
	143	ocorrido em qualquer uma das ramificações, ou as ramificações simplesmente
	144	divergiram -- talvez a sua ramificação mais antiga tenha recebido alguns outros
	145	backports que, por si só, precisaram de resoluções de conflitos, causando uma
	146	divergência.
	147
	148	É importante sempre identificar o commit ou os commits que causaram o conflito,
	149	pois, caso contrário, você não poderá ter confiança na correção da sua
	150	resolução. Como um bônus adicional, especialmente se o patch for em uma área com
	151	a qual você não está muito familiarizado, os registros de alterações (changelogs)
	152	desses commits frequentemente lhe darão o contexto para entender o código e os
	153	problemas ou armadilhas potenciais com a sua resolução de conflito.
	154
	155	git log
	156	~~~~~~~
	157
	158	Um bom primeiro passo é olhar o ``git log`` para o arquivo que possui o
	159	conflito -- isso geralmente é suficiente quando não há muitos patches no
	160	arquivo, mas pode ficar confuso se o arquivo for grande e frequentemente
	161	modificado por patches. Você deve executar o ``git log`` no intervalo de commits
	162	entre a sua ramificação atualmente ativa (``HEAD``) e o pai do patch que você está
	163	escolhendo (``<commit>``), ou seja::
	164
	165	git log HEAD..<commit>^ -- <path>
	166
	167	Melhor ainda, se você quiser restringir essa saída a uma única função (porque é
	168	onde o conflito aparece), você pode usar a seguinte sintaxe::
	169
	170	git log -L:'\<function\>':<path> HEAD..<commit>^
	171
	172	.. note::
	173	O ``\<`` e o ``\>`` ao redor do nome da função garantem que as
	174	correspondências fiquem ancoradas em um limite de palavra. Isso é
	175	importante, pois essa parte é na verdade uma regex e o git segue apenas a
	176	primeira correspondência; portanto, se você usar
	177	``-L:thread_stack:kernel/fork.c``, ele poderá fornecer apenas resultados
	178	para a função ``try_release_thread_stack_to_cache``, embora existam muitas
	179	outras funções naquele arquivo contendo a string ``thread_stack`` em seus
	180	nomes.
	181
	182	Outra opção útil para o ``git log`` é a ``-G``, que permite filtrar por certas
	183	strings que aparecem nos diffs dos commits que você está listando::
	184
	185	git log -G'regex' HEAD..<commit>^ -- <path>
	186
	187	Esta também pode ser uma maneira prática de encontrar rapidamente quando algo
	188	(por exemplo, uma chamada de função ou uma variável) foi alterado, adicionado
	189	ou removido. A string de busca é uma expressão regular, o que significa que você
	190	pode potencialmente buscar por coisas mais específicas, como atribuições a um
	191	membro específico de uma struct::
	192
	193	git log -G'\->index\>.*='
	194
	195	git blame
	196	~~~~~~~~~
	197
	198	Outra maneira de encontrar commits pré-requisitos (embora apenas o mais recente
	199	para um determinado conflito) é executar o ``git blame``. Neste caso, você
	200	precisa executá-lo no commit pai do patch para o qual está fazendo o
	201	cherry-pick e no arquivo onde o conflito apareceu, ou seja::
	202
	203	git blame <commit>^ -- <path>
	204
	205	Este comando também aceita o argumento ``-L`` (para restringir a saída a uma
	206	única função), mas, neste caso, você especifica o nome do arquivo no final do
	207	comando, como de costume::
	208
	209	git blame -L:'\<function\>' <commit>^ -- <path>
	210
	211	Navegue até o local onde o conflito ocorreu. A primeira coluna da saída do
	212	blame é o ID do commit do patch que adicionou uma determinada linha de código.
	213
	214	Pode ser uma boa ideia dar um ``git show`` nesses commits e ver se eles se
	215	parecem com a possível origem do conflito. Às vezes, haverá mais de um desses
	216	commits, seja porque múltiplos commits alteraram linhas diferentes da mesma área
	217	de conflito ou porque múltiplos patches subsequentes alteraram a mesma linha
	218	(ou linhas) várias vezes. Neste último caso, você pode ter que executar o
	219	``git blame`` novamente e especificar a versão mais antiga do arquivo para
	220	analisar, a fim de cavar mais fundo no histórico do arquivo.
	221
	222	Patches pré-requisitos vs. incidentais
	223	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	224
	225	Tendo encontrado o patch que causou o conflito, você precisa determinar se ele
	226	é um pré-requisito para o patch que você está fazendo o backport ou se é apenas
	227	incidental e pode ser pulado. Um patch incidental seria aquele que toca no mesmo
	228	código que o patch para o qual você está fazendo o backport, mas não altera a
	229	semântica do código de nenhuma forma relevante. Por exemplo, um patch de limpeza
	230	de espaços em branco é completamente incidental -- da mesma forma, um patch que
	231	simplesmente renomeia uma função ou uma variável também seria incidental. Por
	232	outro lado, se a função que está sendo alterada sequer existe na sua ramificação
	233	atual, então isso não seria nada incidental e você precisa considerar com
	234	cuidado se o patch que adiciona a função deve ser aplicado via cherry-pick
	235	primeiro.
	236
	237	Se você descobrir que há um patch pré-requisito necessário, então você precisa
	238	parar e fazer o cherry-pick dele em vez disso. Se você já resolveu alguns
	239	conflitos em um arquivo diferente e não quer fazer isso de novo, você pode
	240	criar uma cópia temporária daquele arquivo.
	241
	242	Para abortar o cherry-pick atual, vá em frente e execute
	243	``git cherry-pick --abort`` e, em seguida, reinicie o processo de cherry-pick
	244	com o ID do commit do patch pré-requisito.
	245
	246	Entendendo os marcadores de conflito
	247	------------------------------------
	248
	249	Diffs combinados
	250	~~~~~~~~~~~~~~~~
	251
	252	Digamos que você tenha decidido não fazer o cherry-pick (ou o revert) de patches
	253	adicionais e quer apenas resolver o conflito. O Git terá inserido marcadores de
	254	conflito no seu arquivo. Por padrão, isso se parecerá com algo como::
	255
	256	<<<<<<< HEAD
	257	this is what's in your current tree before cherry-picking
	258	=======
	259	this is what the patch wants it to be after cherry-picking
	260	>>>>>>> <commit>... title
	261
	262	Isso é o que você veria se abrisse o arquivo no seu editor. No entanto, se você
	263	executasse o ``git diff`` sem nenhum argumento, a saída seria algo assim::
	264
	265	$ git diff
	266	[...]
	267	++<<<<<<<< HEAD
	268	+this is what's in your current tree before cherry-picking
	269	++========
	270	+ this is what the patch wants it to be after cherry-picking
	271	++>>>>>>>> <commit>... title
	272
	273	Quando você está resolvendo um conflito, o comportamento do ``git diff`` difere
	274	do seu comportamento normal. Note as duas colunas de marcadores de diff em vez
	275	da coluna única usual; este é o chamado "`diff combinado`_", aqui mostrando o
	276	diff de 3 vias (ou diff-de-diffs) entre:
	277
	278	#. a ramificação atual (antes do cherry-pick) e o diretório de trabalho atual, e
	279	#. a ramificação atual (antes do cherry-pick) e o arquivo como ele fica após o
	280	patch original ter sido aplicado.
	281
	282	.. _diff combinado: https://git-scm.com/docs/diff-format#_combined_diff_format
	283
	284	Diffs melhores
	285	~~~~~~~~~~~~~~
	286
	287	Diffs combinados de 3 vias incluem todas as outras alterações que aconteceram
	288	no arquivo entre a sua ramificação atual e a ramificação a partir da qual você
	289	está fazendo o cherry-pick. Embora isso seja útil para detectar outras
	290	alterações que você precisa levar em consideração, também torna a saída do
	291	``git diff`` um tanto intimidadora e difícil de ler. Em vez disso, você pode
	292	preferir executar ``git diff HEAD`` (ou ``git diff --ours``), que mostra apenas
	293	o diff entre a ramificação atual antes do cherry-pick e o diretório de trabalho
	294	atual. Ele se parece com isso::
	295
	296	$ git diff HEAD
	297	[...]
	298	+<<<<<<<< HEAD
	299	this is what's in your current tree before cherry-picking
	300	+========
	301	+this is what the patch wants it to be after cherry-picking
	302	+>>>>>>>> <commit>... title
	303
	304	Como você pode ver, isso é lido exatamente como qualquer outro diff e deixa claro
	305	quais linhas estão na ramificação atual e quais linhas estão sendo adicionadas
	306	porque fazem parte do conflito de mesclagem ou do patch que está sendo aplicado
	307	via cherry-pick.
	308
	309	Estilos de mesclagem e diff3
	310	~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	311
	312	O estilo padrão de marcador de conflito mostrado acima é conhecido como o estilo
	313	``merge``. Também está disponível um outro estilo, conhecido como o estilo
	314	``diff3``, que se parece com isso::
	315
	316	<<<<<<< HEAD
	317	this is what is in your current tree before cherry-picking
	318	\|\|\|\|\|\|\| parent of <commit> (title)
	319	this is what the patch expected to find there
	320	=======
	321	this is what the patch wants it to be after being applied
	322	>>>>>>> <commit> (title)
	323
	324	Como você pode ver, isso tem 3 partes em vez de 2, e inclui o que o git
	325	esperava encontrar lá, mas não encontrou. É altamente recomendável usar este
	326	estilo de conflito, pois deixa muito mais claro o que o patch realmente alterou;
	327	ou seja, ele permite que você compare as versões de antes e depois do arquivo
	328	para o commit do qual está fazendo o cherry-pick. Isso permite que você tome
	329	melhores decisões sobre como resolver o conflito.
	330
	331	Para alterar os estilos de marcadores de conflito, você pode usar o seguinte
	332	comando::
	333
	334	git config merge.conflictStyle diff3
	335
	336	Existe uma terceira opção, ``zdiff3``, introduzida no `Git 2.35`_, que possui as
	337	mesmas 3 seções do ``diff3``, mas onde as linhas comuns foram cortadas, tornando
	338	a área de conflito menor em alguns casos.
	339
	340	.. _Git 2.35: https://github.blog/2022-01-24-highlights-from-git-2-35/
	341
	342	Iterando em resoluções de conflito
	343	----------------------------------
	344
	345	O primeiro passo em qualquer processo de resolução de conflito é entender o
	346	patch para o qual você está fazendo o backport. Para o kernel Linux, isso é
	347	especialmente importante, pois uma alteração incorreta pode levar ao travamento
	348	de todo o sistema -- ou pior, a uma vulnerabilidade de segurança não detectada.
	349
	350	Entender o patch pode ser fácil ou difícil, dependendo do próprio patch, do
	351	registro de alterações (changelog) e da sua familiaridade com o código que está
	352	sendo alterado. No entanto, uma boa pergunta para cada alteração (ou cada bloco/
	353	hunk do patch) seria: "Por que este hunk está no patch?" As respostas a essas
	354	perguntas orientarão a sua resolução de conflito.
	355
	356	Processo de resolução
	357	~~~~~~~~~~~~~~~~~~~~~
	358
	359	Às vezes, a coisa mais fácil a fazer é apenas remover tudo, exceto a primeira
	360	parteda do conflito, deixando o arquivo essencialmente inalterado, e aplicar
	361	as alterações manualmente. Talvez o patch esteja alterando um argumento de
	362	chamada de função de ``0`` para ``1``, enquanto uma alteração conflitante
	363	adicionou um parâmetro totalmente novo (e insignificante) ao final da lista de
	364	parâmetros; nesse caso, é bastante fácil alterar o argumento de ``0`` para ``1``
	365	manualmente e deixar o restante dos argumentos como estão. Esta técnica de
	366	aplicar alterações manualmente é mais útil se o conflito tiver trazido muito
	367	contexto não relacionado com o qual você não precisa realmente se preocupar.
	368
	369	Para conflitos particularmente difíceis com muitos marcadores de conflito, você
	370	pode usar ``git add`` ou ``git add -i`` para indexar (stage) seletivamente as
	371	suas resoluções para tirá-las do caminho; isso também permite que você use
	372	``git diff HEAD`` para ver sempre o que ainda resta a ser resolvido ou
	373	``git diff --cached`` para ver como está o seu patch até o momento.
	374
	375	Lidando com arquivos renomeados
	376	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	377
	378	Uma das coisas mais irritantes que podem acontecer ao fazer o backport de um
	379	patch é descobrir que um dos arquivos modificados foi renomeado, pois isso
	380	geralmente significa que o git sequer colocará marcadores de conflito, mas
	381	apenas lavará as mãos e dirá (parafraseando): "Caminho não mesclado! Faça você o
	382	trabalho..."
	383
	384	Geralmente existem algumas maneiras de lidar com isso. Se o patch para o
	385	arquivo renomeado for pequeno, como uma alteração de uma única linha, a coisa
	386	mais fácil é prosseguir, aplicar a alteração manualmente e dar o caso por
	387	encerrado. Por outro lado, se a alteração for grande ou complicada, você
	388	definitivamente não vai querer fazê-la manualmente.
	389
	390	Como uma primeira tentativa, você pode tentar algo assim, que reduzirá o limite
	391	(threshold) de detecção de renomeação para 30% (por padrão, o git usa 50%, o que
	392	significa que dois arquivos precisam ter pelo menos 50% em comum para que ele
	393	considere um par de adição/remoção como uma renomeação potencial)::
	394
	395	git cherry-pick -strategy=recursive -Xrename-threshold=30
	396
	397	Às vezes, a coisa certa a fazer será fazer o backport também do patch que
	398	realizou a renomeação, mas esse definitivamente não é o caso mais comum. Em vez
	399	disso, o que você pode fazer é renomear temporariamente o arquivo na
	400	ramificação para a qual está fazendo o backport (usando ``git mv`` e commitando
	401	o resultado), reiniciar a tentativa de cherry-pick do patch, renomear o arquivo
	402	de volta (``git mv`` e commitando novamente) e, finalmente, esmagar (squash) o
	403	resultado usando ``git rebase -i`` (veja o `tutorial de rebase`_) para que ele
	404	apareça como um único commit quando você terminar.
	405
	406	.. _tutorial de rebase: [https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ec](https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ec)
	407
	408	Pegadinhas
	409	----------
	410
	411	Argumentos de função
	412	~~~~~~~~~~~~~~~~~~~~
	413
	414	Preste atenção às alterações em argumentos de função! É fácil deixar passar
	415	detalhes e pensar que duas linhas são iguais quando, na verdade, elas diferem em
	416	algum pequeno detalhe, como qual variável foi passada como argumento
	417	(especialmente se as duas variáveis forem de apenas um caractere e parecerem
	418	iguais, como i e j).
	419
	420	Tratamento de erros
	421	~~~~~~~~~~~~~~~~~~~
	422
	423	Se você fizer o cherry-pick de um patch que inclua uma instrução ``goto``
	424	(geralmente para tratamento de erros), é absolutamente imperativo verificar em
	425	dobro se o rótulo (label) de destino ainda está correto na ramificação para a
	426	qual você está fazendo o backport. O mesmo vale para instruções ``return``,
	427	``break`` e ``continue`` adicionadas.
	428
	429	O tratamento de erros geralmente fica localizado no final da função, portanto,
	430	pode não fazer parte do conflito, mesmo que possa ter sido alterado por outros
	431	patches.
	432
	433	Uma boa maneira de garantir que você revise os caminhos de erro é sempre usar
	434	``git diff -W`` e ``git show -W`` (também conhecido como ``--function-context``)
	435	ao inspecionar suas alterações. Para código em C, isso mostrará toda a função
	436	que está sendo alterada em um patch. Uma das coisas que frequentemente dão
	437	errado durante backports é que algo mais na função mudou em qualquer uma das
	438	ramificações a partir da qual ou para a qual você está fazendo o backport. Ao
	439	incluir a função inteira no diff, você obtém mais contexto e pode identificar
	440	mais facilmente problemas que de outra forma poderiam passar despercebidos.
	441
	442	Código refatorado
	443	~~~~~~~~~~~~~~~~~
	444
	445	Algo que acontece com bastante frequência é o código ser refatorado ao "isolar"
	446	uma sequência ou padrão de código comum em uma função auxiliar. Ao fazer o
	447	backport de patches para uma área onde tal refatoração ocorreu, você efetivamente
	448	precisa fazer o inverso ao realizar o backport: um patch para um único local pode
	449	precisar ser aplicado a múltiplos locais na versão que recebeu o backport. (Um
	450	indicativo para este cenário é que uma função foi renomeada -- mas nem sempre é o
	451	caso.)
	452
	453	Para evitar backports incompletos, vale a pena tentar descobrir se o patch
	454	corrige um bug que aparece em mais de um lugar. Uma maneira de fazer isso seria
	455	usar o ``git grep``. (Isso, na verdade, é uma boa ideia de se fazer em geral, não
	456	apenas para backports.) Se você descobrir que o mesmo tipo de correção se
	457	aplicaria a outros lugares, também vale a pena ver se esses lugares existem no
	458	upstream -- se não existirem, é provável que o patch precise ser ajustado. O
	459	``git log`` é seu amigo para descobrir o que aconteceu com essas áreas, já que o
	460	``git blame`` não mostrará código que foi removido.
	461
	462	Se você encontrar outras instâncias do mesmo padrão na árvore do upstream e não
	463	tiver certeza se isso também é um bug, pode valer a pena perguntar ao autor do
	464	patch. Não é incomum encontrar novos bugs durante o processo de backport!
	465
	466	Verificando o resultado
	467	=======================
	468
	469	colordiff
	470	---------
	471
	472	Tendo commitado um novo patch sem conflitos, você pode agora comparar o seu
	473	patch com o patch original. É altamente recomendável que você use uma
	474	ferramenta como o `colordiff`_ que possa mostrar dois arquivos lado a lado e
	475	colori-los de acordo com as alterações entre eles::
	476
	477	colordiff -yw -W 200 <(git diff -W <upstream commit>^-) <(git diff -W HEAD^-) \| less -SR
	478
	479	.. _colordiff: https://www.colordiff.org/
	480
	481	Aqui, ``-y`` significa fazer uma comparação lado a lado; ``-w`` ignora
	482	espaços em branco e ``-W 200`` define a largura da saída (caso contrário, ele
	483	usará 130 por padrão, o que costuma ser um pouco pouco).
	484
	485	A sintaxe ``rev^-`` é um atalho prático para ``rev^..rev``, essencialmente
	486	fornecendo apenas o diff para aquele único commit; veja também a
	487	`documentação oficial do git rev-parse`_.
	488
	489	.. _documentação oficial do git rev-parse: https://git-scm.com/docs/git-rev-parse#_other_rev_parent_shorthand_notations
	490
	491	Novamente, note a inclusão de ``-W`` para o ``git diff``; isso garante que você
	492	verá a função completa para qualquer função que tenha mudado.
	493
	494	Uma coisa incrivelmente importante que o colordiff faz é destacar as linhas que
	495	são diferentes. Por exemplo, se um ``goto`` de tratamento de erros teve seus
	496	rótulos alterados entre o patch original e o que sofreu o backport, o colordiff
	497	irá mostrá-los lado a lado, mas destacados em uma cor diferente. Assim, é fácil
	498	ver que as duas instruções ``goto`` estão saltando para rótulos diferentes. Da
	499	mesma forma, linhas que não foram modificadas por nenhum dos patches, mas que
	500	diferem no contexto, também serão destacadas e, portanto, se destacarão durante
	501	uma inspeção manual.
	502
	503	Claro, esta é apenas uma inspeção visual; o teste real é compilar e executar o
	504	kernel (ou programa) com o patch aplicado.
	505
	506	Testes de compilação (Build testing)
	507	------------------------------------
	508
	509	Não abordaremos os testes em tempo de execução aqui, mas pode ser uma boa ideia
	510	compilar apenas os arquivos tocados pelo patch como uma verificação rápida de
	511	sanidade. Para o kernel Linux, você pode compilar arquivos únicos assim,
	512	assumindo que você tenha o ``.config`` e o ambiente de compilação configurados
	513	corretamente::
	514
	515	make caminho/para/o/arquivo.o
	516
	517	Note que isso não descobrirá erros de ligação (linker errors), então você ainda
	518	deve fazer uma compilação completa após verificar que o arquivo único compila.
	519	Ao compilar o arquivo único primeiro, você pode evitar ter que esperar por uma
	520	compilação completa caso haja erros de compilador em qualquer um dos arquivos
	521	que você alterou.
	522
	523	Testes em tempo de execução
	524	---------------------------
	525
	526	Mesmo um teste de compilação ou de boot bem-sucedido não é necessariamente o
	527	suficiente para descartar uma dependência ausente em algum lugar. Embora as
	528	chances sejam pequenas, pode haver alterações de código onde duas modificações
	529	independentes no mesmo arquivo resultem em nenhum conflito, nenhum erro em tempo
	530	de compilação e erros em tempo de execução apenas em casos excepcionais.
	531
	532	Um exemplo concreto disso foi um par de patches para o código de entrada de
	533	chamada de sistema (system call entry code), onde o primeiro patch salvava/
	534	restaurava um registrador e um patch posterior fazia uso do mesmo registrador
	535	em algum lugar no meio dessa sequência. Como não havia sobreposição entre as
	536	alterações, era possível fazer o cherry-pick do segundo patch, não ter conflitos
	537	e acreditar que tudo estava bem, quando na verdade o código estava agora
	538	sobrescrevendo (scribbling over) um registrador não salvo.
	539
	540	Embora a vasta maioria dos erros seja capturada durante a compilação ou ao
	541	exercitar o código superficialmente, a única maneira de realmente verificar um
	542	backport é revisar o patch final com o mesmo nível de escrutínio que você daria
	543	(ou deveria dar) a qualquer outro patch. Ter testes unitários e testes de
	544	regressão ou outros tipos de testes automáticos pode ajudar a aumentar a
	545	confiança na correção de um backport.
	546
	547	Enviando backports para a árvore estável (stable)
	548	=================================================
	549
	550	À medida que os mantenedores da árvore estável tentam aplicar correções da linha
	551	principal (mainline) em seus kernels estáveis via cherry-pick, eles podem enviar
	552	e-mails solicitando backports quando encontram conflitos; veja, por exemplo,
	553	<https://lore.kernel.org/stable/2023101528-jawed-shelving-071a@gregkh/>.
	554	Esses e-mails normalmente incluem os passos exatos que você precisa seguir para
	555	fazer o cherry-pick do patch para a árvore correta e enviá-lo.
	556
	557	Uma coisa a se certificar é que o seu registro de alterações (changelog) esteja
	558	em conformidade com o formato esperado::
	559
	560	<original patch title>
	561
	562	[ Upstream commit <mainline rev> ]
	563
	564	<rest of the original changelog>
	565	[ <summary of the conflicts and their resolutions> ]
	566	Signed-off-by: <your name and email>
	567
	568	A linha "Upstream commit" às vezes é ligeiramente diferente dependendo da versão
	569	estável. Versões mais antigas usavam este formato::
	570
	571	commit <mainline rev> upstream.
	572
	573	O mais comum é indicar a versão do kernel à qual o patch se aplica na linha de
	574	assunto do e-mail (usando, por exemplo,
	575	``git send-email --subject-prefix='PATCH 6.1.y'``), mas você também pode
	576	colocá-la na área do Signed-off-by: ou abaixo da linha ``---``.
	577
	578	Os mantenedores da árvore estável esperam envios separados para cada versão
	579	estável ativa, e cada envio também deve ser testado separadamente.
	580
	581	Algumas palavras finais de conselho
	582	===================================
	583
	584	1) Aborde o processo de backport com humildade.
	585	2) Entenda o patch para o qual você está fazendo o backport; isso significa ler
	586	tanto o registro de alterações (changelog) quanto o código.
	587	3) Seja honesto sobre a sua confiança no resultado ao enviar o patch.
	588	4) Peça aprovações explícitas (acks) aos mantenedores relevantes.
	589
	590	Exemplos
	591	========
	592
	593	O texto acima mostra, de forma geral, o processo idealizado de backport de um
	594	patch. Para um exemplo mais concreto, veja este tutorial em vídeo onde dois
	595	patches são portados da linha principal (mainline) para a estável (stable):
	596	`Backporting Linux Kernel Patches`_.
	597
	598	.. _Backporting Linux Kernel Patches: https://youtu.be/sBR7R1V2FeA

Documentation/translations/pt_BR/process/botching-up-ioctls.rst+256−0

@@ -0,0 +1,256 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	============================================
	4	(Como evitar) Deixar as ioctls malfeitas
	5	============================================
	6
	7	De: https://blog.ffwll.ch/2013/11/botching-up-ioctls.html
	8
	9	Por: Daniel Vetter, Copyright © 2013 Intel Corporation
	10
	11	Uma percepção clara que os hackers de gráficos do kernel tiveram nos últimos
	12	anos é que tentar criar uma interface unificada para gerenciar as unidades de
	13	execução e a memória em GPUs completamente diferentes é um esforço inútil.
	14	Portanto, hoje em dia, cada driver tem seu próprio conjunto de ioctls para
	15	alocar memória e enviar trabalho para a GPU. O que é bom, já que não há mais a
	16	insanidade na forma de interfaces falsamente genéricas, mas que na verdade só
	17	são usadas uma vez. No entanto, a desvantagem clara é que há muito mais
	18	potencial para estragar as coisas.
	19
	20	Para evitar repetir todos os mesmos erros novamente, escrevi algumas das lições
	21	aprendidas enquanto fazia um trabalho malfeito para o driver drm/i915. A maioria
	22	delas aborda apenas tecnicalidades e não os problemas macro (big-picture), como
	23	deveria ser exatamente a aparência da ioctl de envio de comando. Aprender essas
	24	lições é provavelmente algo que cada driver de GPU tem que fazer por conta
	25	própria.
	26
	27
	28	Pré-requisitos
	29	--------------
	30
	31	Primeiro, os pré-requisitos. Sem estes você já falhou, porque precisará
	32	adicionar uma camada de compatibilidade de 32 bits (compat layer):
	33
	34	* Use apenas inteiros de tamanho fixo. Para evitar conflitos com typedefs no
	35	espaço de usuário (userspace), o kernel possui tipos especiais como __u32 e
	36	__s64. Use-os.
	37
	38	* Alinhe tudo ao tamanho natural e use preenchimento (padding) explícito.
	39	Plataformas de 32 bits não alinham necessariamente valores de 64 bits a
	40	limites (boundaries) de 64 bits, mas plataformas de 64 bits o fazem. Portanto,
	41	sempre precisamos de padding para o tamanho natural para acertar isso.
	42
	43	* Preencha a struct inteira para um múltiplo de 64 bits se a estrutura contiver
	44	tipos de 64 bits -- caso contrário, o tamanho da estrutura diferirá entre
	45	32 bits e 64 bits. Ter um tamanho de estrutura diferente prejudica ao passar
	46	matrizes (arrays) de estruturas para o kernel, ou se o kernel verificar o
	47	tamanho da estrutura, o que o core do drm, por exemplo, faz.
	48
	49	* Ponteiros são __u64, convertidos de/para um uintptr_t no lado do espaço de
	50	usuário e de/para um void __user * no kernel. Tente de verdade não atrasar
	51	essa conversão ou, pior ainda, manipular o __u64 bruto pelo seu código, pois
	52	isso diminui a verificação que ferramentas como o sparse podem fornecer. A
	53	macro u64_to_user_ptr pode ser usada no kernel para evitar avisos sobre
	54	inteiros e ponteiros de tamanhos diferentes.
	55
	56
	57	Conceitos básicos
	58	-----------------
	59
	60	Evitadas as alegrias de escrever uma camada de compatibilidade (compat layer),
	61	podemos dar uma olhada nos deslizes básicos. Negligenciar estes pontos tornará a
	62	compatibilidade retroativa e futura uma verdadeira dor de cabeça. E, como errar
	63	na primeira tentativa é garantido, você certamente terá uma segunda iteração ou,
	64	pelo menos, uma extensão para qualquer interface fornecida.
	65
	66	* Tenha uma maneira clara para o espaço de usuário descobrir se a sua nova
	67	ioctl ou extensão de ioctl é suportada em um determinado kernel. Se você não
	68	puder confiar que os kernels antigos rejeitarão as novas flags/modos ou
	69	ioctls (já que fazer isso foi deixado de lado no passado), então você
	70	precisará de uma flag de recurso (feature flag) do driver ou de um número de
	71	revisão em algum lugar.
	72
	73	* Tenha um plano para estender as ioctls com novas flags ou novos campos no
	74	final da estrutura. O core do drm verifica o tamanho passado para cada
	75	chamada de ioctl e preenche com zero (zero-extends) quaisquer divergências
	76	entre o kernel e o espaço de usuário. Isso ajuda, mas não é uma solução
	77	completa, já que um espaço de usuário mais novo em um kernel mais antigo não
	78	notará que os campos recém-adicionados no final estão sendo ignorados.
	79	Portanto, isso ainda exige novas flags de recurso do driver.
	80
	81	* Verifique todos os campos e flags não utilizados, além de todo o preenchimento
	82	(padding), para garantir que estejam em 0, e rejeite a ioctl se esse não for
	83	o caso. Caso contrário, seu excelente plano para extensões futuras irá por
	84	água abaixo, pois alguém enviará uma struct de ioctl com lixo de pilha
	85	(stack garbage) aleatório nas partes ainda não utilizadas. O que, então,
	86	consolida na ABI que esses campos nunca poderão ser usados para nada além de
	87	lixo. Esta também é a razão pela qual você deve preencher explicitamente todas
	88	as estruturas, mesmo que nunca as use em uma matriz (array) -- o padding que
	89	o compilador possa inserir poderia conter lixo.
	90
	91	* Tenha casos de teste simples para tudo o que foi mencionado acima.
	92
	93
	94	Diversão com caminhos de erro (Error Paths)
	95	-------------------------------------------
	96
	97	Hoje em dia, não temos mais nenhuma desculpa para que os drivers drm sejam pequenos
	98	exploits de root disfarçados. Isso significa que precisamos tanto de uma
	99	validação completa de entrada quanto de caminhos sólidos de tratamento de erros
	100	-- as GPUs eventualmente vão parar de funcionar (die) nos casos mais bizarros
	101	de qualquer maneira:
	102
	103	* A ioctl deve verificar se há estouros de matriz (array overflows). Ela também
	104	precisa verificar estouros superiores/inferiores (over/underflows) e problemas
	105	de limitação (clamping) de valores inteiros em geral. O exemplo usual são os
	106	valores de posicionamento de sprite alimentados diretamente no hardware, onde
	107	o hardware possui apenas 12 bits ou algo assim. Funciona perfeitamente até que
	108	algum servidor de exibição bizarro não se preocupe em fazer o clamping por si
	109	mesmo e o cursor dê a volta (wrap around) na tela.
	110
	111	* Tenha casos de teste simples para cada caso de falha de validação de entrada
	112	na sua ioctl. Verifique se o código de erro corresponde às suas expectativas.
	113	E, finalmente, certifique-se de testar apenas um único caminho de erro em
	114	cada subteste, enviando dados que, de outra forma, seriam perfeitamente
	115	válidos. Sem isso, uma verificação anterior já poderia rejeitar a ioctl e
	116	ofuscar (shadow) o caminho de código que você realmente deseja testar,
	117	ocultando bugs e regressões.
	118
	119	* Torne todas as suas ioctls reiniciáveis (restartable). Primeiro, o X (X11)
	120	realmente ama sinais (signals) e, segundo, isso permitirá que você teste 90%
	121	de todos os caminhos de tratamento de erro apenas interrompendo sua suíte de
	122	testes principal constantemente com sinais. Graças ao amor do X por sinais,
	123	você obterá uma excelente cobertura de base de todos os seus caminhos de erro
	124	praticamente de graça para drivers de gráficos. Além disso, seja consistente
	125	na forma como você lida com a reinicialização de ioctls -- por exemplo, o drm
	126	possui um pequeno helper drmIoctl em sua biblioteca de espaço de usuário. O
	127	driver i915 estragou isso com a ioctl set_tiling; agora estamos presos para
	128	sempre com algumas semânticas arcanas tanto no kernel quanto no espaço de
	129	usuário.
	130
	131	* Se você não puder tornar um determinado caminho de código reiniciável, torne
	132	uma tarefa travada pelo menos finalizável (killable). As GPUs simplesmente
	133	morrem, e seus usuários não vão gostar mais de você se você travar a máquina
	134	inteira deles (por meio de um processo do X impossível de matar). Se a
	135	recuperação de estado ainda for muito complicada, tenha um timeout ou uma
	136	rede de segurança de verificação de travamento (hangcheck) como um esforço de
	137	última hora (last-ditch) caso o hardware enlouqueça (gone bananas).
	138
	139	* Tenha casos de teste para os cenários mais complexos (corner cases) no seu
	140	código de recuperação de erros -- é fácil demais criar um deadlock entre seu
	141	código de hangcheck e os processos que estão aguardando (waiters).
	142
	143
	144	Tempo, Espera e a Perda de Prazos
	145	---------------------------------
	146
	147	As GPUs fazem quase tudo de forma assíncrona, portanto, temos a necessidade de
	148	cronometrar operações e aguardar pelas que estão pendentes. Esse é um negócio
	149	realmente complicado; no momento, nenhuma das ioctls suportadas pelo drm/i915
	150	acerta isso completamente, o que significa que ainda há toneladas de lições para
	151	aprender aqui.
	152
	153	* Use CLOCK_MONOTONIC como seu tempo de referência, sempre. É o que o alsa, o
	154	drm e o v4l usam por padrão hoje em dia. Mas informe ao espaço de usuário
	155	quais carimbos de data/hora (timestamps) são derivados de domínios de relógio
	156	diferentes, como o relógio principal do seu sistema (fornecido pelo kernel)
	157	ou algum contador de hardware independente em outro lugar. Os relógios vão
	158	divergir se você olhar de perto o suficiente, mas se as ferramentas de
	159	medição de desempenho tiverem essa informação, elas poderão ao menos compensar.
	160	Se o seu espaço de usuário puder obter os valores brutos de alguns relógios
	161	(por exemplo, por meio de instruções de amostragem de contador de desempenho
	162	no fluxo de comandos), considere expor esses também.
	163
	164	* Use __s64 para segundos mais __u64 para nanossegundos para especificar o
	165	tempo. Não é a especificação de tempo mais conveniente, mas é praticamente o
	166	padrão.
	167
	168	* Verifique se os valores de tempo de entrada estão normalizados e rejeite-os
	169	caso contrário. Note que a struct nativa do kernel, ktime, possui um inteiro
	170	sinalizado tanto para segundos quanto para nanossegundos, portanto, cuidado
	171	aqui.
	172
	173	* Para timeouts, use tempos absolutos. Se você for um bom sujeito e tiver
	174	tornado a sua ioctl reiniciável, os timeouts relativos tendem a ser muito
	175	imprecisos (coarse) e podem estender indefinidamente o seu tempo de espera
	176	devido ao arredondamento a cada reinicialização. Especialmente se o seu relógio
	177	de referência for algo realmente lento, como o contador de quadros da tela
	178	(display frame counter). Vestindo o chapéu de advogado de especificações, isso
	179	não é um bug, já que os timeouts sempre podem ser estendidos -- mas os usuários
	180	com certeza vão odiar você se as belas animações deles começarem a gaguejar
	181	(stutter) devido a isso.
	182
	183	* Considere descartar quaisquer ioctls de espera síncrona com timeouts e apenas
	184	entregue um evento assíncrono em um descritor de arquivo passível de poll
	185	(pollable file descriptor). Isso se encaixa muito melhor no loop principal de
	186	aplicações orientadas a eventos.
	187
	188	* Tenha casos de teste para cenários complexos (corner-cases), especialmente se
	189	os valores de retorno para eventos já concluídos, esperas bem-sucedidas e
	190	esperas que estouraram o tempo (timed-out) são todos sãos e adequados às suas
	191	necessidades.
	192
	193
	194	Evitando o vazamento de recursos (Leaking Resources, Not)
	195	---------------------------------------------------------
	196
	197	Um driver drm completo essencialmente implementa um pequeno SO, mas especializado
	198	para as plataformas de GPU fornecidas. Isso significa que um driver precisa
	199	expor toneladas de handles (identificadores) para diferentes objetos e outros
	200	recursos para o espaço de usuário. Fazer isso corretamente traz seu próprio
	201	pequeno conjunto de armadilhas:
	202
	203	* Sempre vincule o tempo de vida (lifetime) de seus recursos criados
	204	dinamicamente ao tempo de vida de um descritor de arquivo (file descriptor -
	205	fd). Considere usar um mapeamento 1:1 se o seu recurso precisar ser
	206	compartilhado entre processos -- a passagem de fds sobre unix domain sockets
	207	também simplifica o gerenciamento do tempo de vida para o espaço de usuário.
	208
	209	* Sempre tenha suporte a O_CLOEXEC.
	210
	211	* Certifique-se de que você tem isolamento suficiente entre os diferentes
	212	clientes. Por padrão, escolha um namespace privado por fd, o que força
	213	qualquer compartilhamento a ser feito de forma explícita. Só adote um
	214	namespace mais global por dispositivo se os objetos forem verdadeiramente
	215	únicos do dispositivo. Um contraexemplo nas interfaces de modeset do drm é
	216	que os objetos de modeset por dispositivo, como conectores, compartilham um
	217	namespace com objetos de framebuffer, que na maioria das vezes não são
	218	compartilhados de forma alguma. Um namespace separado, privado por padrão,
	219	para os framebuffers teria sido mais adequado.
	220
	221	* Pense sobre os requisitos de unicidade para os handles do espaço de usuário.
	222	Por exemplo, para a maioria dos drivers drm, é um bug do espaço de usuário
	223	enviar o mesmo objeto duas vezes na mesma ioctl de envio de comando. Mas,
	224	se os objetos forem compartilháveis, o espaço de usuário precisa saber se
	225	já viu um objeto importado de outro processo ou não. Eu ainda não tentei isso
	226	sozinho devido à falta de uma nova classe de objetos, mas considere usar
	227	números de inode em seus descritores de arquivo compartilhados como
	228	identificadores únicos -- é assim que arquivos reais também são diferenciados.
	229	Infelizmente, isso requer um sistema de arquivos virtual completo no kernel.
	230
	231
	232	Por último, mas não menos importante
	233	------------------------------------
	234
	235	Nem todo problema precisa de uma nova ioctl:
	236
	237	* Pense bem se você realmente quer uma interface privada do driver. Claro que
	238	é muito mais rápido aprovar uma interface privada do driver do que se envolver
	239	em discussões longas por uma solução mais genérica. E, ocasionalmente, criar
	240	uma interface privada para liderar um novo conceito é o que se exige. Mas,
	241	no final, assim que a interface genérica surgir, você acabará mantendo duas
	242	interfaces. Indefinidamente.
	243
	244	* Considere outras interfaces além de ioctls. Um atributo sysfs é muito melhor
	245	para configurações por dispositivo ou para objetos filhos com tempos de vida
	246	razoavelmente estáticos (como conectores de saída no drm com todos os seus
	247	atributos de sobreposição de detecção). Ou talvez apenas a sua suíte de
	248	testes precise dessa interface e, nesse caso, o debugfs, com seu aviso de
	249	isenção de responsabilidade por não ter uma ABI estável, seria melhor.
	250
	251	Finalmente, o objetivo principal é acertar na primeira tentativa, pois se o seu
	252	driver se provar popular e suas plataformas de hardware forem duradouras, você
	253	ficará preso a uma determinada ioctl essencialmente para sempre. Você pode
	254	tentar depreciar ioctls horríveis em iterações mais novas do seu hardware, mas
	255	geralmente leva anos para conseguir isso. E depois mais anos até que o último
	256	usuário capaz de reclamar sobre regressões desapareça também.

Documentation/translations/pt_BR/process/code-of-conduct-interpretation.rst+257−0

@@ -0,0 +1,257 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	Interpretação do Código de Conduta do Kernel Linux
	4	==================================================
	5
	6	O :ref:`pt_BR_code_of_conduct` é um documento geral que tem como objetivo
	7	fornecer um conjunto de regras para quase todas as comunidades de código
	8	aberto. Toda comunidade de código aberto é única e o kernel Linux não é
	9	exceção. Por causa disso, este documento descreve como nós, na comunidade
	10	do kernel Linux, o interpretaremos. Nós também não esperamos que esta
	11	interpretação seja estática ao longo do tempo, e a ajustaremos conforme
	12	necessário.
	13
	14	O esforço de desenvolvimento do kernel Linux é um processo muito pessoal
	15	em comparação com as formas "tradicionais" de desenvolvimento de software.
	16	Suas contribuições e as ideias por trás delas serão cuidadosamente
	17	revisadas, frequentemente resultando em críticas e apontamentos. A
	18	revisão quase sempre exigirá melhorias antes que o material possa ser
	19	incluído no kernel. Saiba que isso acontece porque todos os envolvidos
	20	querem ver a melhor solução possível para o sucesso geral do Linux. Este
	21	processo de desenvolvimento provou criar o kernel de sistema operacional
	22	mais robusto de todos os tempos, e nós não queremos fazer nada que cause
	23	a diminuição da qualidade do envio e do resultado final.
	24
	25	Mantenedores
	26	------------
	27
	28	O Código de Conduta usa o termo "mantenedores" várias vezes. Na
	29	comunidade do kernel, um "mantenedor" é qualquer pessoa responsável por
	30	um subsistema, driver ou arquivo, e que esteja listada no arquivo
	31	MAINTAINERS na árvore de código-fonte do kernel.
	32
	33	Responsabilidades
	34	-----------------
	35
	36	O Código de Conduta menciona direitos e responsabilidades para os
	37	mantenedores, e isso precisa de alguns esclarecimentos adicionais.
	38
	39	Em primeiro lugar e acima de tudo, é uma expectativa razoável que os
	40	mantenedores liderem pelo exemplo.
	41
	42	Dito isto, nossa comunidade é vasta e ampla, e não há um novo requisito
	43	para que os mantenedores lidem unilateralmente com o comportamento de
	44	outras pessoas nas partes da comunidade onde atuam. Essa responsabilidade
	45	é de todos nós e, em última análise, o Código de Conduta documenta os
	46	caminhos finais de escalonamento em caso de preocupações não resolvidas
	47	em relação a questões de conduta.
	48
	49	Os mantenedores devem estar dispostos a ajudar quando ocorrerem problemas
	50	e trabalhar com outras pessoas na comunidade quando necessário. Não tenha
	51	medo de entrar em contato com o Conselho Consultivo Técnico (TAB) ou
	52	outros mantenedores se não tiver certeza de como lidar com as situações
	53	que surgirem. Isso não será considerado um relato de violação, a menos
	54	que você queira que seja. Se não tiver certeza sobre como abordar o TAB
	55	ou quaisquer outros mantenedores, entre em contato com nossa mediadora
	56	de conflitos, Joanna Lee <jlee@linuxfoundation.org>.
	57
	58	No final, "sejam gentis uns com os outros" é realmente o objetivo final
	59	para todos. Sabemos que todos são humanos e que todos falhamos às vezes,
	60	mas o objetivo principal para todos nós deve ser trabalhar em direção a
	61	resoluções amigáveis dos problemas. A aplicação do código de conduta será
	62	apenas uma opção de último recurso.
	63
	64	Nosso objetivo de criar um sistema operacional robusto e tecnicamente
	65	avançado e a complexidade técnica envolvida exigem naturalmente
	66	conhecimento técnico e tomada de decisões.
	67
	68	O conhecimento técnico exigido varia dependendo da área de contribuição.
	69	Ele é determinado principalmente pelo contexto e pela complexidade técnica
	70	e apenas secundariamente pelas expectativas de contribuidores e
	71	mantenedores.
	72
	73	Tanto as expectativas de conhecimento técnico quanto a tomada de decisões
	74	estão sujeitas a discussão, mas no final das contas há uma necessidade
	75	básica de sermos capazes de tomar decisões para progredir. Esta
	76	prerrogativa está nas mãos dos mantenedores e da liderança do projeto e
	77	espera-se que seja usada de boa fé.
	78
	79	Como consequência, definir expectativas de conhecimento técnico, tomar
	80	decisões e rejeitar contribuições inadequadas não são vistos como uma
	81	violação do Código de Conduta.
	82
	83	Embora os mantenedores sejam em geral receptivos aos novatos, sua
	84	capacidade de ajudar os contribuidores a superar os obstáculos de entrada
	85	é limitada, portanto, eles devem definir prioridades. Isso, também, não
	86	deve ser visto como uma violação do Código de Conduta. A comunidade do
	87	kernel está ciente disso e fornece programas de nível de entrada de
	88	várias formas, como o kernelnewbies.org.
	89
	90	Escopo
	91	------
	92
	93	A comunidade do kernel Linux interage primariamente em um conjunto de listas
	94	de e-mail públicas distribuídas por vários servidores diferentes controlados
	95	por várias empresas ou indivíduos diferentes. Todas essas listas estão
	96	definidas no arquivo MAINTAINERS na árvore de código-fonte do kernel.
	97	Quaisquer e-mails enviados para essas listas de e-mail são considerados
	98	cobertos pelo Código de Conduta.
	99
	100	Desenvolvedores que usam o bugzilla do kernel.org e outras ferramentas de
	101	rastreamento de bugs ou bugzilla de subsistemas devem seguir as diretrizes
	102	do Código de Conduta. A comunidade do kernel Linux não possui um endereço
	103	de e-mail de projeto "oficial" ou endereço "oficial" de mídia social.
	104	Qualquer atividade realizada usando uma conta de e-mail do kernel.org deve
	105	seguir o Código de Conduta conforme publicado para o kernel.org, assim como
	106	qualquer indivíduo usando uma conta de e-mail corporativa deve seguir as
	107	regras específicas daquela corporação.
	108
	109	O Código de Conduta não proíbe que se continue a incluir nomes, endereços de
	110	e-mail e comentários associados em mensagens de listas de discussão,
	111	mensagens de log de alterações (changelog) do kernel ou comentários no
	112	código.
	113
	114	A interação em outros fóruns é coberta pelas regras que se aplicam a tais
	115	fóruns e, em geral, não é coberta pelo Código de Conduta. Exceções podem
	116	ser consideradas para circunstâncias extremas.
	117
	118	As contribuições enviadas para o kernel devem usar linguagem apropriada.
	119	O conteúdo já existente que precede o Código de Conduta não será tratado
	120	agora como uma violação. No entanto, a linguagem inapropriada pode ser vista
	121	como um bug; tais bugs serão corrigidos mais rapidamente se quaisquer partes
	122	interessadas enviarem patches com esse propósito. Expressões que atualmente
	123	fazem parte da API de usuário/kernel, ou que refletem a terminologia usada
	124	em padrões ou especificações publicadas, não são consideradas bugs.
	125
	126	Aplicação
	127	---------
	128
	129	O endereço listado no Código de Conduta vai para o Comitê do Código de
	130	Conduta. Os membros exatos que recebem esses e-mails a qualquer momento
	131	estão listados em https://kernel.org/code-of-conduct.html. Os membros não
	132	podem acessar relatos feitos antes de se juntarem ou após terem deixado o
	133	comitê.
	134
	135	O Comitê do Código de Conduta consiste em membros voluntários da comunidade
	136	nomeados pelo TAB, bem como um mediador profissional agindo como um terceiro
	137	neutro. Os processos que o comitê do Código de Conduta usará para lidar com
	138	os relatos variam e dependerão das circunstâncias individuais; no entanto,
	139	este arquivo serve como documentação para o processo geral utilizado.
	140
	141	Qualquer membro do comitê, incluindo o mediador, pode ser contatado
	142	diretamente se o relator não desejar incluir todo o comitê em uma
	143	reclamação ou preocupação.
	144
	145	O Comitê do Código de Conduta revisa os casos de acordo com os processos
	146	(veja acima) e consulta o TAB conforme a necessidade e a conveniência,
	147	por exemplo, para solicitar e receber informações sobre a comunidade do
	148	kernel.
	149
	150	Quaisquer decisões a respeito de recomendações de aplicação (enforcement)
	151	serão levadas ao TAB para implementação junto aos mantenedores relevantes,
	152	se necessário. Uma vez que o TAB aprove uma ou mais das medidas descritas
	153	no escopo do banimento pelo voto de dois terços dos membros, o Comitê do
	154	Código de Conduta aplicará as medidas aprovadas pelo TAB. Quaisquer membros
	155	do Comitê do Código de Conduta que sirvam no TAB não votarão nas medidas.
	156
	157	Em intervalos trimestrais, o Comitê do Código de Conduta e o TAB fornecerão
	158	um relatório resumindo os relatos anonimizados que o comitê do Código de
	159	Conduta recebeu e o status deles, bem como os detalhes de quaisquer
	160	decisões aprovadas pelo TAB, incluindo dados completos e identificáveis da
	161	votação.
	162
	163	Como a maneira pela qual interpretamos e aplicamos o Código de Conduta
	164	evoluirá com o tempo, este documento será atualizado quando necessário para
	165	refletir quaisquer mudanças.
	166
	167	Aplicação para Violações de Comportamento Inaceitável do Código de Conduta
	168	----------------------------------------------------------------------------
	169
	170	O comitê do Código de Conduta trabalha para garantir que nossa comunidade
	171	continue a ser inclusiva e promova discussões e pontos de vista diversos, e
	172	trabalha para melhorar essas características ao longo do tempo. A maioria
	173	dos relatos que o Comitê do Código de Conduta recebe decorre da
	174	compreensão incorreta sobre o processo de desenvolvimento e os papéis,
	175	responsabilidades e o direito dos mantenedores de tomar decisões sobre a
	176	aceitação de código. Estes são resolvidos através do esclarecimento do
	177	processo de desenvolvimento e do escopo do Código de Conduta.
	178
	179	Comportamentos inaceitáveis podem interromper a colaboração respeitosa por um
	180	curto período de tempo e impactar negativamente a saúde da comunidade a longo
	181	prazo. Comportamentos inaceitáveis frequentemente são resolvidos quando os
	182	indivíduos reconhecem seu comportamento e se retratam por ele no ambiente em
	183	que a violação ocorreu.
	184
	185	O Comitê do Código de Conduta recebe relatos sobre comportamentos
	186	inaceitáveis quando eles não são resolvidos através de discussões na
	187	comunidade. O comitê do Código de Conduta toma medidas para restaurar a
	188	colaboração produtiva e respeitosa quando um comportamento inaceitável
	189	impactou negativamente esse relacionamento.
	190
	191	O Comitê do Código de Conduta tem a obrigação de manter os relatos e as
	192	informações dos relatores em sigilo. Os relatos podem vir de partes lesadas
	193	e membros da comunidade que são observadores de comportamentos
	194	inaceitáveis. O Comitê do Código de Conduta tem a responsabilidade de
	195	investigar e resolver esses relatos, trabalhando com todas as partes
	196	envolvidas.
	197
	198	O Comitê do Código de Conduta trabalha com o indivíduo para promover uma
	199	mudança em sua compreensão sobre a importância de reparar os danos causados
	200	por seu comportamento à parte lesada e o impacto negativo a longo prazo na
	201	comunidade.
	202
	203	O objetivo é alcançar uma resolução que seja aceitável para todas as partes.
	204	Se trabalhar com o indivíduo não trouxer o resultado desejado, o Comitê do
	205	Código de Conduta avaliará outras medidas, como buscar um pedido de
	206	desculpas público para reparar o dano.
	207
	208	Buscar retratação pública pela violação
	209	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	210
	211	O Comitê do Código de Conduta chama a atenção publicamente para o comportamento
	212	no ambiente em que a violação ocorreu, buscando uma retratação pública
	213	pela violação.
	214
	215	Uma retratação pública pela violação é o primeiro passo para reconstruir a
	216	confiança. A confiança é essencial para o sucesso contínuo e a saúde da
	217	comunidade, que opera com base na confiança e no respeito.
	218
	219	Medidas corretivas se não houver uma retratação pública pela violação
	220	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	221
	222	O Comitê do Código de Conduta determina o próximo curso de ação para restaurar
	223	a colaboração saudável, recomendando medida(s) corretiva(s) ao TAB para
	224	aprovação.
	225
	226	- Banir o infrator de participar do processo de desenvolvimento do kernel por
	227	um período de até um ciclo completo de desenvolvimento do kernel. O Comitê
	228	do Código de Conduta pode exigir uma retratação pública como condição
	229	para suspender o banimento.
	230
	231	O escopo do banimento por um período de tempo pode incluir:
	232
	233	a. negar contribuições de patch e pull requests
	234	b. pausar a colaboração com o infrator ignorando suas contribuições e/ou
	235	bloqueando sua(s) conta(s) de e-mail
	236	c. restringir sua capacidade de se comunicar pelas plataformas kernel.org,
	237	como listas de discussão e sites de mídia social
	238
	239	Uma vez que o TAB aprove uma ou mais das medidas descritas no escopo do
	240	banimento por dois terços dos membros votando a favor das medidas, o Comitê do
	241	Código de Conduta aplicará a(s) medida(s) aprovada(s) pelo TAB em colaboração
	242	com a comunidade, mantenedores, submantenedores e administradores do
	243	kernel.org. Quaisquer membros do Comitê do Código de Conduta atuando no TAB
	244	não votarão nas medidas.
	245
	246	O Comitê do Código de Conduta está ciente do impacto negativo que buscar uma
	247	retratação pública e instituir um banimento pode ter sobre os indivíduos.
	248	Também está ciente dos danos a longo prazo para a comunidade que podem resultar
	249	da falta de ação quando tais violações públicas graves ocorrem.
	250
	251	A eficácia da(s) medida(s) corretiva(s) aprovada(s) pelo TAB depende da
	252	confiança e cooperação da comunidade, mantenedores, submantenedores e
	253	administradores do kernel.org na sua aplicação.
	254
	255	O Comitê do Código de Conduta espera sinceramente que comportamentos
	256	inaceitáveis que exijam a busca de retratações públicas continuem a ser
	257	ocorrências extremamente raras no futuro.

Documentation/translations/pt_BR/process/code-of-conduct.rst+88−0

@@ -0,0 +1,88 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	.. _pt_BR_code_of_conduct:
	4
	5	Código de Conduta de Compromisso do Colaborador
	6	+++++++++++++++++++++++++++++++++++++++++++++++
	7
	8	Nosso Compromisso
	9	=================
	10
	11	No interesse de promover um ambiente aberto e acolhedor, nós, como colaboradores
	12	e mantenedores, nos comprometemos a tornar a participação em nosso projeto e em
	13	nossa comunidade uma experiência livre de assédio para todos, independentemente
	14	da idade, tamanho corporal, deficiência, etnia, características sexuais,
	15	identidade e expressão de gênero, nível de experiência, educação, status
	16	socioeconômico, nacionalidade, aparência pessoal, raça, religião ou identidade
	17	e orientação sexual.
	18
	19	Nossos Padrões
	20	==============
	21
	22	Exemplos de comportamentos que contribuem para a criação de um ambiente positivo
	23	incluem:
	24
	25	* Utilizar linguagem acolhedora e inclusiva
	26	* Respeitar pontos de vista e experiências divergentes
	27	* Aceitar críticas construtivas de forma cortês
	28	* Focar no que é melhor para a comunidade
	29	* Demonstrar empatia para com outros membros da comunidade
	30
	31	Exemplos de comportamentos inaceitáveis por parte dos participantes incluem:
	32
	33	* O uso de linguagem ou imagens de teor sexual, bem como atenção ou avanços
	34	sexuais indesejados
	35	* Provocações (trolling), comentários insultuosos/depreciativos e ataques
	36	pessoais ou políticos
	37	* Assédio público ou privado
	38	* Publicar informações privadas de terceiros, como endereço físico ou eletrônico,
	39	sem permissão explícita
	40	* Qualquer outra conduta que possa ser razoavelmente considerada inadequada em um
	41	ambiente profissional
	42
	43	Nossas Responsabilidades
	44	========================
	45
	46	Os mantenedores são responsáveis por esclarecer os padrões de comportamento
	47	aceitável e devem tomar medidas corretivas apropriadas e justas em resposta a
	48	quaisquer casos de comportamento inaceitável.
	49
	50	Os mantenedores têm o direito e a responsabilidade de remover, editar ou rejeitar
	51	comentários, commits, código, edições em wiki, issues e outras contribuições que
	52	não estejam alinhadas a este Código de Conduta, ou de banir temporária ou
	53	permanentemente qualquer colaborador por outros comportamentos que considerem
	54	inadequados, ameaçadores, ofensivos ou prejudiciais.
	55
	56	Escopo
	57	======
	58
	59	Este Código de Conduta se aplica tanto dentro dos espaços do projeto quanto em
	60	espaços públicos quando um indivíduo estiver representando o projeto ou sua
	61	comunidade. Exemplos de representação do projeto ou comunidade incluem o uso de um
	62	endereço de e-mail oficial do projeto, publicações por meio de uma conta oficial
	63	em redes sociais ou atuar como um representante nomeado em um evento online ou
	64	presencial. A representação de um projeto pode ser detalhada e esclarecida de forma
	65	adicional pelos mantenedores do projeto.
	66
	67	Aplicação
	68	=========
	69
	70	Casos de comportamento abusivo, de assédio ou inaceitável sob qualquer outro aspecto
	71	podem ser relatados entrando em contato com o Comitê do Código de Conduta pelo e-mail
	72	<conduct@kernel.org>. Todas as reclamações serão revisadas e investigadas, resultando
	73	em uma resposta considerada necessária e adequada às circunstâncias. O Comitê do
	74	Código de Conduta é obrigado a manter a confidencialidade em relação ao denunciante
	75	de um incidente. Detalhes adicionais sobre políticas de aplicação específicas podem
	76	ser publicados separadamente.
	77
	78	Atribuição
	79	==========
	80
	81	Este Código de Conduta foi adaptado do Contributor Covenant, versão 1.4,
	82	disponível em https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
	83
	84	Interpretação
	85	=============
	86
	87	Consulte o documento :ref:`code_of_conduct_interpretation` para entender como a
	88	comunidade do kernel Linux interpretará este documento.

Documentation/translations/pt_BR/process/contribution-maturity-model.rst+111−0

@@ -0,0 +1,111 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	=======================================================
	4	Modelos de Maturidade para Contribuição no Kernel Linux
	5	=======================================================
	6
	7
	8	Contexto
	9	========
	10
	11	Como parte do Linux Kernel Maintainers’ Summit de 2021, houve uma
	12	`discussão <https://lwn.net/Articles/870581/>`_ sobre os desafios na
	13	contratação de mantenedores do kernel, bem como a sucessão de mantenedores.
	14	Algumas das conclusões daquela discussão incluíram que as empresas que fazem
	15	parte da comunidade do Kernel Linux precisam permitir que os engenheiros atuem
	16	como mantenedores como parte de seu trabalho, para que possam crescer e se
	17	tornar líderes respeitados e, eventualmente, mantenedores do kernel. Para
	18	apoiar um fluxo forte de talentos, os desenvolvedores devem ser autorizados e
	19	incentivados a assumir contribuições no upstream, como revisar os patches de
	20	outras pessoas, refatorar a infraestrutura do kernel e escrever documentação.
	21
	22	Para tanto, o Conselho Técnico Consultivo (Technical Advisory Board - TAB) da
	23	Linux Foundation propõe este Modelo de Maturidade para Contribuição no Kernel
	24	Linux. Essas expectativas comuns para o engajamento da comunidade upstream visam
	25	aumentar a influência de desenvolvedores individuais, aumentar a colaboração
	26	de organizações e melhorar a saúde geral do ecossistema do Kernel Linux.
	27
	28	O TAB insta as organizações a avaliarem continuamente seu modelo de maturidade
	29	em Open Source e a se comprometerem com melhorias para se alinharem a este
	30	modelo. Para ser eficaz, essa avaliação deve incorporar o feedback de toda a
	31	organização, incluindo a gerência e os desenvolvedores de todos os níveis de
	32	senioridade. No espírito do Open Source, incentivamos as organizações a
	33	publicarem suas avaliações e planos para melhorar seu engajamento com a
	34	comunidade upstream.
	35
	36	Nível 0
	37	=======
	38
	39	* Engenheiros de Software não têm permissão para contribuir com patches para o
	40	kernel Linux.
	41
	42
	43	Nível 1
	44	=======
	45
	46	* Engenheiros de Software têm permissão para contribuir com patches para o
	47	kernel Linux, seja como parte de suas responsabilidades de trabalho ou em seu
	48	próprio tempo.
	49
	50	Nível 2
	51	=======
	52
	53	* Espera-se que os Engenheiros de Software contribuam para o Kernel Linux como
	54	parte de suas responsabilidades de trabalho.
	55	* Os Engenheiros de Software receberão apoio para participar de conferências
	56	relacionadas ao Linux como parte de seu trabalho.
	57	* As contribuições de código no upstream de um Engenheiro de Software serão
	58	consideradas em promoções e avaliações de desempenho.
	59
	60	Nível 3
	61	=======
	62
	63	* Espera-se que os Engenheiros de Software revisem patches (incluindo patches
	64	escritos por engenheiros de outras empresas) como parte de suas
	65	responsabilidades de trabalho.
	66	* A contribuição com apresentações ou artigos para conferências acadêmicas ou
	67	relacionadas ao Linux (como as organizadas pela Linux Foundation, Usenix,
	68	ACM, etc.) é considerada parte do trabalho do engenheiro.
	69	* As contribuições comunitárias de um Engenheiro de Software serão consideradas
	70	em promoções e avaliações de desempenho.
	71	* As organizações relatarão regularmente as métricas de suas contribuições em
	72	open source e acompanharão essas métricas ao longo do tempo. Essas métricas
	73	podem ser publicadas apenas internamente na organização ou, a critério da
	74	organização, algumas ou todas podem ser publicadas externamente. As métricas
	75	fortemente sugeridas incluem:
	76
	77	* O número de contribuições ao kernel no upstream por equipe ou organização
	78	(por exemplo, todas as pessoas que se reportam a um gerente, diretor ou
	79	vice-presidente).
	80	* A porcentagem de desenvolvedores de kernel que fizeram contribuições no
	81	upstream em relação ao total de desenvolvedores de kernel na organização.
	82	* O intervalo de tempo entre os kernels usados nos servidores e/ou produtos
	83	da organização e a data de publicação do kernel upstream no qual o kernel
	84	interno se baseia.
	85	* O número de commits fora da árvore (out-of-tree) presentes nos kernels
	86	internos.
	87
	88	Nível 4
	89	=======
	90
	91	* Os Engenheiros de Software são incentivados a dedicar uma parte do seu tempo
	92	de trabalho focados no Trabalho no Upstream, o qual é definido como a revisão
	93	de patches, atuação em comitês de programa, melhoria da infraestrutura central
	94	do projeto -- como escrita ou manutenção de testes, redução de dívida técnica
	95	no upstream, escrita de documentação, etc.
	96	* Os Engenheiros de Software recebem apoio para ajudar a organizar conferências
	97	relacionadas ao Linux.
	98	* As organizações considerarão o feedback dos membros da comunidade em
	99	avaliações de desempenho oficiais.
	100
	101	Nível 5
	102	=======
	103
	104	* O desenvolvimento de kernel no upstream é considerado um cargo formal, com
	105	pelo menos um terço do tempo do engenheiro dedicado à realização de Trabalho
	106	no Upstream.
	107	* As organizações buscarão ativamente o feedback dos membros da comunidade como
	108	um fator nas avaliações de desempenho oficiais.
	109	* As organizações relatarão internamente e de forma regular a proporção entre o
	110	Trabalho no Upstream e o trabalho focado em atingir diretamente os objetivos
	111	de negócios.

Documentation/translations/pt_BR/process/cve.rst+125−0

@@ -0,0 +1,125 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	====
	4	CVEs
	5	====
	6
	7	Os números Common Vulnerabilities and Exposure (CVE®) foram desenvolvidos
	8	como uma forma inequívoca de identificar, definir e catalogar vulnerabilidades
	9	de segurança divulgadas publicamente. Com o tempo, sua utilidade diminuiu em
	10	relação ao projeto do kernel, e os números CVE foram frequentemente atribuídos
	11	de formas inadequadas e por motivos inadequados. Por causa disso, a comunidade
	12	de desenvolvimento do kernel tendeu a evitá-los. No entanto, a combinação da
	13	pressão contínua para atribuir CVEs e outras formas de identificadores de
	14	segurança, e abusos contínuos por indivíduos e empresas de fora da comunidade
	15	do kernel, deixou claro que a comunidade do kernel deve controlar
	16	essas atribuições.
	17
	18	A equipe de desenvolvedores do kernel Linux tem a capacidade de atribuir CVEs
	19	para possíveis problemas de segurança do kernel Linux. Essa atribuição é
	20	independente do processo normal de relato de bugs de segurança do kernel
	21	Linux, descrito em :ref:`securitybugs`.
	22
	23	Uma lista de todos os CVEs atribuídos ao kernel Linux pode ser encontrada nos
	24	arquivos da lista de discussão linux-cve, como visto em
	25	https://lore.kernel.org/linux-cve-announce/. Para receber notificações sobre
	26	os CVEs atribuídos, por favor, `inscreva-se
	27	<https://subspace.kernel.org/subscribing.html>`_ nessa lista de discussão.
	28
	29	Processo
	30	========
	31
	32	Como parte do processo normal de lançamento estável, alterações do kernel que
	33	são potencialmente problemas de segurança são identificadas pelos
	34	desenvolvedores responsáveis pelas atribuições de números CVE e recebem
	35	automaticamente números CVE. Essas atribuições são publicadas na lista de
	36	discussão linux-cve-announce como anúncios frequentes.
	37
	38	Observe que, devido à camada em que o kernel Linux se encontra em um sistema,
	39	quase qualquer bug pode ser explorável para comprometer a segurança do kernel,
	40	mas a possibilidade de exploração muitas vezes não é evidente quando o bug é
	41	corrigido. Por causa disso, a equipe de atribuição de CVEs é excessivamente
	42	cautelosa e atribui números CVE a qualquer correção de bug que identificar.
	43	Isso explica o número aparentemente grande de CVEs emitidos pela equipe do
	44	kernel Linux.
	45
	46	Se a equipe de atribuição de CVEs deixar passar uma correção específica que
	47	qualquer usuário considere que deveria receber um CVE, por favor envie um
	48	e-mail para <cve@kernel.org> e a equipe trabalhará com você nisso. Observe
	49	que nenhum possível problema de segurança deve ser enviado para esse alias;
	50	ele é SOMENTE para atribuição de CVEs a correções que já estejam em árvores de
	51	kernel lançadas. Se você acredita ter encontrado um problema de segurança
	52	ainda
	53	não corrigido, por favor siga o processo normal de relato de bugs de segurança do kernel
	54	Linux, descrito em :ref:`securitybugs`.
	55
	56	Nenhum CVE será atribuído automaticamente para problemas de segurança ainda
	57	não corrigidos no kernel Linux; a atribuição só acontecerá automaticamente
	58	depois que uma correção estiver disponível e aplicada a uma árvore de kernel
	59	estável, e ela será rastreada dessa forma pelo ID do commit git da correção
	60	original. Se alguém desejar que um CVE seja atribuído antes que um problema
	61	seja resolvido com um commit, por favor entre em contato com a equipe de
	62	atribuição de CVEs do kernel em <cve@kernel.org> para obter um identificador
	63	atribuído a partir de seu lote de identificadores reservados.
	64
	65	Nenhum CVE será atribuído para qualquer problema encontrado em uma versão do
	66	kernel que atualmente não esteja sendo mantida ativamente pela equipe de kernel
	67	Stable/LTS. Uma lista dos ramos de kernel atualmente suportados pode ser
	68	encontrada em https://kernel.org/releases.html
	69
	70	Contestações de CVEs atribuídos
	71	===============================
	72
	73	A autoridade para contestar ou modificar um CVE atribuído a uma alteração
	74	específica do kernel pertence exclusivamente aos mantenedores do subsistema
	75	relevante afetado. Esse princípio garante um alto grau de precisão e
	76	responsabilização no relato de vulnerabilidades. Somente esses indivíduos, com
	77	profundo conhecimento técnico e conhecimento íntimo do subsistema, podem
	78	avaliar de forma eficaz a validade e o escopo de uma vulnerabilidade relatada e
	79	determinar sua designação CVE apropriada. Qualquer tentativa de modificar ou
	80	contestar um CVE fora dessa autoridade designada pode levar a confusão, relato
	81	impreciso e, em última análise, sistemas comprometidos.
	82
	83	CVEs inválidos
	84	==============
	85
	86	Se um problema de segurança for encontrado em um kernel Linux que é suportado
	87	apenas por uma distribuição Linux devido às alterações feitas por essa
	88	distribuição, ou porque a distribuição oferece suporte a uma versão do kernel
	89	que não é mais uma das versões suportadas pelo kernel.org, então um CVE não
	90	pode ser atribuído pela equipe de CVEs do kernel Linux e deve ser solicitado à
	91	própria distribuição Linux.
	92
	93	Qualquer CVE atribuído ao kernel Linux para uma versão de kernel
	94	ativamente suportada, por qualquer grupo que não seja a equipe de atribuição de
	95	CVEs do kernel, não deve ser tratado como um CVE válido. Por favor, notifique
	96	a equipe de atribuição de CVEs do kernel em <cve@kernel.org> para que ela
	97	possa trabalhar para invalidar essas entradas por meio do processo de remediação
	98	da CNA.
	99
	100	Aplicabilidade de CVEs específicos
	101	==================================
	102
	103	Como o kernel Linux pode ser usado de múltiplas maneiras, com diversas
	104	formas de acesso por usuários externos, ou sem nenhum acesso, a
	105	aplicabilidade de qualquer CVE específico cabe ao usuário do Linux determinar;
	106	isso não cabe à equipe de atribuição de CVEs. Por favor, não entre em contato
	107	conosco para tentar determinar a aplicabilidade de qualquer CVE específico.
	108
	109	Além disso, como a árvore de códigos-fonte é muito grande, e cada sistema usa
	110	apenas um pequeno subconjunto dessa árvore, o usuário do Linux deve estar
	111	ciente de que grandes quantidades de CVEs atribuídos não são relevantes para
	112	seus sistemas.
	113
	114	Em resumo, não conhecemos o seu caso de uso e não sabemos quais partes do
	115	kernel você usa, portanto não há como determinarmos se um CVE específico é
	116	relevante para o seu sistema.
	117
	118	Como sempre, o melhor é adotar todas as alterações de kernel lançadas, pois
	119	elas são testadas em conjunto como um todo unificado por muitos membros da
	120	comunidade, e não como alterações individuais selecionadas. Observe também que,
	121	para muitos bugs, a solução do problema geral não é encontrada em uma única
	122	alteração, mas pela soma de muitas correções umas sobre as outras. Idealmente,
	123	CVEs serão atribuídos a todas as correções de todos os problemas, mas às vezes
	124	podemos deixar de perceber algumas correções; portanto, presuma que algumas alterações
	125	sem um CVE atribuído podem ser relevantes para adotar.

Documentation/translations/pt_BR/process/deprecated.rst+422−0

@@ -0,0 +1,422 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	========================================================================
	4	Interfaces, recursos de linguagem, atributos e convenções obsoletos
	5	========================================================================
	6
	7	Em um mundo perfeito, seria possível converter todas as instâncias de alguma
	8	API obsoleta para a nova API e remover completamente a API antiga em um único
	9	ciclo de desenvolvimento. No entanto, devido ao tamanho do kernel, à hierarquia
	10	de manutenção e ao cronograma, nem sempre é viável realizar esse tipo de
	11	conversão de uma só vez. Isso significa que novas instâncias podem acabar
	12	entrando no kernel enquanto as antigas estão sendo removidas, apenas aumentando
	13	o volume de trabalho para remover a API. A fim de instruir os desenvolvedores
	14	sobre o que se tornou obsoleto e o porquê, esta lista foi criada para servir de
	15	referência quando o uso de elementos obsoletos for proposto para inclusão no
	16	kernel.
	17
	18	__deprecated
	19	------------
	20	Embora este atributo marque visualmente uma interface como obsoleta, ele `não
	21	gera mais avisos durante as compilações
	22	<https://git.kernel.org/linus/771c035372a036f83353eef46dbb829780330234>`_ porque
	23	um dos objetivos permanentes do kernel é compilar sem avisos (warnings), e
	24	ninguém estava de fato agindo para remover essas interfaces obsoletas. Embora o
	25	uso de `__deprecated` seja útil para sinalizar uma API antiga em um arquivo de
	26	cabeçalho (header file), não é a solução completa. Tais interfaces devem ser
	27	totalmente removidas do kernel ou adicionadas a este arquivo para desestimular
	28	outros desenvolvedores de usá-las no futuro.
	29
	30	BBUG() e BUG_ON()
	31	-----------------
	32	Em vez disso, use WARN() e WARN_ON() e trate a condição de erro "impossível"
	33	da forma mais amigável possível. Embora a família de APIs BUG() tenha sido
	34	originalmente projetada para agir como uma asserção de "situação impossível" e
	35	eliminar uma thread do kernel de forma "segura", ela se mostrou arriscada
	36	demais. (Por exemplo: "Em que ordem os bloqueios precisam ser liberados? Os
	37	diversos estados foram restaurados?") Muito frequentemente, o uso de BUG() vai
	38	desestabilizar o sistema ou travá-lo por completo, o que torna impossível
	39	depurar ou até mesmo obter relatórios de travamento (crash reports) viáveis.
	40	Linus tem opiniões `muito fortes
	41	<https://lore.kernel.org/lkml/CA+55aFy6jNLsywVYdGp83AMrXBo_P-pkjkphPGrO=82SPKCpLQ@mail.gmail.com/>`_
	42	`sobre isso
	43	<https://lore.kernel.org/lkml/CAHk-=whDHsbK3HTOpTF=ue_o04onRwTEaK_ZoJp_fjbqq4+=Jw@mail.gmail.com/>`_.
	44
	45	Note que a família WARN() só deve ser usada para situações que "espera-se que
	46	sejam inacessíveis". Se você quiser alertar sobre situações que são
	47	"acessíveis, mas indesejáveis", use a família de funções pr_warn(). Os
	48	administradores do sistema podem ter configurado o sysctl panic_on_warn para
	49	garantir que seus sistemas não continuem executando diante de condições
	50	"inacessíveis". (Para exemplos, veja commits como `este aqui
	51	<https://git.kernel.org/linus/d4689846881d160a4d12a514e991a740bcb5d65a>`_.)
	52
	53	Aritmética explícita em argumentos do alocador
	54	----------------------------------------------
	55	Cálculos dinâmicos de tamanho (especialmente multiplicação) não devem ser
	56	realizados em argumentos de funções de alocação de memória (ou similares)
	57	devido ao risco de estouro de capacidade (overflow). Isso poderia fazer com
	58	que os valores dessem a volta (wrap around), resultando em uma alocação menor
	59	do que o esperado pelo chamador. O uso dessas alocações pode levar a estouros
	60	lineares na memória heap e a outros comportamentos incorretos. (Uma exceção a
	61	isso são valores literais onde o compilador pode emitir um aviso se houver
	62	risco de estouro. No entanto, a maneira preferível nesses casos é refatorar o
	63	código conforme sugerido abaixo para evitar a aritmética explícita.)
	64
	65	Por exemplo, não use ``count * size`` como argumento, como em::
	66
	67	foo = kmalloc(count * size, GFP_KERNEL);
	68
	69	Em vez disso, a forma de dois fatores do alocador deve ser utilizada::
	70
	71	foo = kmalloc_array(count, size, GFP_KERNEL);
	72
	73	Especificamente, kmalloc() pode ser substituído por kmalloc_array(), e
	74	kzalloc() pode ser substituído por kcalloc().
	75
	76	Se nenhuma forma de dois fatores estiver disponível, os auxiliares de
	77	saturação em estouro (saturate-on-overflow) devem ser usados::
	78
	79	bar = dma_alloc_coherent(dev, array_size(count, size), &dma, GFP_KERNEL);
	80
	81	Outro caso comum a ser evitado é calcular o tamanho de uma estrutura com uma
	82	matriz final de outras estruturas, como em::
	83
	84	header = kzalloc(sizeof(header) + count sizeof(*header->item),
	85	GFP_KERNEL);
	86
	87	Em vez disso, use o auxiliar::
	88
	89	header = kzalloc(struct_size(header, item, count), GFP_KERNEL);
	90
	91	.. note:: Se você estiver usando struct_size() em uma estrutura que contém uma
	92	matriz de comprimento zero ou de um único elemento como membro final,
	93	refatore o uso dessa matriz e mude para um `membro de matriz flexível
	94	<#zero-length-and-one-element-arrays>`_ em seu lugar.
	95
	96	Para outros cálculos, faça a composição usando os auxiliares size_mul(),
	97	size_add() e size_sub(). Por exemplo, no caso de::
	98
	99	foo = krealloc(current_size + chunk_size * (count - 3), GFP_KERNEL);
	100
	101	Em vez disso, use os auxiliares::
	102
	103	foo = krealloc(size_add(current_size,
	104	size_mul(chunk_size,
	105	size_sub(count, 3))), GFP_KERNEL);
	106
	107	Para mais detalhes, veja também array3_size() e flex_array_size(), bem como as
	108	funções relacionadas das famílias check_mul_overflow(), check_add_overflow(),
	109	check_sub_overflow() e check_shl_overflow().\
	110
	111	simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull()
	112	----------------------------------------------------------------------
	113	As funções simple_strtol(), simple_strtoll(), simple_strtoul() e
	114	simple_strtoull() ignoram explicitamente estouros de capacidade (overflows),
	115	o que pode levar a resultados inesperados nos chamadores. As respectivas
	116	funções kstrtol(), kstrtoll(), kstrtoul() e kstrtoull() tendem a ser as
	117	substitutas corretas, embora se deva notar que estas exigem que a string seja
	118	terminada em NUL ou em nova linha (newline).
	119
	120	strcpy()
	121	--------
	122	A função strcpy() não realiza verificação de limites no buffer de destino.
	123	Isso pode resultar em estouros lineares além do final do buffer, levando a todo
	124	tipo de comportamentos incorretos. Embora ``CONFIG_FORTIFY_SOURCE=y`` e várias
	125	opções do compilador ajudem a reduzir o risco de usar esta função, não há uma
	126	boa razão para adicionar novos usos dela. A substituta segura é strscpy(),
	127	embora se deva ter cuidado nos casos em que o valor de retorno de strcpy() era
	128	utilizado, já que strscpy() não retorna um ponteiro para o destino, mas sim a
	129	quantidade de bytes não-NUL copiados (ou um código de erro errno negativo quando
	130	ocorre truncamento).
	131
	132	strncpy()
	133	---------
	134	A função strncpy() foi removida do kernel. Todos os chamadores antigos foram
	135	migrados para alternativas mais seguras.
	136
	137	A função strncpy() não garantia a terminação em NUL do buffer de destino,
	138	levando a estouros de leitura linear e outros comportamentos incorretos. Ela
	139	também preenchia incondicionalmente o destino com NUL, o que representava uma
	140	penalidade de desempenho desnecessária para chamadores que usavam apenas
	141	strings terminadas em NUL. Devido aos seus diversos comportamentos, ela era uma
	142	API ambígua para determinar qual era a real intenção do autor ao realizar a
	143	cópia.
	144
	145	As substitutas para strncpy() são:
	146
	147	- strscpy() quando o destino deve ser terminado em NUL.
	148	- strscpy_pad() quando o destino deve ser terminado em NUL e preenchido com
	149	zeros (por exemplo, estruturas que cruzam fronteiras de privilégio).
	150	- memtostr() para destinos terminados em NUL a partir de origens de largura
	151	fixa não terminadas em NUL (com o atributo ``__nonstring`` na origem).
	152	- memtostr_pad() para o mesmo caso anterior, mas com preenchimento de zeros.
	153	- strtomem() para destinos de largura fixa não terminados em NUL, com o
	154	atributo ``__nonstring`` no destino.
	155	- strtomem_pad() para destinos não terminados em NUL que também precisam de
	156	preenchimento com zeros.
	157	- memcpy_and_pad() para cópias limitadas a partir de origens potencialmente não
	158	terminadas, onde o tamanho do destino é um valor definido em tempo de
	159	execução (runtime).
	160
	161	strlcpy()
	162	---------
	163	A função strlcpy() lê primeiro todo o buffer de origem (já que o valor de
	164	retorno deve corresponder ao de strlen()). Essa leitura pode exceder o limite
	165	de tamanho do destino. Isso é ineficiente e pode levar a estouros de leitura
	166	linear se a string de origem não for terminada em NUL. A substituta segura é
	167	strscpy(), embora se deva ter cuidado nos casos em que o valor de retorno de
	168	strlcpy() é utilizado, já que strscpy() retornará valores negativos de errno
	169	quando houver truncamento.
	170
	171	Especificador de formato %p
	172	----------------------------
	173	Tradicionalmente, o uso de "%p" em strings de formatação causava falhas de
	174	exposição de endereços reais no dmesg, proc, sysfs, etc. Em vez de deixar esses
	175	endereços expostos a explorações, todos os usos de "%p" no kernel agora são
	176	exibidos como um valor hash, tornando-os inúteis para fins de endereçamento.
	177	Novos usos de "%p" não devem ser adicionados ao kernel. Para endereços de texto,
	178	usar "%pS" costuma ser melhor, pois exibe o nome do símbolo, que é muito mais
	179	útil. Para quase todo o restante, simplesmente não adicione "%p" de forma
	180	alguma.
	181
	182	Parafraseando as diretrizes atuais do Linus `guidance
	183	<https://lore.kernel.org/lkml/CA+55aFwQEd_d40g4mUCSsVRZzrFPUJt74vc6PPpb675hYNXcKw@mail.gmail.com/>`_:
	184
	185	- Se o valor hash de "%p" é inútil, pergunte a si mesmo se o ponteiro em si é
	186	importante. Talvez ele deva ser removido por completo?
	187	- Se você realmente acredita que o valor real do ponteiro é importante, por que
	188	algum estado do sistema ou nível de privilégio do usuário seria considerado
	189	"especial"? Se você acha que pode justificar isso (em comentários e no log de
	190	commit) de forma sólida o suficiente para resistir ao escrutínio do Linus,
	191	talvez possa usar "%px", certificando-se de aplicar permissões adequadas.
	192
	193	Se você estiver depurando algo em que a geração de hash de "%p" esteja causando
	194	problemas, é possível inicializar o sistema temporariamente com a opção de
	195	depuração "`no_hash_pointers
	196	<https://git.kernel.org/linus/5ead723a20e0447bc7db33dc3070b420e5f80aa6>`_".
	197
	198	Matrizes de Tamanho Variável (VLAs)
	199	-----------------------------------
	200	O uso de VLAs (Variable Length Arrays) na pilha de execução gera um código de
	201	máquina muito pior do que matrizes de tamanho estático na pilha. Embora esses
	202	problemas significativos de `desempenho
	203	<https://git.kernel.org/linus/02361bc77888>`_ sejam motivo suficiente para
	204	eliminar as VLAs, elas também representam um risco de segurança. O crescimento
	205	dinâmico de uma matriz na pilha pode exceder a memória restante no segmento da
	206	pilha. Isso pode levar a um travamento, à possível sobrescrita de dados
	207	sensíveis no final da pilha (quando compilado sem ``CONFIG_THREAD_INFO_IN_TASK=y``)
	208	ou à sobrescrita de posições de memória adjacentes à pilha (quando compilado sem
	209	``CONFIG_VMAP_STACK=y``).
	210
	211	Passagem direta implícita no switch case (fall-through)
	212	-------------------------------------------------------
	213	A linguagem C permite que o fluxo de execução de um bloco switch passe
	214	diretamente para o próximo caso (fall-through) quando uma instrução "break"
	215	está ausente ao final de um caso. No entanto, isso introduz ambiguidade no
	216	código, pois nem sempre fica claro se o "break" ausente é intencional ou um bug.
	217	Por exemplo, não é óbvio apenas olhando para o código se o ``STATE_ONE`` foi
	218	intencionalmente projetado para passar diretamente para o ``STATE_TWO``::
	219
	220	switch (value) {
	221	case STATE_ONE:
	222	do_something();
	223	case STATE_TWO:
	224	do_other();
	225	break;
	226	default:
	227	WARN("unknown state");
	228	}
	229
	230	Como há uma longa lista de falhas `causadas pela ausência de instruções "break"
	231	<https://cwe.mitre.org/data/definitions/484.html>`_, não permitimos mais a
	232	passagem direta implícita. Para identificar os casos de passagem direta
	233	intencionais, adotamos a macro pseudo-palavra-chave "fallthrough", que se
	234	expande para a extensão do gcc `__attribute__((__fallthrough__))
	235	<https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html>`_. (Quando a
	236	sintaxe ``[[fallthrough]]`` do C17/C18 for suportada de forma mais ampla por
	237	compiladores C, analisadores estáticos e IDEs, poderemos mudar para o uso dessa
	238	sintaxe para a pseudo-palavra-chave da macro.)
	239
	240	Todos os blocos de switch/case devem terminar com um dos seguintes elementos:
	241
	242	* break;
	243	* fallthrough;
	244	* continue;
	245	* goto <rótulo>;
	246	* return [expressão];
	247
	248	Matrizes de comprimento zero e de um único elemento
	249	----------------------------------------------------
	250	Há uma necessidade frequente no kernel de fornecer uma maneira de declarar uma
	251	estrutura com um conjunto de elementos finais de tamanho dinâmico. O código do
	252	kernel deve sempre usar `"membros de matriz flexível"
	253	<https://en.wikipedia.org/wiki/Flexible_array_member>`_ para esses casos. O
	254	estilo antigo de matrizes de um único elemento ou de comprimento zero não deve
	255	mais ser utilizado.
	256
	257	No código C mais antigo, elementos finais de tamanho dinâmico eram declarados
	258	especificando uma matriz de um elemento ao final de uma estrutura::
	259
	260	struct something {
	261	size_t count;
	262	struct foo items[1];
	263	};
	264
	265	Isso levava a cálculos de tamanho frágeis via sizeof() (que exigiam a subtração
	266	do tamanho do elemento final único para obter o tamanho correto do "cabeçalho").
	267	Uma `extensão GNU C <https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_ foi
	268	introduzida para permitir matrizes de comprimento zero, a fim de evitar esses
	269	problemas de cálculo de tamanho::
	270
	271	struct something {
	272	size_t count;
	273	struct foo items[0];
	274	};
	275
	276	No entanto, isso trouxe outros problemas e não resolveu algumas limitações de
	277	ambos os estilos, como a incapacidade de detectar quando tal matriz é usada
	278	acidentalmente fora do final de uma estrutura (o que poderia ocorrer
	279	diretamente, ou quando tal estrutura estava contida em unions, estruturas de
	280	estruturas, etc.).
	281
	282	O padrão C99 introduziu os "membros de matriz flexível", nos quais a declaração
	283	da matriz simplesmente não possui um tamanho numérico::
	284
	285	struct something {
	286	size_t count;
	287	struct foo items[];
	288	};
	289
	290	Esta é a maneira como o kernel espera que elementos finais de tamanho dinâmico
	291	sejam declarados. Isso permite que o compilador gere erros quando a matriz
	292	flexível não for o último elemento da estrutura, o que ajuda a evitar que bugs
	293	de `comportamento indefinido
	294	<https://git.kernel.org/linus/76497732932f15e7323dc805e8ea8dc11bb587cf>`_ sejam
	295	introduzidos inadvertidamente na base de código. Também permite que o
	296	compilador analise corretamente os tamanhos das matrizes (via sizeof(),
	297	``CONFIG_FORTIFY_SOURCE`` e ``CONFIG_UBSAN_BOUNDS``). Por exemplo, não existe um
	298	mecanismo que nos alerte de que a seguinte aplicação do operador sizeof() a uma
	299	matriz de comprimento zero sempre resulta em zero::
	300
	301	struct something {
	302	size_t count;
	303	struct foo items[0];
	304	};
	305
	306	struct something *instance;
	307
	308	instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL);
	309	instance->count = count;
	310
	311	size = sizeof(instance->items) * instance->count;
	312	memcpy(instance->items, source, size);
	313
	314	Na última linha do código acima, ``size`` acaba sendo ``zero``, quando se
	315	poderia pensar que ele representaria o tamanho total em bytes da memória
	316	dinâmica recentemente alocada para a matriz final ``items``. Aqui estão alguns
	317	exemplos deste problema: `link 1
	318	<https://git.kernel.org/linus/f2cd32a443da694ac4e28fbf4ac6f9d5cc63a539>`_,
	319	`link 2
	320	<https://git.kernel.org/linus/ab91c2a89f86be2898cee208d492816ec238b2cf>`_.
	321	Em vez disso, `membros de matriz flexível têm tipo incompleto e, portanto, o
	322	operador sizeof() não pode ser aplicado
	323	<https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_, de modo que qualquer
	324	uso incorreto de tais operadores será imediatamente percebido em tempo de
	325	compilação.
	326
	327	Em relação às matrizes de um único elemento, é preciso estar muito ciente de que
	328	`tais matrizes ocupam pelo menos o mesmo espaço que um único objeto daquele tipo
	329	<https://gcc.gnu.org/onlinedocs/gcc/Zero-Length.html>`_ e, portanto, contribuem
	330	para o tamanho da estrutura que as contém. Isso é propício a erros sempre que se
	331	deseja calcular o tamanho total da memória dinâmica a ser alocada para uma
	332	estrutura que contém uma matriz desse tipo como membro::
	333
	334	struct something {
	335	size_t count;
	336	struct foo items[1];
	337	};
	338
	339	struct something *instance;
	340
	341	instance = kmalloc(struct_size(instance, items, count - 1), GFP_KERNEL);
	342	instance->count = count;
	343
	344	size = sizeof(instance->items) * instance->count;
	345	memcpy(instance->items, source, size);
	346
	347	No exemplo acima, foi necessário lembrar de calcular ``count - 1`` ao usar o
	348	auxiliar struct_size(); caso contrário, teríamos alocado memória --de forma não
	349	intencional-- para um objeto ``items`` a mais. A maneira mais limpa e menos
	350	sujeita a erros de implementar isso é através do uso de um `membro de matriz
	351	flexível`, em conjunto com os auxiliares struct_size() e flex_array_size()::
	352
	353	struct something {
	354	size_t count;
	355	struct foo items[];
	356	};
	357
	358	struct something *instance;
	359
	360	instance = kmalloc(struct_size(instance, items, count), GFP_KERNEL);
	361	instance->count = count;
	362
	363	memcpy(instance->items, source, flex_array_size(instance, items, instance->count));
	364
	365	Existem dois casos especiais de substituição nos quais o auxiliar
	366	DECLARE_FLEX_ARRAY() precisa ser utilizado. (Note que ele é nomeado
	367	__DECLARE_FLEX_ARRAY() para uso em cabeçalhos de UAPI.) Esses casos ocorrem
	368	quando a matriz flexível está sozinha em uma estrutura ou faz parte de uma
	369	union. Isso não é permitido pela especificação C99, mas sem justificativa
	370	técnica (como pode ser visto tanto pelo uso existente de tais matrizes nesses
	371	locais quanto pela solução alternativa que DECLARE_FLEX_ARRAY() adota). Por
	372	exemplo, para converter isto::
	373
	374	struct something {
	375	...
	376	union {
	377	struct type1 one[0];
	378	struct type2 two[0];
	379	};
	380	};
	381
	382	O auxiliar deve ser utilizado::
	383
	384	struct something {
	385	...
	386	union {
	387	DECLARE_FLEX_ARRAY(struct type1, one);
	388	DECLARE_FLEX_ARRAY(struct type2, two);
	389	};
	390	};
	391
	392	Atribuições diretas de kmalloc para objetos struct
	393	--------------------------------------------------
	394	Realizar atribuições diretas (open-coded) de alocações da família kmalloc()
	395	impede que o kernel (e o compilador) consigam examinar o tipo da variável que
	396	está recebendo a atribuição, o que limita qualquer introspecção relacionada que
	397	possa ajudar com alinhamento, estouros de capacidade (wrap-around) ou
	398	proteções adicionais (hardening). A família de macros kmalloc_obj() fornece
	399	essa introspecção, que pode ser usada para os padrões de código comuns de
	400	alocações de objetos únicos, de matrizes ou de objetos flexíveis. Por exemplo,
	401	estas atribuições diretas::
	402
	403	ptr = kmalloc(sizeof(*ptr), gfp);
	404	ptr = kzalloc(sizeof(*ptr), gfp);
	405	ptr = kmalloc_array(count, sizeof(*ptr), gfp);
	406	ptr = kcalloc(count, sizeof(*ptr), gfp);
	407	ptr = kmalloc(struct_size(ptr, flex_member, count), gfp);
	408	ptr = kmalloc(sizeof(struct foo), gfp);
	409
	410	tornam-se, respectivamente::
	411
	412	ptr = kmalloc_obj(*ptr [, gfp] );
	413	ptr = kzalloc_obj(*ptr [, gfp] );
	414	ptr = kmalloc_objs(*ptr, count [, gfp] );
	415	ptr = kzalloc_objs(*ptr, count [, gfp] );
	416	ptr = kmalloc_flex(*ptr, flex_member, count [, gfp] );
	417	__auto_type ptr = kmalloc_obj(struct foo [, gfp] );
	418
	419	O argumento gfp é opcional, sendo o valor padrão GFP_KERNEL. Se
	420	``ptr->flex_member`` estiver anotado com __counted_by(), a alocação falhará
	421	automaticamente caso ``count`` seja maior do que o valor máximo representável
	422	que pode ser armazenado no membro contador associado a ``flex_member``.

Documentation/translations/pt_BR/process/development-process.rst+5−0

@@ -20,3 +20,8 @@ conhecimento profundo de programação de kernel para ser compreendida. · 19 unmodified lines
20	1.Intro	20	1.Intro
21	2.Process	21	2.Process
22	3.Early-stage	22	3.Early-stage
		23	4.Coding
		24	5.Posting
		25	6.Followthrough
		26	7.AdvancedTopics
		27	8.Conclusion

Documentation/translations/pt_BR/process/email-clients.rst+368−0

@@ -0,0 +1,368 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	Informações sobre clientes de email para Linux
	4	==============================================
	5
	6	Git
	7	---
	8
	9	Hoje em dia a maioria dos desenvolvedores usa ``git send-email`` em vez de
	10	clientes de email comuns. A página de manual desse comando é bem útil. No lado
	11	de quem recebe, os mantenedores usam ``git am`` para aplicar os patches.
	12
	13	Se você é novo no ``git``, envie seu primeiro patch para si mesmo. Salve-o
	14	como texto bruto, incluindo todos os cabeçalhos. Execute ``git am raw_email.txt``
	15	e então revise o changelog com ``git log``. Quando isso funcionar, envie o
	16	patch para a(s) lista(s) de discussão apropriada(s).
	17
	18	Preferências Gerais
	19	-------------------
	20
	21	Os patches para o kernel Linux são enviados por email, preferencialmente como
	22	texto inline no corpo da mensagem. Alguns mantenedores aceitam anexos, mas,
	23	nesse caso, os anexos devem ter o content-type ``text/plain``. Contudo, anexos
	24	são, em geral, desaconselhados porque dificultam citar trechos do patch durante
	25	o processo de revisão.
	26
	27	Também é altamente recomendável que você use plain text no corpo do email, tanto
	28	para patches quanto para outras mensagens. https://useplaintext.email pode ser
	29	útil para obter informações sobre como configurar seu cliente de email preferido,
	30	além de listar clientes de email recomendados caso você ainda não tenha preferência.
	31
	32	Clientes de email usados para patches do kernel Linux devem enviar o texto do
	33	patch sem alterações. Por exemplo, eles não devem modificar ou apagar tabs ou
	34	espaços, mesmo no início ou no fim das linhas.
	35
	36	Não envie patches com ``format=flowed``. Isso pode causar quebras de linha
	37	inesperadas e indesejadas.
	38
	39	Não deixe seu cliente de email fazer quebra automática de linha para você.
	40	Isso também pode corromper seu patch.
	41
	42	Clientes de email não devem modificar a codificação do conjunto de caracteres do
	43	texto. Patches enviados por email devem usar apenas codificação ASCII ou UTF-8.
	44	Se você configurar seu cliente de email para enviar mensagens com codificação
	45	UTF-8, você evita alguns possíveis problemas de charset.
	46
	47	Clientes de email devem gerar e manter "References:" ou "In-Reply-To:"
	48	cabeçalhos para que o encadeamento de mensagens não seja quebrado.
	49
	50	Copiar e colar (ou recortar e colar) geralmente não funciona para patches
	51	porque tabs são convertidos em espaços. Usar xclipboard, xclip e/ou xcutsel
	52	pode funcionar, mas é melhor testar isso você mesmo ou simplesmente evitar
	53	copiar e colar.
	54
	55	Não use assinaturas PGP/GPG em emails que contenham patches. Isso quebra muitos
	56	scripts que leem e aplicam os patches.
	57	(Isso deve ser corrigível.)
	58
	59	É uma boa ideia enviar um patch para si mesmo, salvar a mensagem recebida e
	60	aplicá-la com sucesso com o comando 'patch' antes de enviar patches para as
	61	listas de discussão do Linux.
	62
	63	Algumas dicas de clientes de email (MUA)
	64	----------------------------------------
	65
	66	Aqui estão algumas dicas específicas de configuração de MUA para editar e enviar
	67	patches para o kernel Linux. Estas dicas não pretendem ser resumos completos da
	68	configuração dos pacotes de software.
	69
	70	Legenda:
	71
	72	- TUI = Interface de Usuário Baseada em Texto
	73	- GUI = Interface Gráfica de Usuário
	74
	75	Alpine (TUI)
	76	************
	77
	78	Opções de configuração:
	79
	80	Na seção :menuselection:`Preferências de Envio`:
	81
	82	- :menuselection:`Não Envie Texto com Quebra de Linha Automática` deve estar ``habilitado``
	83	- :menuselection:`Remover Espaços em Branco Antes de Enviar` deve estar ``desabilitado``
	84
	85	Ao compor a mensagem, o cursor deve ser posicionado onde o patch deverá aparecer,
	86	e então pressionar `CTRL-R` permite especificar o arquivo de patch a ser
	87	inserido na mensagem.
	88
	89	Claws Mail (GUI)
	90	****************
	91
	92	Funciona. Algumas pessoas usam isso com sucesso para patches.
	93
	94	Para inserir um patch, use :menuselection:`Mensagem-->Inserir Arquivo`(`CTRL-I`)
	95	ou um editor externo.
	96
	97	Se o patch inserido precisar ser editado na janela de composição do
	98	Claws, a opção "Quebra automática" em
	99	:menuselection:`Configuração-->Preferências-->Escrever-->Quebra de linha`
	100	deve estar desabilitada.
	101
	102	Evolution (GUI)
	103	***************
	104
	105	Algumas pessoas usam isso com sucesso para patches.
	106
	107	Ao compor o e-mail, selecione: Preformatado
	108	em :menuselection:`Formatar-->Estilo de Parágrafo-->Preformatado` (`CTRL-7`)
	109	ou na barra de ferramentas
	110
	111	Depois use:
	112	:menuselection:`Inserir-->Arquivo de Texto...` (`ALT-N x`)
	113	para inserir o patch.
	114
	115	Você também pode usar ``diff -Nru old.c new.c \| xclip``, selecionar
	116	:menuselection:`Preformatado`, depois colar com o botão do meio.
	117
	118	Kmail (GUI)
	119	***********
	120
	121	Algumas pessoas usam o KMail com sucesso para patches.
	122
	123	A configuração padrão de não compor em HTML é apropriada; não a habilite.
	124
	125	Ao compor um email, em opções, desmarque “quebra de linha automática”. A única
	126	desvantagem é que qualquer texto que você digitar no email não será quebrado
	127	automaticamente, então você terá que quebrar manualmente o texto antes do patch.
	128	A maneira mais fácil é compor o email com quebra de linha automática habilitado,
	129	depois salvá-lo como rascunho. Depois de abri-lo novamente dos rascunhos, ele
	130	estará com quebras de linha rígidas e você poderá desmarcar “quebra de linha
	131	automática” sem perder a quebra existente.
	132
	133	No final do seu email, coloque o delimitador de patch comumente usado antes de
	134	inserir o patch: três hífens (``---``).
	135
	136	Então, no menu :menuselection:`Mensagem`, selecione :menuselection:`inserir arquivo`
	137	e escolha o seu patch. Como benefício adicional, você pode personalizar a barra
	138	de ferramentas de criação de mensagens e colocar o ícone :menuselection:`inserir arquivo` lá.
	139
	140	Deixe a janela do compositor larga o suficiente para que nenhuma linha seja
	141	quebrada. A partir do KMail 1.13.5 (KDE 4.5.4), o KMail aplica quebra de linha
	142	ao enviar o email se as linhas quebrarem na janela do compositor. Ter a quebra de
	143	linha desativada no menu Opções não é suficiente. Por isso se o seu patch tiver
	144	linhas muito longas, você deve deixar a janela do seu compositor bem larga antes
	145	de enviar o email. Veja: https://bugs.kde.org/show_bug.cgi?id=174034
	146
	147	Você pode assinar anexos com GPG com segurança, mas texto em linha é preferido
	148	para patches, então não os assine com GPG. Assinar patches que foram inseridos
	149	como texto em linha torna mais difícil extraí-los de sua codificação 7 bits.
	150
	151	Se você absolutamente precisar enviar patches como anexos em vez de inseri-los
	152	como texto, clique com o botão direito no anexo e selecione
	153	:menuselection:`propriedades`, e destaque :menuselection:`Sugerir exibição automática`
	154	para fazer o anexo ser exibido como texto inserido e ficar mais fácil de
	155	visualizar.
	156
	157	Ao salvar patches enviados como texto inserido, selecione o email que contém o
	158	patch no painel da lista de mensagens, clique com o botão direito e selecione
	159	:menuselection:`salvar como`. Você pode usar o email inteiro sem alterações como
	160	patch se ele tiver sido composto corretamente. Emails são salvos como leitura e
	161	escrita apenas para o usuário, então você terá que alterar as permissões para
	162	torná-los legíveis por grupo e por todos se copiá-los para outro lugar.
	163
	164	Lotus Notes (GUI)
	165	*****************
	166
	167	Fuja dele.
	168
	169	IBM Verse (Web GUI)
	170	*******************
	171
	172	Veja Lotus Notes.
	173
	174	Mutt (TUI)
	175	**********
	176
	177	Muitos desenvolvedores Linux usam ``mutt``, então deve funcionar muito bem.
	178
	179	O mutt não vem com editor, então qualquer editor que você use deve ser usado de
	180	forma que não haja quebras de linha automáticas. A maioria dos editores tem uma
	181	opção :menuselection:`Inserir Arquivo` que insere o conteúdo de um arquivo sem
	182	alterações.
	183
	184	Para usar ``vim`` com o mutt::
	185
	186	set editor="vi"
	187
	188	Se estiver usando xclip, digite o comando::
	189
	190	:set paste
	191
	192	antes do botão do meio ou shift-insert ou use::
	193
	194	:r filename
	195
	196	se você quiser incluir o patch inline.
	197	(a)ttach funciona bem sem ``set paste``.
	198
	199	Você também pode gerar patches com ``git format-patch`` e depois usar o Mutt
	200	para enviá-los::
	201
	202	$ mutt -H 0001-some-bug-fix.patch
	203
	204	Opções de configuração:
	205
	206	Deve funcionar com as configurações padrão. No entanto, é uma boa ideia definir
	207	o ``send_charset`` como::
	208
	209	set send_charset="us-ascii:utf-8"
	210
	211	O Mutt é altamente personalizável. Aqui está uma configuração mínima para
	212	começar a usar o Mutt para enviar patches pelo Gmail::
	213
	214	# .muttrc
	215	# ================ IMAP ====================
	216	set imap_user = 'seuusuario@gmail.com'
	217	set imap_pass = 'suasenha'
	218	set spoolfile = imaps://imap.gmail.com/INBOX
	219	set folder = imaps://imap.gmail.com/
	220	set record="imaps://imap.gmail.com/[Gmail]/Sent Mail"
	221	set postponed="imaps://imap.gmail.com/[Gmail]/Drafts"
	222	set mbox="imaps://imap.gmail.com/[Gmail]/All Mail"
	223
	224	# ================ SMTP ====================
	225	set smtp_url = "smtp://usuario@smtp.gmail.com:587/"
	226	set smtp_pass = $imap_pass
	227	set ssl_force_tls = yes # Exige conexão criptografada
	228
	229	# ================ Composição ====================
	230	set editor = `echo \$EDITOR`
	231	set edit_headers = yes # Exibe os cabeçalhos ao editar
	232	set charset = UTF-8 # valor de $LANG; também usado como
	233	# fallback para send_charset
	234	# Remetente, endereço de e-mail e linha de assinatura devem
	235	# corresponder
	236	unset use_domain # porque joe@localhost é constrangedor
	237	set realname = "SEU NOME"
	238	set from = "usuario@gmail.com"
	239	set use_from = yes
	240
	241	A documentação do Mutt tem muito mais informações:
	242
	243	https://gitlab.com/muttmua/mutt/-/wikis/UseCases/Gmail
	244
	245	http://www.mutt.org/doc/manual/
	246
	247	Pine (TUI)
	248	**********
	249
	250	O Pine já teve alguns problemas de truncamento de espaços em branco no passado,
	251	mas isso deve estar todo corrigido agora.
	252
	253	Use o alpine (sucessor do pine) se possível.
	254
	255	Opções de configuração:
	256
	257	- ``quell-flowed-text`` é necessário para versões recentes
	258	- a opção ``no-strip-whitespace-before-send`` é necessária
	259
	260
	261	Sylpheed (GUI)
	262	**************
	263
	264	- Funciona bem para inserir texto inline (ou usando anexos).
	265	- Permite o uso de um editor externo.
	266	- É lento em pastas grandes.
	267	- Não fará autenticação TLS SMTP sobre uma conexão não-SSL.
	268	- Tem uma barra de régua útil na janela de composição.
	269	- Adicionar endereços ao catálogo de endereços não reconhece corretamente o nome
	270	de exibição.
	271
	272	Thunderbird (GUI)
	273	*****************
	274
	275	O Thunderbird é um clone do Outlook que gosta de bagunçar o texto, mas há formas
	276	de convencê-lo a se comportar.
	277
	278	Depois de fazer as modificações, incluindo a instalação das extensões, você
	279	precisa reiniciar o Thunderbird.
	280
	281	- Permitir o uso de um editor externo:
	282
	283	A forma mais fácil de trabalhar com patches no Thunderbird é usar extensões
	284	que abrem seu editor externo favorito.
	285
	286	Aqui estão alguns exemplos de extensões capazes de fazer isso.
	287
	288	- "Editor Externo Reativado"
	289
	290	https://github.com/Frederick888/external-editor-revived
	291
	292	https://addons.thunderbird.net/en-GB/thunderbird/addon/external-editor-revived/
	293
	294	É necessário instalar um "host de mensagens nativas".
	295	Leia a wiki, que pode ser encontrada aqui:
	296	https://github.com/Frederick888/external-editor-revived/wiki
	297
	298	- "Editor Externo"
	299
	300	https://github.com/exteditor/exteditor
	301
	302	Para isso, baixe e instale a extensão, depois abra a janela de
	303	:menuselection:`compor`, adicione um botão para ela usando
	304	:menuselection:`Visualizar-->Barras de Ferramentas-->Personalizar...`
	305	e então basta clicar no novo botão quando quiser usar o editor externo.
	306
	307	Observe que o "Editor Externo" exige que seu editor não faça fork, ou seja,
	308	o editor não deve retornar antes de fechar. Pode ser necessário passar flags
	309	adicionais ou alterar as configurações do seu editor. Principalmente se você
	310	estiver usando o gvim, deve passar a opção -f para o gvim colocando
	311	``/usr/bin/gvim --nofork"`` (se o binário estiver em ``/usr/bin``) no campo
	312	de editor de texto nas configurações de :menuselection:`editor externo`. Se
	313	estiver usando outro editor, consulte seu manual para descobrir como fazer isso.
	314
	315	Para colocar juízo no editor interno, faça o seguinte:
	316
	317	- Edite as configurações do Thunderbird para que ele não use ``format=flowed``!
	318	Vá até a janela principal e encontre o botão do menu suspenso principal.
	319	:menuselection:`Menu Principal-->Preferências-->Geral-->Editor de Configurações...`
	320	para abrir o editor de registro do Thunderbird.
	321
	322	- Defina ``mailnews.send_plaintext_flowed`` como ``false``
	323
	324	- Altere ``mailnews.wraplength`` de ``72`` para ``0`` ou instale a
	325	extensão "Toggle Line Wrap"
	326
	327	https://github.com/jan-kiszka/togglelinewrap
	328
	329	https://addons.thunderbird.net/thunderbird/addon/toggle-line-wrap
	330
	331	para controlar esse registro dinamicamente.
	332
	333	- Não escreva mensagens em HTML! Vá até a janela principal
	334	:menuselection:`Menu Principal-->Configurações da Conta-->suaconta@servidor.algo-->Composição e Endereçamento`!
	335	Lá você pode desabilitar a opção "Compor mensagens em formato HTML".
	336
	337	- Abra mensagens apenas como texto simples! Vá até a janela principal
	338	:menuselection:`Menu Principal-->Visualizar-->Corpo da Mensagem Como-->Texto Simples`!
	339
	340	TkRat (GUI)
	341	***********
	342
	343	Funciona. Use "Inserir arquivo..." ou um editor externo.
	344
	345	Gmail (Web GUI)
	346	***************
	347
	348	Não funciona para enviar patches.
	349
	350	O cliente web do Gmail converte tabulações em espaços automaticamente.
	351
	352	Ao mesmo tempo, ele quebra linhas a cada 78 caracteres com quebras de linha no
	353	estilo CRLF, embora o problema de tab para espaço possa ser resolvido com um
	354	editor externo.
	355
	356	Outro problema é que o Gmail codifica em base64 qualquer mensagem que tenha um
	357	caractere não-ASCII. Isso inclui coisas como nomes europeus.
	358
	359	HacKerMaiL (TUI)
	360	****************
	361
	362	HacKerMaiL (hkml) é uma ferramenta simples de gerenciamento de e-mails baseada
	363	em public-inbox que não exige inscrição em listas de discussão. É desenvolvida
	364	e mantida pelo mantenedor do DAMON e visa oferecer suporte a fluxos de trabalho
	365	de desenvolvimento simples para o DAMON e para subsistemas gerais do kernel.
	366	Consulte o README (https://github.com/sjp38/hackermail/blob/master/README.md)
	367	para mais detalhes.
	368

Documentation/translations/pt_BR/process/index.rst+102−0

@@ -0,0 +1,102 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	.. raw:: latex
	4
	5	\renewcommand\thesection*
	6	\renewcommand\thesubsection*
	7
	8	===============================================
	9	Trabalhando com a comunidade de desenvolvimento
	10	===============================================
	11
	12	Então você quer ser um desenvolvedor do kernel Linux? Bem-vindo! Embora haja
	13	muito a aprender sobre o kernel em um sentido técnico, também é importante
	14	aprender como nossa comunidade funciona. A leitura desses documentos tornará
	15	muito mais fácil para você ter suas alterações integradas com um mínimo de
	16	problemas.
	17
	18	Uma introdução sobre como funciona o desenvolvimento do kernel
	19	--------------------------------------------------------------
	20
	21	Leia estes documentos primeiro: entender este material facilitará
	22	sua entrada na comunidade do kernel.
	23
	24	.. toctree::
	25	:maxdepth: 1
	26
	27	Como começar <howto>
	28	Guia do Processo de Desenvolvimento <development-process>
	29	Lista de verificação para submissão de patches do kernel Linux <submit-checklist>
	30
	31	Ferramentas e guias técnicos para desenvolvedores do kernel
	32	-----------------------------------------------------------
	33
	34	Esta é uma coleção de material com o qual os desenvolvedores do kernel
	35	devem estar familiarizados.
	36
	37	.. toctree::
	38	:maxdepth: 1
	39
	40	Requisitos mínimos <changes>
	41	Informações sobre clientes de email para Linux <email-clients>
	42	Como aplicar patches <applying-patches>
	43	Backporting e resolução de conflitos <backporting>
	44	Adicionando uma nova chamada de Sistema <adding-syscalls>
	45	Como não Deixar as ioctls malfeitas <botching-up-ioctls>
	46
	47	Guias de políticas e declarações de desenvolvedores
	48	---------------------------------------------------
	49
	50	Estas são as regras pelas quais tentamos viver na comunidade do kernel
	51	(e além).
	52
	53	.. toctree::
	54	:maxdepth: 1
	55
	56	Regras de licenciamento <license-rules>
	57	Código de Conduta de Compromisso do Colaborador <code-of-conduct>
	58	Interpretação do Código de Conduta do Kernel Linux <code-of-conduct-interpretation>
	59	Modelos de Maturidade para Contribuição no Kernel Linux <contribution-maturity-model.rst>
	60	Declaração sobre Drivers do Kernel <kernel-driver-statement>
	61	Estilo de gerenciamento do kernel Linux <management-style>
	62	Conclave (Continuidade do projeto) <conclave>
	63
	64	Lidando com bugs
	65	----------------
	66
	67	Bugs são uma realidade; é importante lidarmos com eles de forma correta.
	68	Os documentos abaixo detalham políticas e conselhos em relação ao
	69	gerenciamento de bugs e vulnerabilidades.
	70
	71	.. toctree::
	72	:maxdepth: 1
	73
	74	Falhas de segurança <security-bugs>
	75	CVEs <cve>
	76
	77	Informações para mantenedores
	78	-----------------------------
	79
	80	Como encontrar as pessoas que aceitarão seus patches e manuais úteis para os
	81	mantenedores de subsistemas.
	82
	83	.. toctree::
	84	:maxdepth: 1
	85
	86	Manuais dos mantenedores <maintainer-handbooks>
	87	Processo do subsistema de rede (netdev) <maintainer-netdev>
	88	Processo do subsistema SoC <maintainer-soc>
	89	Conformidade de DTS para SoC <maintainer-soc-clean-dts>
	90	Processo do subsistema KVM x86 <maintainer-kvm-x86>
	91
	92	Outros materiais
	93	----------------
	94
	95	Aqui estão alguns outros guias para a comunidade que são de interesse para
	96	a maioria dos desenvolvedores:
	97
	98	.. toctree::
	99	:maxdepth: 1
	100
	101	Index de documentos do Kernel <kernel-docs>
	102	Interfaces, recursos de linguagem, atributos e convenções obsoletos <deprecated>

Documentation/translations/pt_BR/process/kernel-driver-statement.rst+205−0

@@ -0,0 +1,205 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	Declaração sobre Drivers do Kernel
	4	----------------------------------
	5
	6	Posicionamento sobre os Módulos do Kernel Linux
	7	===============================================
	8
	9
	10	Nós, os desenvolvedores do kernel Linux abaixo assinados, consideramos
	11	qualquer módulo ou driver de código fechado para o kernel Linux
	12	prejudicial e indesejável. Repetidamente, constatamos que eles são
	13	nocivos aos usuários do Linux, às empresas e ao ecossistema Linux como
	14	um todo. Tais módulos negam a abertura, a estabilidade, a flexibilidade
	15	e a manutenibilidade do modelo de desenvolvimento do Linux e privam
	16	seus usuários do conhecimento da comunidade Linux. Fornecedores que
	17	oferecem módulos de kernel de código fechado forçam seus clientes a
	18	abrir mão de vantagens fundamentais do Linux ou a escolher novos
	19	fornecedores. Portanto, para aproveitar plenamente a economia de custos
	20	e os benefícios de suporte compartilhado que o código aberto tem a
	21	oferecer, incentivamos fortemente para que os fornecedores adotem uma
	22	política de dar suporte a seus clientes no Linux com código de kernel
	23	de código aberto.
	24
	25	Falamos apenas por nós mesmos, e não por qualquer empresa para a qual
	26	possamos trabalhar hoje, tenhamos trabalhado no passado ou venhamos a
	27	trabalhar no futuro.
	28
	29	- Dave Airlie
	30	- Nick Andrew
	31	- Jens Axboe
	32	- Ralf Baechle
	33	- Felipe Balbi
	34	- Ohad Ben-Cohen
	35	- Muli Ben-Yehuda
	36	- Jiri Benc
	37	- Arnd Bergmann
	38	- Thomas Bogendoerfer
	39	- Vitaly Bordug
	40	- James Bottomley
	41	- Josh Boyer
	42	- Neil Brown
	43	- Mark Brown
	44	- David Brownell
	45	- Michael Buesch
	46	- Franck Bui-Huu
	47	- Adrian Bunk
	48	- François Cami
	49	- Ralph Campbell
	50	- Luiz Fernando N. Capitulino
	51	- Mauro Carvalho Chehab
	52	- Denis Cheng
	53	- Jonathan Corbet
	54	- Glauber Costa
	55	- Alan Cox
	56	- Magnus Damm
	57	- Ahmed S. Darwish
	58	- Robert P. J. Day
	59	- Hans de Goede
	60	- Arnaldo Carvalho de Melo
	61	- Helge Deller
	62	- Jean Delvare
	63	- Mathieu Desnoyers
	64	- Sven-Thorsten Dietrich
	65	- Alexey Dobriyan
	66	- Daniel Drake
	67	- Alex Dubov
	68	- Randy Dunlap
	69	- Michael Ellerman
	70	- Pekka Enberg
	71	- Jan Engelhardt
	72	- Mark Fasheh
	73	- J. Bruce Fields
	74	- Larry Finger
	75	- Jeremy Fitzhardinge
	76	- Mike Frysinger
	77	- Kumar Gala
	78	- Robin Getz
	79	- Liam Girdwood
	80	- Jan-Benedict Glaw
	81	- Thomas Gleixner
	82	- Brice Goglin
	83	- Cyrill Gorcunov
	84	- Andy Gospodarek
	85	- Thomas Graf
	86	- Krzysztof Halasa
	87	- Harvey Harrison
	88	- Stephen Hemminger
	89	- Michael Hennerich
	90	- Tejun Heo
	91	- Benjamin Herrenschmidt
	92	- Kristian Høgsberg
	93	- Henrique de Moraes Holschuh
	94	- Marcel Holtmann
	95	- Mike Isely
	96	- Takashi Iwai
	97	- Olof Johansson
	98	- Dave Jones
	99	- Jesper Juhl
	100	- Matthias Kaehlcke
	101	- Kenji Kaneshige
	102	- Jan Kara
	103	- Jeremy Kerr
	104	- Russell King
	105	- Olaf Kirch
	106	- Roel Kluin
	107	- Hans-Jürgen Koch
	108	- Auke Kok
	109	- Peter Korsgaard
	110	- Jiri Kosina
	111	- Aaro Koskinen
	112	- Mariusz Kozlowski
	113	- Greg Kroah-Hartman
	114	- Michael Krufky
	115	- Aneesh Kumar
	116	- Clemens Ladisch
	117	- Christoph Lameter
	118	- Gunnar Larisch
	119	- Anders Larsen
	120	- Grant Likely
	121	- John W. Linville
	122	- Yinghai Lu
	123	- Tony Luck
	124	- Pavel Machek
	125	- Matt Mackall
	126	- Paul Mackerras
	127	- Roland McGrath
	128	- Patrick McHardy
	129	- Kyle McMartin
	130	- Paul Menage
	131	- Thierry Merle
	132	- Eric Miao
	133	- Akinobu Mita
	134	- Ingo Molnar
	135	- James Morris
	136	- Andrew Morton
	137	- Paul Mundt
	138	- Oleg Nesterov
	139	- Luca Olivetti
	140	- S.Çağlar Onur
	141	- Pierre Ossman
	142	- Keith Owens
	143	- Venkatesh Pallipadi
	144	- Nick Piggin
	145	- Nicolas Pitre
	146	- Evgeniy Polyakov
	147	- Richard Purdie
	148	- Mike Rapoport
	149	- Sam Ravnborg
	150	- Gerrit Renker
	151	- Stefan Richter
	152	- David Rientjes
	153	- Luis R. Rodriguez
	154	- Stefan Roese
	155	- Francois Romieu
	156	- Rami Rosen
	157	- Stephen Rothwell
	158	- Maciej W. Rozycki
	159	- Mark Salyzyn
	160	- Yoshinori Sato
	161	- Deepak Saxena
	162	- Holger Schurig
	163	- Amit Shah
	164	- Yoshihiro Shimoda
	165	- Sergei Shtylyov
	166	- Kay Sievers
	167	- Sebastian Siewior
	168	- Rik Snel
	169	- Jes Sorensen
	170	- Alexey Starikovskiy
	171	- Alan Stern
	172	- Timur Tabi
	173	- Hirokazu Takata
	174	- Eliezer Tamir
	175	- Eugene Teo
	176	- Doug Thompson
	177	- FUJITA Tomonori
	178	- Dmitry Torokhov
	179	- Marcelo Tosatti
	180	- Steven Toth
	181	- Theodore Tso
	182	- Matthias Urlichs
	183	- Geert Uytterhoeven
	184	- Arjan van de Ven
	185	- Ivo van Doorn
	186	- Rik van Riel
	187	- Wim Van Sebroeck
	188	- Hans Verkuil
	189	- Horst H. von Brand
	190	- Dmitri Vorobiev
	191	- Anton Vorontsov
	192	- Daniel Walker
	193	- Johannes Weiner
	194	- Harald Welte
	195	- Matthew Wilcox
	196	- Dan J. Williams
	197	- Darrick J. Wong
	198	- David Woodhouse
	199	- Chris Wright
	200	- Bryan Wu
	201	- Rafael J. Wysocki
	202	- Herbert Xu
	203	- Vlad Yasevich
	204	- Peter Zijlstra
	205	- Bartlomiej Zolnierkiewicz

Documentation/translations/pt_BR/process/maintainer-netdev.rst+16−7

@@ -22,11 +22,11 @@ netdev · 21 unmodified lines
22	------	22	------
23	A netdev é a lista de discussão para todos os assuntos do Linux relacionados	23	A netdev é a lista de discussão para todos os assuntos do Linux relacionados
24	a rede. Isso inclui qualquer item encontrado em ``net/`` (ex: código principal	24	a rede. Isso inclui qualquer item encontrado em ``net/`` (ex: código principal
25	como IPv6) e em ``drivers/net`` (ex: drivers específicos de hardware) na árvore	25	como IPv6) e em ``drivers/net`` (ex: drivers específicos de hardware) na árvore
26	de diretórios do Linux.	26	de diretórios do Linux.
27		27
28	Note que alguns subsistemas (ex: drivers de rede sem fio/wireless), que possuem	28	Note que alguns subsistemas (ex: drivers de rede sem fio/wireless), que possuem
29	um alto volume de tráfego, possuem suas próprias listas de discussão e árvores	29	um alto volume de tráfego, possuem suas próprias listas de discussão e árvores
30	específicas.	30	específicas.
31		31
32	Como muitas outras listas de discussão do Linux, a lista netdev é hospedada no	32	Como muitas outras listas de discussão do Linux, a lista netdev é hospedada no
@@ -34,7 +34,7 @@ Como muitas outras listas de discussão do Linux, a lista netdev é hospedada no · 1 unmodified line
34	https://lore.kernel.org/netdev/.	34	https://lore.kernel.org/netdev/.
35		35
36	À exceção dos subsistemas mencionados anteriormente, todo o desenvolvimento de	36	À exceção dos subsistemas mencionados anteriormente, todo o desenvolvimento de
37	rede do Linux (ex: RFCs, revisões, comentários, etc.) ocorre na netdev.	37	rede do Linux (ex: RFCs, revisões, comentários, etc.) ocorre na netdev.
38		38
39	Ciclo de Desenvolvimento	39	Ciclo de Desenvolvimento
40	------------------------	40	------------------------
@@ -506,8 +506,14 @@ netdevsim · 465 unmodified lines
506		506
507	O ``netdevsim`` é um driver de teste que pode ser usado para exercitar APIs de	507	O ``netdevsim`` é um driver de teste que pode ser usado para exercitar APIs de
508	configuração de driver sem a necessidade de hardware compatível. Mock-ups e	508	configuração de driver sem a necessidade de hardware compatível. Mock-ups e
509	testes baseados no ``netdevsim`` são fortemente encorajados ao adicionar novas	509	testes baseados no ``netdevsim`` são encorajados ao adicionar novas APIs com
510	APIs, mas o ``netdevsim`` em si não é considerado um caso de uso/usuário.	510	lógica complexa na pilha. Os testes devem ser escritos de forma que possam ser
		511	executados tanto contra o ``netdevsim`` quanto contra um dispositivo real
		512	(veja ``tools/testing/selftests/drivers/net/README.rst``). Testes exclusivos
		513	para o ``netdevsim`` devem se concentrar em testar casos extremos e caminhos de
		514	falha no núcleo que são difíceis de exercitar com um driver real.
		515
		516	``netdevsim`` em si não é considerado um caso de uso/usuário.
511	Você também deve implementar as novas APIs em um driver real.	517	Você também deve implementar as novas APIs em um driver real.
512		518
513	Não damos garantias de que o ``netdevsim`` mudará no futuro de uma forma que	519	Não damos garantias de que o ``netdevsim`` mudará no futuro de uma forma que
@@ -577,8 +583,11 @@ independentemente do nível de experiência. Para orientações gerais e dicas · 63 unmodified lines
577		583
578	É seguro assumir que os mantenedores da netdev conhecem a comunidade e o nível	584	É seguro assumir que os mantenedores da netdev conhecem a comunidade e o nível
579	de experiência dos revisores. Os revisores não devem se preocupar com o fato de	585	de experiência dos revisores. Os revisores não devem se preocupar com o fato de
580	seus comentários impedirem ou desviarem o fluxo de patches. Revisores menos	586	seus comentários impedirem ou desviarem o fluxo de patches. Uma tag Reviewed-by
581	experientes são fortemente incentivados a fazer uma revisão mais aprofundada das	587	é entendida como "Eu revisei este código da melhor maneira possível" em vez de
		588	"Posso atestar que este código está correto".
		589
		590	Revisores são fortemente incentivados a fazer uma revisão mais aprofundada das
582	submissões e não focar exclusivamente em questões triviais ou subjetivas, como	591	submissões e não focar exclusivamente em questões triviais ou subjetivas, como
583	formatação de código, tags, etc.	592	formatação de código, tags, etc.
584		593

Documentation/translations/pt_BR/process/management-style.rst+265−0

@@ -0,0 +1,265 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	Estilo de gerenciamento do kernel Linux
	4	=======================================
	5
	6	Este é um documento curto descrevendo o estilo de gerenciamento preferido (ou
	7	inventado, dependendo de quem você perguntar) para o kernel do Linux. Ele se
	8	destina a espelhar o documento :ref:`process/coding-style.rst <codingstyle>` em
	9	algum grau, e foi escrito principalmente para evitar responder [#f1]_ as mesmas
	10	(ou semelhantes) perguntas repetidamente.
	11
	12	Estilo de gerenciamento é muito pessoal e muito mais difícil de quantificar do
	13	que simples regras de estilo de codificação, então este documento pode ou não ter
	14	qualquer coisa a ver com a realidade. Começou como uma brincadeira, mas isso não
	15	significa que não possa ser verdade. Você terá que decidir por si mesmo.
	16
	17	A propósito, quando falamos sobre "gerente do kernel", trata-se de pessoas líderes
	18	técnicas, e não das pessoas que fazem gerenciamento tradicional dentro das empresas.
	19	Se você assina pedidos de compra ou tem alguma ideia sobre o orçamento do seu grupo,
	20	você quase certamente não é um gerente do kernel. Essas sugestões podem ou não se
	21	aplicar a você.
	22
	23	Primeiro, eu sugeriria comprar "Os Sete Hábitos das Pessoas Altamente Eficazes"
	24	e NÃO lê-lo. Queime-o, é um ótimo gesto simbólico.
	25
	26	.. [#f1] Este documento faz isso não respondendo tanto à pergunta, mas torna
	27	dolorosamente óbvio para o questionador que não temos ideia de qual é a resposta.
	28
	29	De qualquer maneira, aqui vai:
	30
	31	.. _decisoes:
	32
	33	1) Decisões
	34	-----------
	35
	36	Todo mundo pensa que os gerentes tomam decisões, e que a tomada de decisões é
	37	importante. Quanto maior e mais dolorosa a decisão, maior deve ser o gerente para
	38	tomá-la. Isso é muito profundo e óbvio, mas na verdade não é verdade.
	39
	40	O nome do jogo é evitar ter que tomar uma decisão. Em particular, se alguém
	41	lhe disser "escolha (a) ou (b), realmente precisamos que você decida sobre isso",
	42	você está em apuros como gerente. As pessoas que você gerencia devem conhecer os
	43	detalhes melhor do que você, então se elas vierem até você para uma decisão técnica,
	44	você está ferrado. Você claramente não é competente para tomar essa decisão por elas.
	45
	46	(Consequência: Se as pessoas que você gerencia não conhecem os detalhes melhor
	47	do que você, você também está ferrado, embora por um motivo totalmente diferente.
	48	Isso significa que você está no trabalho errado, e que elas deveriam estar
	49	gerenciando sua genialidade em vez disso).
	50
	51	Então o nome do jogo é evitar decisões, pelo menos as grandes e dolorosas.
	52	Tomar decisões pequenas e sem consequências é bom, e faz você parecer que sabe
	53	o que está fazendo, então o que um gerente do kernel precisa fazer é transformar
	54	as grandes e dolorosas em pequenas coisas com as quais ninguém realmente se importa.
	55
	56	Ajuda a perceber que a diferença fundamental entre uma grande decisão e uma pequena
	57	é se você pode consertar sua decisão depois. Qualquer decisão pode ser pequena
	58	garantindo sempre que, se você estiver errado (e você vai estar errado), você
	59	sempre pode desfazer o dano mais tarde voltando atrás. De repente, você demonstra
	60	o dobro de capacidade como gerente por tomar duas decisões inconsequentes
	61	- a errada e a certa.
	62
	63	E as pessoas verão isso como verdadeira liderança (cof cof besteira cof cof).
	64
	65	Portanto a chave para evitar grandes decisões torna-se apenas evitar fazer coisas
	66	que não podem ser desfeitas. Não se deixe encurralar em um canto do qual você não
	67	possa escapar. Um rato encurralado pode ser perigoso - um gerente encurralado é
	68	apenas lamentável.
	69
	70	Como ninguém seria estúpido o suficiente para realmente deixar um gerente do kernel
	71	ter uma enorme responsabilidade fiscal de qualquer maneira, é geralmente
	72	bastante fácil voltar atrás. Como você não vai ser capaz de desperdiçar enormes
	73	quantidades de dinheiro que você pode não ser capaz de reembolsar, a única coisa que
	74	você pode voltar atrás é uma decisão técnica, e lá o retrocesso é muito fácil:
	75	apenas diga a todos que você era um imbecil incompetente, peça desculpas e desfaça
	76	todo o trabalho inútil em que você fez as pessoas trabalharem no último ano.
	77	De repente, a decisão que você tomou há um ano não era uma grande decisão afinal,
	78	já que poderia ser facilmente desfeita.
	79
	80	Acontece que algumas pessoas têm problemas com essa abordagem, por dois motivos:
	81
	82	- admitir que você foi um idiota é mais difícil do que parece. Todos nós gostamos
	83	de manter as aparências, e sair em público para dizer que você estava errado
	84	às vezes é muito difícil mesmo.
	85	- ter alguém falando que o que você trabalhou no último ano não valeu a pena
	86	depois de tudo pode ser difícil para os pobres engenheiros humildes também,
	87	e enquanto o trabalho real foi fácil de desfazer apenas excluindo-o, você
	88	pode ter perdido irrevogavelmente a confiança desse engenheiro. E lembre-se:
	89	"irrevogável" era o que tentamos evitar em primeiro lugar, e sua decisão acabou
	90	sendo uma grande decisão afinal.
	91
	92	Felizmente, ambas essas razões podem ser mitigadas efetivamente apenas admitindo
	93	de antemão que você não tem a menor ideia, e dizendo às pessoas antes do fato
	94	que sua decisão é puramente preliminar, e pode ser a coisa errada. Você deve
	95	sempre reservar o direito de mudar de ideia, e fazer com que as pessoas estejam
	96	muito cientes disso. E é muito mais fácil admitir que você é estúpido quando
	97	você ainda não fez a coisa realmente estúpida.
	98
	99	Então, quando realmente se revela estúpido, as pessoas apenas reviram os olhos
	100	e dizem "Ops, não de novo".
	101
	102	Essa admissão preventiva de incompetência também pode fazer com que as pessoas
	103	que realmente fazem o trabalho também pensem duas vezes sobre se vale a pena ou
	104	não. Afinal, se elas não têm certeza se é uma boa ideia, você com certeza não
	105	deve encorajá-las prometendo que o que elas trabalham será incluído. Faça com que
	106	elas pelo menos pensem duas vezes antes de embarcar em um grande empreendimento.
	107
	108	Lembre-se: eles devem saber mais sobre os detalhes do que você, e geralmente já
	109	pensam que têm a resposta para tudo. A melhor coisa que você pode fazer como
	110	gerente é não incutir confiança, mas sim uma dose saudável de pensamento crítico
	111	sobre o que eles fazem.
	112
	113	A propósito, um outro jeito de evitar uma decisão é simplesmente choramingar "não
	114	podemos fazer os dois?" e parecer patético. Confie em mim, funciona. Se não estiver
	115	claro qual abordagem é melhor, eles eventualmente descobrirão. A resposta pode
	116	acabar sendo que ambas as equipes ficam tão frustradas com a situação que apenas
	117	desistem.
	118
	119	Isso pode soar como uma falha, mas geralmente é um sinal de que havia algo errado
	120	com ambos os projetos, e a razão pela qual as pessoas envolvidas não conseguiram
	121	decidir foi que ambas estavam erradas. Você acaba saindo por cima, e evitou mais
	122	uma decisão que poderia ter estragado.
	123
	124	2) Pessoas
	125	----------
	126
	127	A maioria das pessoas é idiota, e ser um gerente significa que você terá que lidar
	128	com isso, e talvez mais importante, que elas terão que lidar com você.
	129
	130	Aconteceu que enquanto é fácil desfazer erros técnicos, não é tão fácil desfazer
	131	distúrbios de personalidade. Você só tem que conviver com os deles - e com os seus.
	132
	133	Entretanto, para se preparar como gerente do kernel, é melhor lembrar de não queimar
	134	nenhuma ponte, bombardear nenhum vilarejo inocente ou alienar muitos desenvolvedores
	135	do kernel. Acontece que alienar pessoas é bastante fácil, e reverter esse afastamento
	136	é difícil. Assim, "alienar" cai imediatamente sob o título de "não reversível",
	137	e se torna um não-não de acordo com :ref:`decisoes`.
	138
	139	Existem apenas algumas regras simples aqui:
	140
	141	(1) não chame as pessoas de imbecis (pelo menos não em público)
	142	(2) aprenda a pedir desculpas quando você esquecer a regra (1)
	143
	144	O problema com #1 é que é muito fácil de fazer, já que você pode dizer "você é
	145	um imbecil" de milhões de maneiras diferentes [#f2]_, às vezes sem nem perceber,
	146	e quase sempre com uma convicção ardente de que você está certo.
	147
	148	E quanto mais convencido você estiver de que está certo (e vamos encarar, você
	149	pode chamar praticamente qualquer pessoa de imbecil, e muitas vezes você vai
	150	estar certo), mais difícil acaba sendo se desculpar depois.
	151
	152	Para resolver esse problema, você realmente só tem duas opções:
	153
	154	- fique muito bom em pedir desculpas
	155	- espalhe o "amor" de forma tão uniforme que ninguém realmente acabe se sentindo
	156	injustamente alvo. Torne-o inventivo o suficiente, e eles podem até se divertir.
	157
	158	A opção de ser infalivelmente educado realmente não existe. Ninguém confiará em
	159	alguém que está claramente escondendo seu verdadeiro caráter.
	160
	161	.. [#f2] Paul Simon cantou "Fifty Ways to Leave Your Lover", porque francamente,
	162	"A Million Ways to Tell a Developer They're a D*ckhead" não soa tão bem. Mas
	163	tenho certeza de que ele pensou sobre isso.
	164
	165
	166	3) Pessoas II - o tipo bom
	167	--------------------------
	168
	169	Embora no final das contas a maioria das pessoas seja idiota, a consequência disso
	170	é tristemente que você também é, e que enquanto todos nós podemos nos deleitar na
	171	segura convicção de que somos melhores do que a pessoa média (vamos encarar, ninguém
	172	nunca acredita que é mediano ou abaixo da média), também devemos admitir que não
	173	somos a faca mais afiada por aí, e haverá outras pessoas que são menos idiotas
	174	do que você.
	175
	176	Algumas pessoas reagem mal a pessoas inteligentes. Outras se aproveitam delas.
	177
	178	Tenha certeza de que você, como mantenedor do kernel, está no segundo grupo.
	179	Puxe o saco delas, porque são as pessoas que tornarão seu trabalho mais fácil.
	180	Em particular, elas serão capazes de tomar suas decisões por você, que é tudo
	181	sobre o jogo.
	182
	183	Então quando você encontrar alguém mais inteligente do que você, apenas siga o
	184	fluxo. Suas responsabilidades de gerenciamento tornam-se em grande parte dizer
	185	"Parece uma boa ideia - pode ir fundo", ou "Isso parece bom, mas e quanto a xxx?".
	186	A segunda versão, em particular, é uma ótima maneira de aprender algo novo sobre
	187	"xxx" ou parecer extra gerencial ao apontar algo que a pessoa mais inteligente
	188	não havia pensado. Em qualquer caso, você vence.
	189
	190	Uma coisa a se observar é perceber que a grandeza em uma área não se traduz
	191	necessariamente em outras áreas. Então você pode instigar as pessoas em direções
	192	específicas, mas vamos encarar, elas podem ser boas no que fazem e péssimas em
	193	tudo o mais. A boa notícia é que as pessoas tendem a naturalmente voltar para o
	194	que são boas, então não é como se você estivesse fazendo algo irreversível quando
	195	você as instiga em alguma direção, apenas não pressione demais.
	196
	197	4) Colocando a culpa
	198	--------------------
	199
	200	As coisas vão dar errado, e as pessoas querem alguém para culpar. Pronto, a culpa
	201	é sua.
	202
	203	Não é realmente tão difícil aceitar a culpa, especialmente se as pessoas perceberem
	204	que não foi toda a sua culpa. O que nos leva à melhor maneira de assumir a
	205	culpa: faça isso por outra pessoa. Você se sentirá bem por assumir a culpa, eles
	206	se sentirão bem por não serem culpados, e a pessoa que perdeu toda a coleção de
	207	pornografia de 36 GB por causa da sua incompetência vai admitir relutantemente que
	208	pelo menos você não tentou se esquivar disso.
	209
	210	Então faça o desenvolvedor que realmente estragou (se você conseguir encontrá-lo)
	211	saber em particular que ele estragou. Não apenas para que ele possa evitar isso
	212	no futuro, mas para que ele saiba que lhe deve uma. E, talvez ainda mais importante,
	213	ele provavelmente é a pessoa que pode consertar. Porque, vamos encarar, com certeza
	214	não é você.
	215
	216	Levar a culpa também é o motivo pelo qual você se torna gerente em primeiro lugar.
	217	É parte do que faz as pessoas confiarem em você, e permite a você a glória potencial,
	218	porque você é quem pode dizer "Eu estraguei". E se você seguiu as regras anteriores,
	219	você será muito bom em dizer isso agora.
	220
	221	5) Coisas para evitar
	222	---------------------
	223
	224	Tem uma coisa que as pessoas odeiam ainda mais do que ser chamado de "idiota", e
	225	isso é ser chamado de "idiota" com uma voz moralista. O primeiro você pode se
	226	desculpar, o segundo você realmente não terá a chance. Eles provavelmente não
	227	estarão mais ouvindo, mesmo que você faça um bom trabalho de outra forma.
	228
	229	Todos nós pensamos que somos melhores do que qualquer outra pessoa, o que significa
	230	que quando alguém posa de superior, isso realmente nos irrita. Você pode ser moral
	231	e intelectualmente superior a todos ao seu redor, mas não tente tornar isso muito
	232	óbvio, a menos que você realmente pretenda irritar alguém [#f3]_.
	233
	234	Semelhantemente, não seja muito educado ou sutil sobre as coisas. A educação
	235	facilmente acaba indo longe demais e escondendo o problema, e como dizem, "Na
	236	internet, ninguém pode ouvir você sendo sutil". Use um grande objeto contundente
	237	para martelar o ponto, porque você realmente não pode depender das pessoas
	238	entenderem o seu ponto de outra forma.
	239
	240	Um pouco de humor pode ajudar a amortecer tanto a franqueza quanto a moralização.
	241	Ir além do limite a ponto de ser ridículo pode transmitir um ponto sem tornar
	242	doloroso para o destinatário, que apenas pensa que você está sendo bobo. Isso pode
	243	ajudar a superar o bloqueio mental pessoal que todos nós temos sobre críticas.
	244
	245	.. [#f3] Dica: grupos de discussão na internet que não estão diretamente relacionados
	246	ao seu trabalho são ótimas maneiras de descarregar suas frustrações nos outros.
	247	Escreva posts insultuosos com sarcasmo apenas para entrar em uma boa discussão
	248	de vez em quando, e você se sentirá aliviado. Só não faça sujeira muito perto
	249	de casa (ou seja, não crie problemas onde isso possa afetar sua vida pessoal).
	250
	251	6) Por que eu?
	252	--------------
	253
	254	Já que a sua maior responsabilidade parece ser assumir a culpa pelos erros de outras
	255	pessoas, e tornar dolorosamente óbvio para todos os outros que você é incompetente,
	256	a pergunta óbvia se torna: por que fazer isso em primeiro lugar?
	257
	258	Primeiramente, embora você possa ou não receber adolescentes gritando (meninas ou
	259	meninos, não vamos ser preconceituosos ou sexistas aqui) batendo na porta do seu
	260	camarim, você vai receber uma imensa sensação de realização pessoal por estar
	261	"no comando". Não importa o fato de que você realmente está liderando tentando
	262	acompanhar todos os outros e correndo atrás deles o mais rápido que puder. Todos
	263	ainda vão pensar que você é a pessoa no comando.
	264
	265	É um ótimo trabalho se você conseguir aguentar.

Documentation/translations/pt_BR/process/security-bugs.rst+368−0

@@ -0,0 +1,368 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	Falhas de segurança
	4	===================
	5
	6	Os desenvolvedores do kernel Linux levam a segurança muito a sério. Como tal,
	7	gostaríamos de saber quando uma falha de segurança é encontrada para que ela
	8	possa ser corrigida e divulgada o mais rápido possível.
	9
	10	Preparando seu relatório
	11	------------------------
	12
	13	Como em qualquer relatório de bug, um relatório de falha de segurança exige
	14	muito trabalho de análise por parte dos desenvolvedores, portanto, quanto mais
	15	informações você puder compartilhar sobre o problema, melhor. Por favor, revise
	16	o procedimento descrito em Documentation/admin-guide/reporting-issues.rst se
	17	você não tiver certeza sobre quais informações são úteis. As seguintes
	18	informações são absolutamente necessárias em qualquer relatório de falha de
	19	segurança:
	20
	21	* versão do kernel afetada: sem indicação de versão, seu relatório não
	22	será processado. Uma parte significativa dos relatórios é de bugs que já
	23	foram corrigidos, portanto, é extremamente importante que as
	24	vulnerabilidades sejam verificadas em versões recentes (árvore de
	25	desenvolvimento ou a versão estável mais recente), pelo menos verificando
	26	se o código não mudou desde a versão onde foi detectado.
	27
	28	* descrição do problema: uma descrição detalhada do problema, com rastros
	29	mostrando sua manifestação, e por que você considera o comportamento
	30	observado como um problema no Kernel, é necessária.
	31
	32	* reproduzir: os desenvolvedores precisarão ser capazes de reproduzir o
	33	problema para considerar uma correção como eficaz. Isso inclui tanto uma
	34	maneira de acionar o problema quanto uma maneira de confirmar que ele
	35	ocorre. Será necessário um reprodutor com dependências de baixa
	36	complexidade (código-fonte, script de shell, sequência de instruções,
	37	imagem de sistema de arquivos, etc). Executáveis apenas binários não são
	38	aceitos. Exploits funcionais são extremamente úteis e não serão divulgados
	39	sem o consentimento do relator, a menos que já sejam públicos. Por
	40	definição, se um problema não pode ser reproduzido, ele não é explorável,
	41	portanto, não é um bug de segurança.
	42
	43	* condições: se o bug depender de certas opções de configuração, sysctls,
	44	permissões, temporização, modificações de código, etc., estas devem ser
	45	indicadas.
	46
	47	Além disso, as seguintes informações são altamente desejáveis:
	48
	49	* localização suspeita do bug: os nomes dos arquivos e funções onde
	50	se suspeita que o bug esteja presente são muito importantes, pelo menos
	51	para ajudar a encaminhar o relatório aos mantenedores apropriados. Quando
	52	não for possível (por exemplo, "o sistema trava toda vez que executo este
	53	comando"), a equipe de segurança ajudará a identificar a origem do bug.
	54
	55	* uma proposta de correção: os relatores de bugs que analisaram a causa
	56	de uma falha no código-fonte quase sempre têm uma ideia precisa de como
	57	corrigi-lo, porque passaram muito tempo estudando o problema e suas
	58	implicações. Propor uma correção testada poupará muito tempo dos
	59	mantenedores, mesmo que a correção acabe não sendo a correta, pois ajuda a
	60	entender o bug. Ao propor uma correção testada, por favor, formate-a
	61	sempre de uma maneira que possa ser mesclada imediatamente (consulte
	62	Documentation/process/submitting-patches.rst). Isso evitará algumas trocas
	63	de mensagens caso ela seja aceita, e você receberá o crédito por
	64	encontrar e corrigir o problema. Observe que, neste caso, apenas uma tag
	65	``Signed-off-by:`` é necessária, sem ``Reported-by:`` quando o relator e
	66	o autor forem a mesma pessoa.
	67
	68	* mitigações: com muita frequência, durante a análise de um bug,
	69	surgem algumas maneiras de mitigar o problema. É útil compartilhá-las,
	70	pois podem ser úteis para manter os usuários finais protegidos durante o
	71	tempo que levam para aplicar a correção.
	72
	73	O que se qualifica como um bug de segurança
	74	-------------------------------------------
	75
	76	É importante que a maioria dos bugs seja tratada publicamente, de modo a
	77	envolver o maior público possível e encontrar a melhor solução. Por natureza,
	78	bugs que são tratados em discussões fechadas entre um pequeno conjunto de
	79	participantes têm menos probabilidade de produzir a melhor correção possível
	80	(por exemplo, risco de perder casos de uso válidos, capacidades de testes
	81	limitadas).
	82
	83	Acontece que a maioria dos bugs relatados por meio da equipe de segurança são
	84	apenas bugs comuns que foram qualificados incorretamente como bugs de segurança
	85	devido à falta de conhecimento do modelo de ameaças do kernel Linux, conforme
	86	descrito em Documentation/process/threat-model.rst, e deveriam ter sido
	87	enviados através dos canais normais descritos em
	88	Documentation/admin-guide/reporting-issues.rst
	89
	90	A lista de segurança existe para bugs urgentes que concedem a um atacante uma
	91	capacidade que ele não deveria ter em um sistema de produção corretamente
	92	configurado, e que podem ser facilmente explorados, representando uma ameaça
	93	iminente para muitos usuários. Antes de relatar, considere se o problema
	94	realmente ultrapassa um limite de confiança em tal sistema.
	95
	96	**Se você recorreu a assistência de IA para identificar um bug, você deve
	97	tratá-lo como público**. Embora você possa ter motivos válidos para acreditar
	98	que não seja, a experiência da equipe de segurança mostra que os bugs
	99	descobertos desta forma surgem sistematicamente e de forma simultânea entre
	100	múltiplos pesquisadores, frequentemente no mesmo dia. Neste caso, não
	101	compartilhe publicamente um reprodutor, pois isso poderia causar danos não
	102	intencionais; apenas mencione que um está disponível e os mantenedores poderão
	103	solicitá-lo privadamente se precisarem.
	104
	105	Se você não tiver certeza se um problema se qualifica, opte por relatar de
	106	forma privada: a equipe de segurança prefere triar um relatório limítrofe
	107	a perder uma vulnerabilidade real. Relatar bugs comuns na lista de segurança,
	108	no entanto, não faz com que eles andem mais rápido e consome a capacidade de
	109	triagem de que outros relatórios precisam.
	110
	111	Identificando contatos
	112	----------------------
	113
	114	A maneira mais eficaz de relatar um bug de segurança é enviá-lo diretamente
	115	aos mantenedores do subsistema afetado e Cc: para a equipe de segurança do
	116	kernel Linux. Não o envie para uma lista pública nesta fase, a menos que você
	117	tenha bons motivos para considerar o problema como público ou trivial de ser
	118	descoberto (por exemplo, resultado de uma ferramenta automatizada de varredura
	119	de vulnerabilidades amplamente disponível que possa ser repetida por qualquer
	120	pessoa, ou o uso de ferramentas baseadas em IA).
	121
	122	Se você estiver enviando um relatório de problemas que afetam várias partes no
	123	kernel, mesmo que sejam problemas bastante semelhantes, envie mensagens
	124	individuais (pense que os mantenedores não trabalharão todos nos problemas ao
	125	mesmo tempo). A única exceção é quando um problema diz respeito a partes
	126	intimamente relacionadas, mantidas pelo exato mesmo subconjunto de
	127	mantenedores, e espera-se que essas partes sejam todas corrigidas de uma só vez
	128	pelo mesmo commit; então pode ser aceitável relatá-las de uma vez.
	129
	130	Uma dificuldade para a maioria dos relatores de primeira viagem é descobrir a
	131	lista certa de destinatários para enviar um relatório. No kernel Linux, todos
	132	os mantenedores oficiais são confiáveis, portanto as consequências de incluir
	133	acidentalmente o mantenedor errado são apenas um pequeno ruído para essa
	134	pessoa, ou seja, nada dramático. Sendo assim, um método adequado para descobrir
	135	a lista de mantenedores (o qual os oficiais de segurança do kernel usam) é
	136	contar com o script get_maintainer.pl, ajustado para relatar apenas
	137	mantenedores. Este script, quando recebe um nome de arquivo, procurará por seu
	138	caminho no arquivo MAINTAINERS para deduzir uma lista hierárquica de
	139	mantenedores relevantes. Chamá-lo pela primeira vez com o nível mais refinado
	140	de filtragem retornará, na maioria das vezes, uma lista curta de mantenedores
	141	deste arquivo específico::
	142
	143	$ ./scripts/get_maintainer.pl --no-l --no-r --pattern-depth 1 \
	144	drivers/example.c
	145	Developer One <dev1@example.com> (maintainer:example driver)
	146	Developer Two <dev2@example.org> (maintainer:example driver)
	147
	148	Estes dois mantenedores devem então receber a mensagem. Se o comando não
	149	retornar nada, isso significa que o arquivo afetado faz parte de um subsistema
	150	mais amplo, portanto devemos ser menos específicos::
	151
	152	$ ./scripts/get_maintainer.pl --no-l --no-r drivers/example.c
	153	Developer One <dev1@example.com> (maintainer:example subsystem)
	154	Developer Two <dev2@example.org> (maintainer:example subsystem)
	155	Developer Three <dev3@example.com> (maintainer:example subsystem [GENERAL])
	156	Developer Four <dev4@example.org> (maintainer:example subsystem [GENERAL])
	157
	158	Aqui, escolher os primeiros, mais específicos, é suficiente. Quando a lista for
	159	longa, é possível produzir uma lista de endereços de e-mail delimitada por
	160	vírgulas em uma única linha adequada para o uso no campo TO: de um cliente de
	161	e-mail como este::
	162
	163	$ ./scripts/get_maintainer.pl --no-tree --no-l --no-r --no-n --m \
	164	--no-git-fallback --no-substatus --no-rolestats --no-multiline \
	165	--pattern-depth 1 drivers/example.c
	166	dev1@example.com, dev2@example.org
	167
	168	ou este para a lista mais ampla::
	169
	170	$ ./scripts/get_maintainer.pl --no-tree --no-l --no-r --no-n --m \
	171	--no-git-fallback --no-substatus --no-rolestats --no-multiline \
	172	drivers/example.c
	173	dev1@example.com, dev2@example.org, dev3@example.com, dev4@example.org
	174
	175	Se a esta altura você ainda estiver enfrentando dificuldades para identificar
	176	os mantenedores corretos, e apenas neste caso, é possível enviar seu
	177	relatório apenas para a equipe de segurança do kernel Linux. Sua mensagem
	178	será triada e você receberá instruções sobre quem contatar, se necessário.
	179	Sua mensagem poderá igualmente ser encaminhada como está para os mantenedores
	180	relevantes.
	181
	182	Uso responsável de IA para encontrar bugs
	183	-----------------------------------------
	184
	185	Uma fração significativa dos relatórios de bugs enviados à equipe de segurança
	186	é, na verdade, o resultado de revisões de código assistidas por ferramentas de
	187	IA. Embora isso possa ser um meio eficiente de encontrar bugs em áreas
	188	raramente exploradas, causa uma sobrecarga nos mantenedores, que às vezes são
	189	forçados a ignorar tais relatórios devido à sua má qualidade ou precisão. Sendo
	190	assim, os relatores devem ter um cuidado especial com vários pontos que tendem
	191	a tornar esses relatórios desnecessariamente difíceis de lidar:
	192
	193	* Comprimento: Os relatórios gerados por IA tendem a ser excessivamente
	194	longos, contendo várias seções e detalhes em excesso. Isso dificulta a
	195	identificação de informações importantes, como arquivos afetados, versões e
	196	impacto. Por favor, certifique-se de que um resumo claro do problema e
	197	todos os detalhes críticos sejam apresentados primeiro. Não exija que os
	198	engenheiros de triagem analisem várias páginas de texto. Configure suas
	199	ferramentas para produzir relatórios concisos e em estilo humano.
	200
	201	* Formatação: A maioria dos relatórios gerados por IA está repleta de
	202	tags Markdown. Essas decorações complicam a busca por informações
	203	importantes e não sobrevivem aos processos de citação envolvidos no
	204	encaminhamento ou nas respostas. Por favor, sempre converta seu relatório
	205	para texto simples sem quaisquer decorações de formatação antes de
	206	enviá-lo.
	207
	208	* Avaliação de Impacto: Muitos relatórios gerados por IA carecem de uma
	209	compreensão do modelo de ameaças do kernel (consulte
	210	Documentation/process/threat-model.rst) e fazem de tudo para inventar
	211	consequências teóricas. Isso adiciona ruído e complica a triagem. Por
	212	favor, limite-se a fatos verificáveis (por exemplo, "este bug permite que
	213	qualquer usuário obtenha CAP_NET_ADMIN") sem enumerar implicações
	214	especulativas. Faça com que sua ferramenta leia esta documentação como
	215	parte do processo de avaliação.
	216
	217	* Reproduzidor: As ferramentas baseadas em IA são frequentemente capazes
	218	de gerar reproduzidores. Por favor, certifique-se sempre de que sua
	219	ferramenta forneça um e teste-o exaustivamente. Se o reproduzidor não
	220	funcionar, ou se a ferramenta não puder produzir um, a validade do
	221	relatório deve ser seriamente questionada. Observe que, como o relatório
	222	será postado em uma lista pública, o reproduzidor só deve ser compartilhado
	223	mediante solicitação dos mantenedores.
	224
	225	* Propor uma Correção: muitas ferramentas de IA são na verdade melhores
	226	em escrever código do que em avaliá-lo. Por favor, peça à sua ferramenta
	227	para propor uma correção e teste-a antes de relatar o problema.
	228	Se a correção não puder ser testada porque depende de hardware raro ou de
	229	protocolos de rede quase extintos, é provável que o problema não seja um
	230	bug de segurança. Em qualquer caso, se uma correção for proposta, ela deve
	231	aderir a Documentation/process/submitting-patches.rst e incluir uma tag
	232	'Fixes:' designando o commit que introduziu o bug.
	233
	234	A falha em considerar estes pontos expõe seu relatório ao risco de ser
	235	ignorado.
	236
	237	Use o bom senso ao avaliar o relatório. Se o arquivo afetado não tiver sido
	238	alterado por mais de um ano e for mantido por um único indivíduo, é provável
	239	que o uso tenha diminuído e os usuários expostos sejam virtualmente
	240	inexistentes (por exemplo, drivers para hardware muito antigo, sistemas de
	241	arquivos obsoletos). Nesses casos, não há necessidade de consumir o tempo de
	242	um mantenedor com um relatório sem importância. Se o problema for claramente
	243	trivial e publicamente detectável, você deve relatá-lo diretamente às listas
	244	de discussão públicas.
	245
	246	Enviando o relatório
	247	--------------------
	248
	249	Os relatórios devem ser enviados exclusivamente por e-mail. Por favor, use um
	250	endereço de e-mail funcional, de preferência o mesmo que você deseja que
	251	apareça nas tags ``Reported-by``, se houver. Se não tiver certeza, envie o seu
	252	relatório para você mesmo primeiro.
	253
	254	A equipe de segurança e os mantenedores quase sempre exigem informações
	255	adicionais além das fornecidas inicialmente em um relatório e dependem de uma
	256	colaboração ativa e eficiente com o relator para realizar testes adicionais
	257	(por exemplo, verificar versões, opções de configuração, mitigações ou
	258	patches). Antes de entrar em contato com a equipe de segurança, o relator deve
	259	certificar-se de que está disponível para explicar suas descobertas, participar
	260	de discussões e executar testes adicionais. Relatórios nos quais o relator não
	261	responde prontamente ou não consegue discutir suas descobertas de forma eficaz
	262	podem ser abandonados se a comunicação não melhorar rapidamente.
	263
	264	O relatório deve ser enviado aos mantenedores. Se houver dois ou menos
	265	destinatários em sua mensagem, você também deve sempre colocar em Cc: a equipe
	266	de segurança do kernel Linux, que garantirá que a mensagem seja entregue às
	267	pessoas corretas e poderá auxiliar pequenas equipes de mantenedores com
	268	processos com os quais eles possam não estar familiarizados. Para equipes
	269	maiores, coloque em Cc: a equipe de segurança do kernel Linux em seus primeiros
	270	relatórios ou ao buscar ajuda específica, como ao reenviar uma mensagem que não
	271	obteve resposta dentro de uma semana. Assim que você se sentir confortável com
	272	o processo após alguns relatórios, não será mais necessário colocar a lista de
	273	segurança em Cc: ao enviar para equipes grandes. A equipe de segurança do
	274	kernel Linux pode ser contatada por e-mail em security@kernel.org. Esta é uma
	275	lista privada de oficiais de segurança que ajudarão a verificar o relatório de
	276	bug e auxiliarão os desenvolvedores que trabalham em uma correção. É possível
	277	que a equipe de segurança traga ajuda extra de mantenedores da área para
	278	entender e corrigir a vulnerabilidade de segurança.
	279
	280	Por favor, envie e-mails em texto simples sem anexos, sempre que possível.
	281	É muito mais difícil ter uma discussão com citações de contexto sobre um
	282	problema complexo se todos os detalhes estiverem ocultos em anexos. Pense nisso
	283	como uma :doc:`regular path submission </../../../process/submitting-patches>`
	284	(mesmo que você ainda não tenha um patch): descreva o problema e o impacto,
	285	liste as etapas de reprodução e siga com uma proposta de correção, tudo em
	286	texto simples. Relatórios formatados em Markdown, HTML e RST são
	287	particularmente malvistos, pois são bastante difíceis de ler por humanos e
	288	incentivam o uso de visualizadores dedicados, às vezes online, o que por
	289	definição não é aceitável para um relatório de segurança confidencial. Note
	290	que alguns clientes de e-mail tendem a corromper a formatação de texto simples
	291	por padrão; por favor, consulte Documentation/process/email-clients.rst para
	292	mais informações.
	293
	294	Divulgação e informações sob embargo
	295	------------------------------------
	296
	297	A lista de segurança não é um canal de divulgação. Para isso, veja Coordenação
	298	abaixo.
	299
	300	Assim que uma correção robusta for desenvolvida, o processo de lançamento é
	301	iniciado. Correções para bugs publicamente conhecidos são lançadas
	302	imediatamente.
	303
	304	Embora nossa preferência seja lançar correções para bugs publicamente não
	305	divulgados assim que estiverem disponíveis, isso pode ser adiado a pedido do
	306	relator ou de uma parte afetada por até 7 dias corridos a partir do início do
	307	processo de lançamento, com uma extensão excepcional para 14 dias corridos se
	308	for acordado que a criticidade do bug exige mais tempo. O único motivo válido
	309	para adiar a publicação de uma correção é acomodar a logística de QA e as
	310	implantações em larga escala que exigem coordenação de lançamento.
	311
	312	Embora as informações sob embargo possam ser compartilhadas com indivíduos de
	313	confiança para o desenvolvimento de uma correção, tais informações não serão
	314	publicadas juntamente com a correção ou em qualquer outro canal de divulgação
	315	sem a permissão do relator. Isso inclui, mas não se limita ao relatório de bug
	316	original e discussões de acompanhamento (se houver), exploits, informações de
	317	CVE ou a identidade do relator.
	318
	319	Em outras palavras, nosso único interesse é fazer com que os bugs sejam
	320	corrigidos. Todas as outras informações enviadas à lista de segurança e
	321	quaisquer discussões de acompanhamento do relatório são tratadas de forma
	322	confidencial, mesmo após o término do embargo, perpetuamente.
	323
	324	Coordenação com outros grupos
	325	-----------------------------
	326
	327	Embora a equipe de segurança do kernel se concentre exclusivamente em corrigir
	328	bugs, outros grupos se concentram em corrigir problemas em distribuições e em
	329	coordenar a divulgação entre fornecedores de sistemas operacionais. A
	330	coordenação é geralmente tratada pela lista de discussão "linux-distros" e a
	331	divulgação pela lista pública "oss-security", ambas intimamente relacionadas
	332	e apresentadas na wiki da linux-distros:
	333	https://oss-security.openwall.org/wiki/mailing-lists/distros
	334
	335	Por favor, note que as respectivas políticas e regras são diferentes, já que as
	336	3 listas buscam objetivos distintos. A coordenação entre a equipe de segurança
	337	do kernel e outras equipes é difícil porque para a equipe de segurança do
	338	kernel os embargos ocasionais (sujeitos a um número máximo de dias permitido)
	339	começam a partir da disponibilidade de uma correção, enquanto para a
	340	"linux-distros" eles começam a partir da postagem inicial na lista,
	341	independentemente da disponibilidade de uma correção.
	342
	343	Como tal, a equipe de segurança do kernel recomenda fortemente que, como
	344	relator de um potencial problema de segurança, você NÃO contate a lista de
	345	discussão "linux-distros" ATÉ que uma correção seja aceita pelos mantenedores
	346	do código afetado e você tenha lido a página wiki das distribuições acima e
	347	compreendido totalmente os requisitos que o contato com a "linux-distros"
	348	imporá a você e à comunidade do kernel. Isso também significa que, em geral,
	349	não faz sentido colocar ambas as listas em Cc: ao mesmo tempo, exceto talvez
	350	para coordenação se e enquanto uma correção aceita ainda não tiver sido
	351	mesclada. Em outras palavras, até que uma correção seja aceita, não coloque
	352	em Cc: "linux-distros", e após ela ser mesclada, não coloque em Cc: a equipe
	353	de segurança do kernel.
	354
	355	Atribuição de CVE
	356	-----------------
	357
	358	A equipe de segurança não atribui CVEs, nem os exigimos para relatórios ou
	359	correções, pois isso pode complicar desnecessariamente o processo e adiar o
	360	tratamento do bug. Se um relator desejar que um identificador CVE seja
	361	atribuído para um problema confirmado, ele pode entrar em contato com a
	362	:doc:`kernel CVE assignment team<../../../process/cve>` para obter um.
	363
	364	Acordo de não divulgação
	365	------------------------
	366
	367	A equipe de segurança do kernel Linux não é um órgão formal e, portanto, é
	368	incapaz de celebrar quaisquer acordos de não divulgação.

Documentation/translations/pt_BR/process/submit-checklist.rst+145−0

@@ -0,0 +1,145 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	==============================================================
	4	Lista de verificação para submissão de patches do kernel Linux
	5	==============================================================
	6
	7	Aqui estão algumas coisas básicas que os desenvolvedores devem fazer se
	8	quiserem ver suas submissões de patches de kernel aceitas mais rapidamente.
	9
	10	Estas diretrizes vão além da documentação fornecida em
	11	:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
	12	e em outros locais sobre o envio de patches para o kernel Linux.
	13
	14	Revise seu código
	15	=================
	16
	17	1) Se você usar um recurso, faça o #include do arquivo que define/declara
	18	esse recurso. Não dependa de outros arquivos de cabeçalho que incluam
	19	os que você usa de forma indireta.
	20
	21	2) Verifique o estilo geral do seu patch conforme detalhado em
	22	:ref:`Documentation//process/coding-style.rst <codingstyle>`.
	23
	24	3) Todas as barreiras de memória {por exemplo, ``barrier()``, ``rmb()``,
	25	``wmb()``} precisam de um comentário no código-fonte que explique a
	26	lógica do que estão fazendo e o porquê.
	27
	28	Revise as alterações do Kconfig
	29	===============================
	30
	31	1) Quaisquer novas ou modificadas opções de ``CONFIG`` não bagunçam o
	32	menu de configuração e têm 'desativado' (off) como padrão, a menos que
	33	atendam aos critérios de exceção documentados em
	34	``Documentation/kbuild/kconfig-language.rst``, atributos de menu: valor
	35	padrão.
	36
	37	2) Todas as novas opções de ``Kconfig`` possuem texto de ajuda.
	38
	39	3) Foram cuidadosamente revisadas com relação às combinações relevantes de
	40	``Kconfig``. Isso é muito difícil de acertar apenas com testes --- exige
	41	capacidade de raciocínio.
	42	pays off here.
	43
	44	Forneça documentação
	45	====================
	46
	47	1) Inclua :ref:`kernel-doc <kernel_doc>` para documentar as APIs globais
	48	do kernel. (Não é obrigatório para funções estáticas, mas também é
	49	aceitável nelas.)
	50
	51	2) Todas as novas entradas em ``/proc`` devem ser documentadas sob
	52	``Documentation/``.
	53
	54	3) Todos os novos parâmetros de inicialização (boot) do kernel devem ser
	55	documentados em ``Documentation/admin-guide/kernel-parameters.rst``.
	56
	57	4) Todos os novos parâmetros de módulo devem ser documentados com
	58	``MODULE_PARM_DESC()``.
	59
	60	5) Todas as novas interfaces com o espaço de usuário (userspace) devem ser
	61	documentadas em ``Documentation/ABI/``. Consulte
	62	``Documentation/admin-guide/abi.rst`` (ou ``Documentation/ABI/README``)
	63	para obter mais informações. Patches que alteram interfaces de espaço
	64	de usuário devem incluir em cópia (CC) linux-api@vger.kernel.org.
	65
	66	6) Se quaisquer ioctls forem adicionados pelo patch, atualize também
	67	``Documentation/userspace-api/ioctl/ioctl-number.rst``.
	68
	69	Verifique seu código com ferramentas
	70	====================================
	71
	72	1) Verifique se há violações triviais com o verificador de estilo de patch
	73	antes do envio (``scripts/checkpatch.pl``). Você deve ser capaz de
	74	justificar todas as violações que permanecerem no seu patch.
	75
	76	2) Faça uma verificação limpa com o sparse.
	77
	78	3) Use ``make checkstack`` e corrija quaisquer problemas encontrados por ele.
	79	Observe que o ``checkstack`` não aponta problemas explicitamente, mas
	80	qualquer função individual que utilize mais de 512 bytes na pilha é uma
	81	candidata a alteração.
	82
	83	Compile seu código
	84	==================
	85
	86	1) Compila de forma limpa:
	87
	88	a) com as opções de ``CONFIG`` aplicáveis ou modificadas definidas como
	89	``=y``, ``=m`` e ``=n``. Sem avisos/erros do ``gcc``, sem avisos/erros do
	90	vinculador (linker).
	91
	92	b) Passa em ``allnoconfig``, ``allmodconfig``
	93
	94	c) Compila com sucesso ao usar ``O=builddir``
	95
	96	d) Quaisquer alterações em Documentation/ compilam com sucesso sem novos
	97	avisos/erros. Use ``make htmldocs`` ou ``make pdfdocs`` para verificar
	98	a compilação e corrigir quaisquer problemas.
	99
	100	2) Compila em múltiplas arquiteturas de CPU usando ferramentas locais de
	101	compilação cruzada (cross-compile) ou alguma outra fazenda de compilação
	102	(build farm).
	103	Observe que testar em arquiteturas de diferentes tamanhos de palavra
	104	(32 e 64 bits) e diferentes endianness (big- e little-endian) é eficaz
	105	para capturar vários problemas de portabilidade decorrentes de falsas
	106	suposições sobre o intervalo de quantidade representável, alinhamento
	107	de dados ou endianness, entre outros.
	108
	109	3) O novo código adicionado foi compilado com ``gcc -W`` (use
	110	``make KCFLAGS=-W``). Isso gerará muito ruído, mas é bom para encontrar
	111	bugs como "warning: comparison between signed and unsigned".
	112
	113	4) Se o seu código-fonte modificado depender ou usar quaisquer APIs ou
	114	recursos do kernel relacionados aos seguintes símbolos do ``Kconfig``,
	115	teste múltiplas compilações com os símbolos relacionados do ``Kconfig``
	116	desativados e/ou definidos como ``=m`` (se essa opção estiver disponível)
	117	[não todos ao mesmo tempo, apenas combinações variadas/aleatórias deles]:
	118
	119	``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``,
	120	``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``,
	121	``CONFIG_NET``, ``CONFIG_INET=n`` (mas este último com ``CONFIG_NET=y``).
	122
	123	Teste seu código
	124	================
	125
	126	1) Foi testado com ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``,
	127	``CONFIG_SLUB_DEBUG``, ``CONFIG_DEBUG_PAGEALLOC``,
	128	``CONFIG_DEBUG_MUTEXES``, ``CONFIG_DEBUG_SPINLOCK``,
	129	``CONFIG_DEBUG_ATOMIC_SLEEP``, ``CONFIG_PROVE_RCU`` e
	130	``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` todos habilitados simultaneamente.
	131
	132	2) Foi testado em tempo de compilação e de execução com e sem ``CONFIG_SMP``
	133	e ``CONFIG_PREEMPT``.
	134
	135	3) Todos os caminhos de código foram executados com todos os recursos de
	136	lockdep ativados.
	137
	138	4) Foi verificado com a injeção de falhas de pelo menos slab e alocação de
	139	páginas. Consulte ``Documentation/fault-injection/``.
	140	Se o novo código for substancial, a adição de injeção de falhas específica
	141	do subsistema pode ser apropriada.
	142
	143	5) Testado com a tag mais recente do linux-next para garantir que ele ainda
	144	funcione com todos os outros patches enfileirados e com várias alterações
	145	na VM, VFS e outros subsistemas.

Documentation/translations/zh_CN/accounting/psi.rst+1−1

@@ -148,7 +148,7 @@ psi接口提供的均值即可。 · 147 unmodified lines
148	Cgroup2接口	148	Cgroup2接口
149	===========	149	===========
150		150
151	对于CONFIG_CGROUP=y及挂载了cgroup2文件系统的系统，能够获取cgroups内任务的psi。	151	对于CONFIG_CGROUPS=y及挂载了cgroup2文件系统的系统，能够获取cgroups内任务的psi。
152	此场景下cgroupfs挂载点的子目录包含cpu.pressure、memory.pressure、io.pressure文件，	152	此场景下cgroupfs挂载点的子目录包含cpu.pressure、memory.pressure、io.pressure文件，
153	内容格式与/proc/pressure/下的文件相同。	153	内容格式与/proc/pressure/下的文件相同。
154		154

Documentation/translations/zh_CN/admin-guide/index.rst+152−50

@@ -1,7 +1,13 @@
		1	.. SPDX-License-Identifier: GPL-2.0
1	.. include:: ../disclaimer-zh_CN.rst	2	.. include:: ../disclaimer-zh_CN.rst
2		3
3	:Original: :doc:`../../../admin-guide/index`	4	:Original: Documentation/admin-guide/index.rst
4	:Translator: Alex Shi <alex.shi@linux.alibaba.com>	5
		6	:翻译:
		7
		8	时奎亮 Alex Shi <alex.shi@linux.alibaba.com>
		9
		10	朱岩 Yan Zhu <zhuyan2015@qq.com>
5		11
6		12
7	Linux 内核用户和管理员指南	13	Linux 内核用户和管理员指南
@@ -11,7 +17,11 @@ Linux 内核用户和管理员指南 · 3 unmodified lines
11	整体的顺序或组织 - 这些材料不是一个单一的，连贯的文件！幸运的话，情况会随着	17	整体的顺序或组织 - 这些材料不是一个单一的，连贯的文件！幸运的话，情况会随着
12	时间的推移而迅速改善。	18	时间的推移而迅速改善。
13		19
14	这个初始部分包含总体信息，包括描述内核的README，关于内核参数的文档等。	20
		21	内核管理通用指南
		22	----------------
		23
		24	本节包含总体信息，包括描述内核整体的 README 文件、内核参数文档等。
15		25
16	.. toctree::	26	.. toctree::
17	:maxdepth: 1	27	:maxdepth: 1
@@ -20,17 +30,54 @@ Linux 内核用户和管理员指南 · 2 unmodified lines
20		30
21	Todolist:	31	Todolist:
22		32
23	* kernel-parameters
24	* devices	33	* devices
		34	* features
		35
		36	内核管理接口的重要组成部分是 /proc 和 sysfs 虚拟文件系统；这些文档描述了如何
		37	与之交互。
		38
		39	.. toctree::
		40	:maxdepth: 1
		41
		42	cputopology
		43
		44	Todolist:
		45
		46	* sysfs-rules
25	* sysctl/index	47	* sysctl/index
		48	* abi
26		49
27	本节介绍CPU漏洞及其缓解措施。	50	安全相关文档：
		51
		52	.. toctree::
		53	:maxdepth: 1
28		54
29	Todolist:	55	Todolist:
30		56
31	* hw-vuln/index	57	* hw-vuln/index
		58	* LSM/index
		59	* perf-security
		60
		61
		62	内核启动
		63	--------
		64
		65	.. toctree::
		66	:maxdepth: 1
		67
		68	bootconfig
		69
		70	Todolist:
		71
		72	* kernel-parameters
		73	* efi-stub
		74	* initrd
		75
32		76
33	下面的一组文档，针对的是试图跟踪问题和bug的用户。	77	追踪和识别问题
		78	--------------
		79
		80	以下是一组面向试图追踪特定问题和 bug 的用户的文档。
34		81
35	.. toctree::	82	.. toctree::
36	:maxdepth: 1	83	:maxdepth: 1
@@ -39,94 +86,149 @@ Todolist: · 2 unmodified lines
39	reporting-regressions	86	reporting-regressions
40	bug-hunting	87	bug-hunting
41	bug-bisect	88	bug-bisect
42	tainted-kernels
43	init	89	init
		90	clearing-warn-once
		91	lockup-watchdogs
		92	sysrq
44		93
45	Todolist:	94	Todolist:
46		95
		96	* quickly-build-trimmed-linux
		97	* verify-bugs-and-bisect-regressions
		98	* tainted-kernels
47	* ramoops	99	* ramoops
48	* dynamic-debug-howto	100	* dynamic-debug-howto
49	* kdump/index	101	* kdump/index
50	* perf/index	102	* perf/index
		103	* pstore-blk
		104	* kernel-per-CPU-kthreads
		105	* RAS/index
		106
		107
		108	核心内核子系统
		109	--------------
		110
		111	这些文档描述了核心内核管理接口，这些接口几乎在任何系统上都值得关注。
		112
		113	.. toctree::
		114	:maxdepth: 1
51		115
52	这是应用程序开发人员感兴趣的章节的开始。可以在这里找到涵盖内核ABI各个	116	cpu-load
53	方面的文档。	117	mm/index
		118	module-signing
		119	numastat
54		120
55	Todolist:	121	Todolist:
56		122
57	* sysfs-rules	123	* cgroup-v2
		124	* cgroup-v1/index
		125	* namespaces/index
		126	* pm/index
		127	* syscall-user-dispatch
58		128
59	本手册的其余部分包括各种指南，介绍如何根据您的喜好配置内核的特定行为。
60		129
		130	对非原生二进制格式的支持。请注意，其中一些文档相当古老。
61		131
62	.. toctree::	132	.. toctree::
63	:maxdepth: 1	133	:maxdepth: 1
64		134
65	bootconfig	135	Todolist:
66	clearing-warn-once	136
67	cpu-load	137	* binfmt-misc
68	cputopology	138	* java
69	lockup-watchdogs	139	* mono
70	numastat	140
71	unicode	141
72	sysrq	142	块设备和文件系统管理
73	mm/index	143	--------------------
		144
		145	.. toctree::
		146	:maxdepth: 1
74		147
75	Todolist:	148	Todolist:
76		149
77	* acpi/index
78	* aoe/index
79	* auxdisplay/index
80	* bcache	150	* bcache
81	* binderfs	151	* binderfs
82	* binfmt-misc
83	* blockdev/index	152	* blockdev/index
84	* braille-console
85	* btmrvl
86	* cgroup-v1/index
87	* cgroup-v2
88	* cifs/index	153	* cifs/index
89	* dell_rbu
90	* device-mapper/index	154	* device-mapper/index
91	* edid
92	* efi-stub
93	* ext4	155	* ext4
		156	* filesystem-monitoring
94	* nfs/index	157	* nfs/index
95	* gpio/index
96	* highuid
97	* hw_random
98	* initrd
99	* iostats	158	* iostats
100	* java
101	* jfs	159	* jfs
102	* kernel-per-CPU-kthreads	160	* md
		161	* ufs
		162	* xfs
		163
		164
		165	专用设备指南
		166	------------
		167
		168	如何在 Linux 系统中配置硬件。
		169
		170	.. toctree::
		171	:maxdepth: 1
		172
		173	Todolist:
		174
		175	* acpi/index
		176	* aoe/index
		177	* auxdisplay/index
		178	* braille-console
		179	* btmrvl
		180	* dell_rbu
		181	* edid
		182	* gpio/index
		183	* hw_random
103	* laptops/index	184	* laptops/index
104	* lcd-panel-cgram	185	* lcd-panel-cgram
105	* ldm
106	* LSM/index
107	* md
108	* media/index	186	* media/index
109	* module-signing	187	* nvme-multipath
110	* mono
111	* namespaces/index
112	* parport	188	* parport
113	* perf-security
114	* pm/index
115	* pnp	189	* pnp
116	* rapidio	190	* rapidio
117	* ras
118	* rtc	191	* rtc
119	* serial-console	192	* serial-console
120	* svga	193	* svga
		194	* thermal/index
121	* thunderbolt	195	* thunderbolt
122	* ufs
123	* vga-softcursor	196	* vga-softcursor
124	* video-output	197	* video-output
125	* xfs	198
		199
		200	工作负载分析
		201	------------
		202
		203	这是一个章节的开始，其中包含对从事 Linux 内核安全关键性分析的应用程序开发人员
		204	和系统集成商感兴趣的信息。这里可以找到支持分析内核与应用程序交互以及关键内核
		205	子系统预期的文档。
		206
		207	.. toctree::
		208	:maxdepth: 1
		209
		210	Todolist:
		211
		212	* workload-tracing
		213
		214
		215	其他内容
		216	--------
		217
		218	一些难以分类且通常已过时的文档。
		219
		220	.. toctree::
		221	:maxdepth: 1
		222
		223	Todolist:
		224
		225	* highuid
		226	* ldm
		227	* unicode
126		228
127	.. only:: subproject and html	229	.. only:: subproject and html
128		230
129	Indices	231	索引
130	=======	232	====
131		233
132	* :ref:`genindex`	234	* :ref:`genindex`

Documentation/translations/zh_CN/admin-guide/module-signing.rst+250−0

@@ -0,0 +1,250 @@
	1	.. SPDX-License-Identifier: GPL-2.0
	2	.. include:: ../disclaimer-zh_CN.rst
	3
	4	:Original: Documentation/admin-guide/module-signing.rst
	5	:翻译:
	6	朱岩 Yan Zhu <zhuyan2015@qq.com>
	7
	8
	9	================
	10	内核模块签名机制
	11	================
	12
	13	.. 目录
	14	..
	15	.. - 概述
	16	.. - 配置模块签名
	17	.. - 生成签名密钥
	18	.. - 内核中的公钥
	19	.. - 模块手动签名
	20	.. - 已签名模块和剥离
	21	.. - 加载已签名模块
	22	.. - 无效签名和未签名模块
	23	.. - 管理/保护私钥
	24
	25
	26	概述
	27	====
	28
	29	内核模块签名机制在安装过程中对模块进行加密签名，然后在加载模块时检查签名。这
	30	通过禁止加载未签名的模块或使用无效密钥签名的模块来提高内核安全性。模块签名通
	31	过使恶意模块更难加载到内核中来增加安全性。模块签名检查在内核中完成，因此不需
	32	要受信任的用户空间位。
	33
	34	此机制使用 X.509 ITU-T 标准证书对涉及的公钥进行编码。签名本身不以任何工业标准
	35	类型编码。内置机制目前仅支持 RSA、NIST P-384 ECDSA 和 NIST FIPS-204 ML-DSA
	36	公钥签名标准（尽管它是可插拔的并允许使用其他标准）。对于 RSA 和 ECDSA，可以使
	37	用的可能的哈希算法是大小为 256、384 和 512 的 SHA-2 和 SHA-3（算法由签名中的
	38	数据选择）；ML-DSA 会自行进行哈希运算，但允许与 SHA512 哈希算法结合用于签名属
	39	性。
	40
	41	配置模块签名
	42	============
	43
	44	通过进入内核配置的 :menuselection:`Enable Loadable Module Support` 菜单并打
	45	开以下选项来启用模块签名机制::
	46
	47	CONFIG_MODULE_SIG "Module signature verification"
	48
	49	这有多个可用选项：
	50
	51	(1) :menuselection:`Require modules to be validly signed`
	52	(``CONFIG_MODULE_SIG_FORCE``)
	53
	54	这指定了内核应如何处理其密钥未知或未签名的模块。
	55
	56	如果关闭（即"宽松模式"），则允许使用不可用密钥和未签名的模块，但内核将被
	57	标记为受污染，并且相关模块将被标记为受污染，显示字符'E'。
	58
	59	如果打开（即"限制模式"），只有具有有效签名且可由内核拥有的公钥验证的模块
	60	才会被加载。所有其他模块将生成错误。
	61
	62	无论此处的设置如何，如果模块的签名块无法解析，它将被直接拒绝。
	63
	64
	65	(2) :menuselection:`Automatically sign all modules`
	66	(``CONFIG_MODULE_SIG_ALL``)
	67
	68	如果打开此选项，则在构建的 modules_install 阶段期间将自动签名模块。
	69	如果关闭，则必须使用以下命令手动签名模块::
	70
	71	scripts/sign-file
	72
	73
	74	(3) :menuselection:`Which hash algorithm should modules be signed with?`
	75
	76	这提供了安装阶段将用于签名模块的哈希算法选择：
	77
	78	=============================== ==========================================
	79	``CONFIG_MODULE_SIG_SHA256`` :menuselection:`Sign modules with SHA-256`
	80	``CONFIG_MODULE_SIG_SHA384`` :menuselection:`Sign modules with SHA-384`
	81	``CONFIG_MODULE_SIG_SHA512`` :menuselection:`Sign modules with SHA-512`
	82	``CONFIG_MODULE_SIG_SHA3_256`` :menuselection:`Sign modules with SHA3-256`
	83	``CONFIG_MODULE_SIG_SHA3_384`` :menuselection:`Sign modules with SHA3-384`
	84	``CONFIG_MODULE_SIG_SHA3_512`` :menuselection:`Sign modules with SHA3-512`
	85	=============================== ==========================================
	86
	87	此处选择的算法也将被构建到内核中（而不是作为模块），以便使用该算法签名的
	88	模块可以在不导致循环依赖的情况下检查其签名。
	89
	90
	91	(4) :menuselection:`File name or PKCS#11 URI of module signing key`
	92	(``CONFIG_MODULE_SIG_KEY``)
	93
	94	将此选项设置为除默认值 ``certs/signing_key.pem`` 之外的其他值将禁用签名
	95	密钥的自动生成，并允许使用您选择的密钥对内核模块进行签名。提供的字符串应
	96	标识包含私钥及其对应的 PEM 格式 X.509 证书的文件，或者在 OpenSSL
	97	ENGINE_pkcs11 功能正常的系统上，使用 RFC7512 定义的 PKCS#11 URI。在后一
	98	种情况下，PKCS#11 URI 应引用证书和私钥。
	99
	100	如果包含私钥的 PEM 文件已加密，或者 PKCS#11 令牌需要 PIN，可以通过
	101	``KBUILD_SIGN_PIN`` 变量在构建时提供。
	102
	103
	104	(5) :menuselection:`Additional X.509 keys for default system keyring`
	105	(``CONFIG_SYSTEM_TRUSTED_KEYS``)
	106
	107	此选项可设置为包含附加证书的 PEM 编码文件的文件名，这些证书将默认包含在
	108	系统密钥环中。
	109
	110	请注意，启用模块签名会为内核构建过程添加对执行签名工具的 OpenSSL 开发包的依赖。
	111
	112
	113	生成签名密钥
	114	============
	115
	116	生成和检查签名需要加密密钥对。私钥用于生成签名，相应的公钥用于检查签名。私钥
	117	仅在构建期间需要，之后可以删除或安全存储。公钥被构建到内核中，以便在加载模块
	118	时可以使用它来检查签名。
	119
	120	在正常情况下，当 ``CONFIG_MODULE_SIG_KEY`` 保持默认值时，如果文件中不存在密
	121	钥对，内核构建将使用 openssl 自动生成新的密钥对::
	122
	123	certs/signing_key.pem
	124
	125	在构建 vmlinux 期间（公钥需要构建到 vmlinux 中）使用参数::
	126
	127	certs/x509.genkey
	128
	129	文件（如果尚不存在也会生成）。
	130
	131	可以在 RSA（``MODULE_SIG_KEY_TYPE_RSA``）、
	132	ECDSA（``MODULE_SIG_KEY_TYPE_ECDSA``）和
	133	ML-DSA（``MODULE_SIG_KEY_TYPE_MLDSA_*``）之间选择生成 RSA 4k、NIST P-384
	134	密钥对或 ML-DSA 44、65 或 87 密钥对。
	135
	136	强烈建议您提供自己的 x509.genkey 文件。
	137
	138	最值得注意的是，在 x509.genkey 文件中，req_distinguished_name 部分应从默认值
	139	更改::
	140
	141	[ req_distinguished_name ]
	142	#O = Unspecified company
	143	CN = Build time autogenerated kernel key
	144	#emailAddress = unspecified.user@unspecified.company
	145
	146	生成的 RSA 密钥大小也可以通过以下方式设置::
	147
	148	[ req ]
	149	default_bits = 4096
	150
	151	也可以使用位于 Linux 内核源代码树根节点中的 x509.genkey 密钥生成配置文件和
	152	openssl 命令手动生成公钥/私钥文件。以下是生成公钥/私钥文件的示例::
	153
	154	openssl req -new -nodes -utf8 -sha256 -days 36500 -batch -x509 \
	155	-config x509.genkey -outform PEM -out kernel_key.pem \
	156	-keyout kernel_key.pem
	157
	158	然后可以将生成的 kernel_key.pem 文件的完整路径名指定在
	159	``CONFIG_MODULE_SIG_KEY`` 选项中，并且将使用其中的证书和密钥而不是自动生成的
	160	密钥对。
	161
	162
	163	内核中的公钥
	164	============
	165
	166	内核包含一个可由 root 查看的公钥环。它们在名为 ".builtin_trusted_keys" 的密
	167	钥环中，可以通过以下方式查看::
	168
	169	[root@deneb ~]# cat /proc/keys
	170	...
	171	223c7853 I------ 1 perm 1f030000 0 0 keyring .builtin_trusted_keys: 1
	172	302d2d52 I------ 1 perm 1f010000 0 0 asymmetri Fedora kernel signing key: d69a84e6bce3d216b979e9505b3e3ef9a7118079: X509.RSA a7118079 []
	173
	174	除了专门为模块签名生成的公钥外，还可以在 ``CONFIG_SYSTEM_TRUSTED_KEYS`` 配置
	175	选项引用的 PEM 编码文件中提供其他受信任的证书。
	176
	177	此外，架构代码可以从硬件存储中获取公钥并将其添加（例如从 UEFI 密钥数据库）。
	178
	179	最后，可以通过以下方式添加其他公钥::
	180
	181	keyctl padd asymmetric "" [.builtin_trusted_keys-ID] <[key-file]
	182
	183	例如::
	184
	185	keyctl padd asymmetric "" 0x223c7853 <my_public_key.x509
	186
	187	但是，请注意，内核只允许将由已驻留在 ``.builtin_trusted_keys`` 中的密钥有效
	188	签名的密钥添加到 ``.builtin_trusted_keys``。
	189
	190	模块手动签名
	191	============
	192
	193	要手动对模块进行签名，请使用 Linux 内核源代码树中可用的 scripts/sign-file 工
	194	具。该脚本需要 4 个参数：
	195
	196	1. 哈希算法（例如，sha256）
	197	2. 私钥文件名或 PKCS#11 URI
	198	3. 公钥文件名
	199	4. 要签名的内核模块
	200
	201	以下是签名内核模块的示例::
	202
	203	scripts/sign-file sha512 kernel-signkey.priv \
	204	kernel-signkey.x509 module.ko
	205
	206	使用的哈希算法不必与配置的算法匹配，但如果不同，应确保哈希算法要么内置在内核
	207	中，要么可以在不需要自身的情况下加载。
	208
	209	如果私钥需要密码或 PIN，可以在 $KBUILD_SIGN_PIN 环境变量中提供。
	210
	211
	212	已签名模块和剥离
	213	================
	214
	215	已签名模块在末尾简单地附加了数字签名。模块文件末尾的字符串
	216	``~Module signature appended~.`` 确认签名存在，但不能确认签名有效！
	217
	218	已签名模块是脆弱的，因为签名在定义的ELF容器之外。因此，一旦计算并附加签名，就
	219	不得剥离它们。请注意，整个模块都是签名的有效载荷，包括签名时存在的任何和所有
	220	调试信息。
	221
	222
	223	加载已签名模块
	224	==============
	225
	226	模块通过 insmod、modprobe、 ``init_module()`` 或 ``finit_module()`` 加载，
	227	与未签名模块完全一样，因为在用户空间中不进行任何处理。
	228	所有签名检查都在内核内完成。
	229
	230
	231	无效签名和未签名模块
	232	====================
	233
	234	如果启用了 ``CONFIG_MODULE_SIG_FORCE`` 或在内核启动命令提供了
	235	module.sig_enforce=1，内核将仅加载具有有效签名且具有公钥的模块。否则，它还将
	236	加载未签名的模块。任何具有不匹配签名的模块将不被允许加载。
	237
	238	任何具有不可解析签名的模块将被拒绝。
	239
	240
	241	管理/保护私钥
	242	==============
	243
	244	由于私钥用于签名模块，病毒和恶意软件可以使用私钥签名模块并危害操作系统。私钥
	245	必须被销毁或移动到安全位置，而不是保存在内核源代码树的根节点中。
	246
	247	如果使用相同的私钥为多个内核配置签名模块，必须确保模块版本信息足以防止将模块
	248	加载到不同的内核中。要么设置 ``CONFIG_MODVERSIONS=y``，要么通过更改
	249	``EXTRAVERSION`` 或 ``CONFIG_LOCALVERSION`` 确保每个配置具有不同的内核发布字
	250	符串。

Documentation/translations/zh_CN/dev-tools/kasan.rst+1−1

@@ -79,7 +79,7 @@ KASAN只支持SLUB。 · 78 unmodified lines
79	CONFIG_KASAN=y	79	CONFIG_KASAN=y
80		80
81	同时在 ``CONFIG_KASAN_GENERIC`` (启用通用KASAN模式)， ``CONFIG_KASAN_SW_TAGS``	81	同时在 ``CONFIG_KASAN_GENERIC`` (启用通用KASAN模式)， ``CONFIG_KASAN_SW_TAGS``
82	(启用基于硬件标签的KASAN模式)，和 ``CONFIG_KASAN_HW_TAGS`` (启用基于硬件标签	82	(启用基于软件标签的KASAN模式)，和 ``CONFIG_KASAN_HW_TAGS`` (启用基于硬件标签
83	的KASAN模式)之间进行选择。	83	的KASAN模式)之间进行选择。
84		84
85	对于软件模式，还可以在 ``CONFIG_KASAN_OUTLINE`` 和 ``CONFIG_KASAN_INLINE``	85	对于软件模式，还可以在 ``CONFIG_KASAN_OUTLINE`` 和 ``CONFIG_KASAN_INLINE``

Documentation/translations/zh_CN/how-to.rst+100−49

 过去几年，在广大社区爱好者的友好合作下，Linux 内核中文文档迎来了蓬勃的发
 展。在翻译的早期，一切都是混乱的，社区对译稿只有一个准确翻译的要求，以鼓
 励更多的开发者参与进来，这是从 0 到 1 的必然过程，所以早期的中文文档目录
-更加具有多样性，不过好在文档不多，维护上并没有过大的压力。
+呈现出较强的多样性，不过好在文档不多，维护上并没有过大的压力。
 然而，世事变幻，不觉有年，现在内核中文文档在前进的道路上越走越远，很多潜
 在的问题逐渐浮出水面，而且随着中文文档数量的增加，翻译更多的文档与提高中
 文文档可维护性之间的矛盾愈发尖锐。由于文档翻译的特殊性，很多开发者并不会
 一直更新文档，如果中文文档落后英文文档太多，文档更新的工作量会远大于重新
 翻译。而且邮件列表中陆续有新的面孔出现，他们那股热情，就像燃烧的火焰，能
-瞬间点燃整个空间，可是他们的补丁往往具有个性，这会给审阅带来了很大的困难，
+瞬间点燃整个空间，可是他们的补丁往往具有个性，这给审阅带来了很大的困难，
 reviewer 们只能耐心地指导他们如何与社区更好地合作，但是这项工作具有重复
 性，长此以往，会渐渐浇灭 reviewer 审阅的热情。
-虽然内核文档中已经有了类似的贡献指南，但是缺乏专门针对于中文翻译的，尤其
+虽然内核文档中已经有了类似的贡献指南，但是缺乏专门面向中文翻译的，尤其
 是对于新手来说，浏览大量的文档反而更加迷惑，该文档就是为了缓解这一问题而
-编写，目的是为提供给新手一个快速翻译指南。
+编写，旨在为新手提供一份快速翻译指南。
 详细的贡献指南：Documentation/translations/zh_CN/process/index.rst。
 	sudo dnf install git-email
 	vim ~/.gitconfig
-这里是我的一个配置文件示范，请根据您的邮箱域名服务商提供的手册替换到对
+这里是我的一个配置文件示范，请根据您的邮箱域名服务商提供的手册替换对应
-应的字段。
+的字段。
 ::
 	[user]
 译文格式要求
 ------------
-	- 每行长度最多不超过 40 个字符
+	- 每行长度不超过 40 个字符
 	- 每行长度请保持一致
 	- 标题的下划线长度请按照一个英文一个字符、一个中文两个字符与标题对齐
 	- 其它的修饰符请与英文文档保持一致
 --------
 中文文档有每行 40 字符限制，因为一个中文字符等于 2 个英文字符。但是社区并
-没有那么严格，一个诀窍是将您的翻译的内容与英文原文的每行长度对齐即可，这样，
+没有那么严格，一个诀窍是将您翻译的内容与英文原文的每行长度对齐，这样，
 您也不必总是检查有没有超限。
 如果您的英文阅读能力有限，可以考虑使用辅助翻译工具，例如 deepseek。但是您
 	Update the translation through commit b080e52110ea
 	("docs: update self-protection __ro_after_init status")
-	# 请执行 git log --oneline <您翻译的英文文档路径>，并替换上述内容
+	# 请执行 git log --no-merges --oneline <您翻译的英文文档路径>
+	# 并替换上述内容。注意：应引用实际修改文件内容的 commit，
+	# 而非 merge commit
 	Signed-off-by: Yanteng Si <si.yanteng@linux.dev>
 	# 如果您前面的步骤正确执行，该行会自动显示，否则请检查 gitconfig 文件
 **请注意** 以上四行，缺少任何一行，您都将会在第一轮审阅后返工，如果您需要一个
 更加明确的示例，请对 zh_CN 目录执行 git log。
-导出补丁和制作封面
+导出补丁
-------------------
+--------
+这个时候，可以导出补丁，做发送邮件列表最后的准备了。对于单个补丁，
+命令行执行::
+	git format-patch -1
+然后命令行会输出类似下面的内容::
+	0001-docs-zh_CN-add-xxxxxxxx.patch
-这个时候，可以导出补丁，做发送邮件列表最后的准备了。命令行执行::
+如果您有多个补丁，命令行执行::
 	git format-patch -N
-	# N 要替换为补丁数量，一般 N 大于等于 1
+	# N 要替换为补丁数量，一般 N 大于 1
 然后命令行会输出类似下面的内容::
 	./scripts/checkpatch.pl *.patch
-参考脚本输出，解决掉所有的 error 和 warning，通常情况下，只有下面这个
+参考脚本输出，解决掉所有的 error 和 warning。通常情况下，只有下面这个
 warning 不需要解决::
 	WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
-一个简单的解决方法是一次只检查一个补丁，然后打上该补丁，直接对译文进行修改，
+对于单个补丁，解决方案很简单，只需要打上该补丁，直接对译文进行修改，为补丁追加后续更改::
-然后执行以下命令为补丁追加更改::
 	git checkout docs-next
 	git checkout -b test-trans-new
 	./scripts/checkpatch.pl 0001-xxxxx.patch
 	# 直接修改您的翻译
 	git add .
-	git am --amend
+	git commit --amend
 	# 保存退出
-	git am 0002-xxxxx.patch
-	……
-重新导出再次检测，重复这个过程，直到处理完所有的补丁。
+随后，重新导出补丁再次检测，重复这个过程，直到处理完所有 warning 和
+error。
+如果您有多个补丁，请按补丁集中补丁顺序对每个补丁重复上述流程，一次只处理
+一个，不要一次 git am 多个补丁。全部处理完毕后再重新导出并再次测试。
-最后，如果检测时没有 warning 和 error 需要被处理或者您只有一个补丁，请跳
+为补丁集制作封面
-过下面这个步骤，否则请重新导出补丁制作封面::
+----------------
+对于单个补丁，请跳过本节。
+如果您有多个补丁，则需要为补丁集制作一份封面，即 0 号补丁::
 	git format-patch -N --cover-letter --thread=shallow
 	# N 要替换为补丁数量，一般 N 大于 1
 	vim 0000-cover-letter.patch
 	...
-	Subject: [PATCH 0/N] *** SUBJECT HERE *** #修改该字段，概括您的补丁集都做了哪些事情
+	Subject: [PATCH 0/N] *** SUBJECT HERE *** # 修改该字段，概括您的补丁集都做了哪些事情
-	*** BLURB HERE ***			  #修改该字段，详细描述您的补丁集做了哪些事情
+	*** BLURB HERE ***			  # 修改该字段，详细描述您的补丁集做了哪些事情
 	Yanteng Si (1):
 	  docs/zh_CN: add xxxxx
 	...
-如果您只有一个补丁，则可以不制作封面，即 0 号补丁，只需要执行::
-	git format-patch -1
 把补丁提交到邮件列表
 ====================
 	git send-email *.patch --to <maintainer email addr> --cc <others addr>
 	# 一个 to 对应一个地址，一个 cc 对应一个地址，有几个就写几个
-执行该命令时，请确保网络通常，邮件发送成功一般会返回 250。
+执行该命令时，请确保网络通畅，邮件发送成功一般会返回 250。
 您可以先发送给自己，尝试发出的 patch 是否可以用 'git am' 工具正常打上。
 如果检查正常， 您就可以放心的发送到社区评审了。
-如果该步骤被中断，您可以检查一下，继续用上条命令发送失败的补丁，一定不要再
+如果该步骤被中断，您可以检查一下，然后用上条命令继续发送失败的补丁，一定不
-次发送已经发送成功的补丁。
+要再次发送已经发送成功的补丁。
 积极参与审阅过程并迭代补丁
 ==========================
  - 请先将您的邮箱客户端信件回复修改为 **纯文本** 格式，并去除所有签名，尤其是
    企业邮箱。
- - 然后点击回复按钮，并将要回复的邮件带入，
+ - 然后点击回复按钮，并引用要回复的邮件，
  - 在第一条评论行尾换行，输入您的回复
  - 在第二条评论行尾换行，输入您的回复
  - 直到处理完最后一条评论，换行空两行输入问候语和署名
 迭代补丁
 --------
-建议您每回复一条评论，就修改一处翻译。然后重新生成补丁，相信您现在已经具
+建议您每回复一条评论，就修改一处翻译，然后重新生成补丁，相信您现在
-备了灵活使用 git am --amend 的能力。
+已经具备了灵活使用 git am 与 git commit --amend 的能力。
-每次迭代一个补丁，不要一次多个::
+对于单个补丁，每回复完评论后修改、追加::
-	git am <您要修改的补丁>
+	git am 0001-xxxxx.patch
 	# 直接对文件进行您的修改
 	git add .
 	git commit --amend
-当您将所有的评论落实到位后，导出第二版补丁，并修改封面::
+当您将所有的评论落实到位后，导出第二版补丁::
-	git format-patch -N -v 2 --cover-letter --thread=shallow
+	git format-patch -1 -v 2
+命令行会输出 v2-0001-xxxxx.patch。打开该文件，在 --- 分割线下方追加
+changelog。注意，分割线以下的内容不会进入 git 提交历史，仅作为邮件中的
+说明供 reviewer 检查::
+	Subject: [PATCH v2] docs/zh_CN: add xxxxxx translation
+	Translate .../xxx.rst into Chinese.
+	Signed-off-by: Yanteng Si <si.yanteng@linux.dev>
+	---
+	v1->v2:
+	  - 修正第二节的错别字，Reviewer-A 提出的意见
+	  - 根据 Reviewer-B 的建议调整段落顺序
-打开 0 号补丁，在 BLURB HERE 处编写相较于上个版本，您做了哪些改动。
+	 Documentation/translations/zh_CN/xxx.rst | 100 ++++++
+	 1 file changed, 100 insertions(+)
-然后执行::
+后续迭代 v3、v4 …… 时，新的 changelog 放在最上面，旧的保留在下方，按
+从新到旧的顺序叠加。例如 v3 补丁的 --- 下方::
-	git send-email v2* --to <maintainer email addr> --cc <others addr>
+	---
+	v2->v3:
+	  - ...本次相较 v2 的改动...
+	v1->v2:
+	  - ...上一次相较 v1 的改动...
+然后发送::
+	git send-email v2-0001-*.patch --to <maintainer email addr> --cc <others addr>
+如果您有多个补丁，迭代时请按以下原则：每次只迭代一个补丁，不要一次多个，
+每个补丁独立重复上述流程。所有评论落实到位后，导出 v2 时附带封面::
+	git format-patch -N -v 2 --cover-letter --thread=shallow
+打开 0 号补丁，在 BLURB HERE 处写明整组补丁相较 v1 的总体改动，格式
+同上面的单个补丁 changelog 示例。如果某个补丁需要单独说明，可在该
+补丁文件的 --- 分割线下方追加单个补丁的 changelog。最后执行::
+	git send-email v2-*.patch --to <maintainer email addr> --cc <others addr>
 这样，新的一版补丁就又发送到邮件列表等待审阅，之后就是重复这个过程。
+此外，如果审阅者或维护者在邮件回复中给出了 Reviewed-by tag，请在下
+一版补丁的 commit 信息中加入该 tag，放在 Signed-off-by 行的下方，以
+便维护者合入时保留您的审阅记录。
 审阅周期
 --------
 紧急处理
 --------
-如果您发送到邮件列表之后。发现发错了补丁集，尤其是在多个版本迭代的过程中；
+如果您发送到邮件列表之后，发现发错了补丁集，尤其是在多个版本迭代的过程中；
 自己发现了一些不妥的翻译；发送错了邮件列表……
-git email 默认会抄送给您一份，所以您可以切换为审阅者的角色审查自己的补丁，
+git send-email 默认会抄送给您一份，所以您可以切换为审阅者的角色审查自己的补丁，
 并留下评论，描述有何不妥，将在下个版本怎么改，并付诸行动，重新提交，但是
 注意频率，每天提交的次数不要超过两次。
 对于首次参与 Linux 内核中文文档翻译的新手，建议您在 linux 目录中运行以下命令：
 ::
-	tools/docs/checktransupdate.py -l zh_CN``
+	tools/docs/checktransupdate.py -l zh_CN
 该命令会列出需要翻译或更新的英文文档，结果同时保存在 checktransupdate.log 中。
 进阶
 ----
-希望您不只是单纯的翻译内核文档，在熟悉了一起与社区工作之后，您可以审阅其他
+希望您不只是单纯地翻译内核文档，在熟悉了与社区协作之后，您可以审阅其他
 开发者的翻译，或者提出具有建设性的主张。与此同时，与文档对应的代码更加有趣，
-而且需要完善的地方还有很多，勇敢地去探索，然后提交你的想法吧。
+而且需要完善的地方还有很多，勇敢地去探索，然后提交您的想法吧。
 常见的问题
 ==========
 ------------------
 大部分情况下，是由于您发送了非纯文本格式的信件，请尽量避免使用 webmail，推荐
-使用邮件客户端，比如 thunderbird，记得在设置中的回信配置那改为纯文本发送。
+使用邮件客户端，比如 thunderbird，记得在设置的回信配置中改为纯文本发送。
-如果超过了 24 小时，您依旧没有在<https://lore.kernel.org/linux-doc/>发现您的
+如果超过了 24 小时，您依旧没有在 https://lore.kernel.org/linux-doc/ 上找到您
-邮件，请联系您的网络管理员帮忙解决。
+的邮件，请联系您的网络管理员帮忙解决。

Documentation/translations/zh_CN/rust/arch-support.rst+1−0

@@ -23,6 +23,7 @@ · 22 unmodified lines
23	``arm64`` Maintained 仅小端序。	23	``arm64`` Maintained 仅小端序。
24	``loongarch`` Maintained \-	24	``loongarch`` Maintained \-
25	``riscv`` Maintained 仅 ``riscv64``，且仅限 LLVM/Clang。	25	``riscv`` Maintained 仅 ``riscv64``，且仅限 LLVM/Clang。
		26	``s390`` Maintained 必须禁用 ``CONFIG_EXPOLINE``。
26	``um`` Maintained \-	27	``um`` Maintained \-
27	``x86`` Maintained 仅 ``x86_64``。	28	``x86`` Maintained 仅 ``x86_64``。
28	============= ================ ==============================================	29	============= ================ ==============================================

Documentation/translations/zh_CN/rust/general-information.rst+79−3

@@ -13,6 +13,14 @@ · 12 unmodified lines
13		13
14	本文档包含了在内核中使用Rust支持时需要了解的有用信息。	14	本文档包含了在内核中使用Rust支持时需要了解的有用信息。
15		15
		16	``no_std``
		17	----------
		18
		19	内核中的 Rust 支持只能链接 `core <https://doc.rust-lang.org/core/>`_，
		20	而不能链接 `std <https://doc.rust-lang.org/std/>`_。供内核使用的 crate
		21	必须使用 ``#![no_std]`` 属性选择这种行为。
		22
		23
16	.. _rust_code_documentation_zh_cn:	24	.. _rust_code_documentation_zh_cn:
17		25
18	代码文档	26	代码文档
@@ -20,10 +28,18 @@ · 1 unmodified line
20		28
21	Rust内核代码使用其内置的文档生成器 ``rustdoc`` 进行记录。	29	Rust内核代码使用其内置的文档生成器 ``rustdoc`` 进行记录。
22		30
23	生成的HTML文档包括集成搜索、链接项（如类型、函数、常量）、源代码等。它们可以在以下地址阅读	31	生成的 HTML 文档包括集成搜索、链接项（如类型、函数、常量）、源代码等。
24	（TODO：当在主线中时链接，与其他文档一起生成）：	32	它们可以在以下地址阅读：
		33
		34	https://rust.docs.kernel.org
		35
		36	对于 linux-next，请参阅：
25		37
26	http://kernel.org/	38	https://rust.docs.kernel.org/next/
		39
		40	每个主要版本也有对应的标签，例如：
		41
		42	https://rust.docs.kernel.org/6.10/
27		43
28	这些文档也可以很容易地在本地生成和阅读。这相当快（与编译代码本身的顺序相同），而且不需要特	44	这些文档也可以很容易地在本地生成和阅读。这相当快（与编译代码本身的顺序相同），而且不需要特
29	殊的工具或环境。这有一个额外的好处，那就是它们将根据所使用的特定内核配置进行定制。要生成它	45	殊的工具或环境。这有一个额外的好处，那就是它们将根据所使用的特定内核配置进行定制。要生成它
@@ -62,6 +78,58 @@ Rust内核代码使用其内置的文档生成器 ``rustdoc`` 进行记录。 · 32 unmodified lines
62	模块（例如，驱动程序）不应该直接使用C语言的绑定。相反，子系统应该根据需要提供尽可能安	78	模块（例如，驱动程序）不应该直接使用C语言的绑定。相反，子系统应该根据需要提供尽可能安
63	全的抽象。	79	全的抽象。
64		80
		81	.. code-block::
		82
		83	rust/bindings/
		84	(rust/helpers/)
		85
		86	include/ -----+ <-+
		87	\| \|
		88	drivers/ rust/kernel/ +----------+ <-+ \|
		89	fs/ \| bindgen \| \|
		90	.../ +-------------------+ +----------+ --+ \|
		91	\| Abstractions \| \| \|
		92	+---------+ \| +------+ +------+ \| +----------+ \| \|
		93	\| my_foo \| -----> \| \| foo \| \| bar \| \| -------> \| Bindings \| <-+ \|
		94	\| driver \| Safe \| \| sub- \| \| sub- \| \| Unsafe \| \| \|
		95	+---------+ \| \|system\| \|system\| \| \| bindings \| <-----+
		96	\| \| +------+ +------+ \| \| crate \| \|
		97	\| \| kernel crate \| +----------+ \|
		98	\| +-------------------+ \|
		99	\| \|
		100	+------------------# FORBIDDEN #--------------------------------+
		101
		102	主要思想是将所有与内核 C API 的直接交互封装到经过仔细审查和文档化的抽象
		103	中。这样，只要满足以下条件，这些抽象的用户就不能引入未定义行为
		104	（undefined behavior，UB）：
		105
		106	#. 抽象是正确的（"可靠"）。
		107	#. 任何 ``unsafe`` 块都遵守调用块内操作所需的安全契约。类似地，任何
		108	``unsafe impl`` 都遵守实现该特性所需的安全契约。
		109
		110	绑定
		111	~~~~
		112
		113	通过从 ``include/`` 中将 C 头文件包含到
		114	``rust/bindings/bindings_helper.h``， ``bindgen`` 工具将为所包含的子系统
		115	自动生成绑定。构建后，请查看 ``rust/bindings/`` 目录中的
		116	``*_generated.rs`` 输出文件。
		117
		118	对于 ``bindgen`` 不会自动生成的 C 头文件部分，例如 C ``inline`` 函数或
		119	非平凡宏，可以在 ``rust/helpers/`` 中添加一个小型包装函数，使其也可供
		120	Rust 端使用。
		121
		122	抽象
		123	~~~~
		124
		125	抽象是绑定和内核内用户之间的层。它们位于 ``rust/kernel/`` 中，其作用是
		126	将对绑定的不安全访问封装到尽可能安全并暴露给用户的 API 中。抽象的用户
		127	包括用 Rust 编写的驱动程序或文件系统等。
		128
		129	除了安全方面，这些抽象还应该易于使用，也就是说，把 C 接口转换为符合
		130	Rust 惯例的代码。基本示例包括将 C 的资源获取和释放转换为 Rust 的初始化
		131	和清理模式，或者将 C 整数错误码转换为 Rust 的 ``Result``。
		132
65		133
66	有条件的编译	134	有条件的编译
67	------------	135	------------
@@ -74,3 +142,11 @@ Rust代码可以访问基于内核配置的条件性编译: · 6 unmodified lines
74	#[cfg(CONFIG_X="y")] // Enabled as a built-in (`y`)	142	#[cfg(CONFIG_X="y")] // Enabled as a built-in (`y`)
75	#[cfg(CONFIG_X="m")] // Enabled as a module (`m`)	143	#[cfg(CONFIG_X="m")] // Enabled as a module (`m`)
76	#[cfg(not(CONFIG_X))] // Disabled	144	#[cfg(not(CONFIG_X))] // Disabled
		145
		146	对于 Rust 的 ``cfg`` 不支持的其他条件，例如带有数值比较的表达式，可以
		147	定义一个新的 Kconfig 符号：
		148
		149	.. code-block:: kconfig
		150
		151	config RUSTC_HAS_SPAN_FILE
		152	def_bool RUSTC_VERSION >= 108800

Documentation/translations/zh_CN/rust/quick-start.rst+19−29

@@ -59,7 +59,7 @@ Fedora Linux 提供较新的 Rust 版本，因此通常开箱即用，例如:: · 58 unmodified lines
59	Gentoo Linux	59	Gentoo Linux
60	************	60	************
61		61
62	Gentoo Linux（尤其是 testing 分支）提供较新的 Rust 版本，因此通常开箱即用，	62	Gentoo Linux 提供较新的 Rust 版本，因此通常开箱即用，
63	例如::	63	例如::
64		64
65	USE='rust-src rustfmt clippy' emerge dev-lang/rust dev-util/bindgen	65	USE='rust-src rustfmt clippy' emerge dev-lang/rust dev-util/bindgen
@@ -70,7 +70,7 @@ Gentoo Linux（尤其是 testing 分支）提供较新的 Rust 版本，因此 · 4 unmodified lines
70	Nix	70	Nix
71	***	71	***
72		72
73	Nix（unstable 频道）提供较新的 Rust 版本，因此通常开箱即用，例如::	73	Nix 提供较新的 Rust 版本，因此通常开箱即用，例如::
74		74
75	{ pkgs ? import <nixpkgs> {} }:	75	{ pkgs ? import <nixpkgs> {} }:
76	pkgs.mkShell {	76	pkgs.mkShell {
@@ -85,16 +85,14 @@ openSUSE · 8 unmodified lines
85	openSUSE Slowroll 和 openSUSE Tumbleweed 提供较新的 Rust 版本，因此通常开箱	85	openSUSE Slowroll 和 openSUSE Tumbleweed 提供较新的 Rust 版本，因此通常开箱
86	即用，例如::	86	即用，例如::
87		87
88	zypper install rust rust1.79-src rust-bindgen clang	88	zypper install rust rust-src rust-bindgen clang
89		89
90		90
91	Ubuntu	91	Ubuntu
92	******	92	******
93		93
94	25.04	94	Ubuntu 25.10 和 26.04 LTS 提供较新的 Rust 版本，因此通常开箱即用，
95	~~~~~	95	例如::
96
97	最新的 Ubuntu 版本提供较新的 Rust 版本，因此通常开箱即用，例如::
98		96
99	apt install rustc rust-src bindgen rustfmt rust-clippy	97	apt install rustc rust-src bindgen rustfmt rust-clippy
100		98
@@ -111,32 +109,32 @@ Ubuntu · 10 unmodified lines
111	虽然 Ubuntu 24.04 LTS 及更早版本仍然提供较新的 Rust 版本，但它们需要一些额外的配	109	虽然 Ubuntu 24.04 LTS 及更早版本仍然提供较新的 Rust 版本，但它们需要一些额外的配
112	置，使用带版本号的软件包，例如::	110	置，使用带版本号的软件包，例如::
113		111
114	apt install rustc-1.80 rust-1.80-src bindgen-0.65 rustfmt-1.80 \	112	apt install rustc-1.85 rust-1.85-src bindgen-0.71 rustfmt-1.85 \
115	rust-1.80-clippy	113	rust-1.85-clippy
116	ln -s /usr/lib/rust-1.80/bin/rustfmt /usr/bin/rustfmt-1.80	114	ln -s /usr/lib/rust-1.85/bin/rustfmt /usr/bin/rustfmt-1.85
117	ln -s /usr/lib/rust-1.80/bin/clippy-driver /usr/bin/clippy-driver-1.80	115	ln -s /usr/lib/rust-1.85/bin/clippy-driver /usr/bin/clippy-driver-1.85
118		116
119	这些软件包都不会将其工具设置为默认值；因此应该显式指定它们，例如::	117	这些软件包都不会将其工具设置为默认值；因此应该显式指定它们，例如::
120		118
121	make LLVM=1 RUSTC=rustc-1.80 RUSTDOC=rustdoc-1.80 RUSTFMT=rustfmt-1.80 \	119	make LLVM=1 RUSTC=rustc-1.85 RUSTDOC=rustdoc-1.85 RUSTFMT=rustfmt-1.85 \
122	CLIPPY_DRIVER=clippy-driver-1.80 BINDGEN=bindgen-0.65	120	CLIPPY_DRIVER=clippy-driver-1.85 BINDGEN=bindgen-0.71
123		121
124	或者，修改 ``PATH`` 变量将 Rust 1.80 的二进制文件放在前面，并将 ``bindgen`` 设	122	或者，修改 ``PATH`` 变量将 Rust 1.85 的二进制文件放在前面，并将 ``bindgen`` 设
125	置为默认值，例如::	123	置为默认值，例如::
126		124
127	PATH=/usr/lib/rust-1.80/bin:$PATH	125	PATH=/usr/lib/rust-1.85/bin:$PATH
128	update-alternatives --install /usr/bin/bindgen bindgen \	126	update-alternatives --install /usr/bin/bindgen bindgen \
129	/usr/bin/bindgen-0.65 100	127	/usr/bin/bindgen-0.71 100
130	update-alternatives --set bindgen /usr/bin/bindgen-0.65	128	update-alternatives --set bindgen /usr/bin/bindgen-0.71
131		129
132	使用带版本号的软件包时需要设置 ``RUST_LIB_SRC``，例如::	130	使用带版本号的软件包时可能需要设置 ``RUST_LIB_SRC``，例如::
133		131
134	RUST_LIB_SRC=/usr/src/rustc-$(rustc-1.80 --version \| cut -d' ' -f2)/library	132	RUST_LIB_SRC=/usr/src/rustc-$(rustc-1.85 --version \| cut -d' ' -f2)/library
135		133
136	为方便起见，可以将 ``RUST_LIB_SRC`` 导出到全局环境中。	134	为方便起见，可以将 ``RUST_LIB_SRC`` 导出到全局环境中。
137		135
138	此外， ``bindgen-0.65`` 在较新的版本（24.04 LTS 和 24.10）中可用，但在更早的版	136	此外， ``bindgen-0.71`` 在较新的版本（24.04 LTS）中可用，但在更早的版本
139	本（20.04 LTS 和 22.04 LTS）中可能不可用，因此可能需要手动构建 ``bindgen``	137	（20.04 LTS 和 22.04 LTS）中可能不可用，因此可能需要手动构建 ``bindgen``
140	（请参见下文）。	138	（请参见下文）。
141		139
142		140
@@ -325,11 +323,3 @@ Rust支持（CONFIG_RUST）需要在 ``General setup`` 菜单中启用。在其 · 182 unmodified lines
325		323
326	要想深入了解，请看 ``samples/rust/`` 下的样例源代码、 ``rust/`` 下的Rust支持代码和	324	要想深入了解，请看 ``samples/rust/`` 下的样例源代码、 ``rust/`` 下的Rust支持代码和
327	``Kernel hacking`` 下的 ``Rust hacking`` 菜单。	325	``Kernel hacking`` 下的 ``Rust hacking`` 菜单。
328
329	如果使用的是GDB/Binutils，而Rust符号没有被demangled，原因是工具链还不支持Rust的新v0
330	mangling方案。有几个办法可以解决：
331
332	- 安装一个较新的版本（GDB >= 10.2, Binutils >= 2.36）。
333
334	- 一些版本的GDB（例如vanilla GDB 10.1）能够使用嵌入在调试信息(``CONFIG_DEBUG_INFO``)
335	中的pre-demangled的名字。

Documentation/translations/zh_CN/rust/testing.rst+4−0

 这些测试通过 ``kunit_tests`` 过程宏引入，该宏将测试套件的名称作为参数。
+每个测试套件都应该由 ``rust/kernel/Kconfig.test`` 中的 Kconfig 选项保护。
 例如，假设想要测试前面文档测试示例中的函数 ``f``，我们可以在定义该函数的同一文件中编写：
 .. code-block:: rust
+	#[cfg(CONFIG_RUST_MYMOD_KUNIT_TEST)]
 	#[kunit_tests(rust_kernel_mymod)]
 	mod tests {
 	    use super::*;
 .. code-block:: rust
+	#[cfg(CONFIG_RUST_MYMOD_KUNIT_TEST)]
 	#[kunit_tests(rust_kernel_mymod)]
 	mod tests {
 	    use super::*;

Documentation/translations/zh_CN/scheduler/sched-energy.rst+1−1

@@ -119,7 +119,7 @@ EAS覆盖了CFS的任务唤醒平衡代码。在唤醒平衡时，它使用平 · 118 unmodified lines
119		119
120	如果唤醒的任务被迁移，find_energy_efficient_cpu()使用compute_energy()来估算	120	如果唤醒的任务被迁移，find_energy_efficient_cpu()使用compute_energy()来估算
121	系统将消耗多少能量。compute_energy()检查各CPU当前的利用率情况，并尝试调整来	121	系统将消耗多少能量。compute_energy()检查各CPU当前的利用率情况，并尝试调整来
122	“模拟”任务迁移。EM框架提供了API em_pd_energy()计算每个性能域在给定的利用率条件	122	“模拟”任务迁移。EM框架提供了API em_cpu_energy()计算每个性能域在给定的利用率条件
123	下的预期能量消耗。	123	下的预期能量消耗。
124		124
125	下面详细介绍一个优化能量消耗的任务放置决策的例子。	125	下面详细介绍一个优化能量消耗的任务放置决策的例子。

Documentation/translations/zh_CN/security/self-protection.rst+1−1

@@ -97,7 +97,7 @@ ARCH_OPTIONAL_KERNEL_RWX时的默认设置。 · 96 unmodified lines
97	--------------------	97	--------------------
98		98
99	对于64位系统，一种消除许多系统调用最简单的方法是构建时不启用	99	对于64位系统，一种消除许多系统调用最简单的方法是构建时不启用
100	CONFIG_CONPAT。然而，这种情况通常不可行。	100	CONFIG_COMPAT。然而，这种情况通常不可行。
101		101
102	“seccomp”系统为用户空间提供了一种可选功能，提供了一种减少可供	102	“seccomp”系统为用户空间提供了一种可选功能，提供了一种减少可供
103	运行中进程使用内核入口点数量的方法。这限制了可以访问内核代码	103	运行中进程使用内核入口点数量的方法。这限制了可以访问内核代码

Documentation/translations/zh_TW/process/stable-api-nonsense.rst+31−31

@@ -14,21 +14,21 @@ · 13 unmodified lines
14	中文版校譯者：李陽 Li Yang <leoyang.li@nxp.com>	14	中文版校譯者：李陽 Li Yang <leoyang.li@nxp.com>
15	胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn>	15	胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn>
16		16
17	Linux 內核驅動接口	17	Linux 內核驅動介面
18	==================	18	==================
19		19
20	寫作本文檔的目的，是爲了解釋爲什麼Linux既沒有二進制內核接口，也沒有穩定	20	寫作本文檔的目的，是爲了解釋爲什麼Linux既沒有二進制內核介面，也沒有穩定
21	的內核接口。這裏所說的內核接口，是指內核裏的接口，而不是內核和用戶空間	21	的內核介面。這裏所說的內核介面，是指內核裏的介面，而不是內核和用戶空間
22	的接口。內核到用戶空間的接口，是提供給應用程序使用的系統調用，系統調用	22	的介面。內核到用戶空間的介面，是提供給應用程序使用的系統調用，系統調用
23	在歷史上幾乎沒有過變化，將來也不會有變化。我有一些老應用程序是在0.9版本	23	在歷史上幾乎沒有過變化，將來也不會有變化。我有一些老應用程序是在0.9版本
24	或者更早版本的內核上編譯的，在使用2.6版本內核的Linux發佈上依然用得很好	24	或者更早版本的內核上編譯的，在使用2.6版本內核的Linux發佈上依然用得很好
25	。用戶和應用程序作者可以將這個接口看成是穩定的。	25	。用戶和應用程序作者可以將這個介面看成是穩定的。
26		26
27		27
28	執行綱要	28	執行綱要
29	--------	29	--------
30		30
31	你也許以爲自己想要穩定的內核接口，但是你不清楚你要的實際上不是它。你需	31	你也許以爲自己想要穩定的內核介面，但是你不清楚你要的實際上不是它。你需
32	要的其實是穩定的驅動程序，而你只有將驅動程序放到公版內核的源代碼樹裏，	32	要的其實是穩定的驅動程序，而你只有將驅動程序放到公版內核的源代碼樹裏，
33	纔有可能達到這個目的。而且這樣做還有很多其它好處，正是因爲這些好處使得	33	纔有可能達到這個目的。而且這樣做還有很多其它好處，正是因爲這些好處使得
34	Linux能成爲強壯，穩定，成熟的操作系統，這也是你最開始選擇Linux的原因。	34	Linux能成爲強壯，穩定，成熟的操作系統，這也是你最開始選擇Linux的原因。
@@ -37,8 +37,8 @@ Linux能成爲強壯，穩定，成熟的操作系統，這也是你最開始選 · 2 unmodified lines
37	入門	37	入門
38	-----	38	-----
39		39
40	只有那些寫驅動程序的“怪人”纔會擔心內核接口的改變，對廣大用戶來說，既	40	只有那些寫驅動程序的“怪人”纔會擔心內核介面的改變，對廣大用戶來說，既
41	看不到內核接口，也不需要去關心它。	41	看不到內核介面，也不需要去關心它。
42		42
43	首先，我不打算討論關於任何非GPL許可的內核驅動的法律問題，這些非GPL許可	43	首先，我不打算討論關於任何非GPL許可的內核驅動的法律問題，這些非GPL許可
44	的驅動程序包括不公開源代碼，隱藏源代碼，二進制或者是用源代碼包裝，或者	44	的驅動程序包括不公開源代碼，隱藏源代碼，二進制或者是用源代碼包裝，或者
@@ -46,14 +46,14 @@ Linux能成爲強壯，穩定，成熟的操作系統，這也是你最開始選 · 1 unmodified line
46	詢律師，我只是一個程序員，所以我只打算探討技術問題（不是小看法律問題，	46	詢律師，我只是一個程序員，所以我只打算探討技術問題（不是小看法律問題，
47	法律問題很實際，並且需要一直關注）。	47	法律問題很實際，並且需要一直關注）。
48		48
49	既然只談技術問題，我們就有了下面兩個主題：二進制內核接口和穩定的內核源	49	既然只談技術問題，我們就有了下面兩個主題：二進制內核介面和穩定的內核源
50	代碼接口。這兩個問題是互相關聯的，讓我們先解決掉二進制接口的問題。	50	代碼介面。這兩個問題是互相關聯的，讓我們先解決掉二進制介面的問題。
51		51
52		52
53	二進制內核接口	53	二進制內核介面
54	--------------	54	--------------
55	假如我們有一個穩定的內核源代碼接口，那麼自然而然的，我們就擁有了穩定的	55	假如我們有一個穩定的內核源代碼介面，那麼自然而然的，我們就擁有了穩定的
56	二進制接口，是這樣的嗎？錯。讓我們看看關於Linux內核的幾點事實：	56	二進制介面，是這樣的嗎？錯。讓我們看看關於Linux內核的幾點事實：
57		57
58	- 取決於所用的C編譯器的版本，不同的內核數據結構裏的結構體的對齊方	58	- 取決於所用的C編譯器的版本，不同的內核數據結構裏的結構體的對齊方
59	式會有差別，代碼中不同函數的表現形式也不一樣（函數是不是被inline	59	式會有差別，代碼中不同函數的表現形式也不一樣（函數是不是被inline
@@ -84,18 +84,18 @@ Linux能成爲強壯，穩定，成熟的操作系統，這也是你最開始選 · 24 unmodified lines
84	深刻的教訓...	84	深刻的教訓...
85		85
86		86
87	穩定的內核源代碼接口	87	穩定的內核源代碼介面
88	--------------------	88	--------------------
89		89
90	如果有人不將他的內核驅動程序，放入公版內核的源代碼樹，而又想讓驅動程序	90	如果有人不將他的內核驅動程序，放入公版內核的源代碼樹，而又想讓驅動程序
91	一直保持在最新的內核中可用，那麼這個話題將會變得沒完沒了。	91	一直保持在最新的內核中可用，那麼這個話題將會變得沒完沒了。
92	內核開發是持續而且快節奏的，從來都不會慢下來。內核開發人員在當前接口中	92	內核開發是持續而且快節奏的，從來都不會慢下來。內核開發人員在當前介面中
93	找到bug，或者找到更好的實現方式。一旦發現這些，他們就很快會去修改當前的	93	找到bug，或者找到更好的實現方式。一旦發現這些，他們就很快會去修改當前的
94	接口。修改接口意味着，函數名可能會改變，結構體可能被擴充或者刪減，函數	94	介面。修改介面意味着，函數名可能會改變，結構體可能被擴充或者刪減，函數
95	的參數也可能發生改變。一旦接口被修改，內核中使用這些接口的地方需要同時	95	的參數也可能發生改變。一旦介面被修改，內核中使用這些介面的地方需要同時
96	修正，這樣才能保證所有的東西繼續工作。	96	修正，這樣才能保證所有的東西繼續工作。
97		97
98	舉一個例子，內核的USB驅動程序接口在USB子系統的整個生命週期中，至少經歷	98	舉一個例子，內核的USB驅動程序介面在USB子系統的整個生命週期中，至少經歷
99	了三次重寫。這些重寫解決以下問題：	99	了三次重寫。這些重寫解決以下問題：
100		100
101	- 把數據流從同步模式改成非同步模式，這個改動減少了一些驅動程序的	101	- 把數據流從同步模式改成非同步模式，這個改動減少了一些驅動程序的
@@ -105,22 +105,22 @@ Linux能成爲強壯，穩定，成熟的操作系統，這也是你最開始選 · 3 unmodified lines
105	需要提供更多的參數給USB核心，以修正了很多已經被記錄在案的死鎖。	105	需要提供更多的參數給USB核心，以修正了很多已經被記錄在案的死鎖。
106		106
107	這和一些封閉源代碼的操作系統形成鮮明的對比，在那些操作系統上，不得不額	107	這和一些封閉源代碼的操作系統形成鮮明的對比，在那些操作系統上，不得不額
108	外的維護舊的USB接口。這導致了一個可能性，新的開發者依然會不小心使用舊的	108	外的維護舊的USB介面。這導致了一個可能性，新的開發者依然會不小心使用舊的
109	接口，以不恰當的方式編寫代碼，進而影響到操作系統的穩定性。	109	介面，以不恰當的方式編寫代碼，進而影響到操作系統的穩定性。
110	在上面的例子中，所有的開發者都同意這些重要的改動，在這樣的情況下修改代	110	在上面的例子中，所有的開發者都同意這些重要的改動，在這樣的情況下修改代
111	價很低。如果Linux保持一個穩定的內核源代碼接口，那麼就得創建一個新的接口	111	價很低。如果Linux保持一個穩定的內核源代碼介面，那麼就得創建一個新的介面
112	；舊的，有問題的接口必須一直維護，給Linux USB開發者帶來額外的工作。既然	112	；舊的，有問題的介面必須一直維護，給Linux USB開發者帶來額外的工作。既然
113	所有的Linux USB驅動的作者都是利用自己的時間工作，那麼要求他們去做毫無意	113	所有的Linux USB驅動的作者都是利用自己的時間工作，那麼要求他們去做毫無意
114	義的免費額外工作，是不可能的。	114	義的免費額外工作，是不可能的。
115	安全問題對Linux來說十分重要。一個安全問題被發現，就會在短時間內得到修	115	安全問題對Linux來說十分重要。一個安全問題被發現，就會在短時間內得到修
116	正。在很多情況下，這將導致Linux內核中的一些接口被重寫，以從根本上避免安	116	正。在很多情況下，這將導致Linux內核中的一些介面被重寫，以從根本上避免安
117	全問題。一旦接口被重寫，所有使用這些接口的驅動程序，必須同時得到修正，	117	全問題。一旦介面被重寫，所有使用這些介面的驅動程序，必須同時得到修正，
118	以確定安全問題已經得到修復並且不可能在未來還有同樣的安全問題。如果內核	118	以確定安全問題已經得到修復並且不可能在未來還有同樣的安全問題。如果內核
119	內部接口不允許改變，那麼就不可能修復這樣的安全問題，也不可能確認這樣的	119	內部介面不允許改變，那麼就不可能修復這樣的安全問題，也不可能確認這樣的
120	安全問題以後不會發生。	120	安全問題以後不會發生。
121	開發者一直在清理內核接口。如果一個接口沒有人在使用了，它就會被刪除。這	121	開發者一直在清理內核介面。如果一個介面沒有人在使用了，它就會被刪除。這
122	樣可以確保內核儘可能的小，而且所有潛在的接口都會得到儘可能完整的測試	122	樣可以確保內核儘可能的小，而且所有潛在的介面都會得到儘可能完整的測試
123	（沒有人使用的接口是不可能得到良好的測試的）。	123	（沒有人使用的介面是不可能得到良好的測試的）。
124		124
125		125
126	要做什麼	126	要做什麼
@@ -128,11 +128,11 @@ Linux能成爲強壯，穩定，成熟的操作系統，這也是你最開始選 · 1 unmodified line
128		128
129	如果你寫了一個Linux內核驅動，但是它還不在Linux源代碼樹裏，作爲一個開發	129	如果你寫了一個Linux內核驅動，但是它還不在Linux源代碼樹裏，作爲一個開發
130	者，你應該怎麼做？爲每個發佈的每個版本提供一個二進制驅動，那簡直是一個	130	者，你應該怎麼做？爲每個發佈的每個版本提供一個二進制驅動，那簡直是一個
131	噩夢，要跟上永遠處於變化之中的內核接口，也是一件辛苦活。	131	噩夢，要跟上永遠處於變化之中的內核介面，也是一件辛苦活。
132	很簡單，讓你的驅動進入內核源代碼樹（要記得我們在談論的是以GPL許可發行	132	很簡單，讓你的驅動進入內核源代碼樹（要記得我們在談論的是以GPL許可發行
133	的驅動，如果你的代碼不符合GPL，那麼祝你好運，你只能自己解決這個問題了，	133	的驅動，如果你的代碼不符合GPL，那麼祝你好運，你只能自己解決這個問題了，
134	你這個吸血鬼<把Andrew和Linus對吸血鬼的定義鏈接到這裏>）。當你的代碼加入	134	你這個吸血鬼<把Andrew和Linus對吸血鬼的定義鏈接到這裏>）。當你的代碼加入
135	公版內核源代碼樹之後，如果一個內核接口改變，你的驅動會直接被修改接口的	135	公版內核源代碼樹之後，如果一個內核介面改變，你的驅動會直接被修改介面的
136	那個人修改。保證你的驅動永遠都可以編譯通過，並且一直工作，你幾乎不需要	136	那個人修改。保證你的驅動永遠都可以編譯通過，並且一直工作，你幾乎不需要
137	做什麼事情。	137	做什麼事情。
138		138
@@ -142,7 +142,7 @@ Linux能成爲強壯，穩定，成熟的操作系統，這也是你最開始選 · 3 unmodified lines
142	- 其他人會給驅動添加新特性。	142	- 其他人會給驅動添加新特性。
143	- 其他人會找到驅動中的bug並修復。	143	- 其他人會找到驅動中的bug並修復。
144	- 其他人會在驅動中找到性能優化的機會。	144	- 其他人會在驅動中找到性能優化的機會。
145	- 當外部的接口的改變需要修改驅動程序的時候，其他人會修改驅動程序	145	- 當外部的介面的改變需要修改驅動程序的時候，其他人會修改驅動程序
146	- 不需要聯繫任何發行商，這個驅動會自動的隨着所有的Linux發佈一起發	146	- 不需要聯繫任何發行商，這個驅動會自動的隨着所有的Linux發佈一起發
147	布。	147	布。
148		148

MAINTAINERS+4−3

 DOCUMENTATION
 M:	Jonathan Corbet <corbet@lwn.net>
 R:	Shuah Khan <skhan@linuxfoundation.org>
+R:	Randy Dunlap <rdunlap@infradead.org>
 L:	linux-doc@vger.kernel.org
 S:	Maintained
 P:	Documentation/doc-guide/maintainer-profile.rst
 F:	kernel/trace/trace_sched_wakeup.c
 TRADITIONAL CHINESE DOCUMENTATION
-M:	Hu Haowen <2023002089@link.tyut.edu.cn>
+M:	Chen-Yu Yeh <chenyou910331@gmail.com>
+M:	Weijie Yuan <wy@wyuan.org>
+M:	Dongliang Mu <dzm91@hust.edu.cn>
 S:	Maintained
-W:	https://github.com/srcres258/linux-doc
-T:	git https://github.com/srcres258/linux-doc.git doc-zh-tw
 F:	Documentation/translations/zh_TW/
 TRIGGER SOURCE

README+9−9

@@ -30,15 +30,15 @@ Who Are You? · 29 unmodified lines
30		30
31	Find your role below:	31	Find your role below:
32		32
33	* New Kernel Developer - Getting started with kernel development	33	* New Kernel Developer: Getting started with kernel development
34	* Academic Researcher - Studying kernel internals and architecture	34	* Academic Researcher: Studying kernel internals and architecture
35	* Security Expert - Hardening and vulnerability analysis	35	* Security Expert: Hardening and vulnerability analysis
36	* Backport/Maintenance Engineer - Maintaining stable kernels	36	* Backport/Maintenance Engineer: Maintaining stable kernels
37	* System Administrator - Configuring and troubleshooting	37	* System Administrator: Configuring and troubleshooting
38	* Maintainer - Leading subsystems and reviewing patches	38	* Maintainer: Leading subsystems and reviewing patches
39	* Hardware Vendor - Writing drivers for new hardware	39	* Hardware Vendor: Writing drivers for new hardware
40	* Distribution Maintainer - Packaging kernels for distros	40	* Distribution Maintainer: Packaging kernels for distros
41	* AI Coding Assistant - LLMs and AI-powered development tools	41	* AI Coding Assistant: LLMs and AI-powered development tools
42		42
43		43
44	For Specific Users	44	For Specific Users

scripts/checkpatch.pl+4−3

 				}
 			}
-			# Assisted-by uses AGENT_NAME:MODEL_VERSION format, not email
+			# Assisted-by uses a free-form value (e.g. "LLM"), not an
+			# email address, so skip the email format checks below.
 			if ($sign_off =~ /^Assisted-by:/i) {
-				if ($email !~ /^\S+:\S+/) {
+				if ($email =~ /^\s*$/) {
 					WARN("BAD_SIGN_OFF",
-					     "Assisted-by expects 'AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2]' format\n" . $herecurr);
+					     "Assisted-by requires a value\n" . $herecurr);
 				}
 				next;
 			}

tools/docs/documentation-file-ref-check+1−1

@@ -143,7 +143,7 @@ while (<IN>) { · 142 unmodified lines
143	# Check if exists, evaluating wildcards	143	# Check if exists, evaluating wildcards
144	next if (grep -e, glob("$ref $fulref"));	144	next if (grep -e, glob("$ref $fulref"));
145		145
146	# Accept relative Documentation patches for tools/	146	# Accept relative Documentation paths for tools/
147	if ($f =~ m/tools/) {	147	if ($f =~ m/tools/) {
148	my $path = $f;	148	my $path = $f;
149	$path =~ s,(.)/.,$1,;	149	$path =~ s,(.)/.,$1,;

tools/docs/sphinx-build-wrapper+11−2

     def get_path(self, path, use_cwd=False, abs_path=False):
         """
-        Ancillary routine to handle patches the right way, as shell does.
+        Ancillary routine to handle paths the right way, as shell does.
-        It first expands "~" and "~user". Then, if patch is not absolute,
+        It first expands "~" and "~user". Then, if path is not absolute,
         join self.srctree. Finally, if requested, convert to abspath.
         """
         self.kernelrelease = os.environ.get("KERNELRELEASE", "unknown")
         self.pdflatex = os.environ.get("PDFLATEX", "xelatex")
+        #
+        # Add localversion* to kernelversion if present
+        #
+        for file in glob(os.environ["srctree"] + "/localversion*"):
+            if not file.endswith(".orig"):
+                with open(file, 'r', encoding='utf-8') as f:
+                    text = f.read()
+                    self.kernelversion += text
         #
         # Kernel main Makefile defines a PYTHON3 variable whose default is
         # "python3". When set to a different value, it allows running a

tools/lib/python/abi/abi_regex.py+5−6

         (re.compile(r"\[[^\]]+\]"), "\\\\w\xf7"),
         (re.compile(r"XX+"), "\\\\w\xf7"),
-        (re.compile(r"([^A-Z])[XYZ]([^A-Z])"), "\\1\\\\w\xf7\\2"),
+        (re.compile(r"(?<![A-Z])[XYZ](?![A-Z])"), "\\\\w\xf7"),
-        (re.compile(r"([^A-Z])[XYZ]$"), "\\1\\\\w\xf7"),
         (re.compile(r"_[AB]_"), "_\\\\w\xf7_"),
         # Recover [0-9] type of patterns
             if self.search_string:
                 if what.find(self.search_string) >= 0:
                     print(f"What: {what}")
-        except re.PatternError:
+        except re.error:
             self.log.warning("Ignoring '%s' as it produced an invalid regex:\n"
                              "           '%s'", what, new)
                 try:
                     self.re_string = re.compile(self.search_string)
-                except re.PatternError as e:
+                except re.error as e:
                     msg = f"{self.search_string} is not a valid regular expression"
                     raise ValueError(msg) from e
                 for r, s in self.re_whats:
                     try:
                         new = r.sub(s, new)
-                    except re.PatternError as e:
+                    except re.error as e:
                         # Help debugging troubles with new regexes
-                        raise re.PatternError(f"{e}\nwhile re.sub('{r.pattern}', {s}, str)") from e
+                        raise re.error(f"{e}\nwhile re.sub('{r.pattern}', {s}, str)") from e
                 v["regex"].append(new)

tools/lib/python/kdoc/kdoc_output.py+1−1

@@ -624,7 +624,7 @@ class ManFormat(OutputFormat): · 623 unmodified lines
624	``manual``	624	``manual``
625	Defaults to ``Kernel API Manual``.	625	Defaults to ``Kernel API Manual``.
626		626
627	The above controls the output of teh corresponding fields on troff	627	The above controls the output of the corresponding fields on troff
628	title headers, which will be filled like this::	628	title headers, which will be filled like this::
629		629
630	.TH "{name}" {section} "{date}" "{modulename}" "{manual}"	630	.TH "{name}" {section} "{date}" "{modulename}" "{manual}"

tools/lib/python/kdoc/kdoc_parser.py+53−5

 import sys
 import re
+import difflib
 from pprint import pformat
 from kdoc.c_lex import CTokenizer, tokenizer_set_log
                         self.push_parameter(ln, decl_type, param, dtype,
                                             arg, declaration_name)
+    def get_suggestions_hint(self, decl_name, possible_names):
+        # For decl name 'flags' or 'flgas', suggests 'substruct.flags'
+        submember_exact = []
+        submember_substrings = []
+        submember_suggestions = []
+        for possible_name in possible_names:
+            parts = possible_name.strip().split('.')
+            if len(parts) < 2:
+                continue
+            final_part = parts[-1]
+            if decl_name == final_part:
+                submember_exact.append(possible_name)
+            elif decl_name in final_part:
+                submember_substrings.append(possible_name)
+            elif difflib.get_close_matches(decl_name, [final_part]):
+                submember_suggestions.append(possible_name)
+        # For decl name 'flgas', suggests 'flags'
+        full_suggestions = difflib.get_close_matches(decl_name, possible_names)
+        # For decl name 'member', suggests 'longer_member'
+        full_substrings = [name for name in possible_names if decl_name in name]
+        ordered_lists = [
+            submember_exact,
+            submember_substrings,
+            submember_suggestions,
+            full_suggestions,
+            full_substrings,
+        ]
+        # Deduplicate but maintain order from most to least likely:
+        unique_suggestions = {}
+        for suggestion_list in ordered_lists:
+            for suggestion in suggestion_list:
+                unique_suggestions[suggestion] = None
+        suggestions = list(unique_suggestions.keys())
+        if not suggestions:
+            return ""
+        joined_suggestions = "', '".join(suggestions)
+        return f"(did you mean one of: '{joined_suggestions}')"
     def check_sections(self, ln, decl_name, decl_type):
         """
         Check for errors inside sections, emitting warnings if not found
         for section in self.entry.sections:
             if section not in self.entry.parameterlist and \
                not known_sections.search(section):
+                hint = self.get_suggestions_hint(section, self.entry.parameterlist)
                 if decl_type == 'function':
                     dname = f"{decl_type} parameter"
                 else:
                     dname = f"{decl_type} member"
                 self.emit_msg(ln,
-                              f"Excess {dname} '{section}' description in '{decl_name}'")
+                              f"Excess {dname} '{section}' description in '{decl_name}' {hint}".strip())
         #
         # Check that documented parameter names (from doc comments, including
             if param_name in self.entry.parameterlist:
                 continue
+            hint = self.get_suggestions_hint(param_name, self.entry.parameterlist)
             if decl_type == 'function':
                 dname = f"{decl_type} parameter"
             else:
                 dname = f"{decl_type} member"
             self.emit_msg(ln,
-                          f"Excess {dname} '{param_name}' description in '{decl_name}'")
+                          f"Excess {dname} '{param_name}' description in '{decl_name}' {hint}".strip())
     def check_return_section(self, ln, declaration_name, return_type):
         """
         if self.entry.identifier != declaration_name:
             self.emit_msg(ln, f"expecting prototype for {decl_type} {self.entry.identifier}. "
-                          f"Prototype was for {decl_type} {declaration_name} instead\n")
+                          f"Prototype was for {decl_type} {declaration_name} instead")
             return
         #
         # Go through the list of members applying all of our transformations.
             if self.entry.identifier != declaration_name:
                 self.emit_msg(ln,
-                              f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead\n")
+                              f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead")
                 return
             self.create_parameter_list(ln, 'function', args, ',', declaration_name)
             if self.entry.identifier != declaration_name:
                 self.emit_msg(ln,
-                              f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead\n")
+                              f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead")
                 return
             self.output_declaration('typedef', declaration_name,

tools/lib/python/kdoc/xforms_lists.py+1−0

@@ -90,6 +90,7 @@ class CTransforms: · 89 unmodified lines
90	(CMatch("__(?:re)?alloc_size"), ""),	90	(CMatch("__(?:re)?alloc_size"), ""),
91	(CMatch("__diagnose_as"), ""),	91	(CMatch("__diagnose_as"), ""),
92	(CMatch("DECL_BUCKET_PARAMS"), r"\1, \2"),	92	(CMatch("DECL_BUCKET_PARAMS"), r"\1, \2"),
		93	(CMatch("DEFINE_IDTENTRY_IRQ"), r"static void \1(struct pt_regs *regs, u32 vector)"),
93	(CMatch("__cond_acquires"), ""),	94	(CMatch("__cond_acquires"), ""),
94	(CMatch("__cond_releases"), ""),	95	(CMatch("__cond_releases"), ""),
95	(CMatch("__acquires"), ""),	96	(CMatch("__acquires"), ""),