History

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
  1. CREDITS +4 −0
  2. Documentation/ABI/README +1 −1
  3. Documentation/ABI/testing/sysfs-edac-memory-repair +1 −1
  4. Documentation/admin-guide/kernel-parameters.txt +15 −19
  5. Documentation/admin-guide/media/bttv.rst +1 −1
  6. Documentation/admin-guide/mm/pagemap.rst +4 −4
  7. Documentation/admin-guide/pm/amd-pstate.rst +1 −1
  8. Documentation/conf.py +3 −3
  9. Documentation/core-api/SMP.rst +11 −0
  10. Documentation/core-api/dma-api.rst +1 −1
  11. Documentation/core-api/errseq.rst +1 −1
  12. Documentation/core-api/index.rst +1 −0
  13. Documentation/core-api/list.rst +1 −1
  14. Documentation/core-api/min_heap.rst +0 −13
  15. Documentation/core-api/packing.rst +2 −2
  16. Documentation/core-api/real-time/hardware.rst +104 −0
  17. Documentation/core-api/real-time/index.rst +1 −0
  18. Documentation/core-api/real-time/kernel-configuration.rst +307 −0
  19. Documentation/dev-tools/container.rst +3 −3
  20. Documentation/driver-api/ipmi.rst +1 −1
  21. Documentation/driver-api/usb/writing_usb_driver.rst +0 −3
  22. Documentation/filesystems/overlayfs.rst +1 −2
  23. Documentation/filesystems/proc.rst +1 −1
  24. Documentation/index.rst +8 −0
  25. Documentation/kernel-hacking/locking.rst +4 −4
  26. Documentation/process/coding-assistants.rst +6 −6
  27. Documentation/process/generated-content.rst +7 −0
  28. Documentation/process/submitting-patches.rst +6 −8
  29. Documentation/scheduler/sched-energy.rst +1 −1
  30. Documentation/scheduler/sched-pelt.c +2 −1
  31. Documentation/sphinx-static/custom.css +15 −9
  32. Documentation/sphinx/maintainers_include.py +5 −2
  33. Documentation/translations/it_IT/doc-guide/checktransupdate.rst +59 −0
  34. Documentation/translations/it_IT/doc-guide/contributing.rst +319 −0
  35. Documentation/translations/it_IT/doc-guide/index.rst +3 −10
  36. Documentation/translations/it_IT/doc-guide/kernel-doc.rst +69 −19
  37. Documentation/translations/it_IT/doc-guide/maintainer-profile.rst +60 −0
  38. Documentation/translations/it_IT/doc-guide/parse-headers.rst +110 −110
  39. Documentation/translations/it_IT/doc-guide/sphinx.rst +137 −41
  40. Documentation/translations/it_IT/process/changes.rst +73 −45
  41. Documentation/translations/ja_JP/process/submitting-patches.rst +152 −75
  42. Documentation/translations/pt_BR/index.rst +1 −12
  43. Documentation/translations/pt_BR/process/4.Coding.rst +440 −0
  44. Documentation/translations/pt_BR/process/5.Posting.rst +376 −0
  45. Documentation/translations/pt_BR/process/6.Followthrough.rst +220 −0
  46. Documentation/translations/pt_BR/process/7.AdvancedTopics.rst +201 −0
  47. Documentation/translations/pt_BR/process/8.Conclusion.rst +73 −0
  48. Documentation/translations/pt_BR/process/adding-syscalls.rst +700 −0
  49. Documentation/translations/pt_BR/process/applying-patches.rst +447 −0
  50. Documentation/translations/pt_BR/process/backporting.rst +598 −0
  51. Documentation/translations/pt_BR/process/botching-up-ioctls.rst +256 −0
  52. Documentation/translations/pt_BR/process/code-of-conduct-interpretation.rst +257 −0
  53. Documentation/translations/pt_BR/process/code-of-conduct.rst +88 −0
  54. Documentation/translations/pt_BR/process/contribution-maturity-model.rst +111 −0
  55. Documentation/translations/pt_BR/process/cve.rst +125 −0
  56. Documentation/translations/pt_BR/process/deprecated.rst +422 −0
  57. Documentation/translations/pt_BR/process/development-process.rst +5 −0
  58. Documentation/translations/pt_BR/process/email-clients.rst +368 −0
  59. Documentation/translations/pt_BR/process/index.rst +102 −0
  60. Documentation/translations/pt_BR/process/kernel-driver-statement.rst +205 −0
  61. Documentation/translations/pt_BR/process/maintainer-netdev.rst +16 −7
  62. Documentation/translations/pt_BR/process/management-style.rst +265 −0
  63. Documentation/translations/pt_BR/process/security-bugs.rst +368 −0
  64. Documentation/translations/pt_BR/process/submit-checklist.rst +145 −0
  65. Documentation/translations/zh_CN/accounting/psi.rst +1 −1
  66. Documentation/translations/zh_CN/admin-guide/index.rst +152 −50
  67. Documentation/translations/zh_CN/admin-guide/module-signing.rst +250 −0
  68. Documentation/translations/zh_CN/dev-tools/kasan.rst +1 −1
  69. Documentation/translations/zh_CN/how-to.rst +100 −49
  70. Documentation/translations/zh_CN/rust/arch-support.rst +1 −0
  71. Documentation/translations/zh_CN/rust/general-information.rst +79 −3
  72. Documentation/translations/zh_CN/rust/quick-start.rst +19 −29
  73. Documentation/translations/zh_CN/rust/testing.rst +4 −0
  74. Documentation/translations/zh_CN/scheduler/sched-energy.rst +1 −1
  75. Documentation/translations/zh_CN/security/self-protection.rst +1 −1
  76. Documentation/translations/zh_TW/process/stable-api-nonsense.rst +31 −31
  77. MAINTAINERS +4 −3
  78. README +9 −9
  79. scripts/checkpatch.pl +4 −3
  80. tools/docs/documentation-file-ref-check +1 −1
  81. tools/docs/sphinx-build-wrapper +11 −2
  82. tools/lib/python/abi/abi_regex.py +5 −6
  83. tools/lib/python/kdoc/kdoc_output.py +1 −1
  84. tools/lib/python/kdoc/kdoc_parser.py +53 −5
  85. tools/lib/python/kdoc/xforms_lists.py +1 −0
CREDITS+4−0
@@ -1821,6 +1821,10 @@ S: Am Strand 5 · 1820 unmodified lines
18211821 S: D-19063 Schwerin
18221822 S: Germany
18231823
1824+N: Haowen Hu
1825+E: srcres258@furdevs.cn
1826+D: Traditional Chinese (zh_TW) documentation translation and maintenance
1827+
18241828 N: Jan Hubicka
18251829 E: hubicka@freesoft.cz
18261830 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
6262
6363
6464 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.
6666 Also, the file **should not** have a top-level index, like::
6767
6868 ===
Documentation/ABI/testing/sysfs-edac-memory-repair+1−1
@@ -160,7 +160,7 @@ Description: · 159 unmodified lines
160160 in trace events, such as CXL DRAM and CXL general media
161161 error records of CXL memory devices.
162162
163− When readng back these attributes, it returns the current
163+ When reading back these attributes, it returns the current
164164 value of memory requested to be repaired.
165165
166166 bank_group - The bank group of the memory to repair.
Documentation/admin-guide/kernel-parameters.txt+15−19
@@ -1618,10 +1618,17 @@ Kernel parameters · 1617 unmodified lines
16181618 on all PCI bridges while in the EFI boot stub
16191619
16201620 efi_no_storage_paranoia [EFI,X86,EARLY]
1621− Using this parameter you can use more than 50% of
1622− your efi variable storage. Use this parameter only if
1623− you are really sure that your UEFI does sane gc and
1624− fulfills the spec otherwise your board may brick.
1621+ The kernel reserves 5KB of EFI variable storage for
1622+ safety, because some UEFI implementation may fail to
1623+ boot if there's insufficient space in the EFI variable
1624+ storage.
1625+
1626+ Using this parameter, you can use the 5KB reservation
1627+ in the EFI variable storage.
1628+
1629+ However, Use this parameter only if you are really
1630+ sure that your UEFI does sane gc and fulfills the spec
1631+ otherwise your board may brick.
16251632
16261633 efivar_ssdt= [EFI; X86] Name of an EFI variable that contains an SSDT
16271634 that is to be dynamically loaded by Linux. If there are
@@ -6446,9 +6453,9 @@ Kernel parameters · 4818 unmodified lines
64466453 reboot= [KNL]
64476454 Format (x86 or x86_64):
64486455 [w[arm] | c[old] | h[ard] | s[oft] | g[pio]] | d[efault] \
6449− [[,]s[mp]#### \
6456+ [[,]s[mp]####] \
64506457 [[,]b[ios] | a[cpi] | k[bd] | t[riple] | e[fi] | p[ci]] \
6451− [[,]f[orce]
6458+ [[,]f[orce]]
64526459 Where reboot_mode is one of warm (soft) or cold (hard) or gpio
64536460 (prefix with 'panic_' to set mode for panic
64546461 reboot only),
@@ -6908,7 +6915,7 @@ Kernel parameters · 453 unmodified lines
69086915 xtime_lock contention on larger systems, and/or RCU lock
69096916 contention on all systems with CONFIG_MAXSMP set.
69106917 Format: { "0" | "1" }
6911− 0 -- disable. (may be 1 via CONFIG_CMDLINE="skew_tick=1"
6918+ 0 -- disable. (may be 1 via CONFIG_CMDLINE="skew_tick=1")
69126919 1 -- enable.
69136920 Note: increases power consumption, thus should only be
69146921 enabled if running jitter sensitive (HPC/RT) workloads.
@@ -6949,7 +6956,7 @@ Kernel parameters · 34 unmodified lines
69496956 apic=verbose is specified.
69506957 Example: apic=debug show_lapic=all
69516958
6952− slab_debug[=options[,slabs][;[options[,slabs]]...] [MM]
6959+ slab_debug[=options[,slabs][;[options[,slabs]]...]] [MM]
69536960 Enabling slab_debug allows one to determine the
69546961 culprit if slab objects become corrupted. Enabling
69556962 slab_debug can create guard zones around objects and
@@ -7039,17 +7046,6 @@ Kernel parameters · 83 unmodified lines
70397046 take as long as they take. Specifying 300,000
70407047 for this value provides a 5-minute timeout.
70417048
7042− smsc-ircc2.nopnp [HW] Don't use PNP to discover SMC devices
7043− smsc-ircc2.ircc_cfg= [HW] Device configuration I/O port
7044− smsc-ircc2.ircc_sir= [HW] SIR base I/O port
7045− smsc-ircc2.ircc_fir= [HW] FIR base I/O port
7046− smsc-ircc2.ircc_irq= [HW] IRQ line
7047− smsc-ircc2.ircc_dma= [HW] DMA channel
7048− smsc-ircc2.ircc_transceiver= [HW] Transceiver type:
7049− 0: Toshiba Satellite 1800 (GP data pin select)
7050− 1: Fast pin select (default)
7051− 2: ATC IRMode
7052−
70537049 smt= [KNL,MIPS,S390,EARLY] Set the maximum number of threads
70547050 (logical CPUs) to use per physical CPU on systems
70557051 capable of symmetric multithreading (SMT). Will
Documentation/admin-guide/media/bttv.rst+1−1
@@ -1239,7 +1239,7 @@ Models: · 1238 unmodified lines
12391239 - Galaxis DVB Card C CI
12401240 - Galaxis DVB Card S
12411241 - 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]
12431243
12441244 Hauppauge
12451245 ~~~~~~~~~
Documentation/admin-guide/mm/pagemap.rst+4−4
@@ -67,7 +67,7 @@ number of times a page is mapped. · 66 unmodified lines
6767 * ``/proc/kpageflags``. This file contains a 64-bit set of flags for each
6868 page, indexed by PFN.
6969
70− The flags are (from ``fs/proc/page.c``, above kpageflags_read):
70+ The flags are (from ``include/uapi/linux/kernel-page-flags.h``):
7171
7272 0. LOCKED
7373 1. ERROR
@@ -264,7 +264,7 @@ The ``struct pm_scan_arg`` is used as the argument of the IOCTL. · 190 unmodified lines
264264 provided or not.
265265 3. The range is specified through ``start`` and ``end``.
266266 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``.
268268 5. The output buffer of ``struct page_region`` array and size is specified in
269269 ``vec`` and ``vec_len``.
270270 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
275275
276276 struct pm_scan_arg arg = {
277277 .size = sizeof(arg),
278− .flags = PM_SCAN_CHECK_WPASYNC | PM_SCAN_CHECK_WPASYNC,
278+ .flags = PM_SCAN_WP_MATCHING | PM_SCAN_CHECK_WPASYNC,
279279 ..
280280 .category_mask = PAGE_IS_WRITTEN,
281281 .return_mask = PAGE_IS_WRITTEN,
@@ -288,7 +288,7 @@ present or huge:: · 6 unmodified lines
288288 .size = sizeof(arg),
289289 .flags = 0,
290290 ..
291− .category_mask = PAGE_IS_WRITTEN | PAGE_IS_SWAPPED,
291+ .category_mask = PAGE_IS_WRITTEN | PAGE_IS_FILE,
292292 .category_inverted = PAGE_IS_SWAPPED,
293293 .category_anyof_mask = PAGE_IS_PRESENT | PAGE_IS_HUGE,
294294 .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
471471 Kernel Parameters
472472 -----------------
473473
474−``amd-pstate`` peferred core`` has two states: enable and disable.
474+``amd-pstate`` preferred core has two states: enable and disable.
475475 Enable/disable states can be chosen by different kernel parameters.
476476 Default enable ``amd-pstate`` preferred core.
477477
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
6161
6262 def config_init(app, config):
6363 """
64− Initialize path-dependent variabled
64+ Initialize path-dependent variables
6565
6666 On Sphinx, all directories are relative to what it is passed as
6767 SOURCEDIR parameter for sphinx-build. Due to that, all patterns
6868 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.
7070
7171 As Sphinx doesn't include any patterns outside SOURCEDIR, we should
7272 exclude relative patterns that start with "../".
@@ -287,7 +287,7 @@ author = "The kernel development community" · 214 unmodified lines
287287 try:
288288 makefile_version = None
289289 makefile_patchlevel = None
290− with open("../Makefile", encoding="utf=8") as fp:
290+ with open("../Makefile", encoding="utf-8") as fp:
291291 for line in fp:
292292 key, val = [x.strip() for x in line.split("=", 2)]
293293 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
508508
509509 Is used to link ranges to the IOVA previously allocated. The start of all
510510 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
512512 the size of all but the last range must be aligned to the DMA merge boundary
513513 as well.
514514
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
143143 see if anything has changed, and only later do an
144144 errseq_check_and_advance after taking the lock. e.g.::
145145
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))) {
147147 /* su.s_wd_err is protected by s_wd_err_lock */
148148 spin_lock(&su.s_wd_err_lock);
149149 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
8181 padata
8282 ../RCU/index
8383 wrappers/memory-barriers.rst
84+ SMP
8485
8586 Low-level hardware management
8687 =============================
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
458458 from one list to another, to either the start or end respectively.
459459
460460 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"::
462462
463463 .----------------------------------------------------------------.
464464 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
240240
241241 **Inline Version:** min_heap_full_inline(heap)
242242
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−
256243 Example Usage
257244 =============
258245
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
330330
331331 void unpack_your_data(const packed_buf_t *buf, struct data *unpacked)
332332 {
333− BUILD_BUG_ON(sizeof(*buf) != SIZE;
333+ BUILD_BUG_ON(sizeof(*buf) != SIZE);
334334
335335 unpack_fields(buf, sizeof(*buf), unpacked, fields,
336336 QUIRK_LITTLE_ENDIAN);
@@ -338,7 +338,7 @@ Here is an example of how to use the fields APIs: · 1 unmodified line
338338
339339 void pack_your_data(const struct data *unpacked, packed_buf_t *buf)
340340 {
341− BUILD_BUG_ON(sizeof(*buf) != SIZE;
341+ BUILD_BUG_ON(sizeof(*buf) != SIZE);
342342
343343 pack_fields(buf, sizeof(*buf), unpacked, fields,
344344 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
130130 The goal of this project is to validate real-time network communication. It can
131131 be thought of as a "cyclictest" for networking and also serves as a starting
132132 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
1515 differences
1616 hardware
1717 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
4040
4141 ``-r, --runtime RUNTIME``
4242
43− Container runtime name. Supported runtimes: ``docker``, ``podman``.
43+ Container runtime name. Supported runtimes: ``podman``, ``docker``.
4444
4545 If not specified, the first one found on the system will be used
4646 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
7575
7676 The container image which would typically include a compiler toolchain is
7777 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
79−``podman``. If none is specified, the first one found on the system will be
78+can be selected with the ``-r`` option, which can be either ``podman`` or
79+``docker``. If none is specified, the first one found on the system will be
8080 used while giving priority to Podman. Support for other runtimes may be added
8181 later depending on their popularity among users.
8282
Documentation/driver-api/ipmi.rst+1−1
@@ -280,7 +280,7 @@ Creating the User · 279 unmodified lines
280280 To use the message handler, you must first create a user using
281281 ipmi_create_user. The interface number specifies which SMI you want
282282 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,
284284 the handler_data, that will be passed back to you on all calls.
285285
286286 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
322322 linux-usb Mailing List Archives:
323323 https://lore.kernel.org/linux-usb/
324324
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−
328325 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
123123 mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,\
124124 workdir=/work /merged
125125
126−The "workdir" needs to be an empty directory on the same filesystem
127−as upperdir.
126+The "workdir" needs to be a directory on the same filesystem as upperdir.
128127
129128 Then whenever a lookup is requested in such a merged directory, the
130129 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
513513 allocation (e.g., THP) can differ: a page is accounted as "private" if all
514514 pages part of the corresponding large allocation are *certainly* mapped in the
515515 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
517517 is *maybe* mapped in a different process. In some cases, a large allocation
518518 might be treated as "maybe mapped by multiple processes" even though this
519519 is no longer the case.
Documentation/index.rst+8−0
@@ -21,6 +21,7 @@ community and getting your work upstream. · 20 unmodified lines
2121
2222 .. toctree::
2323 :maxdepth: 1
24+ :caption: Working with the development community
2425
2526 Development process <process/development-process>
2627 Submitting patches <process/submitting-patches>
@@ -37,6 +38,7 @@ kernel. · 10 unmodified lines
3738
3839 .. toctree::
3940 :maxdepth: 1
41+ :caption: Internal API manuals
4042
4143 Core API <core-api/index>
4244 Driver APIs <driver-api/index>
@@ -50,6 +52,7 @@ Various other manuals with useful information for all kernel developers. · 7 unmodified lines
5052
5153 .. toctree::
5254 :maxdepth: 1
55+ :caption: Development tools and processes
5356
5457 Licensing rules <process/license-rules>
5558 Writing documentation <doc-guide/index>
@@ -71,6 +74,7 @@ developers seeking information on the kernel's user-space APIs. · 15 unmodified lines
7174
7275 .. toctree::
7376 :maxdepth: 1
77+ :caption: User-oriented documentation
7478
7579 Administration <admin-guide/index>
7680 Build system <kbuild/index>
@@ -88,6 +92,7 @@ platform firmware. · 11 unmodified lines
8892
8993 .. toctree::
9094 :maxdepth: 1
95+ :caption: Firmware-related documentation
9196
9297 Firmware <firmware-guide/index>
9398 Firmware and Devicetree <devicetree/index>
@@ -98,6 +103,7 @@ Architecture-specific documentation · 4 unmodified lines
98103
99104 .. toctree::
100105 :maxdepth: 2
106+ :caption: Architecture-specific documentation
101107
102108 CPU architectures <arch/index>
103109
@@ -111,6 +117,7 @@ to reStructuredText format, or are simply too old. · 7 unmodified lines
111117
112118 .. toctree::
113119 :maxdepth: 1
120+ :caption: Other documentation
114121
115122 Unsorted documentation <staging/index>
116123
@@ -120,6 +127,7 @@ Translations · 3 unmodified lines
120127
121128 .. toctree::
122129 :maxdepth: 2
130+ :caption: Translations
123131
124132 Translations <translations/index>
125133
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
471471 obj = __cache_find(id);
472472 if (obj) {
473473 ret = 0;
474− strcpy(name, obj->name);
474+ strscpy(name, obj->name);
475475 }
476476 mutex_unlock(&cache_lock);
477477 return ret;
@@ -553,7 +553,7 @@ which are taken away, and the ``+`` are lines which are added. · 75 unmodified lines
553553 obj = __cache_find(id);
554554 if (obj) {
555555 ret = 0;
556− strcpy(name, obj->name);
556+ strscpy(name, obj->name);
557557 }
558558 - mutex_unlock(&cache_lock);
559559 + spin_unlock_irqrestore(&cache_lock, flags);
@@ -676,7 +676,7 @@ Here is the code:: · 116 unmodified lines
676676 obj = __cache_find(id);
677677 - if (obj) {
678678 - ret = 0;
679− - strcpy(name, obj->name);
679+ - strscpy(name, obj->name);
680680 - }
681681 + if (obj)
682682 + __object_get(obj);
@@ -1317,7 +1317,7 @@ from user context, and can sleep. · 634 unmodified lines
13171317
13181318 - put_user()
13191319
1320−- kmalloc(GP_KERNEL) <kmalloc>`
1320+- kmalloc(GFP_KERNEL) <kmalloc>
13211321
13221322 - mutex_lock_interruptible() and
13231323 mutex_lock()
Documentation/process/coding-assistants.rst+6−6
@@ -15,6 +15,10 @@ kernel development process: · 14 unmodified lines
1515 * Documentation/process/coding-style.rst
1616 * Documentation/process/submitting-patches.rst
1717
18+For guidelines on content generated by AI coding assistants see:
19+
20+* Documentation/process/generated-content.rst
21+
1822 Licensing and Legal Requirements
1923 ================================
2024
@@ -43,12 +47,8 @@ When AI tools contribute to kernel development, proper attribution · 22 unmodified lines
4347 helps track the evolving role of AI in the development process.
4448 Contributions should include an Assisted-by tag in the following format::
4549
46− Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2]
47−
48−Where:
50+ Assisted-by: LLM [TOOL1] [TOOL2]
4951
50−* ``AGENT_NAME`` is the name of the AI tool or framework
51−* ``MODEL_VERSION`` is the specific model version used
5252 * ``[TOOL1] [TOOL2]`` are optional specialized analysis tools used
5353 (e.g., coccinelle, sparse, smatch, clang-tidy)
5454
@@ -56,7 +56,7 @@ Basic development tools (git, gcc, make, editors) should not be listed. · 1 unmodified line
5656
5757 Example::
5858
59− Assisted-by: Claude:claude-3-opus coccinelle sparse
59+ Assisted-by: LLM coccinelle sparse
6060
6161 Procedure for finding and fixing bugs
6262 =====================================
Documentation/process/generated-content.rst+7−0
@@ -107,3 +107,10 @@ the resulting changes. · 106 unmodified lines
107107
108108 If you do so anyway, maintainers are entitled to reject your series
109109 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
@@ -404,12 +404,11 @@ patches that are being emailed around. · 403 unmodified lines
404404 The sign-off is a simple line at the end of the explanation for the
405405 patch, which certifies that you wrote it or otherwise have the right to
406406 pass it on as an open-source patch. The rules are pretty simple: if you
407−can certify the below:
407+can certify the below::
408408
409−Developer's Certificate of Origin 1.1
410−^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
409+ Developer's Certificate of Origin 1.1
411410
412−By making a contribution to this project, I certify that:
411+ By making a contribution to this project, I certify that:
413412
414413 (a) The contribution was created in whole or in part by me and I
415414 have the right to submit it under the open source license
@@ -554,12 +553,11 @@ some testing has been performed, provides a means to locate testers for · 138 unmodified lines
554553 future patches, and ensures credit for the testers.
555554
556555 Reviewed-by:, instead, indicates that the patch has been reviewed and found
557−acceptable according to the Reviewer's Statement:
556+acceptable according to the Reviewer's Statement::
558557
559−Reviewer's statement of oversight
560−^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
558+ Reviewer's statement of oversight
561559
562−By offering my Reviewed-by: tag, I state that:
560+ By offering my Reviewed-by: tag, I state that:
563561
564562 (a) I have carried out a technical review of this patch to
565563 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
141141 find_energy_efficient_cpu() uses compute_energy() to estimate what will be the
142142 energy consumed by the system if the waking task was migrated. compute_energy()
143143 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
145145 which computes the expected energy consumption of each performance domain for
146146 the given utilization landscape.
147147
Documentation/scheduler/sched-pelt.c+2−1
@@ -25,7 +25,8 @@ void calc_runnable_avg_yN_inv(void) · 24 unmodified lines
2525 for (i = 0; i < HALFLIFE; i++) {
2626 x = ((1UL<<32)-1)*pow(y, i);
2727
28− if (i % 6 == 0) printf("\n\t");
28+ if (i % 6 == 0)
29+ printf("\n\t");
2930 printf("0x%8x, ", x);
3031 }
3132 printf("\n};\n\n");
Documentation/sphinx-static/custom.css+15−9
@@ -3,6 +3,8 @@ · 2 unmodified lines
33 * CSS tweaks for the Alabaster theme
44 */
55
6+div.body { max-width: 120em; }
7+
68 /* Shrink the headers a bit */
79 div.body h1 { font-size: 180%; }
810 div.body h2 { font-size: 150%; }
@@ -75,6 +77,19 @@ div.kerneltoc li.current ul { margin-left: 0; } · 66 unmodified lines
7577 div.kerneltoc { background-color: #eeeeee; }
7678 div.kerneltoc li.current ul { background-color: white; }
7779
80+/*
81+ * Hide toctree captions on the welcome page, they should only be shown in the
82+ * sidebar.
83+ */
84+section#the-linux-kernel-documentation p.caption { display: none; }
85+
86+/*
87+ * Make section titles bold in the sidebar, and decrease their bottom margin to
88+ * group them with their subsections.
89+ */
90+div.sphinxsidebar p.caption { font-weight: bold; margin-bottom: 0; }
91+div.sphinxsidebar p.caption + ul { margin-top: 0; }
92+
7893 /*
7994 * The CSS magic to toggle the contents on small screens.
8095 */
@@ -156,15 +171,6 @@ div.language-selection ul li:hover { · 75 unmodified lines
156171 background: #dddddd;
157172 }
158173
159−/*
160− * Let long inline literals in paragraph text wrap as needed to prevent
161− * overflow.
162− */
163−code.docutils.literal span.pre {
164− white-space: normal;
165− overflow-wrap: anywhere;
166−}
167−
168174 /* Let rendered reference links in tables wrap when needed. */
169175 div.body table.docutils a.reference {
170176 overflow-wrap: anywhere;
Documentation/sphinx/maintainers_include.py+5−2
@@ -161,7 +161,7 @@ class MaintainersParser: · 160 unmodified lines
161161 html = KERNELDOC_URL + ename + ".html"
162162 entries[entry] = f'`{ename} <{html}>`_'
163163 else:
164− entries[entry] = f':doc:`{ename} </{entry}>`'
164+ entries[entry] = f'/{entry}'
165165
166166 return entries
167167
@@ -345,7 +345,10 @@ class MaintainersProfile(Include): · 177 unmodified lines
345345 output += f"- {name}: {entry}\n"
346346 self.warning(f"{profile}: Invalid 'P' tag: {entry}\n")
347347 else:
348− output += f"- {entry}\n"
348+ if not name:
349+ name = entry
350+
351+ output += f"- :doc:`{name} <{entry}>`\n"
349352
350353 #
351354 # 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 @@
11 .. include:: ../disclaimer-ita.rst
22
3−.. note:: Per leggere la documentazione originale in inglese:
4− :ref:`Documentation/doc-guide/index.rst <doc_guide>`
5−
63 .. _it_doc_guide:
74
85 ==========================================
@@ -15,10 +12,6 @@ Come scrivere la documentazione del kernel · 6 unmodified lines
1512 sphinx
1613 kernel-doc
1714 parse-headers
18−
19−.. only:: subproject and html
20−
21− Indices
22− =======
23−
24− * :ref:`genindex`
15+ contributing
16+ maintainer-profile
17+ checktransupdate
Documentation/translations/it_IT/doc-guide/kernel-doc.rst+69−19
@@ -1,12 +1,7 @@
11 .. include:: ../disclaimer-ita.rst
22
3−.. note:: Per leggere la documentazione originale in inglese:
4− :ref:`Documentation/doc-guide/index.rst <doc_guide>`
5−
63 .. title:: Commenti in kernel-doc
74
8−.. _it_kernel_doc:
9−
105 =================================
116 Scrivere i commenti in kernel-doc
127 =================================
@@ -82,11 +77,15 @@ che questo produca alcuna documentazione. Per esempio:: · 69 unmodified lines
8277
8378 tools/docs/kernel-doc -v -none drivers/foo/bar.c
8479
85−Il formato della documentazione è verificato della procedura di generazione
86−del kernel quando viene richiesto di effettuare dei controlli extra con GCC::
80+Il formato della documentazione dei file ``.c`` è verificato anche dalla
81+procedura di generazione del kernel quando viene richiesto di effettuare dei
82+controlli extra con GCC::
8783
8884 make W=n
8985
86+Tuttavia, il comando precedente non verifica i file d'intestazione. Questi
87+devono essere controllati separatamente utilizzando ``kernel-doc``.
88+
9089 Documentare le funzioni
9190 ------------------------
9291
@@ -172,7 +171,7 @@ Valore di ritorno · 79 unmodified lines
172171 ~~~~~~~~~~~~~~~~~
173172
174173 Il valore di ritorno, se c'è, viene descritto in una sezione dedicata di nome
175−``Return``.
174+``Return`` (o ``Returns``).
176175
177176 .. note::
178177
@@ -202,7 +201,8 @@ Il valore di ritorno, se c'è, viene descritto in una sezione dedicata di nome · 23 unmodified lines
202201 Documentare strutture, unioni ed enumerazioni
203202 ---------------------------------------------
204203
205−Generalmente il formato di un commento kernel-doc per struct, union ed enum è::
204+Generalmente il formato di un commento kernel-doc per ``struct``, ``union``
205+ed ``enum`` è::
206206
207207 /**
208208 * struct struct_name - Brief description.
@@ -237,6 +237,10 @@ Le etichette ``private:`` e ``public:`` devono essere messe subito dopo · 28 unmodified lines
237237 il marcatore di un commento ``/*``. Opzionalmente, possono includere commenti
238238 fra ``:`` e il marcatore di fine commento ``*/``.
239239
240+Quando ``private:`` viene usata su strutture annidate, si propaga solo alle
241+strutture/unioni interne.
242+
243+
240244 Esempio::
241245
242246 /**
@@ -280,13 +284,15 @@ Strutture ed unioni annidate · 37 unmodified lines
280284 union {
281285 struct {
282286 int memb1;
287+ /* private: nasconde memb2 dalla documentazione */
283288 int memb2;
284− }
289+ };
290+ /* Qui torna tutto pubblico, l'ambito private è terminato */
285291 struct {
286292 void *memb3;
287293 int memb4;
288− }
289− }
294+ };
295+ };
290296 union {
291297 struct {
292298 int memb1;
@@ -366,10 +372,23 @@ Anche i tipi di dato per prototipi di funzione possono essere documentati:: · 73 unmodified lines
366372 * Description of the type.
367373 *
368374 * Context: Locking context.
369− * Return: Meaning of the return value.
375+ * Returns: Meaning of the return value.
370376 */
371377 typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
372378
379+Documentazione delle variabili
380+-------------------------------
381+
382+Generalmente il formato di un commento kernel-doc per una variabile è
383+il seguente::
384+
385+ /**
386+ * var var_name - Brief description.
387+ *
388+ * Description of the var_name variable.
389+ */
390+ extern int var_name;
391+
373392 Documentazione di macro simili a oggetti
374393 ----------------------------------------
375394
@@ -433,6 +452,10 @@ del `dominio Sphinx per il C`_. · 57 unmodified lines
433452 ``%CONST``
434453 Il nome di una costante (nessun riferimento, solo formattazione)
435454
455+ Esempi::
456+
457+ %0 %NULL %-1 %-EFAULT %-EINVAL %-ENOMEM
458+
436459 ````literal````
437460 Un blocco di testo che deve essere riportato così com'è. La rappresentazione
438461 finale utilizzerà caratteri a ``spaziatura fissa``.
@@ -484,15 +507,22 @@ la seguente sintassi:: · 45 unmodified lines
484507 See :c:func:`my custom link text for function foo <foo>`.
485508 See :c:type:`my custom link text for struct bar <bar>`.
486509
510+Per ulteriori dettagli, consultate la documentazione del `dominio Sphinx per
511+il C`_.
512+
513+.. note::
514+ Le variabili non vengono automaticamente collegate tramite riferimenti
515+ incrociati. Per queste, dovete aggiungere esplicitamente un riferimento
516+ incrociato del dominio C.
487517
488518 Commenti per una documentazione generale
489519 ----------------------------------------
490520
491521 Al fine d'avere il codice ed i commenti nello stesso file, potete includere
492522 dei blocchi di documentazione kernel-doc con un formato libero invece
493−che nel formato specifico per funzioni, strutture, unioni, enumerati o tipi
494−di dato. Per esempio, questo tipo di commento potrebbe essere usato per la
495−spiegazione delle operazioni di un driver o di una libreria
523+che nel formato specifico per funzioni, strutture, unioni, enumerati, tipi
524+di dato o variabili. Per esempio, questo tipo di commento potrebbe essere
525+usato per la spiegazione delle operazioni di un driver o di una libreria
496526
497527 Questo s'ottiene utilizzando la parola chiave ``DOC:`` a cui viene associato
498528 un titolo.
@@ -565,6 +595,8 @@ identifiers: *[ function/type ...]* · 66 unmodified lines
565595 Include la documentazione per ogni *function* e *type* in *source*.
566596 Se non vengono esplicitamente specificate le funzioni da includere, allora
567597 verranno incluse tutte quelle disponibili in *source*.
598+ *type* può essere un identificatore di tipo ``struct``, ``union``,
599+ ``enum``, ``typedef`` o ``var``.
568600
569601 Esempi::
570602
@@ -601,7 +633,25 @@ dai file sorgenti. · 30 unmodified lines
601633 Come utilizzare kernel-doc per generare pagine man
602634 --------------------------------------------------
603635
604−Se volete utilizzare kernel-doc solo per generare delle pagine man, potete
605−farlo direttamente dai sorgenti del kernel::
636+Per generare le pagine man di tutti i file che contengono marcatori
637+kernel-doc, eseguite::
638+
639+ $ make mandocs
640+
641+Oppure, chiamando direttamente ``script-build-wrapper``::
642+
643+ $ ./tools/docs/sphinx-build-wrapper mandocs
644+
645+Il risultato sarà disponibile nella cartella ``/man`` dentro la cartella
646+di output (predefinita: ``Documentation/output``).
647+
648+Opzionalmente, è possibile generare un sottoinsieme di pagine man usando
649+SPHINXDIRS:
650+
651+ $ make SPHINXDIRS=driver-api/media mandocs
652+
653+.. note::
606654
607− $ tools/docs/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man
655+ Quando si usa SPHINXDIRS={subdir}, verranno generate le pagine man solo
656+ per i file che si trovano esplicitamente all'interno di un file
657+ ``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 @@
11 .. include:: ../disclaimer-ita.rst
22
3−:Original: Documentation/doc-guide/index.rst
4−
5−=========================================
6−Includere gli i file di intestazione uAPI
7−=========================================
3+=====================================
4+Includere i file di intestazione uAPI
5+=====================================
86
97 Qualche volta è utile includere dei file di intestazione e degli esempi di codice C
108 al fine di descrivere l'API per lo spazio utente e per generare dei riferimenti
119 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
1311 d'avviso se un simbolo non viene trovato nella documentazione. Questo permette
1412 di mantenere allineate la documentazione della uAPI (API spazio utente)
1513 con le modifiche del kernel.
16−Il programma :ref:`parse_headers.py <it_parse_headers>` genera questi riferimenti.
17−Esso dev'essere invocato attraverso un Makefile, mentre si genera la
18−documentazione. Per avere un esempio su come utilizzarlo all'interno del kernel
19−consultate ``Documentation/userspace-api/media/Makefile``.
14+Il programma :ref:`parse_headers.py <it_parse_headers>` genera questi
15+riferimenti. Esso dev'essere invocato attraverso un Makefile, mentre si genera
16+la documentazione. Per avere un esempio su come utilizzarlo all'interno del
17+kernel consultate ``Documentation/userspace-api/media/Makefile``.
2018
2119 .. _it_parse_headers:
2220
23−parse_headers.py
24−^^^^^^^^^^^^^^^^
21+tools/docs/parse_headers.py
22+^^^^^^^^^^^^^^^^^^^^^^^^^^^
2523
2624 NOME
2725 ****
2826
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.
2929
30−parse_headers.py - analizza i file C al fine di identificare funzioni,
31−strutture, enumerati e definizioni, e creare riferimenti per Sphinx
30+USO
31+***
3232
33−SINTASSI
34−********
33+parse-headers.py [-h] [-d] [-t] ``FILE_IN`` ``FILE_OUT`` ``FILE_RULES``
3534
35+SINOSSI
36+*******
3637
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.
3843
39−Dove <options> può essere: --debug, --usage o --help.
44+Il file generato viene scritto in ``FILE_OUT``.
4045
46+Il programma è capace di identificare ``define``, ``struct``, ``typedef``,
47+``enum`` e ``symbol`` di un enumerato, creando i riferimenti per ognuno di
48+loro.
4149
42−OPZIONI
43−*******
50+Inoltre, esso è capace di distinguere le ``#define`` utilizzate per
51+specificare le macro specifiche di Linux usate per definire gli ``ioctl``.
4452
53+Il file ``FILE_RULES``, opzionale, contiene un insieme di regole come le
54+seguenti::
4555
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`
4659
47−\ **--debug**\
60+ARGOMENTI POSIZIONALI
61+*********************
4862
49− Lo script viene messo in modalità verbosa, utile per il debugging.
63+ ``FILE_IN``
64+ File C d'ingresso
5065
66+ ``FILE_OUT``
67+ File RST generato
5168
52−\ **--usage**\
69+ ``FILE_RULES``
70+ File delle eccezioni (opzionale)
5371
54− Mostra un messaggio d'aiuto breve e termina.
55−
56−
57−\ **--help**\
72+OPZIONI
73+*******
5874
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)
6082
6183
6284 DESCRIZIONE
6385 ***********
6486
65−Converte un file d'intestazione o un file sorgente C (C_FILE) in un testo
66−reStructuredText incluso mediante il blocco ..parsed-literal
67−con riferimenti alla documentazione che descrive l'API. Opzionalmente,
68−il programma accetta anche un altro file (EXCEPTIONS_FILE) che
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**\ .
87+Crea, a partire da ``FILE_IN``, una versione arricchita di un file
88+d'intestazione del kernel con collegamenti incrociati verso ogni tipo di
89+struttura dati C, formattandola con la notazione reStructuredText, sia
90+come blocco letterale che come tabella dell'indice.
8891
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.
8996
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.
9199
92−replace \ **tipo**\ \ **nome**\ \ **nuovo_valore**\
100+Il file generato viene scritto in ``FILE_OUT``.
93101
94−La dichiarazione \ **replace**\ significa che verrà generato un
95−riferimento per il simbolo \ **name**\ di tipo \ **tipo**\ , ma, invece
96−di utilizzare il valore predefinito, verrà utilizzato il valore
97−\ **nuovo_valore**\ .
102+Il file ``FILE_RULES`` può contenere tre tipi di dichiarazioni:
103+**ignore**, **replace** e **namespace**.
98104
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:
100109
110+1. Regole ignore:
101111
102−\ **ioctl**\
112+ ignore *tipo* *simbolo*
103113
104− La dichiarazione ignore o replace verrà applicata su definizioni di ioctl
105− come la seguente:
114+Rimuove il simbolo dalla generazione dei riferimenti.
106115
107− #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register)
116+2. Regole replace:
108117
118+ replace *tipo* *vecchio_simbolo* *nuovo_riferimento*
109119
120+ Sostituisce *vecchio_simbolo* con *nuovo_riferimento*.
121+ *nuovo_riferimento* può essere:
110122
111−\ **define**\
123+ - un semplice nome di simbolo;
124+ - un riferimento Sphinx completo.
112125
113− La dichiarazione ignore o replace verrà applicata su una qualsiasi #define
114− trovata in C_FILE.
126+3. Regole namespace
115127
128+ namespace *spazio_dei_nomi*
116129
130+ Imposta lo *spazio_dei_nomi* C da utilizzare durante la generazione dei
131+ riferimenti incrociati. Può essere sovrascritto dalle regole replace.
117132
118−\ **typedef**\
133+Nelle regole ignore e replace, *tipo* può essere:
119134
120− La dichiarazione ignore o replace verrà applicata ad una dichiarazione typedef
121− in C_FILE.
135+ - ioctl:
136+ per le definizioni della forma ``_IO*``, per esempio le definizioni
137+ di ioctl
122138
139+ - define:
140+ per le altre definizioni
123141
142+ - symbol:
143+ per i simboli definiti all'interno di enumerati;
124144
125−\ **struct**\
145+ - typedef:
146+ per i typedef;
126147
127− La dichiarazione ignore o replace verrà applicata ai nomi di strutture
128− in C_FILE.
148+ - enum:
149+ per il nome di un enumerato non anonimo;
129150
130−
131−
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.
151+ - struct:
152+ per le strutture.
149153
150154
151155 ESEMPI
152156 ******
153157
158+- Ignora una definizione ``_VIDEODEV2_H`` in ``FILE_IN``::
154159
155−ignore define _VIDEODEV2_H
156−
157−
158−Ignora una definizione #define _VIDEODEV2_H nel file C_FILE.
159−
160−ignore symbol PRIVATE
160+ ignore define _VIDEODEV2_H
161161
162+- In una struttura dati come questo enumerato::
162163
163−In un enumerato come il seguente:
164+ enum foo { BAR1, BAR2, PRIVATE };
164165
165−enum foo { BAR1, BAR2, PRIVATE };
166+ Non genererà alcun riferimento incrociato per ``PRIVATE``::
166167
167−Non genererà alcun riferimento per \ **PRIVATE**\ .
168+ ignore symbol PRIVATE
168169
169−replace symbol BAR1 :c:type:\`foo\`
170−replace symbol BAR2 :c:type:\`foo\`
170+ Nello stesso enumerato, invece di creare un riferimento incrociato per
171+ ogni simbolo, si può far si che tutti puntino al tipo C ``enum foo``::
171172
173+ replace symbol BAR1 :c:type:\`foo\`
174+ replace symbol BAR2 :c:type:\`foo\`
172175
173−In un enumerato come il seguente:
174176
175−enum foo { BAR1, BAR2, PRIVATE };
176−
177−Genererà un riferimento ai valori BAR1 e BAR2 dal simbolo foo nel dominio C.
177+- Usa lo spazio dei nomi C ``MC`` per tutti i simboli in ``FILE_IN``::
178178
179+ namespace MC
179180
180181 BUGS
181182 ****
182183
183−Riferire ogni malfunzionamento a Mauro Carvalho Chehab <mchehab@s-opensource.com>
184−
184+Segnalate qualsiasi malfunzionamento a Mauro Carvalho Chehab
185+<mchehab@kernel.org>
185186
186187 COPYRIGHT
187188 *********
188189
190+Copyright (c) 2016, 2025 di Mauro Carvalho Chehab <mchehab+huawei@kernel.org>.
189191
190−Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.
191−
192−Licenza GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>.
192+Licenza GPLv2: GNU GPL versione 2 <https://gnu.org/licenses/gpl.html>.
193193
194194 Questo è software libero: siete liberi di cambiarlo e ridistribuirlo.
195195 Non c'è alcuna garanzia, nei limiti permessi dalla legge.
Documentation/translations/it_IT/doc-guide/sphinx.rst+137−41
@@ -1,8 +1,5 @@
11 .. include:: ../disclaimer-ita.rst
22
3−.. note:: Per leggere la documentazione originale in inglese:
4− :ref:`Documentation/doc-guide/index.rst <doc_guide>`
5−
63 .. _it_sphinxdoc:
74
85 =============================================
@@ -36,7 +33,7 @@ Installazione Sphinx · 27 unmodified lines
3633 ====================
3734
3835 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.
4037
4138 Esiste uno script che verifica i requisiti Sphinx. Per ulteriori dettagli
4239 consultate :ref:`it_sphinx-pre-install`.
@@ -52,24 +49,14 @@ vi raccomandiamo di installare Sphinx dentro ad un ambiente virtuale usando · 9 unmodified lines
5249 ``virtualenv-3`` o ``virtualenv`` a seconda di come Python 3 è stato
5350 pacchettizzato dalla vostra distribuzione.
5451
55−.. note::
56−
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::
52+Riassumendo, se volete installare l'ultima versione di Sphinx, dovete
53+eseguire::
6754
68− $ virtualenv sphinx_2.4.4
69− $ . sphinx_2.4.4/bin/activate
70− (sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt
55+ $ virtualenv sphinx_latest
56+ $ . sphinx_latest/bin/activate
57+ (sphinx_latest) $ pip install -r Documentation/sphinx/requirements.txt
7158
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
7360 indicare che state usando il nuovo ambiente. Se aprite un nuova sessione,
7461 prima di generare la documentazione, dovrete rieseguire questo comando per
7562 rientrare nell'ambiente virtuale.
@@ -99,6 +86,27 @@ Per alcune distribuzioni Linux potrebbe essere necessario installare · 23 unmodified lines
9986 anche una serie di pacchetti ``texlive`` in modo da fornire il supporto
10087 minimo per il funzionamento di ``XeLaTeX``.
10188
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+
102110 .. _it_sphinx-pre-install:
103111
104112 Verificare le dipendenze Sphinx
@@ -136,6 +144,30 @@ Questo script ha i seguenti parametri: · 31 unmodified lines
136144 Utilizza l'ambiente predefinito dal sistema operativo invece che
137145 l'ambiente virtuale per Python;
138146
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+
139171
140172 Generazione della documentazione Sphinx
141173 =======================================
@@ -143,39 +175,82 @@ Generazione della documentazione Sphinx · 1 unmodified line
143175 Per generare la documentazione in formato HTML o PDF si eseguono i rispettivi
144176 comandi ``make htmldocs`` o ``make pdfdocs``. Esistono anche altri formati
145177 in cui è possibile generare la documentazione; per maggiori informazioni
146−potere eseguire il comando ``make help``.
178+potete eseguire il comando ``make help``.
147179 La documentazione così generata sarà disponibile nella sottocartella
148180 ``Documentation/output``.
149181
150182 Ovviamente, per generare la documentazione, Sphinx (``sphinx-build``)
151−dev'essere installato. Se disponibile, il tema *Read the Docs* per Sphinx
152−verrà utilizzato per ottenere una documentazione HTML più gradevole.
153−Per la documentazione in formato PDF, invece, avrete bisogno di ``XeLaTeX`
154−e di ``convert(1)`` disponibile in ImageMagick
155−(https://www.imagemagick.org). \ [#ink]_
156−Tipicamente, tutti questi pacchetti sono disponibili e pacchettizzati nelle
157−distribuzioni Linux.
183+dev'essere installato. Per la documentazione in formato PDF, invece,
184+avrete bisogno di ``XeLaTeX`` e di ``convert(1)`` disponibile in
185+ImageMagick (https://www.imagemagick.org).\ [#ink]_ Tutti questi pacchetti
186+sono ampiamente disponibili e pacchettizzati nelle distribuzioni.
158187
159188 Per poter passare ulteriori opzioni a Sphinx potete utilizzare la variabile
160−make ``SPHINXOPTS``. Per esempio, se volete che Sphinx sia più verboso durante
161−la generazione potete usare il seguente comando ``make SPHINXOPTS=-v htmldocs``.
189+make ``SPHINXOPTS``. Per esempio, se volete che Sphinx sia più prolisso
190+durante la generazione potete usare il comando
191+``make SPHINXOPTS=-v htmldocs``.
162192
163−Potete anche personalizzare l'ouptut html passando un livello aggiuntivo
193+Potete anche personalizzare l'output html passando un livello aggiuntivo
164194 DOCS_CSS usando la rispettiva variabile d'ambiente ``DOCS_CSS``.
165195
166−La variable make ``SPHINXDIRS`` è utile quando si vuole generare solo una parte
167−della documentazione. Per esempio, si possono generare solo di documenti in
168−``Documentation/doc-guide`` eseguendo ``make SPHINXDIRS=doc-guide htmldocs``. La
169−sezione dedicata alla documentazione di ``make help`` vi mostrerà quali sotto
170−cartelle potete specificare.
196+Il tema di base per generare la documentazione HTML viene è "Alabaster"; questo
197+tema è distribuito assieme a Sphinx e non necessita di un'installazione
198+separata. Il tema di Sphinx può essere sostituito usando la variabile make
199+``DOCS_THEME``.
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.
171213
172214 Potete eliminare la documentazione generata tramite il comando
173215 ``make cleandocs``.
174216
175−.. [#ink] Avere installato anche ``inkscape(1)`` dal progetto Inkscape ()
176− potrebbe aumentare la qualità delle immagini che verranno integrate
177− nel documento PDF, specialmente per quando si usando rilasci del
178− kernel uguali o superiori a 5.18
217+.. [#ink] Avere installato anche ``inkscape(1)`` dal progetto Inkscape
218+ (https://inkscape.org) potrebbe aumentare la qualità delle
219+ immagini integrate nei documenti PDF, specialmente per i rilasci
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+
179254
180255 Scrivere la documentazione
181256 ==========================
@@ -289,8 +364,19 @@ incrociato quando questa ha una voce nell'indice. Se trovate degli usi di · 107 unmodified lines
289364 ``c:func:`` nella documentazione del kernel, sentitevi liberi di rimuoverli.
290365
291366
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+
292378 Tabelle a liste
293−---------------
379+~~~~~~~~~~~~~~~
294380
295381 Il formato ``list-table`` può essere utile per tutte quelle tabelle che non
296382 possono essere facilmente scritte usando il formato ASCII-art di Sphinx. Però,
@@ -403,6 +489,16 @@ percorso al documento. · 106 unmodified lines
403489
404490 Per informazioni riguardo ai riferimenti incrociati ai commenti
405491 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")
406502
407503 .. _it_sphinx_kfigure:
408504
Documentation/translations/it_IT/process/changes.rst+73−45
@@ -23,50 +23,53 @@ Requisiti minimi correnti · 22 unmodified lines
2323
2424 Prima di pensare d'avere trovato un baco, aggiornate i seguenti programmi
2525 **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.
2729
2830 Questa lista presume che abbiate già un kernel Linux funzionante. In aggiunta,
2931 non tutti gli strumenti sono necessari ovunque; ovviamente, se non avete una
3032 PC Card, per esempio, probabilmente non dovreste preoccuparvi di pcmciautils.
3133
32−====================== ================= ========================================
33− Programma Versione minima Comando per verificare la versione
34−====================== ================= ========================================
35−GNU C 8.1 gcc --version
36−Clang/LLVM (optional) 17.0.1 clang --version
37−Rust (opzionale) 1.78.0 rustc --version
38−bindgen (opzionale) 0.65.1 bindgen --version
39−GNU make 4.0 make --version
40−bash 4.2 bash --version
41−binutils 2.30 ld -v
42−flex 2.5.35 flex --version
43−bison 2.0 bison --version
44−pahole 1.16 pahole --version
45−util-linux 2.10o mount --version
46−kmod 13 depmod -V
47−e2fsprogs 1.41.4 e2fsck -V
48−jfsutils 1.1.3 fsck.jfs -V
49−xfsprogs 2.6.0 xfs_db -V
50−squashfs-tools 4.0 mksquashfs -version
51−btrfs-progs 0.18 btrfsck
52−pcmciautils 004 pccardctl -V
53−quota-tools 3.09 quota -V
54−PPP 2.4.0 pppd --version
55−nfs-utils 1.0.5 showmount --version
56−procps 3.2.0 ps --version
57−udev 081 udevd --version
58−grub 0.93 grub --version || grub-install --version
59−mcelog 0.6 mcelog --version
60−iptables 1.4.2 iptables -V
61−openssl & libcrypto 1.0.0 openssl version
62−bc 1.06.95 bc --version
63−Sphinx\ [#f1]_ 2.4.4 sphinx-build --version
64−cpio any cpio --version
65−GNU tar 1.28 tar --version
66−gtags (opzionale) 6.6.5 gtags --version
67−mkimage (opzionale) 2017.01 mkimage --version
68−Python (opzionale) 3.5.x python3 --version
69−====================== ================= ========================================
34+====================== =============== ========================================
35+ Programma Versione minima Comando per verificare la versione
36+====================== =============== ========================================
37+bash 4.2 bash --version
38+bc 1.06.95 bc --version
39+bindgen (opzionale) 0.71.1 bindgen --version
40+binutils 2.30 ld -v
41+bison 2.0 bison --version
42+btrfs-progs 0.18 btrfs --version
43+Clang/LLVM (opzionale) 17.0.1 clang --version
44+e2fsprogs 1.41.4 e2fsck -V
45+flex 2.5.35 flex --version
46+gdb 7.2 gdb --version
47+GNU awk (opzionale) 5.1.0 gawk --version
48+GNU C 8.1 gcc --version
49+GNU make 4.0 make --version
50+GNU tar 1.28 tar --version
51+GRUB 0.93 grub --version || grub-install --version
52+gtags (opzionale) 6.6.5 gtags --version
53+iptables 1.4.2 iptables -V
54+jfsutils 1.1.3 fsck.jfs -V
55+kmod 13 kmod -V
56+mcelog 0.6 mcelog --version
57+mkimage (opzionale) 2017.01 mkimage --version
58+nfs-utils 1.0.5 showmount --version
59+openssl & libcrypto 1.0.0 openssl version
60+pahole 1.26 pahole --version
61+pcmciautils 004 pccardctl -V
62+PPP 2.4.0 pppd --version
63+procps 3.2.0 ps --version
64+Python 3.9.x python3 --version
65+quota-tools 3.09 quota -V
66+Rust (opzionale) 1.85.0 rustc --version
67+Sphinx\ [#f1]_ 3.4.3 sphinx-build --version
68+squashfs-tools 4.0 mksquashfs -version
69+udev 081 udevadm --version
70+util-linux 2.10o mount --version
71+xfsprogs 2.6.0 xfs_db -V
72+====================== =============== ========================================
7073
7174 .. [#f1] Sphinx è necessario solo per produrre la documentazione del Kernel
7275
@@ -144,7 +147,13 @@ pahole · 71 unmodified lines
144147
145148 Dalla versione 5.2, quando viene impostato CONFIG_DEBUG_INFO_BTF, il sistema di
146149 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.
148157
149158 A seconda della distribuzione, lo si può trovare nei pacchetti 'dwarves' o
150159 'pahole'. Oppure lo si può trovare qui: https://fedorapeople.org/~acme/dwarves/.
@@ -155,6 +164,14 @@ Perl · 4 unmodified lines
155164 Per compilare il kernel vi servirà perl 5 e i seguenti moduli ``Getopt::Long``,
156165 ``Getopt::Std``, ``File::Basename``, e ``File::Find``.
157166
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+
158175 BC
159176 --
160177
@@ -193,6 +210,12 @@ pacchetto ``u-boot-tools`` oppure può essere compilato dal codice sorgente di · 32 unmodified lines
193210 U-Boot. Consultate le istruzioni
194211 https://docs.u-boot.org/en/latest/build/tools.html#building-tools-for-linux
195212
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).
196219
197220 Strumenti di sistema
198221 ********************
@@ -405,6 +428,16 @@ Clang/LLVM · 206 unmodified lines
405428
406429 - :ref:`Getting LLVM <getting_llvm>`.
407430
431+Rust
432+----
433+
434+- Documentation/rust/quick-start.rst.
435+
436+bindgen
437+-------
438+
439+- Documentation/rust/quick-start.rst.
440+
408441 Make
409442 ----
410443
@@ -507,11 +540,6 @@ mcelog · 96 unmodified lines
507540
508541 - <https://www.mcelog.org/>
509542
510−cpio
511−----
512−
513−- <https://www.gnu.org/software/cpio/>
514−
515543 Rete
516544 ****
517545
Documentation/translations/ja_JP/process/submitting-patches.rst+152−75
@@ -182,7 +182,7 @@ URL は禁止です。 · 181 unmodified lines
182182 変更を分割する
183183 --------------
184184
185−各 **論理的な変更** は、個別のパッチに分けてください。
185+それぞれの\ **論理的な変更**\ は、個別のパッチに分けてください。
186186
187187 たとえば、単一のドライバに対する変更にバグ修正と性能改善の
188188 両方が含まれるなら、それらは 2 つ以上のパッチに分けてください。
@@ -208,7 +208,7 @@ URL は禁止です。 · 19 unmodified lines
208208 ことがあります。途中でバグを持ち込めば、彼らに感謝されることは
209209 ないでしょう。
210210
211−パッチセットをこれ以上小さくできないなら、一度に投稿するのは
211+パッチセットをそれ以上小さくできないなら、一度に投稿するのは
212212 15 個程度までにして、レビューと統合を待ってください。
213213
214214
@@ -220,18 +220,17 @@ Documentation/process/coding-style.rst を参照してください。 · 5 unmodified lines
220220 これを怠ると、単にレビューアの時間を無駄にするだけでなく、
221221 パッチはおそらく読まれもせずに却下されます。
222222
223−大きな例外が 1 つあります。コードをあるファイルから別の
224−ファイルへ移動する場合です。このときは、コードを移動する
225−その同じパッチの中で、移動したコードを一切変更してはいけません。
226−そうすることで、コードの移動という行為と、あなたの変更とを
227−明確に区別できます。これは実際の差分のレビューを大いに助け、
228−ツールがコード自体の履歴をより適切に追跡できるようにします。
223+一つの重要な例外は、コードをあるファイルから別のファイルへ移動する場合です。
224+その際は、コードを移動するその同じパッチの中で、一切コードを変更しては
225+いけません。これにより、コードの移動という行為と、コードの変更とが
226+明確に区別されます。これは実際の差分のレビューを大いに助け、また、ツールを
227+使ったコード変更の履歴の追跡を容易にします。
229228
230229 提出前に、パッチスタイルチェッカー
231230 (``scripts/checkpatch.pl``) でパッチを確認してください。
232−ただし、スタイルチェッカーは指針として見るべきであり、
231+ただし、スタイルチェッカーは指針にすぎず、
233232 人間の判断に取って代わるものではないことに注意してください。
234−違反があっても、その方がコードの見栄えがよいなら、
233+違反が指摘されるままのコードの方が見栄えがよいなら、おそらく
235234 そのままにしておくのが最善でしょう。
236235
237236 チェッカーは 3 つのレベルで報告します:
@@ -240,8 +239,7 @@ Documentation/process/coding-style.rst を参照してください。 · 2 unmodified lines
240239 - WARNING: 慎重なレビューを要するもの
241240 - CHECK: 検討を要するもの
242241
243−パッチに残した違反については、すべて理由を説明できなければ
244−なりません。
242+パッチに違反を残す場合は、そのすべてを正当化できなければなりません。
245243
246244
247245 パッチの宛先を選択する
@@ -256,8 +254,8 @@ Documentation/process/coding-style.rst を参照してください。 · 8 unmodified lines
256254 サブシステムのメンテナが見つからない場合は、Andrew Morton
257255 (akpm@linux-foundation.org) が最後の手段となるメンテナです。
258256
259−すべてのパッチでは、デフォルトで linux-kernel@vger.kernel.org を
260−使うべきですが、このリストの流量が多いため、目を通さなくなった
257+すべてのパッチは、デフォルトで linux-kernel@vger.kernel.org にも
258+送られるべきですが、このリストは流量が多く、目を通さなくなった
261259 開発者も少なくありません。とはいえ、無関係なメーリングリストや
262260 無関係な人々にスパムを送らないでください。
263261
@@ -268,103 +266,104 @@ Documentation/process/coding-style.rst を参照してください。 · 4 unmodified lines
268266 Linux カーネルに採用されるすべての変更の最終的な裁定者は
269267 Linus Torvalds です。彼のメールアドレスは
270268 <torvalds@linux-foundation.org> です。Linus は大量のメールを
271−受け取っており、現時点では彼に直接届くパッチはごくわずかなので、
272−通常は彼にメールを送ることを極力避けてください。
269+受け取っており、現時点では直接彼を経由するパッチはごくわずかなので、
270+通常は彼にメールを送ることを極力\ **避けて**\ ください。
273271
274−悪用可能なセキュリティバグを修正するパッチがあるなら、
275−そのパッチを security@kernel.org に送ってください。深刻なバグに
272+悪用可能なセキュリティバグを修正するパッチの場合は、
273+それを security@kernel.org に送ってください。深刻なバグに
276274 ついては、ディストリビュータがユーザーにパッチを配布できるよう、
277−短期間の embargo が検討される場合があります。そのような場合、
278−そのパッチを公開メーリングリストに送るべきではありません。
275+短期間の秘匿措置 (訳註: embargo) が検討される可能性があります。
276+ですので、その種のパッチを公開メーリングリストに送らないでください。
279277 Documentation/process/security-bugs.rst も参照してください。
280278
281279 リリース済みカーネルの深刻なバグを修正するパッチは、次のような行を
282−パッチの sign-off 欄に入れることで、stable メンテナへ向けてください::
280+パッチの sign-off 欄に入れることで、stable メンテナに知らせてください。
281+(メールの宛先ではないことに注意。) ::
283282
284283 Cc: stable@vger.kernel.org
285284
286−これはメールの受信者ではないことに注意してください。また、
287−この文書に加えて Documentation/process/stable-kernel-rules.rst も
288−読んでください。
285+また、この文書に加えて Documentation/process/stable-kernel-rules.rst
286+も読んでください。
289287
290288 変更がユーザーランドとカーネルのインターフェースに影響する場合は、
291289 MAINTAINERS ファイルに記載されている MAN-PAGES メンテナに
292−man-pages パッチ、少なくとも変更の通知を送って、情報が
293−マニュアルページに反映されるようにしてください。ユーザー空間 API の
290+マニュアルページのパッチ、もしくは少なくとも変更の通知を送って、情報が
291+そちらにも反映されるようにしてください。ユーザー空間 API の
294292 変更は、linux-api@vger.kernel.org にも Cc してください。
295293
296294 MIME・リンク・圧縮・添付なし、プレーンテキストのみ
297295 ----------------------------------------------------
298296
299297 Linus や他のカーネル開発者は、あなたが投稿する変更を読み、
300−コメントできる必要があります。カーネル開発者が標準的な
301−メールツールを使ってあなたの変更を「引用」し、コードの特定の
302−箇所についてコメントできることが重要です。
298+コメントできる必要があります。カーネル開発者にとって、コードの特定の
299+箇所について、標準的なメールツールを使ってあなたの変更を「引用」し、
300+コメントできることが重要です。
303301
304−このため、すべてのパッチはメール本文中に ``inline`` で投稿すべきです。
302+このため、すべてのパッチはメール本文中に「インライン」で投稿すべきです。
305303 これを行う最も簡単な方法は ``git send-email`` を使うことであり、
306304 強く推奨されます。``git send-email`` の対話型チュートリアルは
307−https://git-send-email.io で利用できます。
305+https://git-send-email.io にあります。
308306
309−``git send-email`` を使わないことを選ぶ場合:
307+``git send-email`` を使わない場合:
310308
311309 .. warning::
312310
313− パッチをコピー＆ペーストする場合は、エディタの word-wrap によって
314− パッチが壊れないよう注意してください。
311+ パッチをコピー＆ペーストする際に、エディタによる自動改行で
312+ パッチが壊されないよう注意してください。
315313
316314 圧縮の有無にかかわらず、パッチを MIME 添付ファイルとして添付しては
317−いけません。多くの一般的なメールアプリケーションは、MIME 添付
318−ファイルを常にプレーンテキストとして送信するとは限らず、あなたの
319−コードにコメントできなくなります。MIME 添付ファイルは Linus が
320−処理するのにも少し余分な時間がかかるため、MIME 添付された変更が
321−受け入れられる可能性を下げます。
315+いけません。よく使われるメールアプリケーションの多くは、MIME 添付
316+ファイルをプレーンテキストとして送信するとは限らず、あなたのコードに
317+対するコメントを妨げます。MIME 添付ファイルは Linus (訳補: をはじめ
318+とする開発者）が処理するのに余分な手間がかかるため、MIME 添付すると
319+その変更が受け入れられる可能性を下げることになります。
322320
323−例外: メーラがパッチを壊してしまう場合は、誰かから MIME を使って
324−再送するよう求められることがあります。
321+例外: パッチがメーラーによって壊されている場合に、MIME による再送
322+を求められることがあります。
325323
326−パッチを変更せずに送信するようメールクライアントを設定するための
327−ヒントについては、Documentation/process/email-clients.rst を参照してください。
324+改変なしにパッチを送信するためのメールクライアント設定のヒントは、
325+Documentation/process/email-clients.rst を参照してください。
328326
329327
330−レビューコメントに返答する
328+レビューコメントに応答する
331329 --------------------------
332330
333−あなたのパッチには、ほぼ確実に、パッチを改善する方法について
334−レビューアからコメントが付きます。それは、あなたのメールへの返信という
335−形で届きます。それらのコメントには必ず返答してください。レビューアを
336−無視することは、こちらも無視されるためのよい方法です。コメントに
337−答えるには、単にそのメールへ返信すれば構いません。コード変更に
331+あなたのパッチには、ほぼ確実に、その改善に向けてレビューアから
332+コメントが付きます。それは、あなたのメールへの返信という
333+形で届きます。それらのコメントには必ず応答してください。レビューアを
334+無視することは、あなたが無視されることにつながります。コメントに
335+答えるには、単にそのメールへ返信すればよいです。コード変更に
338336 つながらないレビューコメントや質問であっても、次のレビューアが状況を
339−よりよく理解できるように、ほぼ確実にコメントまたは changelog エントリに
340−反映すべきです。
341−
342−どのような変更を行うのかをレビューアに必ず伝え、時間を割いてくれた
343−ことに感謝してください。コードレビューは疲れる、時間のかかる作業であり、
344−レビューアが不機嫌になることもあります。そのような場合であっても、
345−丁寧に返答し、指摘された問題に対応してください。次の版を送るときは、
346−cover letter または個々のパッチに ``patch changelog`` を追加し、前回の
337+よりよく理解できるよう、多くの場合、コメントまたは changelog エントリ
338+として残すべきです。
339+
340+どのような変更を行うのかを忘れずにレビューアに伝えてください。そして
341+時間を割いてくれることへの感謝を忘れないでください。
342+コードレビューは疲れる、時間のかかる作業であり、
343+ときにはレビューアが機嫌を損ねることもあります。そのような場合でも、
344+丁寧に応答し、指摘された問題に対応してください。次の版を送る際には、
345+カバーレターまたは個々のパッチに ``patch changelog`` を追加し、前回の
347346 投稿との差分を説明してください。詳細は原文の該当節
348347 ("The canonical patch format") を参照してください。
349348
350349 .. TODO: Convert to file-local cross-reference when the destination is
351350 translated.
352351
353−あなたのパッチにコメントした人には、パッチの Cc リストに追加して、
354−新しい版を知らせてください。
352+あなたのパッチにコメントしてくれた人たちは、パッチの Cc リストに追加して
353+新しい版について知らせてください。
355354
356355 メールクライアントとメーリングリストでの作法についての推奨事項は、
357356 Documentation/process/email-clients.rst を参照してください。
358357
359−メール議論では不要な引用を削った interleaved replies を使う
360−------------------------------------------------------------
358+要点に絞ったインライン返信での議論
359+---------------------------------------
361360
362−Linux カーネル開発の議論では、top-posting は強く非推奨とされています。
363−Interleaved replies、または ``inline`` replies を使うと、会話の流れを
364−ずっと追いやすくなります。詳細は次を参照してください:
361+Linux カーネル開発の議論では、全文引用 (訳註: top-posting) は強く非推奨です。
362+インライン返信 (訳註: interleaved reples or "inline" replies) を使うと、
363+会話の流れをずっと追いやすくなります。詳細は次を参照してください:
365364 https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
366365
367−メーリングリストでは、よく次のように引用されます::
366+これについて、メーリングリストでは、次の引用をしばしば目にします::
368367
369368 A: http://en.wikipedia.org/wiki/Top_post
370369 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
381380 Q: Should I include quotations after my reply?
382381
383382
384−落胆しない、そして急がない
385−--------------------------
383+落胆しない - いらいらしない
384+---------------------------
386385
387386 変更を投稿した後は、辛抱強く待ってください。レビューアは忙しい人たちであり、
388−あなたのパッチをすぐに見られるとは限りません。
387+あなたのパッチにすぐに取りかかれるとは限りません。
389388
390389 かつては、パッチが何のコメントもなく虚空へ消えていくこともありましたが、
391390 現在の開発プロセスはそれよりも円滑に機能しています。数週間以内、
392391 通常は 2〜3 週間以内にコメントを受け取るはずです。そうならない場合は、
393392 パッチを正しい場所へ送ったか確認してください。再投稿したりレビューアに
394−ping したりする前に、少なくとも 1 週間は待ってください。merge window の
395−ような忙しい時期には、さらに長く待つ方がよい場合もあります。
393+ping したりする前に、少なくとも 1 週間は待ってください。マージ期間
394+(訳註: merge window) のような忙しい時期には、さらに長く待ちましょう。
396395
397−数週間後に、subject line に "RESEND" を追加して、パッチまたは
398−パッチシリーズを再送しても構いません::
396+数週間後に、件名に "RESEND" を追加したパッチまたはパッチシリーズを
397+再送することは構いません::
399398
400399 [PATCH Vx RESEND] sub/sys: Condensed patch summary
401400
402−パッチまたはパッチシリーズの修正版を投稿する場合は、"RESEND" を
403−追加しないでください。"RESEND" は、前回の投稿から一切変更していない
404−パッチまたはパッチシリーズを再送する場合にのみ使います。
401+ただし、パッチまたはパッチシリーズの修正版を投稿する際には "RESEND"
402+を追加しないでください。
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
6666 .. toctree::
6767 :maxdepth: 1
6868
69− Introdução <process/1.Intro>
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>
69+ process/index
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
2020 1.Intro
2121 2.Process
2222 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
2222 ------
2323 A **netdev** é a lista de discussão para todos os assuntos do Linux relacionados
2424 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
2626 de diretórios do Linux.
2727
2828 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
3030 específicas.
3131
3232 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
3434 https://lore.kernel.org/netdev/.
3535
3636 À 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**.
3838
3939 Ciclo de Desenvolvimento
4040 ------------------------
@@ -506,8 +506,14 @@ netdevsim · 465 unmodified lines
506506
507507 O ``netdevsim`` é um driver de teste que pode ser usado para exercitar APIs de
508508 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
510−APIs, mas o ``netdevsim`` em si **não** é considerado um caso de uso/usuário.
509+testes baseados no ``netdevsim`` são encorajados ao adicionar novas APIs com
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.
511517 Você também deve implementar as novas APIs em um driver real.
512518
513519 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
577583
578584 É seguro assumir que os mantenedores da netdev conhecem a comunidade e o nível
579585 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
581−experientes são fortemente incentivados a fazer uma revisão mais aprofundada das
586+seus comentários impedirem ou desviarem o fluxo de patches. Uma tag Reviewed-by
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
582591 submissões e não focar exclusivamente em questões triviais ou subjetivas, como
583592 formatação de código, tags, etc.
584593
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
148148 Cgroup2接口
149149 ===========
150150
151−对于CONFIG_CGROUP=y及挂载了cgroup2文件系统的系统，能够获取cgroups内任务的psi。
151+对于CONFIG_CGROUPS=y及挂载了cgroup2文件系统的系统，能够获取cgroups内任务的psi。
152152 此场景下cgroupfs挂载点的子目录包含cpu.pressure、memory.pressure、io.pressure文件，
153153 内容格式与/proc/pressure/下的文件相同。
154154
Documentation/translations/zh_CN/admin-guide/index.rst+152−50
@@ -1,7 +1,13 @@
1+.. SPDX-License-Identifier: GPL-2.0
12 .. include:: ../disclaimer-zh_CN.rst
23
3−:Original: :doc:`../../../admin-guide/index`
4−:Translator: Alex Shi <alex.shi@linux.alibaba.com>
4+:Original: Documentation/admin-guide/index.rst
5+
6+:翻译:
7+
8+ 时奎亮 Alex Shi <alex.shi@linux.alibaba.com>
9+
10+ 朱岩 Yan Zhu <zhuyan2015@qq.com>
511
612
713 Linux 内核用户和管理员指南
@@ -11,7 +17,11 @@ Linux 内核用户和管理员指南 · 3 unmodified lines
1117 整体的顺序或组织 - 这些材料不是一个单一的，连贯的文件！幸运的话，情况会随着
1218 时间的推移而迅速改善。
1319
14−这个初始部分包含总体信息，包括描述内核的README， 关于内核参数的文档等。
20+
21+内核管理通用指南
22+----------------
23+
24+本节包含总体信息，包括描述内核整体的 README 文件、内核参数文档等。
1525
1626 .. toctree::
1727 :maxdepth: 1
@@ -20,17 +30,54 @@ Linux 内核用户和管理员指南 · 2 unmodified lines
2030
2131 Todolist:
2232
23−* kernel-parameters
2433 * devices
34+* features
35+
36+内核管理接口的重要组成部分是 /proc 和 sysfs 虚拟文件系统；这些文档描述了如何
37+与之交互。
38+
39+.. toctree::
40+ :maxdepth: 1
41+
42+ cputopology
43+
44+Todolist:
45+
46+* sysfs-rules
2547 * sysctl/index
48+* abi
2649
27−本节介绍CPU漏洞及其缓解措施。
50+安全相关文档：
51+
52+.. toctree::
53+ :maxdepth: 1
2854
2955 Todolist:
3056
3157 * 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+
3276
33−下面的一组文档，针对的是试图跟踪问题和bug的用户。
77+追踪和识别问题
78+--------------
79+
80+以下是一组面向试图追踪特定问题和 bug 的用户的文档。
3481
3582 .. toctree::
3683 :maxdepth: 1
@@ -39,94 +86,149 @@ Todolist: · 2 unmodified lines
3986 reporting-regressions
4087 bug-hunting
4188 bug-bisect
42− tainted-kernels
4389 init
90+ clearing-warn-once
91+ lockup-watchdogs
92+ sysrq
4493
4594 Todolist:
4695
96+* quickly-build-trimmed-linux
97+* verify-bugs-and-bisect-regressions
98+* tainted-kernels
4799 * ramoops
48100 * dynamic-debug-howto
49101 * kdump/index
50102 * 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
51115
52−这是应用程序开发人员感兴趣的章节的开始。可以在这里找到涵盖内核ABI各个
53−方面的文档。
116+ cpu-load
117+ mm/index
118+ module-signing
119+ numastat
54120
55121 Todolist:
56122
57−* sysfs-rules
123+* cgroup-v2
124+* cgroup-v1/index
125+* namespaces/index
126+* pm/index
127+* syscall-user-dispatch
58128
59−本手册的其余部分包括各种指南，介绍如何根据您的喜好配置内核的特定行为。
60129
130+对非原生二进制格式的支持。请注意，其中一些文档相当 **古老**。
61131
62132 .. toctree::
63133 :maxdepth: 1
64134
65− bootconfig
66− clearing-warn-once
67− cpu-load
68− cputopology
69− lockup-watchdogs
70− numastat
71− unicode
72− sysrq
73− mm/index
135+Todolist:
136+
137+* binfmt-misc
138+* java
139+* mono
140+
141+
142+块设备和文件系统管理
143+--------------------
144+
145+.. toctree::
146+ :maxdepth: 1
74147
75148 Todolist:
76149
77−* acpi/index
78−* aoe/index
79−* auxdisplay/index
80150 * bcache
81151 * binderfs
82−* binfmt-misc
83152 * blockdev/index
84−* braille-console
85−* btmrvl
86−* cgroup-v1/index
87−* cgroup-v2
88153 * cifs/index
89−* dell_rbu
90154 * device-mapper/index
91−* edid
92−* efi-stub
93155 * ext4
156+* filesystem-monitoring
94157 * nfs/index
95−* gpio/index
96−* highuid
97−* hw_random
98−* initrd
99158 * iostats
100−* java
101159 * 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
103184 * laptops/index
104185 * lcd-panel-cgram
105−* ldm
106−* LSM/index
107−* md
108186 * media/index
109−* module-signing
110−* mono
111−* namespaces/index
187+* nvme-multipath
112188 * parport
113−* perf-security
114−* pm/index
115189 * pnp
116190 * rapidio
117−* ras
118191 * rtc
119192 * serial-console
120193 * svga
194+* thermal/index
121195 * thunderbolt
122−* ufs
123196 * vga-softcursor
124197 * 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
126228
127229 .. only:: subproject and html
128230
129− Indices
130− =======
231+ 索引
232+ ====
131233
132234 * :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
7979 CONFIG_KASAN=y
8080
8181 同时在 ``CONFIG_KASAN_GENERIC`` (启用通用KASAN模式)， ``CONFIG_KASAN_SW_TAGS``
82−(启用基于硬件标签的KASAN模式)，和 ``CONFIG_KASAN_HW_TAGS`` (启用基于硬件标签
82+(启用基于软件标签的KASAN模式)，和 ``CONFIG_KASAN_HW_TAGS`` (启用基于硬件标签
8383 的KASAN模式)之间进行选择。
8484
8585 对于软件模式，还可以在 ``CONFIG_KASAN_OUTLINE`` 和 ``CONFIG_KASAN_INLINE``
Documentation/translations/zh_CN/how-to.rst+100−49
@@ -13,20 +13,20 @@ Linux 内核中文文档翻译规范 · 12 unmodified lines
1313 过去几年，在广大社区爱好者的友好合作下，Linux 内核中文文档迎来了蓬勃的发
1414 展。在翻译的早期，一切都是混乱的，社区对译稿只有一个准确翻译的要求，以鼓
1515 励更多的开发者参与进来，这是从 0 到 1 的必然过程，所以早期的中文文档目录
16−更加具有多样性，不过好在文档不多，维护上并没有过大的压力。
16+呈现出较强的多样性，不过好在文档不多，维护上并没有过大的压力。
1717
1818 然而，世事变幻，不觉有年，现在内核中文文档在前进的道路上越走越远，很多潜
1919 在的问题逐渐浮出水面，而且随着中文文档数量的增加，翻译更多的文档与提高中
2020 文文档可维护性之间的矛盾愈发尖锐。由于文档翻译的特殊性，很多开发者并不会
2121 一直更新文档，如果中文文档落后英文文档太多，文档更新的工作量会远大于重新
2222 翻译。而且邮件列表中陆续有新的面孔出现，他们那股热情，就像燃烧的火焰，能
23−瞬间点燃整个空间，可是他们的补丁往往具有个性，这会给审阅带来了很大的困难，
23+瞬间点燃整个空间，可是他们的补丁往往具有个性，这给审阅带来了很大的困难，
2424 reviewer 们只能耐心地指导他们如何与社区更好地合作，但是这项工作具有重复
2525 性，长此以往，会渐渐浇灭 reviewer 审阅的热情。
2626
27−虽然内核文档中已经有了类似的贡献指南，但是缺乏专门针对于中文翻译的，尤其
27+虽然内核文档中已经有了类似的贡献指南，但是缺乏专门面向中文翻译的，尤其
2828 是对于新手来说，浏览大量的文档反而更加迷惑，该文档就是为了缓解这一问题而
29−编写，目的是为提供给新手一个快速翻译指南。
29+编写，旨在为新手提供一份快速翻译指南。
3030
3131 详细的贡献指南：Documentation/translations/zh_CN/process/index.rst。
3232
@@ -145,8 +145,8 @@ Git 和邮箱配置 · 112 unmodified lines
145145 sudo dnf install git-email
146146 vim ~/.gitconfig
147147
148−这里是我的一个配置文件示范，请根据您的邮箱域名服务商提供的手册替换到对
149−应的字段。
148+这里是我的一个配置文件示范，请根据您的邮箱域名服务商提供的手册替换对应
149+的字段。
150150 ::
151151
152152 [user]
@@ -190,7 +190,7 @@ Git 和邮箱配置 · 37 unmodified lines
190190 译文格式要求
191191 ------------
192192
193− - 每行长度最多不超过 40 个字符
193+ - 每行长度不超过 40 个字符
194194 - 每行长度请保持一致
195195 - 标题的下划线长度请按照一个英文一个字符、一个中文两个字符与标题对齐
196196 - 其它的修饰符请与英文文档保持一致
@@ -211,7 +211,7 @@ Git 和邮箱配置 · 14 unmodified lines
211211 --------
212212
213213 中文文档有每行 40 字符限制，因为一个中文字符等于 2 个英文字符。但是社区并
214−没有那么严格，一个诀窍是将您的翻译的内容与英文原文的每行长度对齐即可，这样，
214+没有那么严格，一个诀窍是将您翻译的内容与英文原文的每行长度对齐，这样，
215215 您也不必总是检查有没有超限。
216216
217217 如果您的英文阅读能力有限，可以考虑使用辅助翻译工具，例如 deepseek。但是您
@@ -257,7 +257,9 @@ Git 和邮箱配置 · 39 unmodified lines
257257
258258 Update the translation through commit b080e52110ea
259259 ("docs: update self-protection __ro_after_init status")
260− # 请执行 git log --oneline <您翻译的英文文档路径>，并替换上述内容
260+ # 请执行 git log --no-merges --oneline <您翻译的英文文档路径>
261+ # 并替换上述内容。注意：应引用实际修改文件内容的 commit，
262+ # 而非 merge commit
261263
262264 Signed-off-by: Yanteng Si <si.yanteng@linux.dev>
263265 # 如果您前面的步骤正确执行，该行会自动显示，否则请检查 gitconfig 文件
@@ -267,13 +269,22 @@ Git 和邮箱配置 · 3 unmodified lines
267269 **请注意** 以上四行，缺少任何一行，您都将会在第一轮审阅后返工，如果您需要一个
268270 更加明确的示例，请对 zh_CN 目录执行 git log。
269271
270−导出补丁和制作封面
271−------------------
272+导出补丁
273+--------
274+
275+这个时候，可以导出补丁，做发送邮件列表最后的准备了。对于单个补丁，
276+命令行执行::
277+
278+ git format-patch -1
279+
280+然后命令行会输出类似下面的内容::
281+
282+ 0001-docs-zh_CN-add-xxxxxxxx.patch
272283
273−这个时候，可以导出补丁，做发送邮件列表最后的准备了。命令行执行::
284+如果您有多个补丁，命令行执行::
274285
275286 git format-patch -N
276− # N 要替换为补丁数量，一般 N 大于等于 1
287+ # N 要替换为补丁数量，一般 N 大于 1
277288
278289 然后命令行会输出类似下面的内容::
279290
@@ -288,13 +299,12 @@ Git 和邮箱配置 · 8 unmodified lines
288299
289300 ./scripts/checkpatch.pl *.patch
290301
291−参考脚本输出，解决掉所有的 error 和 warning，通常情况下，只有下面这个
302+参考脚本输出，解决掉所有的 error 和 warning。通常情况下，只有下面这个
292303 warning 不需要解决::
293304
294305 WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
295306
296−一个简单的解决方法是一次只检查一个补丁，然后打上该补丁，直接对译文进行修改，
297−然后执行以下命令为补丁追加更改::
307+对于单个补丁，解决方案很简单，只需要打上该补丁，直接对译文进行修改，为补丁追加后续更改::
298308
299309 git checkout docs-next
300310 git checkout -b test-trans-new
@@ -302,15 +312,21 @@ warning 不需要解决:: · 1 unmodified line
302312 ./scripts/checkpatch.pl 0001-xxxxx.patch
303313 # 直接修改您的翻译
304314 git add .
305− git am --amend
315+ git commit --amend
306316 # 保存退出
307− git am 0002-xxxxx.patch
308− ……
309317
310−重新导出再次检测，重复这个过程，直到处理完所有的补丁。
318+随后，重新导出补丁再次检测，重复这个过程，直到处理完所有 warning 和
319+error。
320+
321+如果您有多个补丁，请按补丁集中补丁顺序对每个补丁重复上述流程，一次只处理
322+一个，不要一次 git am 多个补丁。全部处理完毕后再重新导出并再次测试。
311323
312−最后，如果检测时没有 warning 和 error 需要被处理或者您只有一个补丁，请跳
313−过下面这个步骤，否则请重新导出补丁制作封面::
324+为补丁集制作封面
325+----------------
326+
327+对于单个补丁，请跳过本节。
328+
329+如果您有多个补丁，则需要为补丁集制作一份封面，即 0 号补丁::
314330
315331 git format-patch -N --cover-letter --thread=shallow
316332 # N 要替换为补丁数量，一般 N 大于 1
@@ -327,18 +343,14 @@ warning 不需要解决:: · 10 unmodified lines
327343 vim 0000-cover-letter.patch
328344
329345 ...
330− Subject: [PATCH 0/N] *** SUBJECT HERE *** #修改该字段，概括您的补丁集都做了哪些事情
346+ Subject: [PATCH 0/N] *** SUBJECT HERE *** # 修改该字段，概括您的补丁集都做了哪些事情
331347
332− *** BLURB HERE *** #修改该字段，详细描述您的补丁集做了哪些事情
348+ *** BLURB HERE *** # 修改该字段，详细描述您的补丁集做了哪些事情
333349
334350 Yanteng Si (1):
335351 docs/zh_CN: add xxxxx
336352 ...
337353
338−如果您只有一个补丁，则可以不制作封面，即 0 号补丁，只需要执行::
339−
340− git format-patch -1
341−
342354 把补丁提交到邮件列表
343355 ====================
344356
@@ -361,13 +373,13 @@ warning 不需要解决:: · 16 unmodified lines
361373 git send-email *.patch --to <maintainer email addr> --cc <others addr>
362374 # 一个 to 对应一个地址，一个 cc 对应一个地址，有几个就写几个
363375
364−执行该命令时，请确保网络通常，邮件发送成功一般会返回 250。
376+执行该命令时，请确保网络通畅，邮件发送成功一般会返回 250。
365377
366378 您可以先发送给自己，尝试发出的 patch 是否可以用 'git am' 工具正常打上。
367379 如果检查正常， 您就可以放心的发送到社区评审了。
368380
369−如果该步骤被中断，您可以检查一下，继续用上条命令发送失败的补丁，一定不要再
370−次发送已经发送成功的补丁。
381+如果该步骤被中断，您可以检查一下，然后用上条命令继续发送失败的补丁，一定不
382+要再次发送已经发送成功的补丁。
371383
372384 积极参与审阅过程并迭代补丁
373385 ==========================
@@ -380,7 +392,7 @@ reviewer 的评论，做到每条都有回复，每个回复都落实到位。 · 6 unmodified lines
380392
381393 - 请先将您的邮箱客户端信件回复修改为 **纯文本** 格式，并去除所有签名，尤其是
382394 企业邮箱。
383− - 然后点击回复按钮，并将要回复的邮件带入，
395+ - 然后点击回复按钮，并引用要回复的邮件，
384396 - 在第一条评论行尾换行，输入您的回复
385397 - 在第二条评论行尾换行，输入您的回复
386398 - 直到处理完最后一条评论，换行空两行输入问候语和署名
@@ -390,28 +402,67 @@ reviewer 的评论，做到每条都有回复，每个回复都落实到位。 · 3 unmodified lines
390402 迭代补丁
391403 --------
392404
393−建议您每回复一条评论，就修改一处翻译。然后重新生成补丁，相信您现在已经具
394−备了灵活使用 git am --amend 的能力。
405+建议您每回复一条评论，就修改一处翻译，然后重新生成补丁，相信您现在
406+已经具备了灵活使用 git am 与 git commit --amend 的能力。
395407
396−每次迭代一个补丁，不要一次多个::
408+对于单个补丁，每回复完评论后修改、追加::
397409
398− git am <您要修改的补丁>
410+ git am 0001-xxxxx.patch
399411 # 直接对文件进行您的修改
400412 git add .
401413 git commit --amend
402414
403−当您将所有的评论落实到位后，导出第二版补丁，并修改封面::
415+当您将所有的评论落实到位后，导出第二版补丁::
404416
405− git format-patch -N -v 2 --cover-letter --thread=shallow
417+ git format-patch -1 -v 2
418+
419+命令行会输出 v2-0001-xxxxx.patch。打开该文件，在 --- 分割线下方追加
420+changelog。注意，分割线以下的内容不会进入 git 提交历史，仅作为邮件中的
421+说明供 reviewer 检查::
422+
423+ Subject: [PATCH v2] docs/zh_CN: add xxxxxx translation
424+
425+ Translate .../xxx.rst into Chinese.
426+
427+ Signed-off-by: Yanteng Si <si.yanteng@linux.dev>
428+ ---
429+ v1->v2:
430+ - 修正第二节的错别字，Reviewer-A 提出的意见
431+ - 根据 Reviewer-B 的建议调整段落顺序
406432
407−打开 0 号补丁，在 BLURB HERE 处编写相较于上个版本，您做了哪些改动。
433+ Documentation/translations/zh_CN/xxx.rst | 100 ++++++
434+ 1 file changed, 100 insertions(+)
408435
409−然后执行::
436+后续迭代 v3、v4 …… 时，新的 changelog 放在最上面，旧的保留在下方，按
437+从新到旧的顺序叠加。例如 v3 补丁的 --- 下方::
410438
411− git send-email v2* --to <maintainer email addr> --cc <others addr>
439+ ---
440+ v2->v3:
441+ - ...本次相较 v2 的改动...
442+ v1->v2:
443+ - ...上一次相较 v1 的改动...
444+
445+然后发送::
446+
447+ git send-email v2-0001-*.patch --to <maintainer email addr> --cc <others addr>
448+
449+如果您有多个补丁，迭代时请按以下原则：每次只迭代一个补丁，不要一次多个，
450+每个补丁独立重复上述流程。所有评论落实到位后，导出 v2 时附带封面::
451+
452+ git format-patch -N -v 2 --cover-letter --thread=shallow
453+
454+打开 0 号补丁，在 BLURB HERE 处写明整组补丁相较 v1 的总体改动，格式
455+同上面的单个补丁 changelog 示例。如果某个补丁需要单独说明，可在该
456+补丁文件的 --- 分割线下方追加单个补丁的 changelog。最后执行::
457+
458+ git send-email v2-*.patch --to <maintainer email addr> --cc <others addr>
412459
413460 这样，新的一版补丁就又发送到邮件列表等待审阅，之后就是重复这个过程。
414461
462+此外，如果审阅者或维护者在邮件回复中给出了 Reviewed-by tag，请在下
463+一版补丁的 commit 信息中加入该 tag，放在 Signed-off-by 行的下方，以
464+便维护者合入时保留您的审阅记录。
465+
415466 审阅周期
416467 --------
417468
@@ -425,10 +476,10 @@ reviewer 的评论，做到每条都有回复，每个回复都落实到位。 · 7 unmodified lines
425476 紧急处理
426477 --------
427478
428−如果您发送到邮件列表之后。发现发错了补丁集，尤其是在多个版本迭代的过程中；
479+如果您发送到邮件列表之后，发现发错了补丁集，尤其是在多个版本迭代的过程中；
429480 自己发现了一些不妥的翻译；发送错了邮件列表……
430481
431−git email 默认会抄送给您一份，所以您可以切换为审阅者的角色审查自己的补丁，
482+git send-email 默认会抄送给您一份，所以您可以切换为审阅者的角色审查自己的补丁，
432483 并留下评论，描述有何不妥，将在下个版本怎么改，并付诸行动，重新提交，但是
433484 注意频率，每天提交的次数不要超过两次。
434485
@@ -437,7 +488,7 @@ git email 默认会抄送给您一份，所以您可以切换为审阅者的角 · 2 unmodified lines
437488 对于首次参与 Linux 内核中文文档翻译的新手，建议您在 linux 目录中运行以下命令：
438489 ::
439490
440− tools/docs/checktransupdate.py -l zh_CN``
491+ tools/docs/checktransupdate.py -l zh_CN
441492
442493 该命令会列出需要翻译或更新的英文文档，结果同时保存在 checktransupdate.log 中。
443494
@@ -446,9 +497,9 @@ git email 默认会抄送给您一份，所以您可以切换为审阅者的角 · 2 unmodified lines
446497 进阶
447498 ----
448499
449−希望您不只是单纯的翻译内核文档，在熟悉了一起与社区工作之后，您可以审阅其他
500+希望您不只是单纯地翻译内核文档，在熟悉了与社区协作之后，您可以审阅其他
450501 开发者的翻译，或者提出具有建设性的主张。与此同时，与文档对应的代码更加有趣，
451−而且需要完善的地方还有很多，勇敢地去探索，然后提交你的想法吧。
502+而且需要完善的地方还有很多，勇敢地去探索，然后提交您的想法吧。
452503
453504 常见的问题
454505 ==========
@@ -467,7 +518,7 @@ Maintainer 回复补丁不能正常 apply · 12 unmodified lines
467518 ------------------
468519
469520 大部分情况下，是由于您发送了非纯文本格式的信件，请尽量避免使用 webmail，推荐
470−使用邮件客户端，比如 thunderbird，记得在设置中的回信配置那改为纯文本发送。
521+使用邮件客户端，比如 thunderbird，记得在设置的回信配置中改为纯文本发送。
471522
472−如果超过了 24 小时，您依旧没有在<https://lore.kernel.org/linux-doc/>发现您的
473−邮件，请联系您的网络管理员帮忙解决。
523+如果超过了 24 小时，您依旧没有在 https://lore.kernel.org/linux-doc/ 上找到您
524+的邮件，请联系您的网络管理员帮忙解决。
Documentation/translations/zh_CN/rust/arch-support.rst+1−0
@@ -23,6 +23,7 @@ · 22 unmodified lines
2323 ``arm64`` Maintained 仅小端序。
2424 ``loongarch`` Maintained \-
2525 ``riscv`` Maintained 仅 ``riscv64``，且仅限 LLVM/Clang。
26+``s390`` Maintained 必须禁用 ``CONFIG_EXPOLINE``。
2627 ``um`` Maintained \-
2728 ``x86`` Maintained 仅 ``x86_64``。
2829 ============= ================ ==============================================
Documentation/translations/zh_CN/rust/general-information.rst+79−3
@@ -13,6 +13,14 @@ · 12 unmodified lines
1313
1414 本文档包含了在内核中使用Rust支持时需要了解的有用信息。
1515
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+
1624 .. _rust_code_documentation_zh_cn:
1725
1826 代码文档
@@ -20,10 +28,18 @@ · 1 unmodified line
2028
2129 Rust内核代码使用其内置的文档生成器 ``rustdoc`` 进行记录。
2230
23−生成的HTML文档包括集成搜索、链接项（如类型、函数、常量）、源代码等。它们可以在以下地址阅读
24−（TODO：当在主线中时链接，与其他文档一起生成）：
31+生成的 HTML 文档包括集成搜索、链接项（如类型、函数、常量）、源代码等。
32+它们可以在以下地址阅读：
33+
34+ https://rust.docs.kernel.org
35+
36+对于 linux-next，请参阅：
2537
26− http://kernel.org/
38+ https://rust.docs.kernel.org/next/
39+
40+每个主要版本也有对应的标签，例如：
41+
42+ https://rust.docs.kernel.org/6.10/
2743
2844 这些文档也可以很容易地在本地生成和阅读。这相当快（与编译代码本身的顺序相同），而且不需要特
2945 殊的工具或环境。这有一个额外的好处，那就是它们将根据所使用的特定内核配置进行定制。要生成它
@@ -62,6 +78,58 @@ Rust内核代码使用其内置的文档生成器 ``rustdoc`` 进行记录。 · 32 unmodified lines
6278 模块（例如，驱动程序）不应该直接使用C语言的绑定。相反，子系统应该根据需要提供尽可能安
6379 全的抽象。
6480
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+
65133
66134 有条件的编译
67135 ------------
@@ -74,3 +142,11 @@ Rust代码可以访问基于内核配置的条件性编译: · 6 unmodified lines
74142 #[cfg(CONFIG_X="y")] // Enabled as a built-in (`y`)
75143 #[cfg(CONFIG_X="m")] // Enabled as a module (`m`)
76144 #[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
5959 Gentoo Linux
6060 ************
6161
62−Gentoo Linux（尤其是 testing 分支）提供较新的 Rust 版本，因此通常开箱即用，
62+Gentoo Linux 提供较新的 Rust 版本，因此通常开箱即用，
6363 例如::
6464
6565 USE='rust-src rustfmt clippy' emerge dev-lang/rust dev-util/bindgen
@@ -70,7 +70,7 @@ Gentoo Linux（尤其是 testing 分支）提供较新的 Rust 版本，因此 · 4 unmodified lines
7070 Nix
7171 ***
7272
73−Nix（unstable 频道）提供较新的 Rust 版本，因此通常开箱即用，例如::
73+Nix 提供较新的 Rust 版本，因此通常开箱即用，例如::
7474
7575 { pkgs ? import <nixpkgs> {} }:
7676 pkgs.mkShell {
@@ -85,16 +85,14 @@ openSUSE · 8 unmodified lines
8585 openSUSE Slowroll 和 openSUSE Tumbleweed 提供较新的 Rust 版本，因此通常开箱
8686 即用，例如::
8787
88− zypper install rust rust1.79-src rust-bindgen clang
88+ zypper install rust rust-src rust-bindgen clang
8989
9090
9191 Ubuntu
9292 ******
9393
94−25.04
95−~~~~~
96−
97−最新的 Ubuntu 版本提供较新的 Rust 版本，因此通常开箱即用，例如::
94+Ubuntu 25.10 和 26.04 LTS 提供较新的 Rust 版本，因此通常开箱即用，
95+例如::
9896
9997 apt install rustc rust-src bindgen rustfmt rust-clippy
10098
@@ -111,32 +109,32 @@ Ubuntu · 10 unmodified lines
111109 虽然 Ubuntu 24.04 LTS 及更早版本仍然提供较新的 Rust 版本，但它们需要一些额外的配
112110 置，使用带版本号的软件包，例如::
113111
114− apt install rustc-1.80 rust-1.80-src bindgen-0.65 rustfmt-1.80 \
115− rust-1.80-clippy
116− ln -s /usr/lib/rust-1.80/bin/rustfmt /usr/bin/rustfmt-1.80
117− ln -s /usr/lib/rust-1.80/bin/clippy-driver /usr/bin/clippy-driver-1.80
112+ apt install rustc-1.85 rust-1.85-src bindgen-0.71 rustfmt-1.85 \
113+ rust-1.85-clippy
114+ ln -s /usr/lib/rust-1.85/bin/rustfmt /usr/bin/rustfmt-1.85
115+ ln -s /usr/lib/rust-1.85/bin/clippy-driver /usr/bin/clippy-driver-1.85
118116
119117 这些软件包都不会将其工具设置为默认值；因此应该显式指定它们，例如::
120118
121− make LLVM=1 RUSTC=rustc-1.80 RUSTDOC=rustdoc-1.80 RUSTFMT=rustfmt-1.80 \
122− CLIPPY_DRIVER=clippy-driver-1.80 BINDGEN=bindgen-0.65
119+ make LLVM=1 RUSTC=rustc-1.85 RUSTDOC=rustdoc-1.85 RUSTFMT=rustfmt-1.85 \
120+ CLIPPY_DRIVER=clippy-driver-1.85 BINDGEN=bindgen-0.71
123121
124−或者，修改 ``PATH`` 变量将 Rust 1.80 的二进制文件放在前面，并将 ``bindgen`` 设
122+或者，修改 ``PATH`` 变量将 Rust 1.85 的二进制文件放在前面，并将 ``bindgen`` 设
125123 置为默认值，例如::
126124
127− PATH=/usr/lib/rust-1.80/bin:$PATH
125+ PATH=/usr/lib/rust-1.85/bin:$PATH
128126 update-alternatives --install /usr/bin/bindgen bindgen \
129− /usr/bin/bindgen-0.65 100
130− update-alternatives --set bindgen /usr/bin/bindgen-0.65
127+ /usr/bin/bindgen-0.71 100
128+ update-alternatives --set bindgen /usr/bin/bindgen-0.71
131129
132−使用带版本号的软件包时需要设置 ``RUST_LIB_SRC``，例如::
130+使用带版本号的软件包时可能需要设置 ``RUST_LIB_SRC``，例如::
133131
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
135133
136134 为方便起见，可以将 ``RUST_LIB_SRC`` 导出到全局环境中。
137135
138−此外， ``bindgen-0.65`` 在较新的版本（24.04 LTS 和 24.10）中可用，但在更早的版
139−本（20.04 LTS 和 22.04 LTS）中可能不可用，因此可能需要手动构建 ``bindgen``
136+此外， ``bindgen-0.71`` 在较新的版本（24.04 LTS）中可用，但在更早的版本
137+（20.04 LTS 和 22.04 LTS）中可能不可用，因此可能需要手动构建 ``bindgen``
140138 （请参见下文）。
141139
142140
@@ -325,11 +323,3 @@ Rust支持（CONFIG_RUST）需要在 ``General setup`` 菜单中启用。在其 · 182 unmodified lines
325323
326324 要想深入了解，请看 ``samples/rust/`` 下的样例源代码、 ``rust/`` 下的Rust支持代码和
327325 ``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
@@ -128,10 +128,13 @@ Rust 测试中常用的断言宏是来自 Rust 标准库（ ``core`` ）中的 ` · 127 unmodified lines
128128
129129 这些测试通过 ``kunit_tests`` 过程宏引入，该宏将测试套件的名称作为参数。
130130
131+每个测试套件都应该由 ``rust/kernel/Kconfig.test`` 中的 Kconfig 选项保护。
132+
131133 例如，假设想要测试前面文档测试示例中的函数 ``f``，我们可以在定义该函数的同一文件中编写：
132134
133135 .. code-block:: rust
134136
137+ #[cfg(CONFIG_RUST_MYMOD_KUNIT_TEST)]
135138 #[kunit_tests(rust_kernel_mymod)]
136139 mod tests {
137140 use super::*;
@@ -158,6 +161,7 @@ Rust 测试中常用的断言宏是来自 Rust 标准库（ ``core`` ）中的 ` · 20 unmodified lines
158161
159162 .. code-block:: rust
160163
164+ #[cfg(CONFIG_RUST_MYMOD_KUNIT_TEST)]
161165 #[kunit_tests(rust_kernel_mymod)]
162166 mod tests {
163167 use super::*;
Documentation/translations/zh_CN/scheduler/sched-energy.rst+1−1
@@ -119,7 +119,7 @@ EAS覆盖了CFS的任务唤醒平衡代码。在唤醒平衡时，它使用平 · 118 unmodified lines
119119
120120 如果唤醒的任务被迁移，find_energy_efficient_cpu()使用compute_energy()来估算
121121 系统将消耗多少能量。compute_energy()检查各CPU当前的利用率情况，并尝试调整来
122−“模拟”任务迁移。EM框架提供了API em_pd_energy()计算每个性能域在给定的利用率条件
122+“模拟”任务迁移。EM框架提供了API em_cpu_energy()计算每个性能域在给定的利用率条件
123123 下的预期能量消耗。
124124
125125 下面详细介绍一个优化能量消耗的任务放置决策的例子。
Documentation/translations/zh_CN/security/self-protection.rst+1−1
@@ -97,7 +97,7 @@ ARCH_OPTIONAL_KERNEL_RWX时的默认设置。 · 96 unmodified lines
9797 --------------------
9898
9999 对于64位系统，一种消除许多系统调用最简单的方法是构建时不启用
100−CONFIG_CONPAT。然而，这种情况通常不可行。
100+CONFIG_COMPAT。然而，这种情况通常不可行。
101101
102102 “seccomp”系统为用户空间提供了一种可选功能，提供了一种减少可供
103103 运行中进程使用内核入口点数量的方法。这限制了可以访问内核代码
Documentation/translations/zh_TW/process/stable-api-nonsense.rst+31−31
@@ -14,21 +14,21 @@ · 13 unmodified lines
1414 中文版校譯者： 李陽 Li Yang <leoyang.li@nxp.com>
1515 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn>
1616
17−Linux 內核驅動接口
17+Linux 內核驅動介面
1818 ==================
1919
20−寫作本文檔的目的，是爲了解釋爲什麼Linux既沒有二進制內核接口，也沒有穩定
21−的內核接口。這裏所說的內核接口，是指內核裏的接口，而不是內核和用戶空間
22−的接口。內核到用戶空間的接口，是提供給應用程序使用的系統調用，系統調用
20+寫作本文檔的目的，是爲了解釋爲什麼Linux既沒有二進制內核介面，也沒有穩定
21+的內核介面。這裏所說的內核介面，是指內核裏的介面，而不是內核和用戶空間
22+的介面。內核到用戶空間的介面，是提供給應用程序使用的系統調用，系統調用
2323 在歷史上幾乎沒有過變化，將來也不會有變化。我有一些老應用程序是在0.9版本
2424 或者更早版本的內核上編譯的，在使用2.6版本內核的Linux發佈上依然用得很好
25−。用戶和應用程序作者可以將這個接口看成是穩定的。
25+。用戶和應用程序作者可以將這個介面看成是穩定的。
2626
2727
2828 執行綱要
2929 --------
3030
31−你也許以爲自己想要穩定的內核接口，但是你不清楚你要的實際上不是它。你需
31+你也許以爲自己想要穩定的內核介面，但是你不清楚你要的實際上不是它。你需
3232 要的其實是穩定的驅動程序，而你只有將驅動程序放到公版內核的源代碼樹裏，
3333 纔有可能達到這個目的。而且這樣做還有很多其它好處，正是因爲這些好處使得
3434 Linux能成爲強壯，穩定，成熟的操作系統，這也是你最開始選擇Linux的原因。
@@ -37,8 +37,8 @@ Linux能成爲強壯，穩定，成熟的操作系統，這也是你最開始選 · 2 unmodified lines
3737 入門
3838 -----
3939
40−只有那些寫驅動程序的“怪人”纔會擔心內核接口的改變，對廣大用戶來說，既
41−看不到內核接口，也不需要去關心它。
40+只有那些寫驅動程序的“怪人”纔會擔心內核介面的改變，對廣大用戶來說，既
41+看不到內核介面，也不需要去關心它。
4242
4343 首先，我不打算討論關於任何非GPL許可的內核驅動的法律問題，這些非GPL許可
4444 的驅動程序包括不公開源代碼，隱藏源代碼，二進制或者是用源代碼包裝，或者
@@ -46,14 +46,14 @@ Linux能成爲強壯，穩定，成熟的操作系統，這也是你最開始選 · 1 unmodified line
4646 詢律師，我只是一個程序員，所以我只打算探討技術問題（不是小看法律問題，
4747 法律問題很實際，並且需要一直關注）。
4848
49−既然只談技術問題，我們就有了下面兩個主題：二進制內核接口和穩定的內核源
50−代碼接口。這兩個問題是互相關聯的，讓我們先解決掉二進制接口的問題。
49+既然只談技術問題，我們就有了下面兩個主題：二進制內核介面和穩定的內核源
50+代碼介面。這兩個問題是互相關聯的，讓我們先解決掉二進制介面的問題。
5151
5252
53−二進制內核接口
53+二進制內核介面
5454 --------------
55−假如我們有一個穩定的內核源代碼接口，那麼自然而然的，我們就擁有了穩定的
56−二進制接口，是這樣的嗎？錯。讓我們看看關於Linux內核的幾點事實：
55+假如我們有一個穩定的內核源代碼介面，那麼自然而然的，我們就擁有了穩定的
56+二進制介面，是這樣的嗎？錯。讓我們看看關於Linux內核的幾點事實：
5757
5858 - 取決於所用的C編譯器的版本，不同的內核數據結構裏的結構體的對齊方
5959 式會有差別，代碼中不同函數的表現形式也不一樣（函數是不是被inline
@@ -84,18 +84,18 @@ Linux能成爲強壯，穩定，成熟的操作系統，這也是你最開始選 · 24 unmodified lines
8484 深刻的教訓...
8585
8686
87−穩定的內核源代碼接口
87+穩定的內核源代碼介面
8888 --------------------
8989
9090 如果有人不將他的內核驅動程序，放入公版內核的源代碼樹，而又想讓驅動程序
9191 一直保持在最新的內核中可用，那麼這個話題將會變得沒完沒了。
92−內核開發是持續而且快節奏的，從來都不會慢下來。內核開發人員在當前接口中
92+內核開發是持續而且快節奏的，從來都不會慢下來。內核開發人員在當前介面中
9393 找到bug，或者找到更好的實現方式。一旦發現這些，他們就很快會去修改當前的
94−接口。修改接口意味着，函數名可能會改變，結構體可能被擴充或者刪減，函數
95−的參數也可能發生改變。一旦接口被修改，內核中使用這些接口的地方需要同時
94+介面。修改介面意味着，函數名可能會改變，結構體可能被擴充或者刪減，函數
95+的參數也可能發生改變。一旦介面被修改，內核中使用這些介面的地方需要同時
9696 修正，這樣才能保證所有的東西繼續工作。
9797
98−舉一個例子，內核的USB驅動程序接口在USB子系統的整個生命週期中，至少經歷
98+舉一個例子，內核的USB驅動程序介面在USB子系統的整個生命週期中，至少經歷
9999 了三次重寫。這些重寫解決以下問題：
100100
101101 - 把數據流從同步模式改成非同步模式，這個改動減少了一些驅動程序的
@@ -105,22 +105,22 @@ Linux能成爲強壯，穩定，成熟的操作系統，這也是你最開始選 · 3 unmodified lines
105105 需要提供更多的參數給USB核心，以修正了很多已經被記錄在案的死鎖。
106106
107107 這和一些封閉源代碼的操作系統形成鮮明的對比，在那些操作系統上，不得不額
108−外的維護舊的USB接口。這導致了一個可能性，新的開發者依然會不小心使用舊的
109−接口，以不恰當的方式編寫代碼，進而影響到操作系統的穩定性。
108+外的維護舊的USB介面。這導致了一個可能性，新的開發者依然會不小心使用舊的
109+介面，以不恰當的方式編寫代碼，進而影響到操作系統的穩定性。
110110 在上面的例子中，所有的開發者都同意這些重要的改動，在這樣的情況下修改代
111−價很低。如果Linux保持一個穩定的內核源代碼接口，那麼就得創建一個新的接口
112−；舊的，有問題的接口必須一直維護，給Linux USB開發者帶來額外的工作。既然
111+價很低。如果Linux保持一個穩定的內核源代碼介面，那麼就得創建一個新的介面
112+；舊的，有問題的介面必須一直維護，給Linux USB開發者帶來額外的工作。既然
113113 所有的Linux USB驅動的作者都是利用自己的時間工作，那麼要求他們去做毫無意
114114 義的免費額外工作，是不可能的。
115115 安全問題對Linux來說十分重要。一個安全問題被發現，就會在短時間內得到修
116−正。在很多情況下，這將導致Linux內核中的一些接口被重寫，以從根本上避免安
117−全問題。一旦接口被重寫，所有使用這些接口的驅動程序，必須同時得到修正，
116+正。在很多情況下，這將導致Linux內核中的一些介面被重寫，以從根本上避免安
117+全問題。一旦介面被重寫，所有使用這些介面的驅動程序，必須同時得到修正，
118118 以確定安全問題已經得到修復並且不可能在未來還有同樣的安全問題。如果內核
119−內部接口不允許改變，那麼就不可能修復這樣的安全問題，也不可能確認這樣的
119+內部介面不允許改變，那麼就不可能修復這樣的安全問題，也不可能確認這樣的
120120 安全問題以後不會發生。
121−開發者一直在清理內核接口。如果一個接口沒有人在使用了，它就會被刪除。這
122−樣可以確保內核儘可能的小，而且所有潛在的接口都會得到儘可能完整的測試
123−（沒有人使用的接口是不可能得到良好的測試的）。
121+開發者一直在清理內核介面。如果一個介面沒有人在使用了，它就會被刪除。這
122+樣可以確保內核儘可能的小，而且所有潛在的介面都會得到儘可能完整的測試
123+（沒有人使用的介面是不可能得到良好的測試的）。
124124
125125
126126 要做什麼
@@ -128,11 +128,11 @@ Linux能成爲強壯，穩定，成熟的操作系統，這也是你最開始選 · 1 unmodified line
128128
129129 如果你寫了一個Linux內核驅動，但是它還不在Linux源代碼樹裏，作爲一個開發
130130 者，你應該怎麼做？爲每個發佈的每個版本提供一個二進制驅動，那簡直是一個
131−噩夢，要跟上永遠處於變化之中的內核接口，也是一件辛苦活。
131+噩夢，要跟上永遠處於變化之中的內核介面，也是一件辛苦活。
132132 很簡單，讓你的驅動進入內核源代碼樹（要記得我們在談論的是以GPL許可發行
133133 的驅動，如果你的代碼不符合GPL，那麼祝你好運，你只能自己解決這個問題了，
134134 你這個吸血鬼<把Andrew和Linus對吸血鬼的定義鏈接到這裏>）。當你的代碼加入
135−公版內核源代碼樹之後，如果一個內核接口改變，你的驅動會直接被修改接口的
135+公版內核源代碼樹之後，如果一個內核介面改變，你的驅動會直接被修改介面的
136136 那個人修改。保證你的驅動永遠都可以編譯通過，並且一直工作，你幾乎不需要
137137 做什麼事情。
138138
@@ -142,7 +142,7 @@ Linux能成爲強壯，穩定，成熟的操作系統，這也是你最開始選 · 3 unmodified lines
142142 - 其他人會給驅動添加新特性。
143143 - 其他人會找到驅動中的bug並修復。
144144 - 其他人會在驅動中找到性能優化的機會。
145− - 當外部的接口的改變需要修改驅動程序的時候，其他人會修改驅動程序
145+ - 當外部的介面的改變需要修改驅動程序的時候，其他人會修改驅動程序
146146 - 不需要聯繫任何發行商，這個驅動會自動的隨着所有的Linux發佈一起發
147147 布。
148148
MAINTAINERS+4−3
@@ -7738,6 +7738,7 @@ F: include/linux/dmi.h · 7737 unmodified lines
77387738 DOCUMENTATION
77397739 M: Jonathan Corbet <corbet@lwn.net>
77407740 R: Shuah Khan <skhan@linuxfoundation.org>
7741+R: Randy Dunlap <rdunlap@infradead.org>
77417742 L: linux-doc@vger.kernel.org
77427743 S: Maintained
77437744 P: Documentation/doc-guide/maintainer-profile.rst
@@ -27569,10 +27570,10 @@ F: kernel/trace/trace_osnoise.c · 19825 unmodified lines
2756927570 F: kernel/trace/trace_sched_wakeup.c
2757027571
2757127572 TRADITIONAL CHINESE DOCUMENTATION
27572−M: Hu Haowen <2023002089@link.tyut.edu.cn>
27573+M: Chen-Yu Yeh <chenyou910331@gmail.com>
27574+M: Weijie Yuan <wy@wyuan.org>
27575+M: Dongliang Mu <dzm91@hust.edu.cn>
2757327576 S: Maintained
27574−W: https://github.com/srcres258/linux-doc
27575−T: git https://github.com/srcres258/linux-doc.git doc-zh-tw
2757627577 F: Documentation/translations/zh_TW/
2757727578
2757827579 TRIGGER SOURCE
README+9−9
@@ -30,15 +30,15 @@ Who Are You? · 29 unmodified lines
3030
3131 Find your role below:
3232
33−* New Kernel Developer - Getting started with kernel development
34−* Academic Researcher - Studying kernel internals and architecture
35−* Security Expert - Hardening and vulnerability analysis
36−* Backport/Maintenance Engineer - Maintaining stable kernels
37−* System Administrator - Configuring and troubleshooting
38−* Maintainer - Leading subsystems and reviewing patches
39−* Hardware Vendor - Writing drivers for new hardware
40−* Distribution Maintainer - Packaging kernels for distros
41−* AI Coding Assistant - LLMs and AI-powered development tools
33+* New Kernel Developer: Getting started with kernel development
34+* Academic Researcher: Studying kernel internals and architecture
35+* Security Expert: Hardening and vulnerability analysis
36+* Backport/Maintenance Engineer: Maintaining stable kernels
37+* System Administrator: Configuring and troubleshooting
38+* Maintainer: Leading subsystems and reviewing patches
39+* Hardware Vendor: Writing drivers for new hardware
40+* Distribution Maintainer: Packaging kernels for distros
41+* AI Coding Assistant: LLMs and AI-powered development tools
4242
4343
4444 For Specific Users
scripts/checkpatch.pl+4−3
@@ -3124,11 +3124,12 @@ sub process { · 3123 unmodified lines
31243124 }
31253125 }
31263126
3127− # Assisted-by uses AGENT_NAME:MODEL_VERSION format, not email
3127+ # Assisted-by uses a free-form value (e.g. "LLM"), not an
3128+ # email address, so skip the email format checks below.
31283129 if ($sign_off =~ /^Assisted-by:/i) {
3129− if ($email !~ /^\S+:\S+/) {
3130+ if ($email =~ /^\s*$/) {
31303131 WARN("BAD_SIGN_OFF",
3131− "Assisted-by expects 'AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2]' format\n" . $herecurr);
3132+ "Assisted-by requires a value\n" . $herecurr);
31323133 }
31333134 next;
31343135 }
tools/docs/documentation-file-ref-check+1−1
@@ -143,7 +143,7 @@ while (<IN>) { · 142 unmodified lines
143143 # Check if exists, evaluating wildcards
144144 next if (grep -e, glob("$ref $fulref"));
145145
146− # Accept relative Documentation patches for tools/
146+ # Accept relative Documentation paths for tools/
147147 if ($f =~ m/tools/) {
148148 my $path = $f;
149149 $path =~ s,(.*)/.*,$1,;
tools/docs/sphinx-build-wrapper+11−2
@@ -99,9 +99,9 @@ class SphinxBuilder: · 98 unmodified lines
9999
100100 def get_path(self, path, use_cwd=False, abs_path=False):
101101 """
102− Ancillary routine to handle patches the right way, as shell does.
102+ Ancillary routine to handle paths the right way, as shell does.
103103
104− It first expands "~" and "~user". Then, if patch is not absolute,
104+ It first expands "~" and "~user". Then, if path is not absolute,
105105 join self.srctree. Finally, if requested, convert to abspath.
106106 """
107107
@@ -219,6 +219,15 @@ class SphinxBuilder: · 111 unmodified lines
219219 self.kernelrelease = os.environ.get("KERNELRELEASE", "unknown")
220220 self.pdflatex = os.environ.get("PDFLATEX", "xelatex")
221221
222+ #
223+ # Add localversion* to kernelversion if present
224+ #
225+ for file in glob(os.environ["srctree"] + "/localversion*"):
226+ if not file.endswith(".orig"):
227+ with open(file, 'r', encoding='utf-8') as f:
228+ text = f.read()
229+ self.kernelversion += text
230+
222231 #
223232 # Kernel main Makefile defines a PYTHON3 variable whose default is
224233 # "python3". When set to a different value, it allows running a
tools/lib/python/abi/abi_regex.py+5−6
@@ -65,8 +65,7 @@ class AbiRegex(AbiParser): · 64 unmodified lines
6565 (re.compile(r"\[[^\]]+\]"), "\\\\w\xf7"),
6666
6767 (re.compile(r"XX+"), "\\\\w\xf7"),
68− (re.compile(r"([^A-Z])[XYZ]([^A-Z])"), "\\1\\\\w\xf7\\2"),
69− (re.compile(r"([^A-Z])[XYZ]$"), "\\1\\\\w\xf7"),
68+ (re.compile(r"(?<![A-Z])[XYZ](?![A-Z])"), "\\\\w\xf7"),
7069 (re.compile(r"_[AB]_"), "_\\\\w\xf7_"),
7170
7271 # Recover [0-9] type of patterns
@@ -155,7 +154,7 @@ class AbiRegex(AbiParser): · 82 unmodified lines
155154 if self.search_string:
156155 if what.find(self.search_string) >= 0:
157156 print(f"What: {what}")
158− except re.PatternError:
157+ except re.error:
159158 self.log.warning("Ignoring '%s' as it produced an invalid regex:\n"
160159 " '%s'", what, new)
161160
@@ -194,7 +193,7 @@ class AbiRegex(AbiParser): · 32 unmodified lines
194193
195194 try:
196195 self.re_string = re.compile(self.search_string)
197− except re.PatternError as e:
196+ except re.error as e:
198197 msg = f"{self.search_string} is not a valid regular expression"
199198 raise ValueError(msg) from e
200199
@@ -223,9 +222,9 @@ class AbiRegex(AbiParser): · 22 unmodified lines
223222 for r, s in self.re_whats:
224223 try:
225224 new = r.sub(s, new)
226− except re.PatternError as e:
225+ except re.error as e:
227226 # Help debugging troubles with new regexes
228− raise re.PatternError(f"{e}\nwhile re.sub('{r.pattern}', {s}, str)") from e
227+ raise re.error(f"{e}\nwhile re.sub('{r.pattern}', {s}, str)") from e
229228
230229 v["regex"].append(new)
231230
tools/lib/python/kdoc/kdoc_output.py+1−1
@@ -624,7 +624,7 @@ class ManFormat(OutputFormat): · 623 unmodified lines
624624 ``manual``
625625 Defaults to ``Kernel API Manual``.
626626
627− The above controls the output of teh corresponding fields on troff
627+ The above controls the output of the corresponding fields on troff
628628 title headers, which will be filled like this::
629629
630630 .TH "{name}" {section} "{date}" "{modulename}" "{manual}"
tools/lib/python/kdoc/kdoc_parser.py+53−5
@@ -11,6 +11,7 @@ and extract embedded documentation comments from it. · 10 unmodified lines
1111
1212 import sys
1313 import re
14+import difflib
1415 from pprint import pformat
1516
1617 from kdoc.c_lex import CTokenizer, tokenizer_set_log
@@ -558,6 +559,51 @@ class KernelDoc: · 541 unmodified lines
558559 self.push_parameter(ln, decl_type, param, dtype,
559560 arg, declaration_name)
560561
562+ def get_suggestions_hint(self, decl_name, possible_names):
563+ # For decl name 'flags' or 'flgas', suggests 'substruct.flags'
564+ submember_exact = []
565+ submember_substrings = []
566+ submember_suggestions = []
567+ for possible_name in possible_names:
568+ parts = possible_name.strip().split('.')
569+ if len(parts) < 2:
570+ continue
571+
572+ final_part = parts[-1]
573+ if decl_name == final_part:
574+ submember_exact.append(possible_name)
575+ elif decl_name in final_part:
576+ submember_substrings.append(possible_name)
577+ elif difflib.get_close_matches(decl_name, [final_part]):
578+ submember_suggestions.append(possible_name)
579+
580+ # For decl name 'flgas', suggests 'flags'
581+ full_suggestions = difflib.get_close_matches(decl_name, possible_names)
582+
583+ # For decl name 'member', suggests 'longer_member'
584+ full_substrings = [name for name in possible_names if decl_name in name]
585+
586+ ordered_lists = [
587+ submember_exact,
588+ submember_substrings,
589+ submember_suggestions,
590+ full_suggestions,
591+ full_substrings,
592+ ]
593+
594+ # Deduplicate but maintain order from most to least likely:
595+ unique_suggestions = {}
596+ for suggestion_list in ordered_lists:
597+ for suggestion in suggestion_list:
598+ unique_suggestions[suggestion] = None
599+
600+ suggestions = list(unique_suggestions.keys())
601+ if not suggestions:
602+ return ""
603+
604+ joined_suggestions = "', '".join(suggestions)
605+ return f"(did you mean one of: '{joined_suggestions}')"
606+
561607 def check_sections(self, ln, decl_name, decl_type):
562608 """
563609 Check for errors inside sections, emitting warnings if not found
@@ -566,12 +612,13 @@ class KernelDoc: · 2 unmodified lines
566612 for section in self.entry.sections:
567613 if section not in self.entry.parameterlist and \
568614 not known_sections.search(section):
615+ hint = self.get_suggestions_hint(section, self.entry.parameterlist)
569616 if decl_type == 'function':
570617 dname = f"{decl_type} parameter"
571618 else:
572619 dname = f"{decl_type} member"
573620 self.emit_msg(ln,
574− f"Excess {dname} '{section}' description in '{decl_name}'")
621+ f"Excess {dname} '{section}' description in '{decl_name}' {hint}".strip())
575622
576623 #
577624 # Check that documented parameter names (from doc comments, including
@@ -591,12 +638,13 @@ class KernelDoc: · 13 unmodified lines
591638 if param_name in self.entry.parameterlist:
592639 continue
593640
641+ hint = self.get_suggestions_hint(param_name, self.entry.parameterlist)
594642 if decl_type == 'function':
595643 dname = f"{decl_type} parameter"
596644 else:
597645 dname = f"{decl_type} member"
598646 self.emit_msg(ln,
599− f"Excess {dname} '{param_name}' description in '{decl_name}'")
647+ f"Excess {dname} '{param_name}' description in '{decl_name}' {hint}".strip())
600648
601649 def check_return_section(self, ln, declaration_name, return_type):
602650 """
@@ -791,7 +839,7 @@ class KernelDoc: · 188 unmodified lines
791839
792840 if self.entry.identifier != declaration_name:
793841 self.emit_msg(ln, f"expecting prototype for {decl_type} {self.entry.identifier}. "
794− f"Prototype was for {decl_type} {declaration_name} instead\n")
842+ f"Prototype was for {decl_type} {declaration_name} instead")
795843 return
796844 #
797845 # Go through the list of members applying all of our transformations.
@@ -1108,7 +1156,7 @@ class KernelDoc: · 310 unmodified lines
11081156
11091157 if self.entry.identifier != declaration_name:
11101158 self.emit_msg(ln,
1111− f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead\n")
1159+ f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead")
11121160 return
11131161
11141162 self.create_parameter_list(ln, 'function', args, ',', declaration_name)
@@ -1128,7 +1176,7 @@ class KernelDoc: · 13 unmodified lines
11281176
11291177 if self.entry.identifier != declaration_name:
11301178 self.emit_msg(ln,
1131− f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead\n")
1179+ f"expecting prototype for typedef {self.entry.identifier}. Prototype was for typedef {declaration_name} instead")
11321180 return
11331181
11341182 self.output_declaration('typedef', declaration_name,
tools/lib/python/kdoc/xforms_lists.py+1−0
@@ -90,6 +90,7 @@ class CTransforms: · 89 unmodified lines
9090 (CMatch("__(?:re)?alloc_size"), ""),
9191 (CMatch("__diagnose_as"), ""),
9292 (CMatch("DECL_BUCKET_PARAMS"), r"\1, \2"),
93+ (CMatch("DEFINE_IDTENTRY_IRQ"), r"static void \1(struct pt_regs *regs, u32 vector)"),
9394 (CMatch("__cond_acquires"), ""),
9495 (CMatch("__cond_releases"), ""),
9596 (CMatch("__acquires"), ""),