diff options
| author | Linus Torvalds <torvalds@linux-foundation.org> | 2021-04-26 13:22:43 -0700 |
|---|---|---|
| committer | Linus Torvalds <torvalds@linux-foundation.org> | 2021-04-26 13:22:43 -0700 |
| commit | 2f9ef0559efbee18a10a3ca26eefe57f69918693 (patch) | |
| tree | 3c30d105078c06b51de764e703a59f6ae1c2bb5a | |
| parent | 0c855563182001c829065faa17f8e29e9ceffe13 (diff) | |
| parent | 441ca977a84dadac6173db7c07c25db110b76c1e (diff) | |
Merge tag 'docs-5.13' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet:
"It's been a relatively busy cycle in docsland, though more than
usually well contained to Documentation/ itself. Highlights include:
- The Chinese translators have been busy and show no signs of
stopping anytime soon. Italian has also caught up.
- Aditya Srivastava has been working on improvements to the
kernel-doc script.
- Thorsten continues his work on reporting-issues.rst and related
documentation around regression reporting.
- Lots of documentation updates, typo fixes, etc. as usual"
* tag 'docs-5.13' of git://git.lwn.net/linux: (139 commits)
docs/zh_CN: add openrisc translation to zh_CN index
docs/zh_CN: add openrisc index.rst translation
docs/zh_CN: add openrisc todo.rst translation
docs/zh_CN: add openrisc openrisc_port.rst translation
docs/zh_CN: add core api translation to zh_CN index
docs/zh_CN: add core-api index.rst translation
docs/zh_CN: add core-api irq index.rst translation
docs/zh_CN: add core-api irq irqflags-tracing.rst translation
docs/zh_CN: add core-api irq irq-domain.rst translation
docs/zh_CN: add core-api irq irq-affinity.rst translation
docs/zh_CN: add core-api irq concepts.rst translation
docs: sphinx-pre-install: don't barf on beta Sphinx releases
scripts: kernel-doc: improve parsing for kernel-doc comments syntax
docs/zh_CN: two minor fixes in zh_CN/doc-guide/
Documentation: dev-tools: Add Testing Overview
docs/zh_CN: add translations in zh_CN/dev-tools/gcov
docs: reporting-issues: make people CC the regressions list
MAINTAINERS: add regressions mailing list
doc:it_IT: align Italian documentation
docs/zh_CN: sync reporting-issues.rst
...
133 files changed, 9868 insertions, 2059 deletions
@@ -25,8 +25,9 @@ Alexandre Belloni <alexandre.belloni@bootlin.com> <alexandre.belloni@free-electr Alexei Starovoitov <ast@kernel.org> <alexei.starovoitov@gmail.com> Alexei Starovoitov <ast@kernel.org> <ast@fb.com> Alexei Starovoitov <ast@kernel.org> <ast@plumgrid.com> -Alex Shi <alex.shi@linux.alibaba.com> <alex.shi@intel.com> -Alex Shi <alex.shi@linux.alibaba.com> <alex.shi@linaro.org> +Alex Shi <alexs@kernel.org> <alex.shi@intel.com> +Alex Shi <alexs@kernel.org> <alex.shi@linaro.org> +Alex Shi <alexs@kernel.org> <alex.shi@linux.alibaba.com> Al Viro <viro@ftp.linux.org.uk> Al Viro <viro@zenIV.linux.org.uk> Andi Kleen <ak@linux.intel.com> <ak@suse.de> @@ -550,7 +550,7 @@ D: gadget layers, SPI subsystem, GPIO subsystem, and more than a few D: device drivers. His encouragement also helped many engineers get D: started working on the Linux kernel. David passed away in early D: 2011, and will be greatly missed. -W: https://lkml.org/lkml/2011/4/5/36 +W: https://lore.kernel.org/lkml/20110405034819.GA7872@kroah.com N: Gary Brubaker E: xavyer@ix.netcom.com diff --git a/Documentation/admin-guide/LSM/LoadPin.rst b/Documentation/admin-guide/LSM/LoadPin.rst index 716ad9b23c9a..dd3ca68b5df1 100644 --- a/Documentation/admin-guide/LSM/LoadPin.rst +++ b/Documentation/admin-guide/LSM/LoadPin.rst @@ -11,8 +11,8 @@ restrictions without needing to sign the files individually. The LSM is selectable at build-time with ``CONFIG_SECURITY_LOADPIN``, and can be controlled at boot-time with the kernel command line option -"``loadpin.enabled``". By default, it is enabled, but can be disabled at -boot ("``loadpin.enabled=0``"). +"``loadpin.enforce``". By default, it is enabled, but can be disabled at +boot ("``loadpin.enforce=0``"). LoadPin starts pinning when it sees the first file loaded. If the block device backing the filesystem is not read-only, a sysctl is @@ -28,4 +28,4 @@ different mechanisms such as ``CONFIG_MODULE_SIG`` and ``CONFIG_KEXEC_VERIFY_SIG`` to verify kernel module and kernel image while still use LoadPin to protect the integrity of other files kernel loads. The full list of valid file types can be found in ``kernel_read_file_str`` -defined in ``include/linux/fs.h``. +defined in ``include/linux/kernel_read_file.h``. diff --git a/Documentation/admin-guide/cgroup-v1/memory.rst b/Documentation/admin-guide/cgroup-v1/memory.rst index 0936412e044e..41191b5fb69d 100644 --- a/Documentation/admin-guide/cgroup-v1/memory.rst +++ b/Documentation/admin-guide/cgroup-v1/memory.rst @@ -360,8 +360,8 @@ U != 0, K = unlimited: U != 0, K < U: Kernel memory is a subset of the user memory. This setup is useful in - deployments where the total amount of memory per-cgroup is overcommited. - Overcommiting kernel memory limits is definitely not recommended, since the + deployments where the total amount of memory per-cgroup is overcommitted. + Overcommitting kernel memory limits is definitely not recommended, since the box can still run out of non-reclaimable memory. In this case, the admin could set up K so that the sum of all groups is never greater than the total memory, and freely set U at the cost of his @@ -851,6 +851,9 @@ At reading, current status of OOM is shown. (if 1, oom-killer is disabled) - under_oom 0 or 1 (if 1, the memory cgroup is under OOM, tasks may be stopped.) + - oom_kill integer counter + The number of processes belonging to this cgroup killed by any + kind of OOM killer. 11. Memory Pressure =================== diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst index 6c04aea8f4cd..b119b8277b3e 100644 --- a/Documentation/admin-guide/dynamic-debug-howto.rst +++ b/Documentation/admin-guide/dynamic-debug-howto.rst @@ -347,7 +347,7 @@ Examples <debugfs>/dynamic_debug/control // enable messages in files of which the paths include string "usb" - nullarbor:~ # echo -n '*usb* +p' > <debugfs>/dynamic_debug/control + nullarbor:~ # echo -n 'file *usb* +p' > <debugfs>/dynamic_debug/control // enable all messages nullarbor:~ # echo -n '+p' > <debugfs>/dynamic_debug/control diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 423116c4e787..dc00afcabb95 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -35,7 +35,6 @@ problems and bugs in particular. :maxdepth: 1 reporting-issues - Reporting bugs (obsolete) <reporting-bugs> security-bugs bug-hunting bug-bisect diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst index 1132796a8d96..24302cad174a 100644 --- a/Documentation/admin-guide/kernel-parameters.rst +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -140,6 +140,7 @@ parameter is applicable:: PPT Parallel port support is enabled. PS2 Appropriate PS/2 support is enabled. RAM RAM disk support is enabled. + RISCV RISCV architecture is enabled. RDT Intel Resource Director Technology. S390 S390 architecture is enabled. SCSI Appropriate SCSI support is enabled. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 9b3c086d4266..550cf2b2b7e8 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -3471,7 +3471,8 @@ nr_uarts= [SERIAL] maximum number of UARTs to be registered. - numa_balancing= [KNL,X86] Enable or disable automatic NUMA balancing. + numa_balancing= [KNL,ARM64,PPC,RISCV,S390,X86] Enable or disable automatic + NUMA balancing. Allowed values are enable and disable numa_zonelist_order= [KNL, BOOT] Select zonelist order for NUMA. diff --git a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst index 531f689311f2..5e51ee5b0358 100644 --- a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst +++ b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst @@ -332,23 +332,3 @@ To reduce its OS jitter, do at least one of the following: kthreads from being created in the first place. However, please note that this will not eliminate OS jitter, but will instead shift it to RCU_SOFTIRQ. - -Name: - watchdog/%u - -Purpose: - Detect software lockups on each CPU. - -To reduce its OS jitter, do at least one of the following: - -1. Build with CONFIG_LOCKUP_DETECTOR=n, which will prevent these - kthreads from being created in the first place. -2. Boot with "nosoftlockup=0", which will also prevent these kthreads - from being created. Other related watchdog and softlockup boot - parameters may be found in Documentation/admin-guide/kernel-parameters.rst - and Documentation/watchdog/watchdog-parameters.rst. -3. Echo a zero to /proc/sys/kernel/watchdog to disable the - watchdog timer. -4. Echo a large number of /proc/sys/kernel/watchdog_thresh in - order to reduce the frequency of OS jitter due to the watchdog - timer down to a level that is acceptable for your workload. diff --git a/Documentation/admin-guide/mm/numaperf.rst b/Documentation/admin-guide/mm/numaperf.rst index c2f826409bf0..166697325947 100644 --- a/Documentation/admin-guide/mm/numaperf.rst +++ b/Documentation/admin-guide/mm/numaperf.rst @@ -151,7 +151,7 @@ Each cache level's directory provides its attributes. For example, the following shows a single cache level and the attributes available for software to query:: - # tree sys/devices/system/node/node0/memory_side_cache/ + # tree /sys/devices/system/node/node0/memory_side_cache/ /sys/devices/system/node/node0/memory_side_cache/ |-- index1 | |-- indexing diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst deleted file mode 100644 index 409fa91d7495..000000000000 --- a/Documentation/admin-guide/reporting-bugs.rst +++ /dev/null @@ -1,187 +0,0 @@ -.. _reportingbugs: - -.. note:: - - This document is obsolete, and will be replaced by - 'Documentation/admin-guide/reporting-issues.rst' in the near future. - -Reporting bugs -++++++++++++++ - -Background -========== - -The upstream Linux kernel maintainers only fix bugs for specific kernel -versions. Those versions include the current "release candidate" (or -rc) -kernel, any "stable" kernel versions, and any "long term" kernels. - -Please see https://www.kernel.org/ for a list of supported kernels. Any -kernel marked with [EOL] is "end of life" and will not have any fixes -backported to it. - -If you've found a bug on a kernel version that isn't listed on kernel.org, -contact your Linux distribution or embedded vendor for support. -Alternatively, you can attempt to run one of the supported stable or -rc -kernels, and see if you can reproduce the bug on that. It's preferable -to reproduce the bug on the latest -rc kernel. - - -How to report Linux kernel bugs -=============================== - - -Identify the problematic subsystem ----------------------------------- - -Identifying which part of the Linux kernel might be causing your issue -increases your chances of getting your bug fixed. Simply posting to the -generic linux-kernel mailing list (LKML) may cause your bug report to be -lost in the noise of a mailing list that gets 1000+ emails a day. - -Instead, try to figure out which kernel subsystem is causing the issue, -and email that subsystem's maintainer and mailing list. If the subsystem -maintainer doesn't answer, then expand your scope to mailing lists like -LKML. - - -Identify who to notify ----------------------- - -Once you know the subsystem that is causing the issue, you should send a -bug report. Some maintainers prefer bugs to be reported via bugzilla -(https://bugzilla.kernel.org), while others prefer that bugs be reported -via the subsystem mailing list. - -To find out where to send an emailed bug report, find your subsystem or -device driver in the MAINTAINERS file. Search in the file for relevant -entries, and send your bug report to the person(s) listed in the "M:" -lines, making sure to Cc the mailing list(s) in the "L:" lines. When the -maintainer replies to you, make sure to 'Reply-all' in order to keep the -public mailing list(s) in the email thread. - -If you know which driver is causing issues, you can pass one of the driver -files to the get_maintainer.pl script:: - - perl scripts/get_maintainer.pl -f <filename> - -If it is a security bug, please copy the Security Contact listed in the -MAINTAINERS file. They can help coordinate bugfix and disclosure. See -:ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>` for more information. - -If you can't figure out which subsystem caused the issue, you should file -a bug in kernel.org bugzilla and send email to -linux-kernel@vger.kernel.org, referencing the bugzilla URL. (For more -information on the linux-kernel mailing list see -http://vger.kernel.org/lkml/). - - -Tips for reporting bugs ------------------------ - -If you haven't reported a bug before, please read: - - https://www.chiark.greenend.org.uk/~sgtatham/bugs.html - - http://www.catb.org/esr/faqs/smart-questions.html - -It's REALLY important to report bugs that seem unrelated as separate email -threads or separate bugzilla entries. If you report several unrelated -bugs at once, it's difficult for maintainers to tease apart the relevant -data. - - -Gather information ------------------- - -The most important information in a bug report is how to reproduce the -bug. This includes system information, and (most importantly) -step-by-step instructions for how a user can trigger the bug. - -If the failure includes an "OOPS:", take a picture of the screen, capture -a netconsole trace, or type the message from your screen into the bug -report. Please read "Documentation/admin-guide/bug-hunting.rst" before posting your -bug report. This explains what you should do with the "Oops" information -to make it useful to the recipient. - -This is a suggested format for a bug report sent via email or bugzilla. -Having a standardized bug report form makes it easier for you not to -overlook things, and easier for the developers to find the pieces of -information they're really interested in. If some information is not -relevant to your bug, feel free to exclude it. - -First run the ver_linux script included as scripts/ver_linux, which -reports the version of some important subsystems. Run this script with -the command ``awk -f scripts/ver_linux``. - -Use that information to fill in all fields of the bug report form, and -post it to the mailing list with a subject of "PROBLEM: <one line -summary from [1.]>" for easy identification by the developers:: - - [1.] One line summary of the problem: - [2.] Full description of the problem/report: - [3.] Keywords (i.e., modules, networking, kernel): - [4.] Kernel information - [4.1.] Kernel version (from /proc/version): - [4.2.] Kernel .config file: - [5.] Most recent kernel version which did not have the bug: - [6.] Output of Oops.. message (if applicable) with symbolic information - resolved (see Documentation/admin-guide/bug-hunting.rst) - [7.] A small shell script or example program which triggers the - problem (if possible) - [8.] Environment - [8.1.] Software (add the output of the ver_linux script here) - [8.2.] Processor information (from /proc/cpuinfo): - [8.3.] Module information (from /proc/modules): - [8.4.] Loaded driver and hardware information (/proc/ioports, /proc/iomem) - [8.5.] PCI information ('lspci -vvv' as root) - [8.6.] SCSI information (from /proc/scsi/scsi) - [8.7.] Other information that might be relevant to the problem - (please look in /proc and include all information that you - think to be relevant): - [X.] Other notes, patches, fixes, workarounds: - - -Follow up -========= - -Expectations for bug reporters ------------------------------- - -Linux kernel maintainers expect bug reporters to be able to follow up on -bug reports. That may include running new tests, applying patches, -recompiling your kernel, and/or re-triggering your bug. The most -frustrating thing for maintainers is for someone to report a bug, and then -never follow up on a request to try out a fix. - -That said, it's still useful for a kernel maintainer to know a bug exists -on a supported kernel, even if you can't follow up with retests. Follow -up reports, such as replying to the email thread with "I tried the latest -kernel and I can't reproduce my bug anymore" are also helpful, because -maintainers have to assume silence means things are still broken. - -Expectations for kernel maintainers ------------------------------------ - -Linux kernel maintainers are busy, overworked human beings. Some times -they may not be able to address your bug in a day, a week, or two weeks. -If they don't answer your email, they may be on vacation, or at a Linux -conference. Check the conference schedule at https://LWN.net for more info: - - https://lwn.net/Calendar/ - -In general, kernel maintainers take 1 to 5 business days to respond to -bugs. The majority of kernel maintainers are employed to work on the -kernel, and they may not work on the weekends. Maintainers are scattered -around the world, and they may not work in your time zone. Unless you -have a high priority bug, please wait at least a week after the first bug -report before sending the maintainer a reminder email. - -The exceptions to this rule are regressions, kernel crashes, security holes, -or userspace breakage caused by new kernel behavior. Those bugs should be -addressed by the maintainers ASAP. If you suspect a maintainer is not -responding to these types of bugs in a timely manner (especially during a -merge window), escalate the bug to LKML and Linus Torvalds. - -Thank you! - -[Some of this is taken from Frohwalt Egerer's original linux-kernel FAQ] diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst index 07879d01fe68..48b4d0ef2b09 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -9,25 +9,6 @@ (for example by the kernel's build system) might contain content taken from files which use a more restrictive license. -.. important:: - - This document is being prepared to replace - 'Documentation/admin-guide/reporting-bugs.rst'. The main work is done and - you are already free to follow its instructions when reporting issues to the - Linux kernel developers. But keep in mind, below text still needs a few - finishing touches and review. It was merged to the Linux kernel sources at - this stage to make this process easier and increase the text's visibility. - - Any improvements for the text or other feedback is thus very much welcome. - Please send it to 'Thorsten Leemhuis <linux@leemhuis.info>' and 'Jonathan - Corbet <corbet@lwn.net>', ideally with 'Linux kernel mailing list (LKML) - <linux-kernel@vger.kernel.org>' and the 'Linux Kernel Documentation List - <linux-doc@vger.kernel.org>' in CC. - - Areas in the text that still need work or discussion contain a hint like this - which point out the remaining issues; all of them start with the word "FIXME" - to make them easy to find. - Reporting issues ++++++++++++++++ @@ -36,46 +17,43 @@ Reporting issues The short guide (aka TL;DR) =========================== -If you're facing multiple issues with the Linux kernel at once, report each -separately to its developers. Try your best guess which kernel part might be -causing the issue. Check the :ref:`MAINTAINERS <maintainers>` file for how its -developers expect to be told about issues. Note, it's rarely -`bugzilla.kernel.org <https://bugzilla.kernel.org/>`_, as in almost all cases -the report needs to be sent by email! - -Check the destination thoroughly for existing reports; also search the LKML -archives and the web. Join existing discussion if you find matches. If you -don't find any, install `the latest Linux mainline kernel -<https://kernel.org/>`_. Make sure it's vanilla, thus is not patched or using -add-on kernel modules. Also ensure the kernel is running in a healthy -environment and is not already tainted before the issue occurs. - -If you can reproduce your issue with the mainline kernel, send a report to the -destination you determined earlier. Make sure it includes all relevant -information, which in case of a regression should mention the change that's -causing it which can often can be found with a bisection. Also ensure the -report reaches all people that need to know about it, for example the security -team, the stable maintainers or the developers of the patch that causes a -regression. Once the report is out, answer any questions that might be raised -and help where you can. That includes keeping the ball rolling: every time a -new rc1 mainline kernel is released, check if the issue is still happening -there and attach a status update to your initial report. - -If you can not reproduce the issue with the mainline kernel, consider sticking -with it; if you'd like to use an older version line and want to see it fixed -there, first make sure it's still supported. Install its latest release as -vanilla kernel. If you cannot reproduce the issue there, try to find the commit -that fixed it in mainline or any discussion preceding it: those will often -mention if backporting is planed or considered too complex. If backporting was -not discussed, ask if it's in the cards. In case you don't find any commits or -a preceding discussion, see the Linux-stable mailing list archives for existing -reports, as it might be a regression specific to the version line. If it is, -report it like you would report a problem in mainline (including the -bisection). - -If you reached this point without a solution, ask for advice one the -subsystem's mailing list. - +Are you facing a regression with vanilla kernels from the same stable or +longterm series? One still supported? Then search the `LKML +<https://lore.kernel.org/lkml/>`_ and the `Linux stable mailing list +<https://lore.kernel.org/stable/>`_ archives for matching reports to join. If +you don't find any, install `the latest release from that series +<https://kernel.org/>`_. If it still shows the issue, report it to the stable +mailing list (stable@vger.kernel.org) and CC the regressions list +(regressions@lists.linux.dev). + +In all other cases try your best guess which kernel part might be causing the +issue. Check the :ref:`MAINTAINERS <maintainers>` file for how its developers +expect to be told about problems, which most of the time will be by email with a +mailing list in CC. Check the destination's archives for matching reports; +search the `LKML <https://lore.kernel.org/lkml/>`_ and the web, too. If you +don't find any to join, install `the latest mainline kernel +<https://kernel.org/>`_. If the issue is present there, send a report. + +The issue was fixed there, but you would like to see it resolved in a still +supported stable or longterm series as well? Then install its latest release. +If it shows the problem, search for the change that fixed it in mainline and +check if backporting is in the works or was discarded; if it's neither, ask +those who handled the change for it. + +**General remarks**: When installing and testing a kernel as outlined above, +ensure it's vanilla (IOW: not patched and not using add-on modules). Also make +sure it's built and running in a healthy environment and not already tainted +before the issue occurs. + +If you are facing multiple issues with the Linux kernel at once, report each +separately. While writing your report, include all information relevant to the +issue, like the kernel and the distro used. In case of a regression, CC the +regressions mailing list (regressions@lists.linux.dev) to your report; also try +to include the commit-id of the change causing it, which a bisection can find. + +Once the report is out, answer any questions that come up and help where you +can. That includes keeping the ball rolling by occasionally retesting with newer +releases and sending a status update afterwards. Step-by-step guide how to report issues to the kernel maintainers ================================================================= @@ -94,28 +72,23 @@ early if an issue that looks like a Linux kernel problem is actually caused by something else. These steps thus help to ensure the time you invest in this process won't feel wasted in the end: - * Stop reading this document and report the problem to your vendor instead, - unless you are running the latest mainline kernel already or are willing to - install it. This kernel must not be modified or enhanced in any way, and - thus be considered 'vanilla'. + * Are you facing an issue with a Linux kernel a hardware or software vendor + provided? Then in almost all cases you are better off to stop reading this + document and reporting the issue to your vendor instead, unless you are + willing to install the latest Linux version yourself. Be aware the latter + will often be needed anyway to hunt down and fix issues. + + * Perform a rough search for existing reports with your favorite internet + search engine; additionally, check the archives of the `Linux Kernel Mailing + List (LKML) <https://lore.kernel.org/lkml/>`_. If you find matching reports, + join the discussion instead of sending a new one. * See if the issue you are dealing with qualifies as regression, security issue, or a really severe problem: those are 'issues of high priority' that need special handling in some steps that are about to follow. - * Check if your kernel was 'tainted' when the issue occurred, as the event - that made the kernel set this flag might be causing the issue you face. - - * Locate the driver or kernel subsystem that seems to be causing the issue. - Find out how and where its developers expect reports. Note: most of the - time this won't be bugzilla.kernel.org, as issues typically need to be sent - by mail to a maintainer and a public mailing list. - - * Search the archives of the bug tracker or mailing list in question - thoroughly for reports that might match your issue. Also check if you find - something with your favorite internet search engine or in the Linux Kernel - Mailing List (LKML) archives. If you find anything, join the discussion - instead of sending a new report. + * Make sure it's not the kernel's surroundings that are causing the issue + you face. * Create a fresh backup and put system repair and restore tools at hand. @@ -123,8 +96,8 @@ process won't feel wasted in the end: kernel modules on-the-fly, which solutions like DKMS might be doing locally without your knowledge. - * Make sure it's not the kernel's surroundings that are causing the issue - you face. + * Check if your kernel was 'tainted' when the issue occurred, as the event + that made the kernel set this flag might be causing the issue you face. * Write down coarsely how to reproduce the issue. If you deal with multiple issues at once, create separate notes for each of them and make sure they @@ -132,20 +105,35 @@ process won't feel wasted in the end: needs to get reported to the kernel developers separately, unless they are strongly entangled. + * If you are facing a regression within a stable or longterm version line + (say something broke when updating from 5.10.4 to 5.10.5), scroll down to + 'Dealing with regressions within a stable and longterm kernel line'. + + * Locate the driver or kernel subsystem that seems to be causing the issue. + Find out how and where its developers expect reports. Note: most of the + time this won't be bugzilla.kernel.org, as issues typically need to be sent + by mail to a maintainer and a public mailing list. + + * Search the archives of the bug tracker or mailing list in question + thoroughly for reports that might match your issue. If you find anything, + join the discussion instead of sending a new report. + After these preparations you'll now enter the main part: - * Install the latest Linux mainline kernel: that's where all issues get - fixed first, because it's the version line the kernel developers mainly - care about. Testing and reporting with the latest Linux stable kernel can - be an acceptable alternative in some situations, for example during the - merge window; but during that period you might want to suspend your efforts - till its end anyway. + * Unless you are already running the latest 'mainline' Linux kernel, better + go and install it for the reporting process. Testing and reporting with + the latest 'stable' Linux can be an acceptable alternative in some + situations; during the merge window that actually might be even the best + approach, but in that development phase it can be an even better idea to + suspend your efforts for a few days anyway. Whatever version you choose, + ideally use a 'vanilla' build. Ignoring these advices will dramatically + increase the risk your report will be rejected or ignored. * Ensure the kernel you just installed does not 'taint' itself when running. * Reproduce the issue with the kernel you just installed. If it doesn't show - up there, head over to the instructions for issues only happening with + up there, scroll down to the instructions for issues only happening with stable and longterm kernels. * Optimize your notes: try to find and write the most straightforward way to @@ -154,8 +142,8 @@ After these preparations you'll now enter the main part: that hear about it for the first time. And if you learned something in this process, consider searching again for existing reports about the issue. - * If the failure includes a stack dump, like an Oops does, consider decoding - it to find the offending line of code. + * If your failure involves a 'panic', 'Oops', 'warning', or 'BUG', consider + decoding the kernel log to find the line of code that triggered the error. * If your problem is a regression, try to narrow down when the issue was introduced as much as possible. @@ -184,28 +172,54 @@ After these preparations you'll now enter the main part: help yourself, if you don't get any help or if it's unsatisfying. +Reporting regressions within a stable and longterm kernel line +-------------------------------------------------------------- + +This subsection is for you, if you followed above process and got sent here at +the point about regression within a stable or longterm kernel version line. You +face one of those if something breaks when updating from 5.10.4 to 5.10.5 (a +switch from 5.9.15 to 5.10.5 does not qualify). The developers want to fix such +regressions as quickly as possible, hence there is a streamlined process to +report them: + + * Check if the kernel developers still maintain the Linux kernel version + line you care about: go to the `front page of kernel.org + <https://kernel.org/>`_ and make sure it mentions + the latest release of the particular version line without an '[EOL]' tag. + + * Check the archives of the `Linux stable mailing list + <https://lore.kernel.org/stable/>`_ for existing reports. + + * Install the latest release from the particular version line as a vanilla + kernel. Ensure this kernel is not tainted and still shows the problem, as + the issue might have already been fixed there. If you first noticed the + problem with a vendor kernel, check a vanilla build of the last version + known to work performs fine as well. + + * Send a short problem report to the Linux stable mailing list + (stable@vger.kernel.org) and CC the Linux regressions mailing list + (regressions@lists.linux.dev). Roughly describe the issue and ideally + explain how to reproduce it. Mention the first version that shows the + problem and the last version that's working fine. Then wait for further + instructions. + +The reference section below explains each of these steps in more detail. + + Reporting issues only occurring in older kernel version lines ------------------------------------------------------------- -This section is for you, if you tried the latest mainline kernel as outlined +This subsection is for you, if you tried the latest mainline kernel as outlined above, but failed to reproduce your issue there; at the same time you want to -see the issue fixed in older version lines or a vendor kernel that's regularly -rebased on new stable or longterm releases. If that case follow these steps: +see the issue fixed in a still supported stable or longterm series or vendor +kernels regularly rebased on those. If that the case, follow these steps: * Prepare yourself for the possibility that going through the next few steps might not get the issue solved in older releases: the fix might be too big or risky to get backported there. - * Check if the kernel developers still maintain the Linux kernel version - line you care about: go to the front page of kernel.org and make sure it - mentions the latest release of the particular version line without an - '[EOL]' tag. - - * Check the archives of the Linux stable mailing list for existing reports. - - * Install the latest release from the particular version line as a vanilla - kernel. Ensure this kernel is not tainted and still shows the problem, as - the issue might have already been fixed there. + * Perform the first three steps in the section "Dealing with regressions + within a stable and longterm kernel line" above. * Search the Linux kernel version control system for the change that fixed the issue in mainline, as its commit message might tell you if the fix is @@ -215,22 +229,13 @@ rebased on new stable or longterm releases. If that case follow these steps: deemed unsuitable for backporting. If backporting was not considered at all, join the newest discussion, asking if it's in the cards. - * Check if you're dealing with a regression that was never present in - mainline by installing the first release of the version line you care - about. If the issue doesn't show up with it, you basically need to report - the issue with this version like you would report a problem with mainline - (see above). This ideally includes a bisection followed by a search for - existing reports on the net; with the help of the subject and the two - relevant commit-ids. If that doesn't turn up anything, write the report; CC - or forward the report to the stable maintainers, the stable mailing list, - and those who authored the change. Include the shortened commit-id if you - found the change that causes it. - * One of the former steps should lead to a solution. If that doesn't work out, ask the maintainers for the subsystem that seems to be causing the issue for advice; CC the mailing list for the particular subsystem as well as the stable mailing list. +The reference section below explains each of these steps in more detail. + Reference section: Reporting issues to the kernel maintainers ============================================================= @@ -276,54 +281,103 @@ issues to the Linux kernel developers. Make sure you're using the upstream Linux kernel ------------------------------------------------ - *Stop reading this document and report the problem to your vendor instead, - unless you are running the latest mainline kernel already or are willing to - install it. This kernel must not be modified or enhanced in any way, and - thus be considered 'vanilla'.* + *Are you facing an issue with a Linux kernel a hardware or software vendor + provided? Then in almost all cases you are better off to stop reading this + document and reporting the issue to your vendor instead, unless you are + willing to install the latest Linux version yourself. Be aware the latter + will often be needed anyway to hunt down and fix issues.* Like most programmers, Linux kernel developers don't like to spend time dealing -with reports for issues that don't even happen with the source code they -maintain: it's just a waste everybody's time, yours included. That's why you -later will have to test your issue with the latest 'vanilla' kernel: a kernel -that was build using the Linux sources taken straight from `kernel.org -<https://kernel.org/>`_ and not modified or enhanced in any way. - -Almost all kernels used in devices (Computers, Laptops, Smartphones, Routers, -…) and most kernels shipped by Linux distributors are ancient from the point of -kernel development and heavily modified. They thus do not qualify for reporting -an issue to the Linux kernel developers: the issue you face with such a kernel -might be fixed already or caused by the changes or additions, even if they look -small or totally unrelated. That's why issues with such kernels need to be -reported to the vendor that distributed it. Its developers should look into the +with reports for issues that don't even happen with their current code. It's +just a waste everybody's time, especially yours. Unfortunately such situations +easily happen when it comes to the kernel and often leads to frustration on both +sides. That's because almost all Linux-based kernels pre-installed on devices +(Computers, Laptops, Smartphones, Routers, …) and most shipped by Linux +distributors are quite distant from the official Linux kernel as distributed by +kernel.org: these kernels from these vendors are often ancient from the point of +Linux development or heavily modified, often both. + +Most of these vendor kernels are quite unsuitable for reporting issues to the +Linux kernel developers: an issue you face with one of them might have been +fixed by the Linux kernel developers months or years ago already; additionally, +the modifications and enhancements by the vendor might be causing the issue you +face, even if they look small or totally unrelated. That's why you should report +issues with these kernels to the vendor. Its developers should look into the report and, in case it turns out to be an upstream issue, fix it directly -upstream or report it there. In practice that sometimes does not work out. If -that the case, you might want to circumvent the vendor by installing the latest -mainline kernel yourself and reporting the issue as outlined in this document; -just make sure to use really fresh kernel (see below). - - -.. note:: - - FIXME: Should we accept reports for issues with kernel images that are pretty - close to vanilla? But when are they close enough and how to put that line in - words? Maybe something like this? +upstream or forward the report there. In practice that often does not work out +or might not what you want. You thus might want to consider circumventing the +vendor by installing the very latest Linux kernel core yourself. If that's an +option for you move ahead in this process, as a later step in this guide will +explain how to do that once it rules out other potential causes for your issue. + +Note, the previous paragraph is starting with the word 'most', as sometimes +developers in fact are willing to handle reports about issues occurring with +vendor kernels. If they do in the end highly depends on the developers and the +issue in question. Your chances are quite good if the distributor applied only +small modifications to a kernel based on a recent Linux version; that for +example often holds true for the mainline kernels shipped by Debian GNU/Linux +Sid or Fedora Rawhide. Some developers will also accept reports about issues +with kernels from distributions shipping the latest stable kernel, as long as +its only slightly modified; that for example is often the case for Arch Linux, +regular Fedora releases, and openSUSE Tumbleweed. But keep in mind, you better +want to use a mainline Linux and avoid using a stable kernel for this +process, as outlined in the section 'Install a fresh kernel for testing' in more +detail. + +Obviously you are free to ignore all this advice and report problems with an old +or heavily modified vendor kernel to the upstream Linux developers. But note, +those often get rejected or ignored, so consider yourself warned. But it's still +better than not reporting the issue at all: sometimes such reports directly or +indirectly will help to get the issue fixed over time. + + +Search for existing reports, first run +-------------------------------------- + + *Perform a rough search for existing reports with your favorite internet + search engine; additionally, check the archives of the Linux Kernel Mailing + List (LKML). If you find matching reports, join the discussion instead of + sending a new one.* + +Reporting an issue that someone else already brought forward is often a waste of +time for everyone involved, especially you as the reporter. So it's in your own +interest to thoroughly check if somebody reported the issue already. At this +step of the process it's okay to just perform a rough search: a later step will +tell you to perform a more detailed search once you know where your issue needs +to be reported to. Nevertheless, do not hurry with this step of the reporting +process, it can save you time and trouble. + +Simply search the internet with your favorite search engine first. Afterwards, +search the `Linux Kernel Mailing List (LKML) archives +<https://lore.kernel.org/lkml/>`_. - *Note: Some Linux kernel developers accept reports from vendor kernels that - are known to be close to upstream. That for example is often the case for - the kernels that Debian GNU/Linux Sid or Fedora Rawhide ship, which are - normally following mainline closely and carry only a few patches. So a - report with one of these might be accepted by the developers that need to - handle it. But if they do, depends heavily on the individual developers and - the issue at hand. That's why installing a mainline vanilla kernel is the - safe bet.* +If you get flooded with results consider telling your search engine to limit +search timeframe to the past month or year. And wherever you search, make sure +to use good search terms; vary them a few times, too. While doing so try to +look at the issue from the perspective of someone else: that will help you to +come up with other words to use as search terms. Also make sure not to use too +many search terms at once. Remember to search with and without information like +the name of the kernel driver or the name of the affected hardware component. +But its exact brand name (say 'ASUS Red Devil Radeon RX 5700 XT Gaming OC') +often is not much helpful, as it is too specific. Instead try search terms like +the model line (Radeon 5700 or Radeon 5000) and the code name of the main chip +('Navi' or 'Navi10') with and without its manufacturer ('AMD'). - *Arch Linux, other Fedora releases, and openSUSE Tumbleweed often use quite - recent stable kernels that are pretty close to upstream, too. Some - developers accept bugs from them as well. But note that you normally should - avoid stable kernels for reporting issues and use a mainline kernel instead - (see below).* +In case you find an existing report about your issue, join the discussion, as +you might be able to provide valuable additional information. That can be +important even when a fix is prepared or in its final stages already, as +developers might look for people that can provide additional information or +test a proposed fix. Jump to the section 'Duties after the report went out' for +details on how to get properly involved. - Are there any other major Linux distributions that should be mentioned here? +Note, searching `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_ might also +be a good idea, as that might provide valuable insights or turn up matching +reports. If you find the latter, just keep in mind: most subsystems expect +reports in different places, as described below in the section "Check where you +need to report your issue". The developers that should take care of the issue +thus might not even be aware of the bugzilla ticket. Hence, check the ticket if +the issue already got reported as outlined in this document and if not consider +doing so. Issue of high priority? @@ -365,6 +419,75 @@ fatal error where the kernel stop itself) with a 'Oops' (a recoverable error), as the kernel remains running after the latter. +Ensure a healthy environment +---------------------------- + + *Make sure it's not the kernel's surroundings that are causing the issue + you face.* + +Problems that look a lot like a kernel issue are sometimes caused by build or +runtime environment. It's hard to rule out that problem completely, but you +should minimize it: + + * Use proven tools when building your kernel, as bugs in the compiler or the + binutils can cause the resulting kernel to misbehave. + + * Ensure your computer components run within their design specifications; + that's especially important for the main processor, the main memory, and the + motherboard. Therefore, stop undervolting or overclocking when facing a + potential kernel issue. + + * Try to make sure it's not faulty hardware that is causing your issue. Bad + main memory for example can result in a multitude of issues that will + manifest itself in problems looking like kernel issues. + + * If you're dealing with a filesystem issue, you might want to check the file + system in question with ``fsck``, as it might be damaged in a way that leads + to unexpected kernel behavior. + + * When dealing with a regression, make sure it's not something else that + changed in parallel to updating the kernel. The problem for example might be + caused by other software that was updated at the same time. It can also + happen that a hardware component coincidentally just broke when you rebooted + into a new kernel for the first time. Updating the systems BIOS or changing + something in the BIOS Setup can also lead to problems that on look a lot + like a kernel regression. + + +Prepare for emergencies +----------------------- + + *Create a fresh backup and put system repair and restore tools at hand.* + +Reminder, you are dealing with computers, which sometimes do unexpected things, +especially if you fiddle with crucial parts like the kernel of its operating +system. That's what you are about to do in this process. Thus, make sure to +create a fresh backup; also ensure you have all tools at hand to repair or +reinstall the operating system as well as everything you need to restore the +backup. + + +Make sure your kernel doesn't get enhanced +------------------------------------------ + + *Ensure your system does not enhance its kernels by building additional + kernel modules on-the-fly, which solutions like DKMS might be doing locally + without your knowledge.* + +The risk your issue report gets ignored or rejected dramatically increases if +your kernel gets enhanced in any way. That's why you should remove or disable +mechanisms like akmods and DKMS: those build add-on kernel modules +automatically, for example when you install a new Linux kernel or boot it for +the first time. Also remove any modules they might have installed. Then reboot +before proceeding. + +Note, you might not be aware that your system is using one of these solutions: +they often get set up silently when you install Nvidia's proprietary graphics +driver, VirtualBox, or other software that requires a some support from a +module not part of the Linux kernel. That why your might need to uninstall the +packages with such software to get rid of any 3rd party kernel module. + + Check 'taint' flag ------------------ @@ -433,9 +556,52 @@ three things: the name of the module in question). -Locate kernel area that causes the issue +Document how to reproduce issue +------------------------------- + + *Write down coarsely how to reproduce the issue. If you deal with multiple + issues at once, create separate notes for each of them and make sure they + work independently on a freshly booted system. That's needed, as each issue + needs to get reported to the kernel developers separately, unless they are + strongly entangled.* + +If you deal with multiple issues at once, you'll have to report each of them +separately, as they might be handled by different developers. Describing +various issues in one report also makes it quite difficult for others to tear +it apart. Hence, only combine issues in one report if they are very strongly +entangled. + +Additionally, during the reporting process you will have to test if the issue +happens with other kernel versions. Therefore, it will make your work easier if +you know exactly how to reproduce an issue quickly on a freshly booted system. + +Note: it's often fruitless to report issues that only happened once, as they +might be caused by a bit flip due to cosmic radiation. That's why you should +try to rule that out by reproducing the issue before going further. Feel free +to ignore this advice if you are experienced enough to tell a one-time error +due to faulty hardware apart from a kernel issue that rarely happens and thus +is hard to reproduce. + + +Regression in stable or longterm kernel? ---------------------------------------- + *If you are facing a regression within a stable or longterm version line + (say something broke when updating from 5.10.4 to 5.10.5), scroll down to + 'Dealing with regressions within a stable and longterm kernel line'.* + +Regression within a stable and longterm kernel version line are something the +Linux developers want to fix badly, as such issues are even more unwanted than +regression in the main development branch, as they can quickly affect a lot of +people. The developers thus want to learn about such issues as quickly as +possible, hence there is a streamlined process to report them. Note, +regressions with newer kernel version line (say something broke when switching +from 5.9.15 to 5.10.5) do not qualify. + + +Check where you need to report your issue +----------------------------------------- + *Locate the driver or kernel subsystem that seems to be causing the issue. Find out how and where its developers expect reports. Note: most of the time this won't be bugzilla.kernel.org, as issues typically need to be sent @@ -526,26 +692,6 @@ example above does not have such a line. That is the case for most sections, as Linux kernel development is completely driven by mail. Very few subsystems use a bug tracker, and only some of those rely on bugzilla.kernel.org. - -.. note:: - - FIXME: The old text took a totally different approach to bugzilla.kernel.org, - as it mentions it as the place to file issue for people that don't known how - to contact the appropriate people. The new one mentions it rarely; and when - it does like here, it warns users that it's often the wrong place to go. - - This approach was chosen as the main author of this document noticed quite a - few users (or even a lot?) get no reply to the bugs they file in bugzilla. - That's kind of expected, as quite a few (many? most?) of the maintainers - don't even get notified when reports for their subsystem get filed there. And - not getting a single reply to report is something that is just annoying for - users and might make them angry. Improving bugzilla.k.o would be an option, - but on the kernel and maintainers summit 2017 it was agreed on to first go - this route (sorry it took so long): it's easier to achieve and less - controversial, as putting additional burden on already overworked maintainers - is unlikely to get well received. - - In this and many other cases you thus have to look for lines starting with 'Mail:' instead. Those mention the name and the email addresses for the maintainers of the particular code. Also look for a line starting with 'Mailing @@ -558,21 +704,6 @@ and might leave some work for other developers on the subsystem specific list; and LKML is important to have one place where all issue reports can be found. -.. note:: - - FIXME: Above section tells users to always CC LKML. These days it's a kind of - "catch-all" list anyway, which nearly nobody seems to follow closely. So it - seems appropriate to go "all in" and make people send their reports here, - too, as everything (reports, fixes, ...) then can be found in one place (at - least for all reports sent by mail and all subsystems that CC LKML). - - Related: Should we create mailing list like 'linux-issues@vger.kernel.org' - and tell users above to always CC it when reporting issues? Then there would - be one central place reporters could search for existing reports (at least - for issues reported by mail) without getting regular LKML traffic mixed into - the results. - - Finding the maintainers with the help of a script ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -611,205 +742,87 @@ modified during tree-wide cleanups by developers that do not care about the particular driver at all. -Search for existing reports ---------------------------- +Search for existing reports, second run +--------------------------------------- *Search the archives of the bug tracker or mailing list in question - thoroughly for reports that might match your issue. Also check if you find - something with your favorite internet search engine or in the Linux Kernel - Mailing List (LKML) archives. If you find anything, join the discussion - instead of sending a new report.* - -Reporting an issue that someone else already brought forward is often a waste -of time for everyone involved, especially you as the reporter. So it's in your -own interest to thoroughly check if somebody reported the issue already. Thus -do not hurry with this step of the reporting process. Spending 30 to 60 minutes -or even more time can save you and others quite a lot of time and trouble. - -The best place to search is the bug tracker or the mailing list where your -report needs to be filed. You'll find quite a few of those lists on -`lore.kernel.org <https://lore.kernel.org/>`_, but some are hosted in -different places. That for example is the case for the ath10k WiFi driver used -as example in the previous step. But you'll often find the archives for these -lists easily on the net. Searching for 'archive ath10k@lists.infradead.org' for -example will quickly lead you to the `Info page for the ath10k mailing list -<https://lists.infradead.org/mailman/listinfo/ath10k>`_, which at the top links -to its `list archives <https://lists.infradead.org/pipermail/ath10k/>`_. - -Sadly this and quite a few other lists miss a way to search the archives. In -those cases use a regular internet search engine and add something like + thoroughly for reports that might match your issue. If you find anything, + join the discussion instead of sending a new report.* + +As mentioned earlier already: reporting an issue that someone else already +brought forward is often a waste of time for everyone involved, especially you +as the reporter. That's why you should search for existing report again, now +that you know where they need to be reported to. If it's mailing list, you will +often find its archives on `lore.kernel.org <https://lore.kernel.org/>`_. + +But some list are hosted in different places. That for example is the case for +the ath10k WiFi driver used as example in the previous step. But you'll often +find the archives for these lists easily on the net. Searching for 'archive +ath10k@lists.infradead.org' for example will lead you to the `Info page for the +ath10k mailing list <https://lists.infradead.org/mailman/listinfo/ath10k>`_, +which at the top links to its +`list archives <https://lists.infradead.org/pipermail/ath10k/>`_. Sadly this and +quite a few other lists miss a way to search the archives. In those cases use a +regular internet search engine and add something like 'site:lists.infradead.org/pipermail/ath10k/' to your search terms, which limits the results to the archives at that URL. -Additionally, search the internet and the `Linux Kernel Mailing List (LKML) -archives <https://lore.kernel.org/lkml/>`_, as maybe the real culprit might be -in some other subsystem. Searching in `bugzilla.kernel.org -<https://bugzilla.kernel.org/>`_ might also be a good idea, but if you find -anything there keep in mind: most subsystems expect reports in different -places, hence those you find there might have not even reached the people -responsible for the subsystem in question. Nevertheless, the data there might -provide valuable insights. - -If you get flooded with results consider telling your search engine to limit -search timeframe to the past month or year. And wherever you search, make sure -to use good search terms; vary them a few times, too. While doing so try to -look at the issue from the perspective of someone else: that will help you to -come up with other words to use as search terms. Also make sure not to use too -many search terms at once. Remember to search with and without information like -the name of the kernel driver or the name of the affected hardware component. -But its exact brand name (say 'ASUS Red Devil Radeon RX 5700 XT Gaming OC') -often is not much helpful, as it is too specific. Instead try search terms like -the model line (Radeon 5700 or Radeon 5000) and the code name of the main chip -('Navi' or 'Navi10') with and without its manufacturer ('AMD'). - -In case you find an existing report about your issue, join the discussion, as -you might be able to provide valuable additional information. That can be -important even when a fix is prepared or in its final stages already, as -developers might look for people that can provide additional information or -test a proposed fix. Jump to the section 'Duties after the report went out' for -details on how to get properly involved. - - -Prepare for emergencies ------------------------ - - *Create a fresh backup and put system repair and restore tools at hand.* - -Reminder, you are dealing with computers, which sometimes do unexpected things, -especially if you fiddle with crucial parts like the kernel of its operating -system. That's what you are about to do in this process. Thus, make sure to -create a fresh backup; also ensure you have all tools at hand to repair or -reinstall the operating system as well as everything you need to restore the -backup. - - -Make sure your kernel doesn't get enhanced ------------------------------------------- - - *Ensure your system does not enhance its kernels by building additional - kernel modules on-the-fly, which solutions like DKMS might be doing locally - without your knowledge.* - -Your kernel must be 'vanilla' when reporting an issue, but stops being pure as -soon as it loads a kernel module not built from the sources used to compile the -kernel image itself. That's why you need to ensure your Linux kernel stays -vanilla by removing or disabling mechanisms like akmods and DKMS: those might -build additional kernel modules automatically, for example when your boot into -a newly installed Linux kernel the first time. Reboot after removing them and -any modules they installed. - -Note, you might not be aware that your system is using one of these solutions: -they often get set up silently when you install Nvidia's proprietary graphics -driver, VirtualBox, or other software that requires a some support from a -module not part of the Linux kernel. That why your might need to uninstall the -packages with such software to get rid of any 3rd party kernel module. - - -Ensure a healthy environment ----------------------------- - - *Make sure it's not the kernel's surroundings that are causing the issue - you face.* - -Problems that look a lot like a kernel issue are sometimes caused by build or -runtime environment. It's hard to rule out that problem completely, but you -should minimize it: - - * Use proven tools when building your kernel, as bugs in the compiler or the - binutils can cause the resulting kernel to misbehave. - - * Ensure your computer components run within their design specifications; - that's especially important for the main processor, the main memory, and the - motherboard. Therefore, stop undervolting or overclocking when facing a - potential kernel issue. - - * Try to make sure it's not faulty hardware that is causing your issue. Bad - main memory for example can result in a multitude of issues that will - manifest itself in problems looking like kernel issues. - - * If you're dealing with a filesystem issue, you might want to check the file - system in question with ``fsck``, as it might be damaged in a way that leads - to unexpected kernel behavior. - - * When dealing with a regression, make sure it's not something else that - changed in parallel to updating the kernel. The problem for example might be - caused by other software that was updated at the same time. It can also - happen that a hardware component coincidentally just broke when you rebooted - into a new kernel for the first time. Updating the systems BIOS or changing - something in the BIOS Setup can also lead to problems that on look a lot - like a kernel regression. - +It's also wise to check the internet, LKML and maybe bugzilla.kernel.org again +at this point. -Document how to reproduce issue -------------------------------- +For details how to search and what to do if you find matching reports see +"Search for existing reports, first run" above. - *Write down coarsely how to reproduce the issue. If you deal with multiple - issues at once, create separate notes for each of them and make sure they - work independently on a freshly booted system. That's needed, as each issue - needs to get reported to the kernel developers separately, unless they are - strongly entangled.* - -If you deal with multiple issues at once, you'll have to report each of them -separately, as they might be handled by different developers. Describing -various issues in one report also makes it quite difficult for others to tear -it apart. Hence, only combine issues in one report if they are very strongly -entangled. - -Additionally, during the reporting process you will have to test if the issue -happens with other kernel versions. Therefore, it will make your work easier if -you know exactly how to reproduce an issue quickly on a freshly booted system. - -Note: it's often fruitless to report issues that only happened once, as they -might be caused by a bit flip due to cosmic radiation. That's why you should -try to rule that out by reproducing the issue before going further. Feel free -to ignore this advice if you are experienced enough to tell a one-time error -due to faulty hardware apart from a kernel issue that rarely happens and thus -is hard to reproduce. +Do not hurry with this step of the reporting process: spending 30 to 60 minutes +or even more time can save you and others quite a lot of time and trouble. Install a fresh kernel for testing ---------------------------------- - *Install the latest Linux mainline kernel: that's where all issues get - fixed first, because it's the version line the kernel developers mainly - care about. Testing and reporting with the latest Linux stable kernel can - be an acceptable alternative in some situations, for example during the - merge window; but during that period you might want to suspend your efforts - till its end anyway.* - -Reporting an issue to the Linux kernel developers they fixed weeks or months -ago is annoying for them and wasting their and your time. That's why it's in -everybody's interest to check if the issue occurs with the latest codebase -before reporting it. - -In the scope of the Linux kernel the term 'latest' means: a kernel version -recently created from the main line of development, as this 'mainline' tree is -where developers first apply fixes; only after that are they are allowed to get -backported to older, still supported version lines called 'stable' and -'longterm' kernels. That's why you should check a recent mainline kernel, even -if you deal with an issue you only want to see fixed in an older version line. -Another reason: some fixes are only applied to mainline or recent version -lines, as it's too hard or risky to backport them to older versions. If that -the case, reporting the issue again is unlikely to change anything. - -Longterm kernels (sometimes called "LTS kernels") are therefore unsuitable for -testing; they simply are too distant from current development. Even the latest -Linux 'stable' kernel is a significant bit behind and thus better avoided. At -least most of the time, as sometimes a stable kernel can the best choice; but -in those situations you might want to wait a few days anyway: - -Choosing between mainline, stable and waiting -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Head over to `kernel.org <https://kernel.org/>`_ to decide which version to -use. Ignore the big yellow button that says 'Latest release' and look a little -lower for a table. At its top you'll see a line starting with 'mainline', which -most of the time will point to a pre-release with a version number like -'5.8-rc2'. If that's the case, you'll want to use this mainline kernel for -testing. Do not let that 'rc' scare you, these 'development kernels' are pretty -reliable — and you made a backup, as you were instructed above, didn't you? - -In about two out of every nine to ten weeks, 'mainline' might point you to a + *Unless you are already running the latest 'mainline' Linux kernel, better + go and install it for the reporting process. Testing and reporting with + the latest 'stable' Linux can be an acceptable alternative in some + situations; during the merge window that actually might be even the best + approach, but in that development phase it can be an even better idea to + suspend your efforts for a few days anyway. Whatever version you choose, + ideally use a 'vanilla' built. Ignoring these advices will dramatically + increase the risk your report will be rejected or ignored.* + +As mentioned in the detailed explanation for the first step already: Like most +programmers, Linux kernel developers don't like to spend time dealing with +reports for issues that don't even happen with the current code. It's just a +waste everybody's time, especially yours. That's why it's in everybody's +interest that you confirm the issue still exists with the latest upstream code +before reporting it. You are free to ignore this advice, but as outlined +earlier: doing so dramatically increases the risk that your issue report might +get rejected or simply ignored. + +In the scope of the kernel "latest upstream" normally means: + + * Install a mainline kernel; the latest stable kernel can be an option, but + most of the time is better avoided. Longterm kernels (sometimes called 'LTS + kernels') are unsuitable at this point of the process. The next subsection + explains all of this in more detail. + + * The over next subsection describes way to obtain and install such a kernel. + It also outlines that using a pre-compiled kernel are fine, but better are + vanilla, which means: it was built using Linux sources taken straight `from + kernel.org <https://kernel.org/>`_ and not modified or enhanced in any way. + +Choosing the right version for testing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Head over to `kernel.org <https://kernel.org/>`_ to find out which version you +want to use for testing. Ignore the big yellow button that says 'Latest release' +and look a little lower at the table. At its top you'll see a line starting with +mainline, which most of the time will point to a pre-release with a version +number like '5.8-rc2'. If that's the case, you'll want to use this mainline +kernel for testing, as that where all fixes have to be applied first. Do not let +that 'rc' scare you, these 'development kernels' are pretty reliable — and you +made a backup, as you were instructed above, didn't you? + +In about two out of every nine to ten weeks, mainline might point you to a proper release with a version number like '5.7'. If that happens, consider suspending the reporting process until the first pre-release of the next version (5.8-rc1) shows up on kernel.org. That's because the Linux development @@ -830,45 +843,79 @@ case mainline for some reason does currently not work for you. An in general: using it for reproducing the issue is also better than not reporting it issue at all. +Better avoid using the latest stable kernel outside merge windows, as all fixes +must be applied to mainline first. That's why checking the latest mainline +kernel is so important: any issue you want to see fixed in older version lines +needs to be fixed in mainline first before it can get backported, which can +take a few days or weeks. Another reason: the fix you hope for might be too +hard or risky for backporting; reporting the issue again hence is unlikely to +change anything. + +These aspects are also why longterm kernels (sometimes called "LTS kernels") +are unsuitable for this part of the reporting process: they are to distant from +the current code. Hence go and test mainline first and follow the process +further: if the issue doesn't occur with mainline it will guide you how to get +it fixed in older version lines, if that's in the cards for the fix in question. + How to obtain a fresh Linux kernel ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can use pre-built or self-compiled kernel for testing; if you choose the -latter approach, you can either obtain the source code using git or download it -as tar archive. - -Using a pre-compiled kernel for testing is often the quickest, easiest, and -safest way – especially is you are unfamiliar with the Linux kernel. But it -needs to be a vanilla kernel, which can be hard to come buy. You are in luck if -you are using a popular Linux distribution: for quite a few of them you'll find -repositories on the net that contain packages with the latest mainline or -stable kernels in vanilla fashion. It's totally okay to use these, just make -sure from the repository's documentation they are really vanilla. And ensure -the packages contain the latest versions as offered on kernel.org; they are -likely unsuitable if the package is older than a week, as new mainline and -stable kernels typically get released at least once a week. And be aware that -you might need to get build your own kernel later anyway when it comes to -helping test fixes, as described later in this document. - -Developers and experienced Linux users familiar with git are often best served -by obtaining the latest Linux kernel sources straight from the `official -development repository on kernel.org +**Using a pre-compiled kernel**: This is often the quickest, easiest, and safest +way for testing — especially is you are unfamiliar with the Linux kernel. The +problem: most of those shipped by distributors or add-on repositories are build +from modified Linux sources. They are thus not vanilla and therefore often +unsuitable for testing and issue reporting: the changes might cause the issue +you face or influence it somehow. + +But you are in luck if you are using a popular Linux distribution: for quite a +few of them you'll find repositories on the net that contain packages with the +latest mainline or stable Linux built as vanilla kernel. It's totally okay to +use these, just make sure from the repository's description they are vanilla or +at least close to it. Additionally ensure the packages contain the latest +versions as offered on kernel.org. The packages are likely unsuitable if they +are older than a week, as new mainline and stable kernels typically get released +at least once a week. + +Please note that you might need to build your own kernel manually later: that's +sometimes needed for debugging or testing fixes, as described later in this +document. Also be aware that pre-compiled kernels might lack debug symbols that +are needed to decode messages the kernel prints when a panic, Oops, warning, or +BUG occurs; if you plan to decode those, you might be better off compiling a +kernel yourself (see the end of this subsection and the section titled 'Decode +failure messages' for details). + +**Using git**: Developers and experienced Linux users familiar with git are +often best served by obtaining the latest Linux kernel sources straight from the +`official development repository on kernel.org <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_. Those are likely a bit ahead of the latest mainline pre-release. Don't worry about it: they are as reliable as a proper pre-release, unless the kernel's development cycle is currently in the middle of a merge window. But even then they are quite reliable. -People unfamiliar with git are often best served by downloading the sources as -tarball from `kernel.org <https://kernel.org/>`_. +**Conventional**: People unfamiliar with git are often best served by +downloading the sources as tarball from `kernel.org <https://kernel.org/>`_. -How to actually build a kernel isnot described here, as many websites explain +How to actually build a kernel is not described here, as many websites explain the necessary steps already. If you are new to it, consider following one of those how-to's that suggest to use ``make localmodconfig``, as that tries to pick up the configuration of your current kernel and then tries to adjust it somewhat for your system. That does not make the resulting kernel any better, but quicker to compile. +Note: If you are dealing with a panic, Oops, warning, or BUG from the kernel, +please try to enable CONFIG_KALLSYMS when configuring your kernel. +Additionally, enable CONFIG_DEBUG_KERNEL and CONFIG_DEBUG_INFO, too; the +latter is the relevant one of those two, but can only be reached if you enable +the former. Be aware CONFIG_DEBUG_INFO increases the storage space required to +build a kernel by quite a bit. But that's worth it, as these options will allow +you later to pinpoint the exact line of code that triggers your issue. The +section 'Decode failure messages' below explains this in more detail. + +But keep in mind: Always keep a record of the issue encountered in case it is +hard to reproduce. Sending an undecoded report is better than not reporting +the issue at all. + Check 'taint' flag ------------------ @@ -888,7 +935,7 @@ Reproduce issue with the fresh kernel ------------------------------------- *Reproduce the issue with the kernel you just installed. If it doesn't show - up there, head over to the instructions for issues only happening with + up there, scroll down to the instructions for issues only happening with stable and longterm kernels.* Check if the issue occurs with the fresh Linux kernel version you just @@ -923,31 +970,55 @@ instead you can join. Decode failure messages ----------------------- -.. note:: + *If your failure involves a 'panic', 'Oops', 'warning', or 'BUG', consider + decoding the kernel log to find the line of code that triggered the error.* - FIXME: The text in this section is a placeholder for now and quite similar to - the old text found in 'Documentation/admin-guide/reporting-bugs.rst' - currently. It and the document it references are known to be outdated and - thus need to be revisited. Thus consider this note a request for help: if you - are familiar with this topic, please write a few lines that would fit here. - Alternatively, simply outline the current situation roughly to the main - authors of this document (see intro), as they might be able to write - something then. +When the kernel detects an internal problem, it will log some information about +the executed code. This makes it possible to pinpoint the exact line in the +source code that triggered the issue and shows how it was called. But that only +works if you enabled CONFIG_DEBUG_INFO and CONFIG_KALLSYMS when configuring +your kernel. If you did so, consider to decode the information from the +kernel's log. That will make it a lot easier to understand what lead to the +'panic', 'Oops', 'warning', or 'BUG', which increases the chances that someone +can provide a fix. - This section in the end should answer questions like "when is this actually - needed", "what .config options to ideally set earlier to make this step easy - or unnecessary?" (likely CONFIG_UNWINDER_ORC when it's available, otherwise - CONFIG_UNWINDER_FRAME_POINTER; but is there anything else needed?). +Decoding can be done with a script you find in the Linux source tree. If you +are running a kernel you compiled yourself earlier, call it like this:: -.. + [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh ./linux-5.10.5/vmlinux + +If you are running a packaged vanilla kernel, you will likely have to install +the corresponding packages with debug symbols. Then call the script (which you +might need to get from the Linux sources if your distro does not package it) +like this:: + + [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh \ + /usr/lib/debug/lib/modules/5.10.10-4.1.x86_64/vmlinux /usr/src/kernels/5.10.10-4.1.x86_64/ + +The script will work on log lines like the following, which show the address of +the code the kernel was executing when the error occurred:: + + [ 68.387301] RIP: 0010:test_module_init+0x5/0xffa [test_module] + +Once decoded, these lines will look like this:: - *If the failure includes a stack dump, like an Oops does, consider decoding - it to find the offending line of code.* + [ 68.387301] RIP: 0010:test_module_init (/home/username/linux-5.10.5/test-module/test-module.c:16) test_module -When the kernel detects an error, it will print a stack dump that allows to -identify the exact line of code where the issue happens. But that information -sometimes needs to get decoded to be readable, which is explained in -admin-guide/bug-hunting.rst. +In this case the executed code was built from the file +'~/linux-5.10.5/test-module/test-module.c' and the error occurred by the +instructions found in line '16'. + +The script will similarly decode the addresses mentioned in the section +starting with 'Call trace', which show the path to the function where the +problem occurred. Additionally, the script will show the assembler output for +the code section the kernel was executing. + +Note, if you can't get this to work, simply skip this step and mention the +reason for it in the report. If you're lucky, it might not be needed. And if it +is, someone might help you to get things going. Also be aware this is just one +of several ways to decode kernel stack traces. Sometimes different steps will +be required to retrieve the relevant details. Don't worry about that, if that's +needed in your case, developers will tell you what to do. Special care for regressions @@ -1000,8 +1071,7 @@ In the whole process keep in mind: an issue only qualifies as regression if the older and the newer kernel got built with a similar configuration. The best way to archive this: copy the configuration file (``.config``) from the old working kernel freshly to each newer kernel version you try. Afterwards run ``make -oldnoconfig`` to adjust it for the needs of the new version without enabling -any new feature, as those are allowed to cause regressions. +olddefconfig`` to adjust it for the needs of the new version. Write and send the report @@ -1166,17 +1236,26 @@ Special handling for high priority issues Reports for high priority issues need special handling. -**Severe bugs**: make sure the subject or ticket title as well as the first +**Severe issues**: make sure the subject or ticket title as well as the first paragraph makes the severeness obvious. -**Regressions**: If the issue is a regression add [REGRESSION] to the mail's -subject or the title in the bug-tracker. If you did not perform a bisection -mention at least the latest mainline version you tested that worked fine (say -5.7) and the oldest where the issue occurs (say 5.8). If you did a successful -bisection mention the commit id and subject of the change that causes the -regression. Also make sure to add the author of that change to your report; if -you need to file your bug in a bug-tracker forward the report to him in a -private mail and mention where your filed it. +**Regressions**: make the report's subject start with '[REGRESSION]'. + +In case you performed a successful bisection, use the title of the change that +introduced the regression as the second part of your subject. Make the report +also mention the commit id of the culprit. In case of an unsuccessful bisection, +make your report mention the latest tested version that's working fine (say 5.7) +and the oldest where the issue occurs (say 5.8-rc1). + +When sending the report by mail, CC the Linux regressions mailing list +(regressions@lists.linux.dev). In case the report needs to be filed to some web +tracker, proceed to do so; once filed, forward the report by mail to the +regressions list. Make sure to inline the forwarded report, hence do not attach +it. Also add a short note at the top where you mention the URL to the ticket. + +When mailing or forwarding the report, in case of a successful bisection add the +author of the culprit to the recipients; also CC everyone in the signed-off-by +chain, which you find at the end of its commit message. **Security issues**: for these issues your will have to evaluate if a short-term risk to other users would arise if details were publicly disclosed. @@ -1255,7 +1334,7 @@ you never have heard of yet; or you might be asked to apply a patch to the Linux kernel sources to test if it helps. In some cases it will be fine sending a reply asking for instructions how to do that. But before going that route try to find the answer own your own by searching the internet; alternatively -consider asking in other places for advice. For example ask a fried or post +consider asking in other places for advice. For example ask a friend or post about it to a chatroom or forum you normally hang out. **Be patient**: If you are really lucky you might get a reply to your report @@ -1390,32 +1469,11 @@ easier. And with a bit of luck there might be someone in the team that knows a bit about programming and might be able to write a fix. -Details about reporting issues only occurring in older kernel version lines ---------------------------------------------------------------------------- +Reference for "Reporting regressions within a stable and longterm kernel line" +------------------------------------------------------------------------------ -This subsection provides details for steps you need to take if you could not -reproduce your issue with a mainline kernel, but want to see it fixed in older -version lines (aka stable and longterm kernels). - -Some fixes are too complex -~~~~~~~~~~~~~~~~~~~~~~~~~~ - - *Prepare yourself for the possibility that going through the next few steps - might not get the issue solved in older releases: the fix might be too big - or risky to get backported there.* - -Even small and seemingly obvious code-changes sometimes introduce new and -totally unexpected problems. The maintainers of the stable and longterm kernels -are very aware of that and thus only apply changes to these kernels that are -within rules outlined in 'Documentation/process/stable-kernel-rules.rst'. - -Complex or risky changes for example do not qualify and thus only get applied -to mainline. Other fixes are easy to get backported to the newest stable and -longterm kernels, but too risky to integrate into older ones. So be aware the -fix you are hoping for might be one of those that won't be backported to the -version line your care about. In that case you'll have no other choice then to -live with the issue or switch to a newer Linux version, unless you want to -patch the fix into your kernels yourself. +This subsection provides details for the steps you need to perform if you face +a regression within a stable and longterm kernel line. Make sure the particular version line still gets support ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1431,7 +1489,7 @@ chosen and gets supported for at least two years (often six). That's why you need to check if the kernel developers still support the version line you care for. -Note, if kernel.org lists two 'stable' version lines on the front page, you +Note, if kernel.org lists two stable version lines on the front page, you should consider switching to the newer one and forget about the older one: support for it is likely to be abandoned soon. Then it will get a "end-of-life" (EOL) stamp. Version lines that reached that point still get mentioned on the @@ -1454,12 +1512,103 @@ Reproduce issue with the newest release *Install the latest release from the particular version line as a vanilla kernel. Ensure this kernel is not tainted and still shows the problem, as - the issue might have already been fixed there.* + the issue might have already been fixed there. If you first noticed the + problem with a vendor kernel, check a vanilla build of the last version + known to work performs fine as well.* Before investing any more time in this process you want to check if the issue was already fixed in the latest release of version line you're interested in. This kernel needs to be vanilla and shouldn't be tainted before the issue -happens, as detailed outlined already above in the process of testing mainline. +happens, as detailed outlined already above in the section "Install a fresh +kernel for testing". + +Did you first notice the regression with a vendor kernel? Then changes the +vendor applied might be interfering. You need to rule that out by performing +a recheck. Say something broke when you updated from 5.10.4-vendor.42 to +5.10.5-vendor.43. Then after testing the latest 5.10 release as outlined in +the previous paragraph check if a vanilla build of Linux 5.10.4 works fine as +well. If things are broken there, the issue does not qualify as upstream +regression and you need switch back to the main step-by-step guide to report +the issue. + +Report the regression +~~~~~~~~~~~~~~~~~~~~~ + + *Send a short problem report to the Linux stable mailing list + (stable@vger.kernel.org) and CC the Linux regressions mailing list + (regressions@lists.linux.dev). Roughly describe the issue and ideally + explain how to reproduce it. Mention the first version that shows the + problem and the last version that's working fine. Then wait for further + instructions.* + +When reporting a regression that happens within a stable or longterm kernel +line (say when updating from 5.10.4 to 5.10.5) a brief report is enough for +the start to get the issue reported quickly. Hence a rough description is all +it takes. + +But note, it helps developers a great deal if you can specify the exact version +that introduced the problem. Hence if possible within a reasonable time frame, +try to find that version using vanilla kernels. Lets assume something broke when +your distributor released a update from Linux kernel 5.10.5 to 5.10.8. Then as +instructed above go and check the latest kernel from that version line, say +5.10.9. If it shows the problem, try a vanilla 5.10.5 to ensure that no patches +the distributor applied interfere. If the issue doesn't manifest itself there, +try 5.10.7 and then (depending on the outcome) 5.10.8 or 5.10.6 to find the +first version where things broke. Mention it in the report and state that 5.10.9 +is still broken. + +What the previous paragraph outlines is basically a rough manual 'bisection'. +Once your report is out your might get asked to do a proper one, as it allows to +pinpoint the exact change that causes the issue (which then can easily get +reverted to fix the issue quickly). Hence consider to do a proper bisection +right away if time permits. See the section 'Special care for regressions' and +the document 'Documentation/admin-guide/bug-bisect.rst' for details how to +perform one. + + +Reference for "Reporting issues only occurring in older kernel version lines" +----------------------------------------------------------------------------- + +This section provides details for the steps you need to take if you could not +reproduce your issue with a mainline kernel, but want to see it fixed in older +version lines (aka stable and longterm kernels). + +Some fixes are too complex +~~~~~~~~~~~~~~~~~~~~~~~~~~ + + *Prepare yourself for the possibility that going through the next few steps + might not get the issue solved in older releases: the fix might be too big + or risky to get backported there.* + +Even small and seemingly obvious code-changes sometimes introduce new and +totally unexpected problems. The maintainers of the stable and longterm kernels +are very aware of that and thus only apply changes to these kernels that are +within rules outlined in 'Documentation/process/stable-kernel-rules.rst'. + +Complex or risky changes for example do not qualify and thus only get applied +to mainline. Other fixes are easy to get backported to the newest stable and +longterm kernels, but too risky to integrate into older ones. So be aware the +fix you are hoping for might be one of those that won't be backported to the +version line your care about. In that case you'll have no other choice then to +live with the issue or switch to a newer Linux version, unless you want to +patch the fix into your kernels yourself. + +Common preparations +~~~~~~~~~~~~~~~~~~~ + + *Perform the first three steps in the section "Reporting issues only + occurring in older kernel version lines" above.* + +You need to carry out a few steps already described in another section of this +guide. Those steps will let you: + + * Check if the kernel developers still maintain the Linux kernel version line + you care about. + + * Search the Linux stable mailing list for exiting reports. + + * Check with the latest release. + Check code history and search for existing discussions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1513,41 +1662,6 @@ discussions abound it. join the discussion: mention the version where you face the issue and that you would like to see it fixed, if suitable. -Check if it's a regression specific to stable or longterm kernels -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - *Check if you're dealing with a regression that was never present in - mainline by installing the first release of the version line you care - about. If the issue doesn't show up with it, you basically need to report - the issue with this version like you would report a problem with mainline - (see above). This ideally includes a bisection followed by a search for - existing reports on the net; with the help of the subject and the two - relevant commit-ids. If that doesn't turn up anything, write the report; CC - or forward the report to the stable maintainers, the stable mailing list, - and those who authored the change. Include the shortened commit-id if you - found the change that causes it.* - -Sometimes you won't find anything in the previous step: the issue you face -might have never occurred in mainline, as it is caused by some change that is -incomplete or not correctly applied. To check this, install the first release -from version line you care about, e.g., if you care about 5.4.x, install 5.4. - -If the issue doesn't show itself there, it's a regression specific to the -particular version line. In that case you need to report it like an issue -happening in mainline, like the last few steps in the main section in the above -outline. - -One of them suggests doing a bisection, which you are strongly advised to do in -this case. After finding the culprit, search the net for existing reports -again: not only search for the exact subject and the commit-id (proper and -shortened to twelve characters) of the change, but also for the commit-id -(proper and shortened) mentioned as 'Upstream commit' in the commit message. - -Write the report; just keep a few specialties in mind: CC or forward the report -to the stable maintainers, the stable mailing list, which the :ref:`MAINTAINERS -<maintainers>` file mentions in the section "STABLE BRANCH". If you performed a -successful bisection, CC the author of the change and include its subject and -the shortened commit-id. Ask for advice ~~~~~~~~~~~~~~ @@ -1560,8 +1674,7 @@ Ask for advice If the previous three steps didn't get you closer to a solution there is only one option left: ask for advice. Do that in a mail you sent to the maintainers for the subsystem where the issue seems to have its roots; CC the mailing list -for the subsystem as well as the stable mailing list the :ref:`MAINTAINERS -<maintainers>` file mention in the section "STABLE BRANCH". +for the subsystem as well as the stable mailing list (stable@vger.kernel.org). Why some issues won't get any reaction or remain unfixed after being reported @@ -1629,3 +1742,13 @@ issues to the Linux kernel developers: the length and complexity of this document and the implications between the lines illustrate that. But that's how it is for now. The main author of this text hopes documenting the state of the art will lay some groundwork to improve the situation over time. + + +.. + This text is maintained by Thorsten Leemhuis <linux@leemhuis.info>. If you + spot a typo or small mistake, feel free to let him know directly and he'll + fix it. You are free to do the same in a mostly informal way if you want + to contribute changes to the text, but for copyright reasons please CC + linux-doc@vger.kernel.org and "sign-off" your contribution as + Documentation/process/submitting-patches.rst outlines in the section "Sign + your work - the Developer's Certificate of Origin". diff --git a/Documentation/admin-guide/sysrq.rst b/Documentation/admin-guide/sysrq.rst index 67dfa4c29093..60ce5f5ebab6 100644 --- a/Documentation/admin-guide/sysrq.rst +++ b/Documentation/admin-guide/sysrq.rst @@ -90,8 +90,8 @@ Command Function ``b`` Will immediately reboot the system without syncing or unmounting your disks. -``c`` Will perform a system crash by a NULL pointer dereference. - A crashdump will be taken if configured. +``c`` Will perform a system crash and a crashdump will be taken + if configured. ``d`` Shows all locks that are held. diff --git a/Documentation/arch.rst b/Documentation/arch.rst new file mode 100644 index 000000000000..f10bd32a5972 --- /dev/null +++ b/Documentation/arch.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GPL-2.0 + +CPU Architectures +================= + +These books provide programming details about architecture-specific +implementation. + +.. toctree:: + :maxdepth: 2 + + arm/index + arm64/index + ia64/index + m68k/index + mips/index + nios2/index + openrisc/index + parisc/index + powerpc/index + riscv/index + s390/index + sh/index + sparc/index + x86/index + xtensa/index diff --git a/Documentation/arm/marvell.rst b/Documentation/arm/marvell.rst index 94cd73383594..c50be711ec72 100644 --- a/Documentation/arm/marvell.rst +++ b/Documentation/arm/marvell.rst @@ -18,12 +18,12 @@ Orion family - 88F5181L - 88F5182 - - Datasheet: http://www.embeddedarm.com/documentation/third-party/MV88F5182-datasheet.pdf - - Programmer's User Guide: http://www.embeddedarm.com/documentation/third-party/MV88F5182-opensource-manual.pdf - - User Manual: http://www.embeddedarm.com/documentation/third-party/MV88F5182-usermanual.pdf + - Datasheet: https://web.archive.org/web/20210124231420/http://csclub.uwaterloo.ca/~board/ts7800/MV88F5182-datasheet.pdf + - Programmer's User Guide: https://web.archive.org/web/20210124231536/http://csclub.uwaterloo.ca/~board/ts7800/MV88F5182-opensource-manual.pdf + - User Manual: https://web.archive.org/web/20210124231631/http://csclub.uwaterloo.ca/~board/ts7800/MV88F5182-usermanual.pdf - 88F5281 - - Datasheet: http://www.ocmodshop.com/images/reviews/networking/qnap_ts409u/marvel_88f5281_data_sheet.pdf + - Datasheet: https://web.archive.org/web/20131028144728/http://www.ocmodshop.com/images/reviews/networking/qnap_ts409u/marvel_88f5281_data_sheet.pdf - 88F6183 Core: Feroceon 88fr331 (88f51xx) or 88fr531-vd (88f52xx) ARMv5 compatible @@ -38,33 +38,33 @@ Kirkwood family Flavors: - 88F6282 a.k.a Armada 300 - - Product Brief : http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf + - Product Brief : https://web.archive.org/web/20111027032509/http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf - 88F6283 a.k.a Armada 310 - - Product Brief : http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf + - Product Brief : https://web.archive.org/web/20111027032509/http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf - 88F6190 - - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6190-003_WEB.pdf - - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf - - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + - Product Brief : https://web.archive.org/web/20130730072715/http://www.marvell.com/embedded-processors/kirkwood/assets/88F6190-003_WEB.pdf + - Hardware Spec : https://web.archive.org/web/20121021182835/http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf + - Functional Spec: https://web.archive.org/web/20130730091033/http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf - 88F6192 - - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6192-003_ver1.pdf - - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf - - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + - Product Brief : https://web.archive.org/web/20131113121446/http://www.marvell.com/embedded-processors/kirkwood/assets/88F6192-003_ver1.pdf + - Hardware Spec : https://web.archive.org/web/20121021182835/http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf + - Functional Spec: https://web.archive.org/web/20130730091033/http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf - 88F6182 - 88F6180 - - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6180-003_ver1.pdf - - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6180_OpenSource.pdf - - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + - Product Brief : https://web.archive.org/web/20120616201621/http://www.marvell.com/embedded-processors/kirkwood/assets/88F6180-003_ver1.pdf + - Hardware Spec : https://web.archive.org/web/20130730091654/http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6180_OpenSource.pdf + - Functional Spec: https://web.archive.org/web/20130730091033/http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf - 88F6281 - - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6281-004_ver1.pdf - - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6281_OpenSource.pdf - - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + - Product Brief : https://web.archive.org/web/20120131133709/http://www.marvell.com/embedded-processors/kirkwood/assets/88F6281-004_ver1.pdf + - Hardware Spec : https://web.archive.org/web/20120620073511/http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6281_OpenSource.pdf + - Functional Spec: https://web.archive.org/web/20130730091033/http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf Homepage: - http://www.marvell.com/embedded-processors/kirkwood/ + https://web.archive.org/web/20160513194943/http://www.marvell.com/embedded-processors/kirkwood/ Core: Feroceon 88fr131 ARMv5 compatible Linux kernel mach directory: @@ -78,14 +78,15 @@ Discovery family Flavors: - MV78100 - - Product Brief : http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78100-003_WEB.pdf - - Hardware Spec : http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78100_OpenSource.pdf - - Functional Spec: http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf + - Product Brief : https://web.archive.org/web/20120616194711/http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78100-003_WEB.pdf + - Hardware Spec : https://web.archive.org/web/20141005120451/http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78100_OpenSource.pdf + - Functional Spec: https://web.archive.org/web/20111110081125/http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf - MV78200 - - Product Brief : http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78200-002_WEB.pdf - - Hardware Spec : http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78200_OpenSource.pdf - - Functional Spec: http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf + - Product Brief : https://web.archive.org/web/20140801121623/http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78200-002_WEB.pdf + - Hardware Spec : https://web.archive.org/web/20141005120458/http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78200_OpenSource.pdf + - Functional Spec: https://web.archive.org/web/20111110081125/http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf + - MV76100 Not supported by the Linux kernel. @@ -106,9 +107,9 @@ EBU Armada family - 88F6707 - 88F6W11 - - Product Brief: http://www.marvell.com/embedded-processors/armada-300/assets/Marvell_ARMADA_370_SoC.pdf - - Hardware Spec: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-datasheet.pdf - - Functional Spec: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-FunctionalSpec-datasheet.pdf + - Product Brief: https://web.archive.org/web/20121115063038/http://www.marvell.com/embedded-processors/armada-300/assets/Marvell_ARMADA_370_SoC.pdf + - Hardware Spec: https://web.archive.org/web/20140617183747/http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-datasheet.pdf + - Functional Spec: https://web.archive.org/web/20140617183701/http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-FunctionalSpec-datasheet.pdf Core: Sheeva ARMv7 compatible PJ4B @@ -116,7 +117,7 @@ EBU Armada family Armada 375 Flavors: - 88F6720 - - Product Brief: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA_375_SoC-01_product_brief.pdf + - Product Brief: https://web.archive.org/web/20131216023516/http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA_375_SoC-01_product_brief.pdf Core: ARM Cortex-A9 @@ -126,8 +127,8 @@ EBU Armada family - 88F6820 Armada 385 - 88F6828 Armada 388 - - Product infos: http://www.marvell.com/embedded-processors/armada-38x/ - - Functional Spec: http://www.marvell.com/content/dam/marvell/en/public-collateral/embedded-processors/marvell-embedded-processors-armada-38x-functional-specifications-2015-11.pdf + - Product infos: https://web.archive.org/web/20181006144616/http://www.marvell.com/embedded-processors/armada-38x/ + - Functional Spec: https://web.archive.org/web/20200420191927/https://www.marvell.com/content/dam/marvell/en/public-collateral/embedded-processors/marvell-embedded-processors-armada-38x-functional-specifications-2015-11.pdf Core: ARM Cortex-A9 @@ -136,7 +137,7 @@ EBU Armada family - 88F6920 Armada 390 - 88F6928 Armada 398 - - Product infos: http://www.marvell.com/embedded-processors/armada-39x/ + - Product infos: https://web.archive.org/web/20181020222559/http://www.marvell.com/embedded-processors/armada-39x/ Core: ARM Cortex-A9 @@ -150,16 +151,16 @@ EBU Armada family not to be confused with the non-SMP 78xx0 SoCs Product Brief: - http://www.marvell.com/embedded-processors/armada-xp/assets/Marvell-ArmadaXP-SoC-product%20brief.pdf + https://web.archive.org/web/20121021173528/http://www.marvell.com/embedded-processors/armada-xp/assets/Marvell-ArmadaXP-SoC-product%20brief.pdf Functional Spec: - http://www.marvell.com/embedded-processors/armada-xp/assets/ARMADA-XP-Functional-SpecDatasheet.pdf + https://web.archive.org/web/20180829171131/http://www.marvell.com/embedded-processors/armada-xp/assets/ARMADA-XP-Functional-SpecDatasheet.pdf - Hardware Specs: - - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78230_OS.PDF - - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78260_OS.PDF - - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78460_OS.PDF + - https://web.archive.org/web/20141127013651/http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78230_OS.PDF + - https://web.archive.org/web/20141222000224/http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78260_OS.PDF + - https://web.archive.org/web/20141222000230/http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78460_OS.PDF Core: Sheeva ARMv7 compatible Dual-core or Quad-core PJ4B-MP @@ -180,13 +181,13 @@ EBU Armada family ARMv8 ARM Cortex A53 (ARMv8) Homepage: - http://www.marvell.com/embedded-processors/armada-3700/ + https://web.archive.org/web/20181103003602/http://www.marvell.com/embedded-processors/armada-3700/ Product Brief: - http://www.marvell.com/content/dam/marvell/en/public-collateral/embedded-processors/marvell-embedded-processors-armada-37xx-product-brief-2016-01.pdf + https://web.archive.org/web/20210121194810/https://www.marvell.com/content/dam/marvell/en/public-collateral/embedded-processors/marvell-embedded-processors-armada-37xx-product-brief-2016-01.pdf Hardware Spec: - http://www.marvell.com/content/dam/marvell/en/public-collateral/embedded-processors/marvell-embedded-processors-armada-37xx-hardware-specifications-2019-09.pdf + https://web.archive.org/web/20210202162011/http://www.marvell.com/content/dam/marvell/en/public-collateral/embedded-processors/marvell-embedded-processors-armada-37xx-hardware-specifications-2019-09.pdf Device tree files: arch/arm64/boot/dts/marvell/armada-37* @@ -198,11 +199,11 @@ EBU Armada family ARMv8 Core: ARM Cortex A72 Homepage: - http://www.marvell.com/embedded-processors/armada-70xx/ + https://web.archive.org/web/20181020222606/http://www.marvell.com/embedded-processors/armada-70xx/ Product Brief: - - http://www.marvell.com/embedded-processors/assets/Armada7020PB-Jan2016.pdf - - http://www.marvell.com/embedded-processors/assets/Armada7040PB-Jan2016.pdf + - https://web.archive.org/web/20161010105541/http://www.marvell.com/embedded-processors/assets/Armada7020PB-Jan2016.pdf + - https://web.archive.org/web/20160928154533/http://www.marvell.com/embedded-processors/assets/Armada7040PB-Jan2016.pdf Device tree files: arch/arm64/boot/dts/marvell/armada-70* @@ -214,11 +215,11 @@ EBU Armada family ARMv8 ARM Cortex A72 Homepage: - http://www.marvell.com/embedded-processors/armada-80xx/ + https://web.archive.org/web/20181022004830/http://www.marvell.com/embedded-processors/armada-80xx/ Product Brief: - - http://www.marvell.com/embedded-processors/assets/Armada8020PB-Jan2016.pdf - - http://www.marvell.com/embedded-processors/assets/Armada8040PB-Jan2016.pdf + - https://web.archive.org/web/20210124233728/https://www.marvell.com/content/dam/marvell/en/public-collateral/embedded-processors/marvell-embedded-processors-armada-8020-product-brief-2017-12.pdf + - https://web.archive.org/web/20161010105532/http://www.marvell.com/embedded-processors/assets/Armada8040PB-Jan2016.pdf Device tree files: arch/arm64/boot/dts/marvell/armada-80* @@ -233,10 +234,10 @@ Avanta family - 88F6560 Homepage: - http://www.marvell.com/broadband/ + https://web.archive.org/web/20181005145041/http://www.marvell.com/broadband/ Product Brief: - http://www.marvell.com/broadband/assets/Marvell_Avanta_88F6510_305_060-001_product_brief.pdf + https://web.archive.org/web/20180829171057/http://www.marvell.com/broadband/assets/Marvell_Avanta_88F6510_305_060-001_product_brief.pdf No public datasheet available. @@ -255,7 +256,7 @@ Storage family - 88RC1580 Product infos: - http://www.marvell.com/storage/armada-sp/ + https://web.archive.org/web/20191129073953/http://www.marvell.com/storage/armada-sp/ Core: Sheeva ARMv7 comatible Quad-core PJ4C @@ -269,16 +270,16 @@ Dove family (application processor) - 88AP510 a.k.a Armada 510 Product Brief: - http://www.marvell.com/application-processors/armada-500/assets/Marvell_Armada510_SoC.pdf + https://web.archive.org/web/20111102020643/http://www.marvell.com/application-processors/armada-500/assets/Marvell_Armada510_SoC.pdf Hardware Spec: - http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Hardware-Spec.pdf + https://web.archive.org/web/20160428160231/http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Hardware-Spec.pdf Functional Spec: - http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Functional-Spec.pdf + https://web.archive.org/web/20120130172443/http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Functional-Spec.pdf Homepage: - http://www.marvell.com/application-processors/armada-500/ + https://web.archive.org/web/20160822232651/http://www.marvell.com/application-processors/armada-500/ Core: ARMv7 compatible @@ -295,22 +296,22 @@ PXA 2xx/3xx/93x/95x family - Application processor only - Core: ARMv5 XScale1 core - PXA270, PXA271, PXA272 - - Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_pb.pdf - - Design guide : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_design_guide.pdf - - Developers manual : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_dev_man.pdf - - Specification : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_emts.pdf - - Specification update : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_spec_update.pdf + - Product Brief : https://web.archive.org/web/20150927135510/http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_pb.pdf + - Design guide : https://web.archive.org/web/20120111181937/http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_design_guide.pdf + - Developers manual : https://web.archive.org/web/20150927164805/http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_dev_man.pdf + - Specification : https://web.archive.org/web/20140211221535/http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_emts.pdf + - Specification update : https://web.archive.org/web/20120111104906/http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_spec_update.pdf - Application processor only - Core: ARMv5 XScale2 core - PXA300, PXA310, PXA320 - - PXA 300 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA300_PB_R4.pdf - - PXA 310 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA310_PB_R4.pdf - - PXA 320 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA320_PB_R4.pdf - - Design guide : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Design_Guide.pdf - - Developers manual : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Developers_Manual.zip - - Specifications : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_EMTS.pdf - - Specification Update : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Spec_Update.zip - - Reference Manual : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_TavorP_BootROM_Ref_Manual.pdf + - PXA 300 Product Brief : https://web.archive.org/web/20120111121203/http://www.marvell.com/application-processors/pxa-family/assets/PXA300_PB_R4.pdf + - PXA 310 Product Brief : https://web.archive.org/web/20120111104515/http://www.marvell.com/application-processors/pxa-family/assets/PXA310_PB_R4.pdf + - PXA 320 Product Brief : https://web.archive.org/web/20121021182826/http://www.marvell.com/application-processors/pxa-family/assets/PXA320_PB_R4.pdf + - Design guide : https://web.archive.org/web/20130727144625/http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Design_Guide.pdf + - Developers manual : https://web.archive.org/web/20130727144605/http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Developers_Manual.zip + - Specifications : https://web.archive.org/web/20130727144559/http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_EMTS.pdf + - Specification Update : https://web.archive.org/web/20150927183411/http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Spec_Update.zip + - Reference Manual : https://web.archive.org/web/20120111103844/http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_TavorP_BootROM_Ref_Manual.pdf - Application processor only - Core: ARMv5 XScale3 core - PXA930, PXA935 @@ -341,26 +342,26 @@ MMP/MMP2/MMP3 family (communication processor) Flavors: - PXA168, a.k.a Armada 168 - - Homepage : http://www.marvell.com/application-processors/armada-100/armada-168.jsp - - Product brief : http://www.marvell.com/application-processors/armada-100/assets/pxa_168_pb.pdf - - Hardware manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_datasheet.pdf - - Software manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_software_manual.pdf - - Specification update : http://www.marvell.com/application-processors/armada-100/assets/ARMADA16x_Spec_update.pdf - - Boot ROM manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_ref_manual.pdf - - App node package : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_app_note_package.pdf + - Homepage : https://web.archive.org/web/20110926014256/http://www.marvell.com/application-processors/armada-100/armada-168.jsp + - Product brief : https://web.archive.org/web/20111102030100/http://www.marvell.com/application-processors/armada-100/assets/pxa_168_pb.pdf + - Hardware manual : https://web.archive.org/web/20160428165359/http://www.marvell.com/application-processors/armada-100/assets/armada_16x_datasheet.pdf + - Software manual : https://web.archive.org/web/20160428154454/http://www.marvell.com/application-processors/armada-100/assets/armada_16x_software_manual.pdf + - Specification update : https://web.archive.org/web/20150927160338/http://www.marvell.com/application-processors/armada-100/assets/ARMADA16x_Spec_update.pdf + - Boot ROM manual : https://web.archive.org/web/20130727205559/http://www.marvell.com/application-processors/armada-100/assets/armada_16x_ref_manual.pdf + - App node package : https://web.archive.org/web/20141005090706/http://www.marvell.com/application-processors/armada-100/assets/armada_16x_app_note_package.pdf - Application processor only - Core: ARMv5 compatible Marvell PJ1 88sv331 (Mohawk) - PXA910/PXA920 - - Homepage : http://www.marvell.com/communication-processors/pxa910/ - - Product Brief : http://www.marvell.com/communication-processors/pxa910/assets/Marvell_PXA910_Platform-001_PB_final.pdf + - Homepage : https://web.archive.org/web/20150928121236/http://www.marvell.com/communication-processors/pxa910/ + - Product Brief : https://archive.org/download/marvell-pxa910-pb/Marvell_PXA910_Platform-001_PB.pdf - Application processor with Communication processor - Core: ARMv5 compatible Marvell PJ1 88sv331 (Mohawk) - - PXA688, a.k.a. MMP2, a.k.a Armada 610 - - Product Brief : http://www.marvell.com/application-processors/armada-600/assets/armada610_pb.pdf + - PXA688, a.k.a. MMP2, a.k.a Armada 610 (OLPC XO-1.75) + - Product Brief : https://web.archive.org/web/20111102023255/http://www.marvell.com/application-processors/armada-600/assets/armada610_pb.pdf - Application processor only - Core: ARMv7 compatible Sheeva PJ4 88sv581x core - - PXA2128, a.k.a. MMP3 (OLPC XO4, Linux support not upstream) - - Product Brief : http://www.marvell.com/application-processors/armada/pxa2128/assets/Marvell-ARMADA-PXA2128-SoC-PB.pdf + - PXA2128, a.k.a. MMP3, a.k.a Armada 620 (OLPC XO-4) + - Product Brief : https://web.archive.org/web/20120824055155/http://www.marvell.com/application-processors/armada/pxa2128/assets/Marvell-ARMADA-PXA2128-SoC-PB.pdf - Application processor only - Core: Dual-core ARMv7 compatible Sheeva PJ4C core - PXA960/PXA968/PXA978 (Linux support not upstream) diff --git a/Documentation/arm/uefi.rst b/Documentation/arm/uefi.rst index f732f957421f..9b0b5e458a1e 100644 --- a/Documentation/arm/uefi.rst +++ b/Documentation/arm/uefi.rst @@ -64,4 +64,11 @@ linux,uefi-mmap-desc-size 32-bit Size in bytes of each entry in the UEFI memory map. linux,uefi-mmap-desc-ver 32-bit Version of the mmap descriptor format. + +linux,initrd-start 64-bit Physical start address of an initrd + +linux,initrd-end 64-bit Physical end address of an initrd + +kaslr-seed 64-bit Entropy used to randomize the kernel image + base address location. ========================== ====== =========================================== diff --git a/Documentation/conf.py b/Documentation/conf.py index fd65168c10f8..879e86dbea66 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -331,27 +331,34 @@ htmlhelp_basename = 'TheLinuxKerneldoc' # -- Options for LaTeX output --------------------------------------------- latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -'papersize': 'a4paper', + # The paper size ('letterpaper' or 'a4paper'). + 'papersize': 'a4paper', -# The font size ('10pt', '11pt' or '12pt'). -'pointsize': '11pt', + # The font size ('10pt', '11pt' or '12pt'). + 'pointsize': '11pt', -# Latex figure (float) alignment -#'figure_align': 'htbp', + # Latex figure (float) alignment + #'figure_align': 'htbp', -# Don't mangle with UTF-8 chars -'inputenc': '', -'utf8extra': '', + # Don't mangle with UTF-8 chars + 'inputenc': '', + 'utf8extra': '', -# Additional stuff for the LaTeX preamble. + # Set document margins + 'sphinxsetup': ''' + hmargin=0.5in, vmargin=1in, + parsedliteralwraps=true, + verbatimhintsturnover=false, + ''', + + # Additional stuff for the LaTeX preamble. 'preamble': ''' - % Use some font with UTF-8 support with XeLaTeX + % Use some font with UTF-8 support with XeLaTeX \\usepackage{fontspec} \\setsansfont{DejaVu Sans} \\setromanfont{DejaVu Serif} \\setmonofont{DejaVu Sans Mono} - ''' + ''', } # At least one book (translations) may have Asian characters diff --git a/Documentation/core-api/rbtree.rst b/Documentation/core-api/rbtree.rst index 6b88837fbf82..ed1a9fbc779e 100644 --- a/Documentation/core-api/rbtree.rst +++ b/Documentation/core-api/rbtree.rst @@ -201,7 +201,7 @@ search trees, such as for traversals or users relying on a the particular order for their own logic. To this end, users can use 'struct rb_root_cached' to optimize O(logN) rb_first() calls to a simple pointer fetch avoiding potentially expensive tree iterations. This is done at negligible runtime -overhead for maintanence; albeit larger memory footprint. +overhead for maintenance; albeit larger memory footprint. Similar to the rb_root structure, cached rbtrees are initialized to be empty via:: diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst new file mode 100644 index 000000000000..51fed1bd72ec --- /dev/null +++ b/Documentation/dev-tools/checkpatch.rst @@ -0,0 +1,755 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +========== +Checkpatch +========== + +Checkpatch (scripts/checkpatch.pl) is a perl script which checks for trivial +style violations in patches and optionally corrects them. Checkpatch can +also be run on file contexts and without the kernel tree. + +Checkpatch is not always right. Your judgement takes precedence over checkpatch +messages. If your code looks better with the violations, then its probably +best left alone. + + +Options +======= + +This section will describe the options checkpatch can be run with. + +Usage:: + + ./scripts/checkpatch.pl [OPTION]... [FILE]... + +Available options: + + - -q, --quiet + + Enable quiet mode. + + - -v, --verbose + Enable verbose mode. Additional verbose test descriptions are output + so as to provide information on why that particular message is shown. + + - --no-tree + + Run checkpatch without the kernel tree. + + - --no-signoff + + Disable the 'Signed-off-by' line check. The sign-off is a simple line at + the end of the explanation for the patch, which certifies that you wrote it + or otherwise have the right to pass it on as an open-source patch. + + Example:: + + Signed-off-by: Random J Developer <random@developer.example.org> + + Setting this flag effectively stops a message for a missing signed-off-by + line in a patch context. + + - --patch + + Treat FILE as a patch. This is the default option and need not be + explicitly specified. + + - --emacs + + Set output to emacs compile window format. This allows emacs users to jump + from the error in the compile window directly to the offending line in the + patch. + + - --terse + + Output only one line per report. + + - --showfile + + Show the diffed file position instead of the input file position. + + - -g, --git + + Treat FILE as a single commit or a git revision range. + + Single commit with: + + - <rev> + - <rev>^ + - <rev>~n + + Multiple commits with: + + - <rev1>..<rev2> + - <rev1>...<rev2> + - <rev>-<count> + + - -f, --file + + Treat FILE as a regular source file. This option must be used when running + checkpatch on source files in the kernel. + + - --subjective, --strict + + Enable stricter tests in checkpatch. By default the tests emitted as CHECK + do not activate by default. Use this flag to activate the CHECK tests. + + - --list-types + + Every message emitted by checkpatch has an associated TYPE. Add this flag + to display all the types in checkpatch. + + Note that when this flag is active, checkpatch does not read the input FILE, + and no message is emitted. Only a list of types in checkpatch is output. + + - --types TYPE(,TYPE2...) + + Only display messages with the given types. + + Example:: + + ./scripts/checkpatch.pl mypatch.patch --types EMAIL_SUBJECT,BRACES + + - --ignore TYPE(,TYPE2...) + + Checkpatch will not emit messages for the specified types. + + Example:: + + ./scripts/checkpatch.pl mypatch.patch --ignore EMAIL_SUBJECT,BRACES + + - --show-types + + By default checkpatch doesn't display the type associated with the messages. + Set this flag to show the message type in the output. + + - --max-line-length=n + + Set the max line length (default 100). If a line exceeds the specified + length, a LONG_LINE message is emitted. + + + The message level is different for patch and file contexts. For patches, + a WARNING is emitted. While a milder CHECK is emitted for files. So for + file contexts, the --strict flag must also be enabled. + + - --min-conf-desc-length=n + + Set the Kconfig entry minimum description length, if shorter, warn. + + - --tab-size=n + + Set the number of spaces for tab (default 8). + + - --root=PATH + + PATH to the kernel tree root. + + This option must be specified when invoking checkpatch from outside + the kernel root. + + - --no-summary + + Suppress the per file summary. + + - --mailback + + Only produce a report in case of Warnings or Errors. Milder Checks are + excluded from this. + + - --summary-file + + Include the filename in summary. + + - --debug KEY=[0|1] + + Turn on/off debugging of KEY, where KEY is one of 'values', 'possible', + 'type', and 'attr' (default is all off). + + - --fix + + This is an EXPERIMENTAL feature. If correctable errors exists, a file + <inputfile>.EXPERIMENTAL-checkpatch-fixes is created which has the + automatically fixable errors corrected. + + - --fix-inplace + + EXPERIMENTAL - Similar to --fix but input file is overwritten with fixes. + + DO NOT USE this flag unless you are absolutely sure and you have a backup + in place. + + - --ignore-perl-version + + Override checking of perl version. Runtime errors maybe encountered after + enabling this flag if the perl version does not meet the minimum specified. + + - --codespell + + Use the codespell dictionary for checking spelling errors. + + - --codespellfile + + Use the specified codespell file. + Default is '/usr/share/codespell/dictionary.txt'. + + - --typedefsfile + + Read additional types from this file. + + - --color[=WHEN] + + Use colors 'always', 'never', or only when output is a terminal ('auto'). + Default is 'auto'. + + - --kconfig-prefix=WORD + + Use WORD as a prefix for Kconfig symbols (default is `CONFIG_`). + + - -h, --help, --version + + Display the help text. + +Message Levels +============== + +Messages in checkpatch are divided into three levels. The levels of messages +in checkpatch denote the severity of the error. They are: + + - ERROR + + This is the most strict level. Messages of type ERROR must be taken + seriously as they denote things that are very likely to be wrong. + + - WARNING + + This is the next stricter level. Messages of type WARNING requires a + more careful review. But it is milder than an ERROR. + + - CHECK + + This is the mildest level. These are things which may require some thought. + +Type Descriptions +================= + +This section contains a description of all the message types in checkpatch. + +.. Types in this section are also parsed by checkpatch. +.. The types are grouped into subsections based on use. + + +Allocation style +---------------- + + **ALLOC_ARRAY_ARGS** + The first argument for kcalloc or kmalloc_array should be the + number of elements. sizeof() as the first argument is generally + wrong. + See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html + + **ALLOC_SIZEOF_STRUCT** + The allocation style is bad. In general for family of + allocation functions using sizeof() to get memory size, + constructs like:: + + p = alloc(sizeof(struct foo), ...) + + should be:: + + p = alloc(sizeof(*p), ...) + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#allocating-memory + + **ALLOC_WITH_MULTIPLY** + Prefer kmalloc_array/kcalloc over kmalloc/kzalloc with a + sizeof multiply. + See: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html + + +API usage +--------- + + **ARCH_DEFINES** + Architecture specific defines should be avoided wherever + possible. + + **ARCH_INCLUDE_LINUX** + Whenever asm/file.h is included and linux/file.h exists, a + conversion can be made when linux/file.h includes asm/file.h. + However this is not always the case (See signal.h). + This message type is emitted only for includes from arch/. + + **AVOID_BUG** + BUG() or BUG_ON() should be avoided totally. + Use WARN() and WARN_ON() instead, and handle the "impossible" + error condition as gracefully as possible. + See: https://www.kernel.org/doc/html/latest/process/deprecated.html#bug-and-bug-on + + **CONSIDER_KSTRTO** + The simple_strtol(), simple_strtoll(), simple_strtoul(), and + simple_strtoull() functions explicitly ignore overflows, which + may lead to unexpected results in callers. The respective kstrtol(), + kstrtoll(), kstrtoul(), and kstrtoull() functions tend to be the + correct replacements. + See: https://www.kernel.org/doc/html/latest/process/deprecated.html#simple-strtol-simple-strtoll-simple-strtoul-simple-strtoull + + **LOCKDEP** + The lockdep_no_validate class was added as a temporary measure to + prevent warnings on conversion of device->sem to device->mutex. + It should not be used for any other purpose. + See: https://lore.kernel.org/lkml/1268959062.9440.467.camel@laptop/ + + **MALFORMED_INCLUDE** + The #include statement has a malformed path. This has happened + because the author has included a double slash "//" in the pathname + accidentally. + + **USE_LOCKDEP** + lockdep_assert_held() annotations should be preferred over + assertions based on spin_is_locked() + See: https://www.kernel.org/doc/html/latest/locking/lockdep-design.html#annotations + + **UAPI_INCLUDE** + No #include statements in include/uapi should use a uapi/ path. + + +Comment style +------------- + + **BLOCK_COMMENT_STYLE** + The comment style is incorrect. The preferred style for multi- + line comments is:: + + /* + * This is the preferred style + * for multi line comments. + */ + + The networking comment style is a bit different, with the first line + not empty like the former:: + + /* This is the preferred comment style + * for files in net/ and drivers/net/ + */ + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting + + **C99_COMMENTS** + C99 style single line comments (//) should not be used. + Prefer the block comment style instead. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting + + +Commit message +-------------- + + **BAD_SIGN_OFF** + The signed-off-by line does not fall in line with the standards + specified by the community. + See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1 + + **BAD_STABLE_ADDRESS_STYLE** + The email format for stable is incorrect. + Some valid options for stable address are:: + + 1. stable@vger.kernel.org + 2. stable@kernel.org + + For adding version info, the following comment style should be used:: + + stable@vger.kernel.org # version info + + **COMMIT_COMMENT_SYMBOL** + Commit log lines starting with a '#' are ignored by git as + comments. To solve this problem addition of a single space + infront of the log line is enough. + + **COMMIT_MESSAGE** + The patch is missing a commit description. A brief + description of the changes made by the patch should be added. + See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes + + **MISSING_SIGN_OFF** + The patch is missing a Signed-off-by line. A signed-off-by + line should be added according to Developer's certificate of + Origin. + See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin + + **NO_AUTHOR_SIGN_OFF** + The author of the patch has not signed off the patch. It is + required that a simple sign off line should be present at the + end of explanation of the patch to denote that the author has + written it or otherwise has the rights to pass it on as an open + source patch. + See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin + + **DIFF_IN_COMMIT_MSG** + Avoid having diff content in commit message. + This causes problems when one tries to apply a file containing both + the changelog and the diff because patch(1) tries to apply the diff + which it found in the changelog. + See: https://lore.kernel.org/lkml/20150611134006.9df79a893e3636019ad2759e@linux-foundation.org/ + + **GERRIT_CHANGE_ID** + To be picked up by gerrit, the footer of the commit message might + have a Change-Id like:: + + Change-Id: Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b + Signed-off-by: A. U. Thor <author@example.com> + + The Change-Id line must be removed before submitting. + + **GIT_COMMIT_ID** + The proper way to reference a commit id is: + commit <12+ chars of sha1> ("<title line>") + + An example may be:: + + Commit e21d2170f36602ae2708 ("video: remove unnecessary + platform_set_drvdata()") removed the unnecessary + platform_set_drvdata(), but left the variable "dev" unused, + delete it. + + See: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes + + +Comparison style +---------------- + + **ASSIGN_IN_IF** + Do not use assignments in if condition. + Example:: + + if ((foo = bar(...)) < BAZ) { + + should be written as:: + + foo = bar(...); + if (foo < BAZ) { + + **BOOL_COMPARISON** + Comparisons of A to true and false are better written + as A and !A. + See: https://lore.kernel.org/lkml/1365563834.27174.12.camel@joe-AO722/ + + **COMPARISON_TO_NULL** + Comparisons to NULL in the form (foo == NULL) or (foo != NULL) + are better written as (!foo) and (foo). + + **CONSTANT_COMPARISON** + Comparisons with a constant or upper case identifier on the left + side of the test should be avoided. + + +Macros, Attributes and Symbols +------------------------------ + + **ARRAY_SIZE** + The ARRAY_SIZE(foo) macro should be preferred over + sizeof(foo)/sizeof(foo[0]) for finding number of elements in an + array. + + The macro is defined in include/linux/kernel.h:: + + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) + + **AVOID_EXTERNS** + Function prototypes don't need to be declared extern in .h + files. It's assumed by the compiler and is unnecessary. + + **AVOID_L_PREFIX** + Local symbol names that are prefixed with `.L` should be avoided, + as this has special meaning for the assembler; a symbol entry will + not be emitted into the symbol table. This can prevent `objtool` + from generating correct unwind info. + + Symbols with STB_LOCAL binding may still be used, and `.L` prefixed + local symbol names are still generally usable within a function, + but `.L` prefixed local symbol names should not be used to denote + the beginning or end of code regions via + `SYM_CODE_START_LOCAL`/`SYM_CODE_END` + + **BIT_MACRO** + Defines like: 1 << <digit> could be BIT(digit). + The BIT() macro is defined in include/linux/bitops.h:: + + #define BIT(nr) (1UL << (nr)) + + **CONST_READ_MOSTLY** + When a variable is tagged with the __read_mostly annotation, it is a + signal to the compiler that accesses to the variable will be mostly + reads and rarely(but NOT never) a write. + + const __read_mostly does not make any sense as const data is already + read-only. The __read_mostly annotation thus should be removed. + + **DATE_TIME** + It is generally desirable that building the same source code with + the same set of tools is reproducible, i.e. the output is always + exactly the same. + + The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros, + and enables warnings if they are used as they can lead to + non-deterministic builds. + See: https://www.kernel.org/doc/html/latest/kbuild/reproducible-builds.html#timestamps + + **DEFINE_ARCH_HAS** + The ARCH_HAS_xyz and ARCH_HAVE_xyz patterns are wrong. + + For big conceptual features use Kconfig symbols instead. And for + smaller things where we have compatibility fallback functions but + want architectures able to override them with optimized ones, we + should either use weak functions (appropriate for some cases), or + the symbol that protects them should be the same symbol we use. + See: https://lore.kernel.org/lkml/CA+55aFycQ9XJvEOsiM3txHL5bjUc8CeKWJNR_H+MiicaddB42Q@mail.gmail.com/ + + **INIT_ATTRIBUTE** + Const init definitions should use __initconst instead of + __initdata. + + Similarly init definitions without const require a separate + use of const. + + **INLINE_LOCATION** + The inline keyword should sit between storage class and type. + + For example, the following segment:: + + inline static int example_function(void) + { + ... + } + + should be:: + + static inline int example_function(void) + { + ... + } + + **MULTISTATEMENT_MACRO_USE_DO_WHILE** + Macros with multiple statements should be enclosed in a + do - while block. Same should also be the case for macros + starting with `if` to avoid logic defects:: + + #define macrofun(a, b, c) \ + do { \ + if (a == 5) \ + do_this(b, c); \ + } while (0) + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#macros-enums-and-rtl + + **WEAK_DECLARATION** + Using weak declarations like __attribute__((weak)) or __weak + can have unintended link defects. Avoid using them. + + +Functions and Variables +----------------------- + + **CAMELCASE** + Avoid CamelCase Identifiers. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#naming + + **FUNCTION_WITHOUT_ARGS** + Function declarations without arguments like:: + + int foo() + + should be:: + + int foo(void) + + **GLOBAL_INITIALISERS** + Global variables should not be initialized explicitly to + 0 (or NULL, false, etc.). Your compiler (or rather your + loader, which is responsible for zeroing out the relevant + sections) automatically does it for you. + + **INITIALISED_STATIC** + Static variables should not be initialized explicitly to zero. + Your compiler (or rather your loader) automatically does + it for you. + + **RETURN_PARENTHESES** + return is not a function and as such doesn't need parentheses:: + + return (bar); + + can simply be:: + + return bar; + + +Spacing and Brackets +-------------------- + + **ASSIGNMENT_CONTINUATIONS** + Assignment operators should not be written at the start of a + line but should follow the operand at the previous line. + + **BRACES** + The placement of braces is stylistically incorrect. + The preferred way is to put the opening brace last on the line, + and put the closing brace first:: + + if (x is true) { + we do y + } + + This applies for all non-functional blocks. + However, there is one special case, namely functions: they have the + opening brace at the beginning of the next line, thus:: + + int function(int x) + { + body of function + } + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces + + **BRACKET_SPACE** + Whitespace before opening bracket '[' is prohibited. + There are some exceptions: + + 1. With a type on the left:: + + ;int [] a; + + 2. At the beginning of a line for slice initialisers:: + + [0...10] = 5, + + 3. Inside a curly brace:: + + = { [0...10] = 5 } + + **CODE_INDENT** + Code indent should use tabs instead of spaces. + Outside of comments, documentation and Kconfig, + spaces are never used for indentation. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation + + **CONCATENATED_STRING** + Concatenated elements should have a space in between. + Example:: + + printk(KERN_INFO"bar"); + + should be:: + + printk(KERN_INFO "bar"); + + **ELSE_AFTER_BRACE** + `else {` should follow the closing block `}` on the same line. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces + + **LINE_SPACING** + Vertical space is wasted given the limited number of lines an + editor window can display when multiple blank lines are used. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces + + **OPEN_BRACE** + The opening brace should be following the function definitions on the + next line. For any non-functional block it should be on the same line + as the last construct. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces + + **POINTER_LOCATION** + When using pointer data or a function that returns a pointer type, + the preferred use of * is adjacent to the data name or function name + and not adjacent to the type name. + Examples:: + + char *linux_banner; + unsigned long long memparse(char *ptr, char **retptr); + char *match_strdup(substring_t *s); + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces + + **SPACING** + Whitespace style used in the kernel sources is described in kernel docs. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces + + **SWITCH_CASE_INDENT_LEVEL** + switch should be at the same indent as case. + Example:: + + switch (suffix) { + case 'G': + case 'g': + mem <<= 30; + break; + case 'M': + case 'm': + mem <<= 20; + break; + case 'K': + case 'k': + mem <<= 10; + /* fall through */ + default: + break; + } + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation + + **TRAILING_WHITESPACE** + Trailing whitespace should always be removed. + Some editors highlight the trailing whitespace and cause visual + distractions when editing files. + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces + + **WHILE_AFTER_BRACE** + while should follow the closing bracket on the same line:: + + do { + ... + } while(something); + + See: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces + + +Others +------ + + **CONFIG_DESCRIPTION** + Kconfig symbols should have a help text which fully describes + it. + + **CORRUPTED_PATCH** + The patch seems to be corrupted or lines are wrapped. + Please regenerate the patch file before sending it to the maintainer. + + **DOS_LINE_ENDINGS** + For DOS-formatted patches, there are extra ^M symbols at the end of + the line. These should be removed. + + **EXECUTE_PERMISSIONS** + There is no reason for source files to be executable. The executable + bit can be removed safely. + + **NON_OCTAL_PERMISSIONS** + Permission bits should use 4 digit octal permissions (like 0700 or 0444). + Avoid using any other base like decimal. + + **NOT_UNIFIED_DIFF** + The patch file does not appear to be in unified-diff format. Please + regenerate the patch file before sending it to the maintainer. + + **PRINTF_0XDECIMAL** + Prefixing 0x with decimal output is defective and should be corrected. + + **TRAILING_STATEMENTS** + Trailing statements (for example after any conditional) should be + on the next line. + Like:: + + if (x == y) break; + + should be:: + + if (x == y) + break; diff --git a/Documentation/dev-tools/gcov.rst b/Documentation/dev-tools/gcov.rst index 9e989baae154..5fce2b06f229 100644 --- a/Documentation/dev-tools/gcov.rst +++ b/Documentation/dev-tools/gcov.rst @@ -124,6 +124,8 @@ box for setups where kernels are built and run on the same machine. In cases where the kernel runs on a separate machine, special preparations must be made, depending on where the gcov tool is used: +.. _gcov-test: + a) gcov is run on the TEST machine The gcov tool version on the test machine must be compatible with the @@ -143,6 +145,8 @@ a) gcov is run on the TEST machine machine. If any of the path components is symbolic link, the actual directory needs to be used instead (due to make's CURDIR handling). +.. _gcov-build: + b) gcov is run on the BUILD machine The following files need to be copied after each test case from test @@ -211,7 +215,7 @@ Appendix A: gather_on_build.sh ------------------------------ Sample script to gather coverage meta files on the build machine -(see 6a): +(see :ref:`Separated build and test machines a. <gcov-test>`): .. code-block:: sh @@ -244,7 +248,7 @@ Appendix B: gather_on_test.sh ----------------------------- Sample script to gather coverage data files on the test machine -(see 6b): +(see :ref:`Separated build and test machines b. <gcov-build>`): .. code-block:: sh diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst index 1b1cf4f5c9d9..010a2af1e7d9 100644 --- a/Documentation/dev-tools/index.rst +++ b/Documentation/dev-tools/index.rst @@ -7,6 +7,9 @@ be used to work on the kernel. For now, the documents have been pulled together without any significant effort to integrate them into a coherent whole; patches welcome! +A brief overview of testing-specific tools can be found in +Documentation/dev-tools/testing-overview.rst + .. class:: toc-title Table of contents @@ -14,6 +17,8 @@ whole; patches welcome! .. toctree:: :maxdepth: 2 + testing-overview + checkpatch coccinelle sparse kcov diff --git a/Documentation/dev-tools/testing-overview.rst b/Documentation/dev-tools/testing-overview.rst new file mode 100644 index 000000000000..b5b46709969c --- /dev/null +++ b/Documentation/dev-tools/testing-overview.rst @@ -0,0 +1,117 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================== +Kernel Testing Guide +==================== + + +There are a number of different tools for testing the Linux kernel, so knowing +when to use each of them can be a challenge. This document provides a rough +overview of their differences, and how they fit together. + + +Writing and Running Tests +========================= + +The bulk of kernel tests are written using either the kselftest or KUnit +frameworks. These both provide infrastructure to help make running tests and +groups of tests easier, as well as providing helpers to aid in writing new +tests. + +If you're looking to verify the behaviour of the Kernel — particularly specific +parts of the kernel — then you'll want to use KUnit or kselftest. + + +The Difference Between KUnit and kselftest +------------------------------------------ + +KUnit (Documentation/dev-tools/kunit/index.rst) is an entirely in-kernel system +for "white box" testing: because test code is part of the kernel, it can access +internal structures and functions which aren't exposed to userspace. + +KUnit tests therefore are best written against small, self-contained parts +of the kernel, which can be tested in isolation. This aligns well with the +concept of 'unit' testing. + +For example, a KUnit test might test an individual kernel function (or even a +single codepath through a function, such as an error handling case), rather +than a feature as a whole. + +This also makes KUnit tests very fast to build and run, allowing them to be +run frequently as part of the development process. + +There is a KUnit test style guide which may give further pointers in +Documentation/dev-tools/kunit/style.rst + + +kselftest (Documentation/dev-tools/kselftest.rst), on the other hand, is +largely implemented in userspace, and tests are normal userspace scripts or +programs. + +This makes it easier to write more complicated tests, or tests which need to +manipulate the overall system state more (e.g., spawning processes, etc.). +However, it's not possible to call kernel functions directly from kselftest. +This means that only kernel functionality which is exposed to userspace somehow +(e.g. by a syscall, device, filesystem, etc.) can be tested with kselftest. To +work around this, some tests include a companion kernel module which exposes +more information or functionality. If a test runs mostly or entirely within the +kernel, however, KUnit may be the more appropriate tool. + +kselftest is therefore suited well to tests of whole features, as these will +expose an interface to userspace, which can be tested, but not implementation +details. This aligns well with 'system' or 'end-to-end' testing. + +For example, all new system calls should be accompanied by kselftest tests. + +Code Coverage Tools +=================== + +The Linux Kernel supports two different code coverage measurement tools. These +can be used to verify that a test is executing particular functions or lines +of code. This is useful for determining how much of the kernel is being tested, +and for finding corner-cases which are not covered by the appropriate test. + +:doc:`gcov` is GCC's coverage testing tool, which can be used with the kernel +to get global or per-module coverage. Unlike KCOV, it does not record per-task +coverage. Coverage data can be read from debugfs, and interpreted using the +usual gcov tooling. + +:doc:`kcov` is a feature which can be built in to the kernel to allow +capturing coverage on a per-task level. It's therefore useful for fuzzing and +other situations where information about code executed during, for example, a +single syscall is useful. + + +Dynamic Analysis Tools +====================== + +The kernel also supports a number of dynamic analysis tools, which attempt to +detect classes of issues when they occur in a running kernel. These typically +each look for a different class of bugs, such as invalid memory accesses, +concurrency issues such as data races, or other undefined behaviour like +integer overflows. + +Some of these tools are listed below: + +* kmemleak detects possible memory leaks. See + Documentation/dev-tools/kmemleak.rst +* KASAN detects invalid memory accesses such as out-of-bounds and + use-after-free errors. See Documentation/dev-tools/kasan.rst +* UBSAN detects behaviour that is undefined by the C standard, like integer + overflows. See Documentation/dev-tools/ubsan.rst +* KCSAN detects data races. See Documentation/dev-tools/kcsan.rst +* KFENCE is a low-overhead detector of memory issues, which is much faster than + KASAN and can be used in production. See Documentation/dev-tools/kfence.rst +* lockdep is a locking correctness validator. See + Documentation/locking/lockdep-design.rst +* There are several other pieces of debug instrumentation in the kernel, many + of which can be found in lib/Kconfig.debug + +These tools tend to test the kernel as a whole, and do not "pass" like +kselftest or KUnit tests. They can be combined with KUnit or kselftest by +running tests on a kernel with these tools enabled: you can then be sure +that none of these errors are occurring during the test. + +Some of these tools integrate with KUnit or kselftest and will +automatically fail tests if an issue is detected. + diff --git a/Documentation/devicetree/bindings/submitting-patches.rst b/Documentation/devicetree/bindings/submitting-patches.rst index 68129ff09967..1d11c25249ff 100644 --- a/Documentation/devicetree/bindings/submitting-patches.rst +++ b/Documentation/devicetree/bindings/submitting-patches.rst @@ -75,8 +75,8 @@ II. For kernel maintainers binding, and it hasn't received an Acked-by from the devicetree maintainers after a few weeks, go ahead and take it. - Subsystem bindings (anything affecting more than a single device) - then getting a devicetree maintainer to review it is required. + For subsystem bindings (anything affecting more than a single device), + getting a devicetree maintainer to review it is required. 3) For a series going though multiple trees, the binding patch should be kept with the driver using the binding. diff --git a/Documentation/driver-api/driver-model/class.rst b/Documentation/driver-api/driver-model/class.rst deleted file mode 100644 index fff55b80e86a..000000000000 --- a/Documentation/driver-api/driver-model/class.rst +++ /dev/null @@ -1,149 +0,0 @@ -============== -Device Classes -============== - -Introduction -~~~~~~~~~~~~ -A device class describes a type of device, like an audio or network -device. The following device classes have been identified: - -<Insert List of Device Classes Here> - - -Each device class defines a set of semantics and a programming interface -that devices of that class adhere to. Device drivers are the -implementation of that programming interface for a particular device on -a particular bus. - -Device classes are agnostic with respect to what bus a device resides -on. - - -Programming Interface -~~~~~~~~~~~~~~~~~~~~~ -The device class structure looks like:: - - - typedef int (*devclass_add)(struct device *); - typedef void (*devclass_remove)(struct device *); - -See the kerneldoc for the struct class. - -A typical device class definition would look like:: - - struct device_class input_devclass = { - .name = "input", - .add_device = input_add_device, - .remove_device = input_remove_device, - }; - -Each device class structure should be exported in a header file so it -can be used by drivers, extensions and interfaces. - -Device classes are registered and unregistered with the core using:: - - int devclass_register(struct device_class * cls); - void devclass_unregister(struct device_class * cls); - - -Devices -~~~~~~~ -As devices are bound to drivers, they are added to the device class -that the driver belongs to. Before the driver model core, this would -typically happen during the driver's probe() callback, once the device -has been initialized. It now happens after the probe() callback -finishes from the core. - -The device is enumerated in the class. Each time a device is added to -the class, the class's devnum field is incremented and assigned to the -device. The field is never decremented, so if the device is removed -from the class and re-added, it will receive a different enumerated -value. - -The class is allowed to create a class-specific structure for the -device and store it in the device's class_data pointer. - -There is no list of devices in the device class. Each driver has a -list of devices that it supports. The device class has a list of -drivers of that particular class. To access all of the devices in the -class, iterate over the device lists of each driver in the class. - - -Device Drivers -~~~~~~~~~~~~~~ -Device drivers are added to device classes when they are registered -with the core. A driver specifies the class it belongs to by setting -the struct device_driver::devclass field. - - -sysfs directory structure -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There is a top-level sysfs directory named 'class'. - -Each class gets a directory in the class directory, along with two -default subdirectories:: - - class/ - `-- input - |-- devices - `-- drivers - - -Drivers registered with the class get a symlink in the drivers/ directory -that points to the driver's directory (under its bus directory):: - - class/ - `-- input - |-- devices - `-- drivers - `-- usb:usb_mouse -> ../../../bus/drivers/usb_mouse/ - - -Each device gets a symlink in the devices/ directory that points to the -device's directory in the physical hierarchy:: - - class/ - `-- input - |-- devices - | `-- 1 -> ../../../root/pci0/00:1f.0/usb_bus/00:1f.2-1:0/ - `-- drivers - - -Exporting Attributes -~~~~~~~~~~~~~~~~~~~~ - -:: - - struct devclass_attribute { - struct attribute attr; - ssize_t (*show)(struct device_class *, char * buf, size_t count, loff_t off); - ssize_t (*store)(struct device_class *, const char * buf, size_t count, loff_t off); - }; - -Class drivers can export attributes using the DEVCLASS_ATTR macro that works -similarly to the DEVICE_ATTR macro for devices. For example, a definition -like this:: - - static DEVCLASS_ATTR(debug,0644,show_debug,store_debug); - -is equivalent to declaring:: - - static devclass_attribute devclass_attr_debug; - -The bus driver can add and remove the attribute from the class's -sysfs directory using:: - - int devclass_create_file(struct device_class *, struct devclass_attribute *); - void devclass_remove_file(struct device_class *, struct devclass_attribute *); - -In the example above, the file will be named 'debug' in placed in the -class's directory in sysfs. - - -Interfaces -~~~~~~~~~~ -There may exist multiple mechanisms for accessing the same device of a -particular class type. Device interfaces describe these mechanisms. - -When a device is added to a device class, the core attempts to add it -to every interface that is registered with the device class. diff --git a/Documentation/driver-api/driver-model/device.rst b/Documentation/driver-api/driver-model/device.rst index b9b022371e85..0833be568b06 100644 --- a/Documentation/driver-api/driver-model/device.rst +++ b/Documentation/driver-api/driver-model/device.rst @@ -63,8 +63,14 @@ Attributes are declared using a macro called DEVICE_ATTR:: Example::: - static DEVICE_ATTR(type, 0444, show_type, NULL); - static DEVICE_ATTR(power, 0644, show_power, store_power); + static DEVICE_ATTR(type, 0444, type_show, NULL); + static DEVICE_ATTR(power, 0644, power_show, power_store); + +Helper macros are available for common values of mode, so the above examples +can be simplified to::: + + static DEVICE_ATTR_RO(type); + static DEVICE_ATTR_RW(power); This declares two structures of type struct device_attribute with respective names 'dev_attr_type' and 'dev_attr_power'. These two attributes can be @@ -76,19 +82,24 @@ organized as follows into a group:: NULL, }; - static struct attribute_group dev_attr_group = { + static struct attribute_group dev_group = { .attrs = dev_attrs, }; - static const struct attribute_group *dev_attr_groups[] = { - &dev_attr_group, + static const struct attribute_group *dev_groups[] = { + &dev_group, NULL, }; +A helper macro is available for the common case of a single group, so the +above two structures can be declared using::: + + ATTRIBUTE_GROUPS(dev); + This array of groups can then be associated with a device by setting the group pointer in struct device before device_register() is invoked:: - dev->groups = dev_attr_groups; + dev->groups = dev_groups; device_register(dev); The device_register() function will use the 'groups' pointer to create the diff --git a/Documentation/driver-api/driver-model/index.rst b/Documentation/driver-api/driver-model/index.rst index 755016422269..4831bdd92e5c 100644 --- a/Documentation/driver-api/driver-model/index.rst +++ b/Documentation/driver-api/driver-model/index.rst @@ -7,7 +7,6 @@ Driver Model binding bus - class design-patterns device devres diff --git a/Documentation/driver-api/gpio/intro.rst b/Documentation/driver-api/gpio/intro.rst index 94dd7185e76e..2e924fb5b3d5 100644 --- a/Documentation/driver-api/gpio/intro.rst +++ b/Documentation/driver-api/gpio/intro.rst @@ -27,7 +27,7 @@ What is a GPIO? =============== A "General Purpose Input/Output" (GPIO) is a flexible software-controlled -digital signal. They are provided from many kinds of chip, and are familiar +digital signal. They are provided from many kinds of chips, and are familiar to Linux developers working with embedded and custom hardware. Each GPIO represents a bit connected to a particular pin, or "ball" on Ball Grid Array (BGA) packages. Board schematics show which external hardware connects to diff --git a/Documentation/fb/fbcon.rst b/Documentation/fb/fbcon.rst index 57f66de2f7e1..212f7003cfba 100644 --- a/Documentation/fb/fbcon.rst +++ b/Documentation/fb/fbcon.rst @@ -207,9 +207,9 @@ Documentation/driver-api/console.rst. To summarize: Echo a value to the bind file that represents the framebuffer console driver. So assuming vtcon1 represents fbcon, then:: - echo 1 > sys/class/vtconsole/vtcon1/bind - attach framebuffer console to + echo 1 > /sys/class/vtconsole/vtcon1/bind - attach framebuffer console to console layer - echo 0 > sys/class/vtconsole/vtcon1/bind - detach framebuffer console from + echo 0 > /sys/class/vtconsole/vtcon1/bind - detach framebuffer console from console layer If fbcon is detached from the console layer, your boot console driver (which is diff --git a/Documentation/features/arch-support.txt b/Documentation/features/arch-support.txt index d22a1095e661..118ae031840b 100644 --- a/Documentation/features/arch-support.txt +++ b/Documentation/features/arch-support.txt @@ -8,4 +8,5 @@ The meaning of entries in the tables is: | ok | # feature supported by the architecture |TODO| # feature not yet supported by the architecture | .. | # feature cannot be supported by the hardware + | N/A| # feature doesn't apply to the architecture diff --git a/Documentation/features/vm/TLB/arch-support.txt b/Documentation/features/vm/TLB/arch-support.txt index 48a5ca548399..e1c3a4c4d107 100644 --- a/Documentation/features/vm/TLB/arch-support.txt +++ b/Documentation/features/vm/TLB/arch-support.txt @@ -9,7 +9,7 @@ | alpha: | TODO | | arc: | TODO | | arm: | TODO | - | arm64: | TODO | + | arm64: | N/A | | csky: | TODO | | h8300: | .. | | hexagon: | TODO | diff --git a/Documentation/filesystems/api-summary.rst b/Documentation/filesystems/api-summary.rst index a94f17d9b836..7e5c04c98619 100644 --- a/Documentation/filesystems/api-summary.rst +++ b/Documentation/filesystems/api-summary.rst @@ -101,6 +101,9 @@ Other Functions .. kernel-doc:: fs/xattr.c :export: +.. kernel-doc:: fs/namespace.c + :export: + The proc filesystem =================== @@ -122,6 +125,12 @@ Events based on file descriptors .. kernel-doc:: fs/eventfd.c :export: +eventpoll (epoll) interfaces +============================ + +.. kernel-doc:: fs/eventpoll.c + :internal: + The Filesystem for Exporting Kernel Objects =========================================== diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index 48fbfc336ebf..81bfe3c800cc 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -540,7 +540,9 @@ encoded manner. The codes are the following: ac area is accountable nr swap space is not reserved for the area ht area uses huge tlb pages + sf synchronous page fault ar architecture specific flag + wf wipe on fork dd do not include area into core dump sd soft dirty flag mm mixed map area @@ -549,6 +551,8 @@ encoded manner. The codes are the following: mg mergable advise flag bt arm64 BTI guarded page mt arm64 MTE allocation tags are enabled + um userfaultfd missing tracking + uw userfaultfd wr-protect tracking == ======================================= Note that there is no guarantee that every flag and associated mnemonic will diff --git a/Documentation/filesystems/vfat.rst b/Documentation/filesystems/vfat.rst index e85d74e91295..760a4d83fdf9 100644 --- a/Documentation/filesystems/vfat.rst +++ b/Documentation/filesystems/vfat.rst @@ -189,7 +189,7 @@ VFAT MOUNT OPTIONS **discard** If set, issues discard/TRIM commands to the block device when blocks are freed. This is useful for SSD devices - and sparse/thinly-provisoned LUNs. + and sparse/thinly-provisioned LUNs. **nfs=stale_rw|nostale_ro** Enable this only if you want to export the FAT filesystem diff --git a/Documentation/hid/intel-ish-hid.rst b/Documentation/hid/intel-ish-hid.rst index f6ce44ff611d..7a851252267a 100644 --- a/Documentation/hid/intel-ish-hid.rst +++ b/Documentation/hid/intel-ish-hid.rst @@ -345,7 +345,7 @@ Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space. To debug ISH, event tracing mechanism is used. To enable debug logs:: echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable - cat sys/kernel/debug/tracing/trace + cat /sys/kernel/debug/tracing/trace 3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260 ----------------------------------------------------- diff --git a/Documentation/index.rst b/Documentation/index.rst index 31f2adc8542d..54ce34fd6fbd 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -149,27 +149,11 @@ Architecture-agnostic documentation Architecture-specific documentation ----------------------------------- -These books provide programming details about architecture-specific -implementation. - .. toctree:: :maxdepth: 2 - arm/index - arm64/index - ia64/index - m68k/index - mips/index - nios2/index - openrisc/index - parisc/index - powerpc/index - riscv/index - s390/index - sh/index - sparc/index - x86/index - xtensa/index + arch + Other documentation ------------------- diff --git a/Documentation/input/event-codes.rst b/Documentation/input/event-codes.rst index 3118fc1c1e26..b24ae7d292cc 100644 --- a/Documentation/input/event-codes.rst +++ b/Documentation/input/event-codes.rst @@ -246,9 +246,9 @@ A few EV_ABS codes have special meanings: A device should set the resolution of the axis to indicate whether the pressure is in measurable units. If the resolution is zero, the - pressure data is in arbitrary units. If the resolution is nonzero, the + pressure data is in arbitrary units. If the resolution is non-zero, the pressure data is in units/gram. For example, a value of 10 with a - resolution of 1 represents 10 gram, a value of 10 with a resolution on + resolution of 1 represents 10 gram, a value of 10 with a resolution of 1000 represents 10 microgram. EV_SW @@ -344,7 +344,7 @@ INPUT_PROP_BUTTONPAD For touchpads where the button is placed beneath the surface, such that pressing down on the pad causes a button click, this property should be -set. Common in clickpad notebooks and macbooks from 2009 and onwards. +set. Common in Clickpad notebooks and Macbooks from 2009 and onwards. Originally, the buttonpad property was coded into the bcm5974 driver version field under the name integrated button. For backwards @@ -356,7 +356,7 @@ INPUT_PROP_SEMI_MT Some touchpads, most common between 2008 and 2011, can detect the presence of multiple contacts without resolving the individual positions; only the number of contacts and a rectangular shape is known. For such -touchpads, the semi-mt property should be set. +touchpads, the SEMI_MT property should be set. Depending on the device, the rectangle may enclose all touches, like a bounding box, or just some of them, for instance the two most recent @@ -394,7 +394,7 @@ Guidelines ========== The guidelines below ensure proper single-touch and multi-finger functionality. -For multi-touch functionality, see the multi-touch-protocol.txt document for +For multi-touch functionality, see the multi-touch-protocol.rst document for more information. Mice diff --git a/Documentation/input/ff.rst b/Documentation/input/ff.rst index 0c02e87ee86d..5a1da42c33b3 100644 --- a/Documentation/input/ff.rst +++ b/Documentation/input/ff.rst @@ -16,8 +16,8 @@ goal is not to support these devices as if they were simple input-only devices (as it is already the case), but to really enable the rendering of force effects. This document only describes the force feedback part of the Linux input -interface. Please read joystick.txt and input.txt before reading further this -document. +interface. Please read joydev/joystick.rst and input.rst before reading further +this document. Instructions to the user ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -36,7 +36,7 @@ should keep a hand on your device, in order to avoid it to break down if something goes wrong. If you have a serial iforce device, you need to start inputattach. See -joystick.txt for details. +joydev/joystick.rst for details. Does it work ? -------------- diff --git a/Documentation/input/gameport-programming.rst b/Documentation/input/gameport-programming.rst index c96911df1c54..7d7063ad0f9f 100644 --- a/Documentation/input/gameport-programming.rst +++ b/Documentation/input/gameport-programming.rst @@ -21,7 +21,7 @@ choose which one to program the hardware to, starting from the more exotic addresses is preferred, because the likelihood of clashing with the standard 0x201 address is smaller. -Eg. if your driver supports addresses 0x200, 0x208, 0x210 and 0x218, then +E.g. if your driver supports addresses 0x200, 0x208, 0x210 and 0x218, then 0x218 would be the address of first choice. If your hardware supports a gameport address that is not mapped to ISA io @@ -78,7 +78,7 @@ the gameport. To register a cooked gameport:: for (i = 0; i < 4; i++) axes[i] = my_mmio[i]; - buttons[i] = my_mmio[4]; + buttons[0] = my_mmio[4]; } int my_open(struct gameport *gameport, int mode) @@ -117,25 +117,28 @@ Simple:: The gameport structure ~~~~~~~~~~~~~~~~~~~~~~ -.. note:: - - This section is outdated. There are several fields here that don't - match what's there at include/linux/gameport.h. - :: struct gameport { - void *private; + void *port_data; A private pointer for free use in the gameport driver. (Not the joystick driver!) :: - int number; + char name[32]; + +Driver's name as set by driver calling gameport_set_name(). Informational +purpose only. + +:: + + char phys[32]; -Number assigned to the gameport when registered. Informational purpose only. +gameport's physical name/description as set by driver calling gameport_set_phys(). +Informational purpose only. :: @@ -210,8 +213,16 @@ gameport. :: - struct gameport_dev *dev; - struct gameport *next; + struct timer_list poll_timer; + unsigned int poll_interval; /* in msecs */ + spinlock_t timer_lock; + unsigned int poll_cnt; + void (*poll_handler)(struct gameport *); + struct gameport *parent, *child; + struct gameport_driver *drv; + struct mutex drv_mutex; /* protects serio->drv so attributes can pin driver */ + struct device dev; + struct list_head node; For internal use by the gameport layer. diff --git a/Documentation/input/input-programming.rst b/Documentation/input/input-programming.rst index 5938145b0e35..2638dce69764 100644 --- a/Documentation/input/input-programming.rst +++ b/Documentation/input/input-programming.rst @@ -120,7 +120,7 @@ Then there is the:: call to tell those who receive the events that we've sent a complete report. This doesn't seem important in the one button case, but is quite important -for for example mouse movement, where you don't want the X and Y values +for example for mouse movement, where you don't want the X and Y values to be interpreted separately, because that'd result in a different movement. dev->open() and dev->close() @@ -128,7 +128,7 @@ dev->open() and dev->close() In case the driver has to repeatedly poll the device, because it doesn't have an interrupt coming from it and the polling is too expensive to be done -all the time, or if the device uses a valuable resource (eg. interrupt), it +all the time, or if the device uses a valuable resource (e.g. interrupt), it can use the open and close callback to know when it can stop polling or release the interrupt and when it must resume polling or grab the interrupt again. To do that, we would add this to our example driver:: @@ -161,7 +161,7 @@ makes sure that dev->open() is called only when the first user connects to the device and that dev->close() is called when the very last user disconnects. Calls to both callbacks are serialized. -The open() callback should return a 0 in case of success or any nonzero value +The open() callback should return a 0 in case of success or any non-zero value in case of failure. The close() callback (which is void) must always succeed. Inhibiting input devices @@ -182,8 +182,8 @@ providing events to the input core. Calling the device's close() method on inhibit (if there are users) allows the driver to save power. Either by directly powering down the device or by -releasing the runtime-pm reference it got in open() when the driver is using -runtime-pm. +releasing the runtime-PM reference it got in open() when the driver is using +runtime-PM. Inhibiting and uninhibiting are orthogonal to opening and closing the device by input handlers. Userspace might want to inhibit a device in anticipation before @@ -219,8 +219,8 @@ It's reported to the input system via:: input_report_key(struct input_dev *dev, int code, int value) See uapi/linux/input-event-codes.h for the allowable values of code (from 0 to -KEY_MAX). Value is interpreted as a truth value, ie any nonzero value means key -pressed, zero value means key released. The input code generates events only +KEY_MAX). Value is interpreted as a truth value, i.e. any non-zero value means +key pressed, zero value means key released. The input code generates events only in case the value is different from before. In addition to EV_KEY, there are two more basic event types: EV_REL and @@ -231,12 +231,12 @@ because it doesn't have any absolute coordinate system to work in. Absolute events are namely for joysticks and digitizers - devices that do work in an absolute coordinate systems. -Having the device report EV_REL buttons is as simple as with EV_KEY, simply +Having the device report EV_REL buttons is as simple as with EV_KEY; simply set the corresponding bits and call the:: input_report_rel(struct input_dev *dev, int code, int value) -function. Events are generated only for nonzero value. +function. Events are generated only for non-zero values. However EV_ABS requires a little special care. Before calling input_register_device, you have to fill additional fields in the input_dev @@ -280,7 +280,7 @@ device driver. It's a string like 'Generic button device' containing a user friendly name of the device. The id* fields contain the bus ID (PCI, USB, ...), vendor ID and device ID -of the device. The bus IDs are defined in input.h. The vendor and device ids +of the device. The bus IDs are defined in input.h. The vendor and device IDs are defined in pci_ids.h, usb_ids.h and similar include files. These fields should be set by the input device driver before registering it. diff --git a/Documentation/input/input.rst b/Documentation/input/input.rst index 0eb61e67a7b7..2c67fa904adc 100644 --- a/Documentation/input/input.rst +++ b/Documentation/input/input.rst @@ -9,7 +9,7 @@ Introduction Architecture ============ -Input subsystem a collection of drivers that is designed to support +Input subsystem is a collection of drivers that is designed to support all input devices under Linux. Most of the drivers reside in drivers/input, although quite a few live in drivers/hid and drivers/platform. @@ -50,7 +50,7 @@ will be available as a character device on major 13, minor 63:: crw-r--r-- 1 root root 13, 63 Mar 28 22:45 mice -This device usually created automatically by the system. The commands +This device is usually created automatically by the system. The commands to create it by hand are:: cd /dev @@ -180,7 +180,7 @@ whole suite. It handles all HID devices, and because there is a very wide variety of them, and because the USB HID specification isn't simple, it needs to be this big. -Currently, it handles USB mice, joysticks, gamepads, steering wheels +Currently, it handles USB mice, joysticks, gamepads, steering wheels, keyboards, trackballs and digitizers. However, USB uses HID also for monitor controls, speaker controls, UPSs, @@ -268,7 +268,7 @@ events on a read. Their layout is:: }; ``time`` is the timestamp, it returns the time at which the event happened. -Type is for example EV_REL for relative moment, EV_KEY for a keypress or +Type is for example EV_REL for relative movement, EV_KEY for a keypress or release. More types are defined in include/uapi/linux/input-event-codes.h. ``code`` is event code, for example REL_X or KEY_BACKSPACE, again a complete diff --git a/Documentation/input/multi-touch-protocol.rst b/Documentation/input/multi-touch-protocol.rst index 21c1e6a22888..1085cbee4ee7 100644 --- a/Documentation/input/multi-touch-protocol.rst +++ b/Documentation/input/multi-touch-protocol.rst @@ -261,7 +261,7 @@ ABS_MT_PRESSURE signal intensity distribution. If the resolution is zero, the pressure data is in arbitrary units. - If the resolution is nonzero, the pressure data is in units/gram. See + If the resolution is non-zero, the pressure data is in units/gram. See :ref:`input-event-codes` for details. ABS_MT_DISTANCE @@ -279,14 +279,14 @@ ABS_MT_ORIENTATION max should be returned; when aligned with the X axis in the negative direction, the range -max should be returned. - Touch ellipsis are symmetrical by default. For devices capable of true 360 + Touch ellipses are symmetrical by default. For devices capable of true 360 degree orientation, the reported orientation must exceed the range max to indicate more than a quarter of a revolution. For an upside-down finger, range max * 2 should be returned. Orientation can be omitted if the touch area is circular, or if the information is not available in the kernel driver. Partial orientation - support is possible if the device can distinguish between the two axis, but + support is possible if the device can distinguish between the two axes, but not (uniquely) any values in between. In such cases, the range of ABS_MT_ORIENTATION should be [0, 1] [#f4]_. @@ -356,7 +356,7 @@ The range of ABS_MT_ORIENTATION should be set to [0, 1], to indicate that the device can distinguish between a finger along the Y axis (0) and a finger along the X axis (1). -For win8 devices with both T and C coordinates, the position mapping is:: +For Win8 devices with both T and C coordinates, the position mapping is:: ABS_MT_POSITION_X := T_X ABS_MT_POSITION_Y := T_Y diff --git a/Documentation/input/notifier.rst b/Documentation/input/notifier.rst index 161350cb865e..824379399e61 100644 --- a/Documentation/input/notifier.rst +++ b/Documentation/input/notifier.rst @@ -4,11 +4,12 @@ Keyboard notifier One can use register_keyboard_notifier to get called back on keyboard events (see kbd_keycode() function for details). The passed structure is -keyboard_notifier_param: +keyboard_notifier_param (see <linux/keyboard.h>): - 'vc' always provide the VC for which the keyboard event applies; - 'down' is 1 for a key press event, 0 for a key release; - 'shift' is the current modifier state, mask bit indexes are KG_*; +- 'ledstate' is the current LED state; - 'value' depends on the type of event. - KBD_KEYCODE events are always sent before other events, value is the keycode. diff --git a/Documentation/input/uinput.rst b/Documentation/input/uinput.rst index 10c62e62a0a6..30fe80e325a5 100644 --- a/Documentation/input/uinput.rst +++ b/Documentation/input/uinput.rst @@ -179,7 +179,7 @@ uinput old interface -------------------- Before uinput version 5, there wasn't a dedicated ioctl to set up a virtual -device. Programs supportinf older versions of uinput interface need to fill +device. Programs supporting older versions of uinput interface need to fill a uinput_user_dev structure and write it to the uinput file descriptor to configure the new uinput device. New code should not use the old interface but interact with uinput via ioctl calls, or use libevdev. diff --git a/Documentation/leds/leds-lm3556.rst b/Documentation/leds/leds-lm3556.rst index 1ef17d7d800e..32e3983473ba 100644 --- a/Documentation/leds/leds-lm3556.rst +++ b/Documentation/leds/leds-lm3556.rst @@ -23,7 +23,7 @@ from 93.75 mA to 1500 mA.The Flash currents are adjusted via the CURRENT CONTROL REGISTER(0x09).Flash mode is activated by the ENABLE REGISTER(0x0A), or by pulling the STROBE pin HIGH. -LM3556 Flash can be controlled through sys/class/leds/flash/brightness file +LM3556 Flash can be controlled through /sys/class/leds/flash/brightness file * if STROBE pin is enabled, below example control brightness only, and ON / OFF will be controlled by STROBE pin. @@ -32,17 +32,17 @@ Flash Example: OFF:: - #echo 0 > sys/class/leds/flash/brightness + #echo 0 > /sys/class/leds/flash/brightness 93.75 mA:: - #echo 1 > sys/class/leds/flash/brightness + #echo 1 > /sys/class/leds/flash/brightness ... 1500 mA:: - #echo 16 > sys/class/leds/flash/brightness + #echo 16 > /sys/class/leds/flash/brightness Torch Mode ^^^^^^^^^^ @@ -51,7 +51,7 @@ In Torch Mode, the current source(LED) is programmed via the CURRENT CONTROL REGISTER(0x09).Torch Mode is activated by the ENABLE REGISTER(0x0A) or by the hardware TORCH input. -LM3556 torch can be controlled through sys/class/leds/torch/brightness file. +LM3556 torch can be controlled through /sys/class/leds/torch/brightness file. * if TORCH pin is enabled, below example control brightness only, and ON / OFF will be controlled by TORCH pin. @@ -59,22 +59,22 @@ Torch Example: OFF:: - #echo 0 > sys/class/leds/torch/brightness + #echo 0 > /sys/class/leds/torch/brightness 46.88 mA:: - #echo 1 > sys/class/leds/torch/brightness + #echo 1 > /sys/class/leds/torch/brightness ... 375 mA:: - #echo 8 > sys/class/leds/torch/brightness + #echo 8 > /sys/class/leds/torch/brightness Indicator Mode ^^^^^^^^^^^^^^ -Indicator pattern can be set through sys/class/leds/indicator/pattern file, +Indicator pattern can be set through /sys/class/leds/indicator/pattern file, and 4 patterns are pre-defined in indicator_pattern array. According to N-lank, Pulse time and N Period values, different pattern wiill @@ -87,13 +87,13 @@ Indicator pattern example: pattern 0:: - #echo 0 > sys/class/leds/indicator/pattern + #echo 0 > /sys/class/leds/indicator/pattern ... pattern 3:: - #echo 3 > sys/class/leds/indicator/pattern + #echo 3 > /sys/class/leds/indicator/pattern Indicator brightness can be controlled through sys/class/leds/indicator/brightness file. @@ -102,17 +102,17 @@ Example: OFF:: - #echo 0 > sys/class/leds/indicator/brightness + #echo 0 > /sys/class/leds/indicator/brightness 5.86 mA:: - #echo 1 > sys/class/leds/indicator/brightness + #echo 1 > /sys/class/leds/indicator/brightness ... 46.875mA:: - #echo 8 > sys/class/leds/indicator/brightness + #echo 8 > /sys/class/leds/indicator/brightness Notes ----- diff --git a/Documentation/livepatch/shadow-vars.rst b/Documentation/livepatch/shadow-vars.rst index c05715aeafa4..6a7d43a8787d 100644 --- a/Documentation/livepatch/shadow-vars.rst +++ b/Documentation/livepatch/shadow-vars.rst @@ -165,8 +165,8 @@ In-flight parent objects Sometimes it may not be convenient or possible to allocate shadow variables alongside their parent objects. Or a livepatch fix may -require shadow varibles to only a subset of parent object instances. In -these cases, the klp_shadow_get_or_alloc() call can be used to attach +require shadow variables for only a subset of parent object instances. +In these cases, the klp_shadow_get_or_alloc() call can be used to attach shadow variables to parents already in-flight. For commit 1d147bfa6429, a good spot to allocate a shadow spinlock is diff --git a/Documentation/powerpc/booting.rst b/Documentation/powerpc/booting.rst index 2d0ec2ff2b57..11aa440f98cc 100644 --- a/Documentation/powerpc/booting.rst +++ b/Documentation/powerpc/booting.rst @@ -94,7 +94,7 @@ should: a) add your platform support as a _boolean_ option in arch/powerpc/Kconfig, following the example of PPC_PSERIES, - PPC_PMAC and PPC_MAPLE. The later is probably a good + PPC_PMAC and PPC_MAPLE. The latter is probably a good example of a board support to start from. b) create your main platform file as diff --git a/Documentation/powerpc/dawr-power9.rst b/Documentation/powerpc/dawr-power9.rst index c96ab6befd9c..e55ac6a24b97 100644 --- a/Documentation/powerpc/dawr-power9.rst +++ b/Documentation/powerpc/dawr-power9.rst @@ -4,7 +4,7 @@ DAWR issues on POWER9 On POWER9 the Data Address Watchpoint Register (DAWR) can cause a checkstop if it points to cache inhibited (CI) memory. Currently Linux has no way to -disinguish CI memory when configuring the DAWR, so (for now) the DAWR is +distinguish CI memory when configuring the DAWR, so (for now) the DAWR is disabled by this commit:: commit 9654153158d3e0684a1bdb76dbababdb7111d5a0 diff --git a/Documentation/powerpc/eeh-pci-error-recovery.rst b/Documentation/powerpc/eeh-pci-error-recovery.rst index 438a87ebc095..d6643a91bdf8 100644 --- a/Documentation/powerpc/eeh-pci-error-recovery.rst +++ b/Documentation/powerpc/eeh-pci-error-recovery.rst @@ -73,7 +73,7 @@ return all-ff's (0xff, 0xffff, 0xffffffff for 8/16/32-bit reads). This value was chosen because it is the same value you would get if the device was physically unplugged from the slot. This includes access to PCI memory, I/O space, and PCI config -space. Interrupts; however, will continued to be delivered. +space. Interrupts; however, will continue to be delivered. Detection and recovery are performed with the aid of ppc64 firmware. The programming interfaces in the Linux kernel diff --git a/Documentation/powerpc/elfnote.rst b/Documentation/powerpc/elfnote.rst index 06602248621c..3ec8d61e9a33 100644 --- a/Documentation/powerpc/elfnote.rst +++ b/Documentation/powerpc/elfnote.rst @@ -8,7 +8,7 @@ capabilities and information which can be used by a bootloader or userland. Types and Descriptors --------------------- -The types to be used with the "PowerPC" namesapce are defined in [#f1]_. +The types to be used with the "PowerPC" namespace are defined in [#f1]_. 1) PPC_ELFNOTE_CAPABILITIES diff --git a/Documentation/powerpc/firmware-assisted-dump.rst b/Documentation/powerpc/firmware-assisted-dump.rst index 20ea8cdee0aa..e363fc48529a 100644 --- a/Documentation/powerpc/firmware-assisted-dump.rst +++ b/Documentation/powerpc/firmware-assisted-dump.rst @@ -171,7 +171,7 @@ that were present in CMA region:: (meta area) | | | - Metadata: This area holds a metadata struture whose + Metadata: This area holds a metadata structure whose address is registered with f/w and retrieved in the second kernel after crash, on platforms that support tags (OPAL). Having such structure with info needed @@ -207,7 +207,7 @@ Currently the dump will be copied from /proc/vmcore to a new file upon user intervention. The dump data available through /proc/vmcore will be in ELF format. Hence the existing kdump infrastructure (kdump scripts) to save the dump works fine with minor modifications. KDump scripts on -major Distro releases have already been modified to work seemlessly (no +major Distro releases have already been modified to work seamlessly (no user intervention in saving the dump) when FADump is used, instead of KDump, as dump mechanism. diff --git a/Documentation/powerpc/kaslr-booke32.rst b/Documentation/powerpc/kaslr-booke32.rst index 8b259fdfdf03..5681c1d1b65b 100644 --- a/Documentation/powerpc/kaslr-booke32.rst +++ b/Documentation/powerpc/kaslr-booke32.rst @@ -38,5 +38,5 @@ bit of the entropy to decide the index of the 64M zone. Then we chose a kernstart_virt_addr -To enable KASLR, set CONFIG_RANDOMIZE_BASE = y. If KASLR is enable and you +To enable KASLR, set CONFIG_RANDOMIZE_BASE = y. If KASLR is enabled and you want to disable it at runtime, add "nokaslr" to the kernel cmdline. diff --git a/Documentation/powerpc/mpc52xx.rst b/Documentation/powerpc/mpc52xx.rst index 30260707c3fe..5243b1763fad 100644 --- a/Documentation/powerpc/mpc52xx.rst +++ b/Documentation/powerpc/mpc52xx.rst @@ -34,7 +34,7 @@ To compile/use : Some remarks: - The port is named mpc52xxx, and config options are PPC_MPC52xx. The MGT5100 - is not supported, and I'm not sure anyone is interesting in working on it + is not supported, and I'm not sure anyone is interested in working on it so. I didn't took 5xxx because there's apparently a lot of 5xxx that have nothing to do with the MPC5200. I also included the 'MPC' for the same reason. diff --git a/Documentation/powerpc/papr_hcalls.rst b/Documentation/powerpc/papr_hcalls.rst index 48fcf1255a33..3d553e8a2937 100644 --- a/Documentation/powerpc/papr_hcalls.rst +++ b/Documentation/powerpc/papr_hcalls.rst @@ -40,7 +40,7 @@ and any in-arguments for the hcall are provided in registers *r4-r12*. If values have to be passed through a memory buffer, the data stored in that buffer should be in Big-endian byte order. -Once control is returns back to the guest after hypervisor has serviced the +Once control returns back to the guest after hypervisor has serviced the 'HVCS' instruction the return value of the hcall is available in *r3* and any out values are returned in registers *r4-r12*. Again like in case of in-arguments, any out values stored in a memory buffer will be in Big-endian byte order. @@ -147,7 +147,7 @@ corresponding opcode values please look into the arch specific header [4]_: | Out: *numBytesRead* | Return Value: *H_Success, H_Parameter, H_P2, H_P3, H_Hardware* -Given a DRC Index of an NVDIMM, read N-bytes from the the metadata area +Given a DRC Index of an NVDIMM, read N-bytes from the metadata area associated with it, at a specified offset and copy it to provided buffer. The metadata area stores configuration information such as label information, bad-blocks etc. The metadata area is located out-of-band of NVDIMM storage diff --git a/Documentation/powerpc/transactional_memory.rst b/Documentation/powerpc/transactional_memory.rst index b5b09bf00966..040a20675fd1 100644 --- a/Documentation/powerpc/transactional_memory.rst +++ b/Documentation/powerpc/transactional_memory.rst @@ -189,7 +189,7 @@ kernel aborted a transaction: ====================== ================================ These can be checked by the user program's abort handler as TEXASR[0:7]. If -bit 7 is set, it indicates that the error is consider persistent. For example +bit 7 is set, it indicates that the error is considered persistent. For example a TM_CAUSE_ALIGNMENT will be persistent while a TM_CAUSE_RESCHED will not. GDB @@ -271,4 +271,4 @@ with these lines: hrfid and mtmsrd have the same quirk. -The Linux kernel uses this quirk in it's early exception handling. +The Linux kernel uses this quirk in its early exception handling. diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 91de63b201c1..c66a19201deb 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -341,6 +341,16 @@ that you have sent your patches to the right place. Wait for a minimum of one week before resubmitting or pinging reviewers - possibly longer during busy times like merge windows. +It's also ok to resend the patch or the patch series after a couple of +weeks with the word "RESEND" added to the subject line:: + + [PATCH Vx RESEND] sub/sys: Condensed patch summary + +Don't add "RESEND" when you are submitting a modified version of your +patch or patch series - "RESEND" only applies to resubmission of a +patch or patch series which have not been modified in any way from the +previous submission. + Include PATCH in the subject ----------------------------- @@ -625,16 +635,19 @@ not considered part of the summary phrase, but describe how the patch should be treated. Common tags might include a version descriptor if the multiple versions of the patch have been sent out in response to comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for -comments. If there are four patches in a patch series the individual -patches may be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures -that developers understand the order in which the patches should be -applied and that they have reviewed or applied all of the patches in -the patch series. +comments. -A couple of example Subjects:: +If there are four patches in a patch series the individual patches may +be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures that developers +understand the order in which the patches should be applied and that +they have reviewed or applied all of the patches in the patch series. + +Here are some good example Subjects:: Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching Subject: [PATCH v2 01/27] x86: fix eflags tracking + Subject: [PATCH v2] sub/sys: Condensed patch summary + Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary The ``from`` line must be the very first line in the message body, and has the form: @@ -647,34 +660,54 @@ then the ``From:`` line from the email header will be used to determine the patch author in the changelog. The explanation body will be committed to the permanent source -changelog, so should make sense to a competent reader who has long -since forgotten the immediate details of the discussion that might -have led to this patch. Including symptoms of the failure which the -patch addresses (kernel log messages, oops messages, etc.) is -especially useful for people who might be searching the commit logs -looking for the applicable patch. If a patch fixes a compile failure, -it may not be necessary to include _all_ of the compile failures; just -enough that it is likely that someone searching for the patch can find -it. As in the ``summary phrase``, it is important to be both succinct as -well as descriptive. - -The ``---`` marker line serves the essential purpose of marking for patch -handling tools where the changelog message ends. - -One good use for the additional comments after the ``---`` marker is for -a ``diffstat``, to show what files have changed, and the number of -inserted and deleted lines per file. A ``diffstat`` is especially useful -on bigger patches. Other comments relevant only to the moment or the -maintainer, not suitable for the permanent changelog, should also go -here. A good example of such comments might be ``patch changelogs`` -which describe what has changed between the v1 and v2 version of the -patch. - -If you are going to include a ``diffstat`` after the ``---`` marker, please -use ``diffstat`` options ``-p 1 -w 70`` so that filenames are listed from -the top of the kernel source tree and don't use too much horizontal -space (easily fit in 80 columns, maybe with some indentation). (``git`` -generates appropriate diffstats by default.) +changelog, so should make sense to a competent reader who has long since +forgotten the immediate details of the discussion that might have led to +this patch. Including symptoms of the failure which the patch addresses +(kernel log messages, oops messages, etc.) are especially useful for +people who might be searching the commit logs looking for the applicable +patch. The text should be written in such detail so that when read +weeks, months or even years later, it can give the reader the needed +details to grasp the reasoning for **why** the patch was created. + +If a patch fixes a compile failure, it may not be necessary to include +_all_ of the compile failures; just enough that it is likely that +someone searching for the patch can find it. As in the ``summary +phrase``, it is important to be both succinct as well as descriptive. + +The ``---`` marker line serves the essential purpose of marking for +patch handling tools where the changelog message ends. + +One good use for the additional comments after the ``---`` marker is +for a ``diffstat``, to show what files have changed, and the number of +inserted and deleted lines per file. A ``diffstat`` is especially useful +on bigger patches. If you are going to include a ``diffstat`` after the +``---`` marker, please use ``diffstat`` options ``-p 1 -w 70`` so that +filenames are listed from the top of the kernel source tree and don't +use too much horizontal space (easily fit in 80 columns, maybe with some +indentation). (``git`` generates appropriate diffstats by default.) + +Other comments relevant only to the moment or the maintainer, not +suitable for the permanent changelog, should also go here. A good +example of such comments might be ``patch changelogs`` which describe +what has changed between the v1 and v2 version of the patch. + +Please put this information **after** the ``---`` line which separates +the changelog from the rest of the patch. The version information is +not part of the changelog which gets committed to the git tree. It is +additional information for the reviewers. If it's placed above the +commit tags, it needs manual interaction to remove it. If it is below +the separator line, it gets automatically stripped off when applying the +patch:: + + <commit message> + ... + Signed-off-by: Author <author@mail> + --- + V2 -> V3: Removed redundant helper function + V1 -> V2: Cleaned up coding style and addressed review comments + + path/to/file | 5+++-- + ... See more details on the proper patch format in the following references. diff --git a/Documentation/scsi/ChangeLog.megaraid b/Documentation/scsi/ChangeLog.megaraid index d2052fdbedd2..cbb329956897 100644 --- a/Documentation/scsi/ChangeLog.megaraid +++ b/Documentation/scsi/ChangeLog.megaraid @@ -220,7 +220,7 @@ Older Version : 2.20.4.5 (scsi module), 2.20.2.5 (cmm module) 4. Use the pre defined DMA mask constants from dma-mapping.h Use the DMA_{64,32}BIT_MASK constants from dma-mapping.h when calling - pci_set_dma_mask() or pci_set_consistend_dma_mask(). See + pci_set_dma_mask() or pci_set_consistent_dma_mask(). See http://marc.theaimsgroup.com/?t=108001993000001&r=1&w=2 for more details. Signed-off-by: Tobias Klauser <tklauser@nuerscht.ch> diff --git a/Documentation/sphinx/rstFlatTable.py b/Documentation/sphinx/rstFlatTable.py index a3eea0bbe6ba..16bea0632555 100755 --- a/Documentation/sphinx/rstFlatTable.py +++ b/Documentation/sphinx/rstFlatTable.py @@ -22,7 +22,7 @@ u""" * *auto span* rightmost cell of a table row over the missing cells on the right side of that table-row. With Option ``:fill-cells:`` this behavior - can changed from *auto span* to *auto fill*, which automaticly inserts + can be changed from *auto span* to *auto fill*, which automatically inserts (empty) cells instead of spanning the last cell. Options: @@ -161,7 +161,7 @@ class ListTableBuilder(object): for colwidth in colwidths: colspec = nodes.colspec(colwidth=colwidth) # FIXME: It seems, that the stub method only works well in the - # absence of rowspan (observed by the html buidler, the docutils-xml + # absence of rowspan (observed by the html builder, the docutils-xml # build seems OK). This is not extraordinary, because there exists # no table directive (except *this* flat-table) which allows to # define coexistent of rowspan and stubs (there was no use-case diff --git a/Documentation/spi/butterfly.rst b/Documentation/spi/butterfly.rst index e614a589547c..56088fb090c7 100644 --- a/Documentation/spi/butterfly.rst +++ b/Documentation/spi/butterfly.rst @@ -11,7 +11,7 @@ develop firmware for this, and flash it using this adapter cable. You can make this adapter from an old printer cable and solder things directly to the Butterfly. Or (if you have the parts and skills) you -can come up with something fancier, providing ciruit protection to the +can come up with something fancier, providing circuit protection to the Butterfly and the printer port, or with a better power supply than two signal pins from the printer port. Or for that matter, you can use similar cables to talk to many AVR boards, even a breadboard. diff --git a/Documentation/translations/it_IT/doc-guide/sphinx.rst b/Documentation/translations/it_IT/doc-guide/sphinx.rst index 090d2949d345..0046d75d9a70 100644 --- a/Documentation/translations/it_IT/doc-guide/sphinx.rst +++ b/Documentation/translations/it_IT/doc-guide/sphinx.rst @@ -330,17 +330,17 @@ la lista di celle che compongono la *riga* stessa. Fanno eccezione i *commenti* - head col 3 - head col 4 - * - column 1 + * - row 1 - field 1.1 - field 1.2 with autospan - * - column 2 + * - row 2 - field 2.1 - :rspan:`1` :cspan:`1` field 2.2 - 3.3 * .. _`it last row`: - - column 3 + - row 3 Che verrà rappresentata nel seguente modo: @@ -352,37 +352,46 @@ Che verrà rappresentata nel seguente modo: - head col 3 - head col 4 - * - column 1 + * - row 1 - field 1.1 - field 1.2 with autospan - * - column 2 + * - row 2 - field 2.1 - :rspan:`1` :cspan:`1` field 2.2 - 3.3 * .. _`it last row`: - - column 3 + - row 3 Riferimenti incrociati ---------------------- -Per fare dei riferimenti incrociati da una pagina ad un'altra -specificando il percorso a partire dalla cartella *Documentation*. -Per esempio, se volete aggiungere un riferimento a questa pagina -(l'estensione .rst è opzionale):: +Aggiungere un riferimento incrociato da una pagina della +documentazione ad un'altra può essere fatto scrivendo il percorso al +file corrispondende, non serve alcuna sintassi speciale. Si possono +usare sia percorsi assoluti che relativi. Quelli assoluti iniziano con +"documentation/". Per esempio, potete fare riferimento a questo +documento in uno dei seguenti modi (da notare che l'estensione +``.rst`` è necessaria):: - See Documentation/translations/it_IT/doc-guide/sphinx.rst. + Vedere Documentation/doc-guide/sphinx.rst. Questo funziona sempre + Guardate pshinx.rst, che si trova nella stessa cartella. + Leggete ../sphinx.rst, che si trova nella cartella precedente. -Se preferite usare un percorso relative allora vi serve la direttiva -Sphinx ``doc``. Per esempio, se volete aggiungere un riferimento a -questa pagina dalla stessa cartella:: +Se volete che il collegamento abbia un testo diverso rispetto al +titolo del documento, allora dovrete usare la direttiva Sphinx +``doc``. Per esempio:: - See :doc:`sphinx`. + Vedere :doc:`il mio testo per il collegamento <sphinx>`. -Per maggiori informazioni su come aggiungere riferimenti incrociati a -commenti kernel-doc di funzioni o tipi, leggete -Documentation/translations/it_IT/doc-guide/sphinx.rst. +Nella maggioranza dei casi si consiglia il primo metodo perché è più +pulito ed adatto a chi legge dai sorgenti. Se incontrare un ``:doc:`` +che non da alcun valore, sentitevi liberi di convertirlo in un +percorso al documento. + +Per informazioni riguardo ai riferimenti incrociati ai commenti +kernel-doc per funzioni o tipi, consultate .. _it_sphinx_kfigure: @@ -391,7 +400,7 @@ Figure ed immagini Se volete aggiungere un'immagine, utilizzate le direttive ``kernel-figure`` e ``kernel-image``. Per esempio, per inserire una figura di un'immagine in -formato SVG:: +formato SVG (:ref:`it_svg_image_example`):: .. kernel-figure:: ../../../doc-guide/svg_image.svg :alt: una semplice immagine SVG diff --git a/Documentation/translations/it_IT/kernel-hacking/hacking.rst b/Documentation/translations/it_IT/kernel-hacking/hacking.rst index 3d30b69f1ec1..f6beb385b4ac 100644 --- a/Documentation/translations/it_IT/kernel-hacking/hacking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/hacking.rst @@ -369,7 +369,7 @@ all'inizio dell'avvio del sistema è attraverso la procedura Prima di inventare la vostra cache per gli oggetti più usati, considerate l'uso di una cache slab disponibile in ``include/linux/slab.h``. -:c:func:`current()` +:c:macro:`current` ------------------- Definita in ``include/asm/current.h`` diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst index bf1acd6204ef..1e7c84def369 100644 --- a/Documentation/translations/it_IT/kernel-hacking/locking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst @@ -127,11 +127,11 @@ il vostro processo si auto-sospenderà; verrà riattivato quando il mutex verrà rilasciato. Questo significa che il processore potrà occuparsi d'altro mentre il vostro processo è in attesa. Esistono molti casi in cui non potete permettervi di sospendere un processo (vedere -:ref:`Quali funzioni possono essere chiamate in modo sicuro dalle interruzioni? <it_sleeping-things>`) +`Quali funzioni possono essere chiamate in modo sicuro dalle interruzioni?`_) e quindi dovrete utilizzare gli spinlock. Nessuno di questi *lock* è ricorsivo: vedere -:ref:`Stallo: semplice ed avanzato <it_deadlock>` +`Stallo: semplice ed avanzato`_ I *lock* e i kernel per sistemi monoprocessore ---------------------------------------------- @@ -190,7 +190,7 @@ perfetto questa funzione si chiamerebbe 'spin_lock_softirq()'). Da notare che in questo caso potete utilizzare anche spin_lock_irq() o spin_lock_irqsave(), queste fermano anche le interruzioni hardware: -vedere :ref:`Contesto di interruzione hardware <it_hardirq-context>`. +vedere `Contesto di interruzione hardware`_. Questo funziona alla perfezione anche sui sistemi monoprocessore: gli spinlock svaniscono e questa macro diventa semplicemente local_bh_disable() @@ -241,7 +241,7 @@ Lo stesso softirq Lo stesso softirq può essere eseguito su un diverso processore: allo scopo di migliorare le prestazioni potete utilizzare dati riservati ad ogni -processore (vedere :ref:`Dati per processore <it_per-cpu>`). Se siete arrivati +processore (vedere `Dati per processore`_). Se siete arrivati fino a questo punto nell'uso dei softirq, probabilmente tenete alla scalabilità delle prestazioni abbastanza da giustificarne la complessità aggiuntiva. @@ -896,8 +896,6 @@ leggendo solamente il codice. E come dice Alan Cox: “Lock data, not code”. Problemi comuni =============== -.. _`it_deadlock`: - Stallo: semplice ed avanzato ---------------------------- @@ -1282,7 +1280,6 @@ Il beneficio qui sta nel fatto che il contatore di riferimenti no viene scritto: l'oggetto non viene alterato in alcun modo e quindi diventa molto più veloce su sistemi molti-processore grazie alla loro memoria cache. -.. _`it_per-cpu`: Dati per processore ------------------- @@ -1333,7 +1330,6 @@ Naturalmente, questo è più lento della semplice chiamata spin_lock_irq(), quindi ha senso solo se questo genere di accesso è estremamente raro. -.. _`it_sleeping-things`: Quali funzioni possono essere chiamate in modo sicuro dalle interruzioni? ========================================================================= diff --git a/Documentation/translations/it_IT/process/4.Coding.rst b/Documentation/translations/it_IT/process/4.Coding.rst index 8012fe9497ae..54fd255b77d0 100644 --- a/Documentation/translations/it_IT/process/4.Coding.rst +++ b/Documentation/translations/it_IT/process/4.Coding.rst @@ -264,11 +264,10 @@ La maggior parte di queste opzioni possono essere attivate per qualsiasi kernel utilizzato per lo sviluppo o a scopo di test. In particolare dovreste attivare: - - ENABLE_MUST_CHECK e FRAME_WARN per ottenere degli - avvertimenti dedicati a problemi come l'uso di interfacce deprecate o - l'ignorare un importante valore di ritorno di una funzione. Il risultato - generato da questi avvertimenti può risultare verboso, ma non bisogna - preoccuparsi per gli avvertimenti provenienti da altre parti del kernel. + - FRAME_WARN per ottenere degli avvertimenti su stack frame più + grandi di un dato valore. Il risultato generato da questi + avvertimenti può risultare verboso, ma non bisogna preoccuparsi per + gli avvertimenti provenienti da altre parti del kernel. - DEBUG_OBJECTS aggiungerà un codice per tracciare il ciclo di vita di diversi oggetti creati dal kernel e avvisa quando qualcosa viene eseguito diff --git a/Documentation/translations/it_IT/process/adding-syscalls.rst b/Documentation/translations/it_IT/process/adding-syscalls.rst index c478b6e8c292..df8c652d004b 100644 --- a/Documentation/translations/it_IT/process/adding-syscalls.rst +++ b/Documentation/translations/it_IT/process/adding-syscalls.rst @@ -562,7 +562,7 @@ kernel. Se la nuova funzionalità è utile all'interno del kernel, per esempio dev'essere condivisa fra una vecchia e una nuova chiamata di sistema o dev'essere utilizzata da una chiamata di sistema e la sua variante compatibile, allora dev'essere implementata come una funzione di supporto -(*helper function*) (per esempio ``kern_xyzzy()``). Questa funzione potrà +(*helper function*) (per esempio ``ksys_xyzzy()``). Questa funzione potrà essere chiamata dallo *stub* (``sys_xyzzy()``), dalla variante compatibile (``compat_sys_xyzzy()``), e/o da altri parti del kernel. diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst index c86c4543f249..95f2e7c985e2 100644 --- a/Documentation/translations/it_IT/process/coding-style.rst +++ b/Documentation/translations/it_IT/process/coding-style.rst @@ -75,9 +75,26 @@ stessa riga: if (condition) do_this; do_something_everytime; -né mettete più assegnamenti sulla stessa riga. Lo stile del kernel +Non usate le virgole per evitare le parentesi: + +.. code-block:: c + + if (condition) + do_this(), do_that(); + +Invece, usate sempre le parentesi per racchiudere più istruzioni. + +.. code-block:: c + + if (condition) { + do_this(); + do_that(); + } + +Non mettete nemmeno più assegnamenti sulla stessa riga. Lo stile del kernel è ultrasemplice. Evitate espressioni intricate. + Al di fuori dei commenti, della documentazione ed escludendo i Kconfig, gli spazi non vengono mai usati per l'indentazione, e l'esempio qui sopra è volutamente errato. @@ -320,8 +337,7 @@ qualcosa di simile, **non** dovreste chiamarla ``cntusr()``. Codificare il tipo di funzione nel suo nome (quella cosa chiamata notazione ungherese) è stupido - il compilatore conosce comunque il tipo e -può verificarli, e inoltre confonde i programmatori. Non c'è da -sorprendersi che MicroSoft faccia programmi bacati. +può verificarli, e inoltre confonde i programmatori. Le variabili LOCALI dovrebbero avere nomi corti, e significativi. Se avete un qualsiasi contatore di ciclo, probabilmente sarà chiamato ``i``. diff --git a/Documentation/translations/it_IT/process/howto.rst b/Documentation/translations/it_IT/process/howto.rst index 1db5a1082389..9554368a2ae2 100644 --- a/Documentation/translations/it_IT/process/howto.rst +++ b/Documentation/translations/it_IT/process/howto.rst @@ -357,17 +357,10 @@ benvenuti. Riportare Bug ------------- -https://bugzilla.kernel.org è dove gli sviluppatori del kernel Linux tracciano -i bachi del kernel. Gli utenti sono incoraggiati nel riportare tutti i bachi -che trovano utilizzando questo strumento. -Per maggiori dettagli su come usare il bugzilla del kernel, guardare: - - https://bugzilla.kernel.org/page.cgi?id=faq.html - -Il file admin-guide/reporting-bugs.rst nella cartella principale del kernel -fornisce un buon modello sul come segnalare un baco nel kernel, e spiega quali -informazioni sono necessarie agli sviluppatori per poter aiutare il -rintracciamento del problema. +Il file 'Documentation/admin-guide/reporting-issues.rst' nella +cartella principale del kernel spiega come segnalare un baco nel +kernel, e fornisce dettagli su quali informazioni sono necessarie agli +sviluppatori del kernel per poter studiare il problema. Gestire i rapporti sui bug -------------------------- @@ -380,8 +373,14 @@ al corrente della vostra presenza. Riparare bachi è una delle migliori vie per acquisire meriti tra gli altri sviluppatori, perchè non a molte persone piace perdere tempo a sistemare i bachi di altri. -Per lavorare sui rapporti di bachi già riportati, andate su -https://bugzilla.kernel.org. +Per lavorare sui bachi già segnalati, per prima cosa cercate il +sottosistema che vi interessa. Poi, verificate nel file MAINTAINERS +dove vengono collezionati solitamente i bachi per quel sottosistema; +spesso sarà una lista di discussione, raramente un bugtracker. Cercate +bachi nell'archivio e aiutate dove credete di poterlo fare. Potete +anche consultare https://bugzilla.kernel.org; però, solo una manciata di +sottosistemi lo usano attivamente, ciò nonostante i bachi che +coinvolgono l'intero kernel sono sempre riportati lì. Liste di discussione -------------------- diff --git a/Documentation/translations/it_IT/process/magic-number.rst b/Documentation/translations/it_IT/process/magic-number.rst index e8c782d155a3..f452fafb1e84 100644 --- a/Documentation/translations/it_IT/process/magic-number.rst +++ b/Documentation/translations/it_IT/process/magic-number.rst @@ -101,7 +101,6 @@ RFCOMM_TTY_MAGIC 0x6d02 ``net/bluetooth/ USB_SERIAL_PORT_MAGIC 0x7301 usb_serial_port ``drivers/usb/serial/usb-serial.h`` CG_MAGIC 0x00090255 ufs_cylinder_group ``include/linux/ufs_fs.h`` LSEMAGIC 0x05091998 lse ``drivers/fc4/fc.c`` -GDTIOCTL_MAGIC 0x06030f07 gdth_iowr_str ``drivers/scsi/gdth_ioctl.h`` RIEBL_MAGIC 0x09051990 ``drivers/net/atarilance.c`` NBD_REQUEST_MAGIC 0x12560953 nbd_request ``include/linux/nbd.h`` RED_MAGIC2 0x170fc2a5 (any) ``mm/slab.c`` @@ -144,7 +143,6 @@ PWC_MAGIC 0x89DC10AB pwc_device ``drivers/usb/me NBD_REPLY_MAGIC 0x96744668 nbd_reply ``include/linux/nbd.h`` ENI155_MAGIC 0xa54b872d midway_eprom ``drivers/atm/eni.h`` CODA_MAGIC 0xC0DAC0DA coda_file_info ``fs/coda/coda_fs_i.h`` -DPMEM_MAGIC 0xc0ffee11 gdt_pci_sram ``drivers/scsi/gdth.h`` YAM_MAGIC 0xF10A7654 yam_port ``drivers/net/hamradio/yam.c`` CCB_MAGIC 0xf2691ad2 ccb ``drivers/scsi/ncr53c8xx.c`` QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry ``drivers/scsi/arm/queue.c`` diff --git a/Documentation/translations/it_IT/process/submit-checklist.rst b/Documentation/translations/it_IT/process/submit-checklist.rst index 614fc17d9086..2fc09cc1f0be 100644 --- a/Documentation/translations/it_IT/process/submit-checklist.rst +++ b/Documentation/translations/it_IT/process/submit-checklist.rst @@ -28,6 +28,10 @@ sottomissione delle patch, in particolare c) quando si usa ``O=builddir`` + d) Qualsiasi modifica in Documentation/ deve compilare con successo senza + avvisi o errori. Usare ``make htmldocs`` o ``make pdfdocs`` per verificare + e correggere i problemi + 3) Compilare per diverse architetture di processore usando strumenti per la cross-compilazione o altri. @@ -54,8 +58,7 @@ sottomissione delle patch, in particolare 9) Verificare con sparse. -10) Usare ``make checkstack`` e ``make namespacecheck`` e correggere tutti i - problemi rilevati. +10) Usare ``make checkstack`` e correggere tutti i problemi rilevati. .. note:: @@ -95,31 +98,29 @@ sottomissione delle patch, in particolare informazioni. Le patch che modificano le interfacce utente dovrebbero essere inviate in copia anche a linux-api@vger.kernel.org. -20) Verifica che il kernel passi con successo ``make headers_check`` - -21) La patch è stata verificata con l'iniezione di fallimenti in slab e +20) La patch è stata verificata con l'iniezione di fallimenti in slab e nell'allocazione di pagine. Vedere ``Documentation/fault-injection/``. Se il nuovo codice è corposo, potrebbe essere opportuno aggiungere l'iniezione di fallimenti specifici per il sottosistema. -22) Il nuovo codice è stato compilato con ``gcc -W`` (usate +21) Il nuovo codice è stato compilato con ``gcc -W`` (usate ``make KCFLAGS=-W``). Questo genererà molti avvisi, ma è ottimo per scovare bachi come "warning: comparison between signed and unsigned". -23) La patch è stata verificata dopo essere stata inclusa nella serie di patch +22) La patch è stata verificata dopo essere stata inclusa nella serie di patch -mm; questo al fine di assicurarsi che continui a funzionare assieme a tutte le altre patch in coda e i vari cambiamenti nei sottosistemi VM, VFS e altri. -24) Tutte le barriere di sincronizzazione {per esempio, ``barrier()``, +23) Tutte le barriere di sincronizzazione {per esempio, ``barrier()``, ``rmb()``, ``wmb()``} devono essere accompagnate da un commento nei sorgenti che ne spieghi la logica: cosa fanno e perché. -25) Se la patch aggiunge nuove chiamate ioctl, allora aggiornate +24) Se la patch aggiunge nuove chiamate ioctl, allora aggiornate ``Documentation/userspace-api/ioctl/ioctl-number.rst``. -26) Se il codice che avete modificato dipende o usa una qualsiasi interfaccia o +25) Se il codice che avete modificato dipende o usa una qualsiasi interfaccia o funzionalità del kernel che è associata a uno dei seguenti simboli ``Kconfig``, allora verificate che il kernel compili con diverse configurazioni dove i simboli sono disabilitati e/o ``=m`` (se c'è la diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst index ae00352346ed..ded95048b9a8 100644 --- a/Documentation/translations/it_IT/process/submitting-patches.rst +++ b/Documentation/translations/it_IT/process/submitting-patches.rst @@ -433,6 +433,14 @@ Alcune persone aggiungono delle etichette alla fine. Per ora queste verranno ignorate, ma potete farlo per meglio identificare procedure aziendali interne o per aggiungere dettagli circa la firma. +In seguito al SoB (Signed-off-by:) dell'autore ve ne sono altri da +parte di tutte quelle persone che si sono occupate della gestione e +del trasporto della patch. Queste però non sono state coinvolte nello +sviluppo, ma la loro sequenza d'apparizione ci racconta il percorso +**reale** che una patch a intrapreso dallo sviluppatore, fino al +manutentore, per poi giungere a Linus. + + Quando utilizzare Acked-by:, Cc:, e Co-developed-by: ---------------------------------------------------- @@ -574,6 +582,10 @@ kernel stabili al fine di capire quale kernel deve ricevere la correzione. Questo è il modo suggerito per indicare che un baco è stato corretto nella patch. Per maggiori dettagli leggete :ref:`it_describe_changes` +Da notare che aggiungere un tag "Fixes:" non esime dalle regole +previste per i kernel stabili, e nemmeno dalla necessità di aggiungere +in copia conoscenza stable@vger.kernel.org su tutte le patch per +suddetti kernel. Il formato canonico delle patch ------------------------------- @@ -642,16 +654,20 @@ Le etichette non verranno considerate come parte della frase riassuntiva, ma indicano come la patch dovrebbe essere trattata. Fra le etichette più comuni ci sono quelle di versione che vengono usate quando una patch è stata inviata più volte (per esempio, "v1, v2, v3"); oppure "RFC" per indicare che si -attendono dei commenti (*Request For Comments*). Se ci sono quattro patch -nella serie, queste dovrebbero essere enumerate così: 1/4, 2/4, 3/4, 4/4. -Questo assicura che gli sviluppatori capiranno l'ordine in cui le patch -dovrebbero essere applicate, e per tracciare quelle che hanno revisionate o -che hanno applicato. +attendono dei commenti (*Request For Comments*). + +Se ci sono quattro patch nella serie, queste dovrebbero essere +enumerate così: 1/4, 2/4, 3/4, 4/4. Questo assicura che gli +sviluppatori capiranno l'ordine in cui le patch dovrebbero essere +applicate, e per tracciare quelle che hanno revisionate o che hanno +applicato. Un paio di esempi di oggetti:: Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching Subject: [PATCH v2 01/27] x86: fix eflags tracking + Subject: [PATCH v2] sub/sys: Condensed patch summary + Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary La riga ``from`` dev'essere la prima nel corpo del messaggio ed è nel formato: @@ -668,30 +684,76 @@ deve aver senso per un lettore esperto che è ha dimenticato i dettagli della discussione che hanno portato alla patch. L'inclusione di informazioni sui problemi oggetto dalla patch (messaggi del kernel, messaggi di oops, eccetera) è particolarmente utile per le persone che potrebbero cercare fra -i messaggi di log per la patch che li tratta. Se la patch corregge un errore -di compilazione, non sarà necessario includere proprio _tutto_ quello che -è uscito dal compilatore; aggiungete solo quello che è necessario per far si -che la vostra patch venga trovata. Come nella ``summary phrase``, è importante -essere sia brevi che descrittivi. +i messaggi di log per la patch che li tratta. Il testo dovrebbe essere scritto +con abbastanza dettagli da far capire al lettore **perché** quella +patch fu creata, e questo a distanza di settimane, mesi, o addirittura +anni. + +Se la patch corregge un errore di compilazione, non sarà necessario +includere proprio _tutto_ quello che è uscito dal compilatore; +aggiungete solo quello che è necessario per far si che la vostra patch +venga trovata. Come nella ``summary phrase``, è importante essere sia +brevi che descrittivi. La linea di demarcazione ``---`` serve essenzialmente a segnare dove finisce il messaggio di changelog. Aggiungere il ``diffstat`` dopo ``---`` è un buon uso di questo spazio, per mostrare i file che sono cambiati, e il numero di file aggiunto o rimossi. -Un ``diffstat`` è particolarmente utile per le patch grandi. Altri commenti -che sono importanti solo per i manutentori, quindi inadatti al changelog -permanente, dovrebbero essere messi qui. Un buon esempio per questo tipo -di commenti potrebbe essere quello di descrivere le differenze fra le versioni +Un ``diffstat`` è particolarmente utile per le patch grandi. Se +includete un ``diffstat`` dopo ``---``, usate le opzioni ``-p 1 -w70`` +cosicché i nomi dei file elencati non occupino troppo spazio +(facilmente rientreranno negli 80 caratteri, magari con qualche +indentazione). (``git`` genera di base dei diffstat adatti). + +I commenti che sono importanti solo per i manutentori, quindi +inadatti al changelog permanente, dovrebbero essere messi qui. Un +buon esempio per questo tipo di commenti potrebbe essere il cosiddetto +``patch changelogs`` che descrivere le differenze fra le versioni della patch. -Se includete un ``diffstat`` dopo ``---``, usate le opzioni ``-p 1 -w70`` -cosicché i nomi dei file elencati non occupino troppo spazio (facilmente -rientreranno negli 80 caratteri, magari con qualche indentazione). -(``git`` genera di base dei diffstat adatti). +Queste informazioni devono andare **dopo** la linea ``---`` che separa +il *changelog* dal resto della patch. Le informazioni riguardanti la +versione di una patch non sono parte del *chagelog* che viene incluso +in git. Queste sono informazioni utili solo ai revisori. Se venissero +messe sopra la riga, qualcuno dovrà fare del lavoro manuale per +rimuoverle; cosa che invece viene fatta automaticamente quando vengono +messe correttamente oltre la riga.:: + + <commit message> + ... + Signed-off-by: Author <author@mail> + --- + V2 -> V3: Removed redundant helper function + V1 -> V2: Cleaned up coding style and addressed review comments + + path/to/file | 5+++-- + ... Maggiori dettagli sul formato delle patch nei riferimenti qui di seguito. +Aggiungere i *backtrace* nei messaggi di commit +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +I *backtrace* aiutano a documentare la sequenza di chiamate a funzione +che portano ad un problema. Tuttavia, non tutti i *backtrace* sono +davvero utili. Per esempio, le sequenze iniziali di avvio sono uniche +e ovvie. Copiare integralmente l'output di ``dmesg`` aggiunge tante +informazioni che distraggono dal vero problema (per esempio, i +marcatori temporali, la lista dei moduli, la lista dei registri, lo +stato dello stack). + +Quindi, per rendere utile un *backtrace* dovreste eliminare le +informazioni inutili, cosicché ci si possa focalizzare sul +problema. Ecco un esempio di un *backtrace* essenziale:: + + unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064) + at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) + Call Trace: + mba_wrmsr + update_domains + rdtgroup_mkdir + .. _it_explicit_in_reply_to: Usare esplicitamente In-Reply-To nell'intestazione diff --git a/Documentation/translations/ja_JP/SubmitChecklist b/Documentation/translations/ja_JP/SubmitChecklist index b42220d3d46c..4429447b0965 100644 --- a/Documentation/translations/ja_JP/SubmitChecklist +++ b/Documentation/translations/ja_JP/SubmitChecklist @@ -88,20 +88,18 @@ Linux カーネルパッチ投稿者向けチェックリスト 18: 新しいuserspaceインタフェースを作成した場合には、Documentation/ABI/ に Documentation/ABI/README を参考にして必ずドキュメントを追加してください。 -19: 'make headers_check'を実行して全く問題がないことを確認してください。 - -20: 少なくともslabアロケーションとpageアロケーションに失敗した場合の +19: 少なくともslabアロケーションとpageアロケーションに失敗した場合の 挙動について、fault-injectionを利用して確認してください。 Documentation/fault-injection/ を参照してください。 追加したコードがかなりの量であったならば、サブシステム特有の fault-injectionを追加したほうが良いかもしれません。 -21: 新たに追加したコードは、`gcc -W'でコンパイルしてください。 +20: 新たに追加したコードは、`gcc -W'でコンパイルしてください。 このオプションは大量の不要なメッセージを出力しますが、 "warning: comparison between signed and unsigned" のようなメッセージは、 バグを見つけるのに役に立ちます。 -22: 投稿したパッチが -mm パッチセットにマージされた後、全ての既存のパッチや +21: 投稿したパッチが -mm パッチセットにマージされた後、全ての既存のパッチや VM, VFS およびその他のサブシステムに関する様々な変更と、現時点でも共存 できることを確認するテストを行ってください。 diff --git a/Documentation/translations/ko_KR/howto.rst b/Documentation/translations/ko_KR/howto.rst index 787f1e85f8a0..a2bdd564c907 100644 --- a/Documentation/translations/ko_KR/howto.rst +++ b/Documentation/translations/ko_KR/howto.rst @@ -339,14 +339,8 @@ Andrew Morton의 글이 있다. 버그 보고 --------- -https://bugzilla.kernel.org 는 리눅스 커널 개발자들이 커널의 버그를 추적하는 -곳이다. 사용자들은 발견한 모든 버그들을 보고하기 위하여 이 툴을 사용할 것을 -권장한다. kernel bugzilla를 사용하는 자세한 방법은 다음을 참조하라. - - https://bugzilla.kernel.org/page.cgi?id=faq.html - 메인 커널 소스 디렉토리에 있는 'Documentation/admin-guide/reporting-issues.rst' -파일은 커널 버그라고 생각되는 것을 보고하는 방법에 관한 좋은 템플릿이며 문제를 +파일은 커널 버그라고 생각되는 것을 어떻게 보고하면 되는지, 그리고 문제를 추적하기 위해서 커널 개발자들이 필요로 하는 정보가 무엇들인지를 상세히 설명하고 있다. @@ -362,8 +356,14 @@ https://bugzilla.kernel.org 는 리눅스 커널 개발자들이 커널의 버 점수를 얻을 수 있는 가장 좋은 방법중의 하나이다. 왜냐하면 많은 사람들은 다른 사람들의 버그들을 수정하기 위하여 시간을 낭비하지 않기 때문이다. -이미 보고된 버그 리포트들을 가지고 작업하기 위해서 https://bugzilla.kernel.org -를 참조하라. +이미 보고된 버그 리포트들을 가지고 작업하기 위해서는 여러분이 관심있는 +서브시스템을 찾아라. 해당 서브시스템의 버그들이 어디로 리포트 되는지 +MAINTAINERS 파일을 체크하라; 그건 대부분 메일링 리스트이고, 가끔은 버그 추적 +시스템이다. 그 장소에 있는 최근 버그 리포트 기록들을 검색하고 여러분이 보기에 +적합하다 싶은 것을 도와라. 여러분은 버그 리포트를 위해 +https://bugzilla.kernel.org 를 체크하고자 할 수도 있다; 소수의 커널 +서브시스템들만이 버그 신고와 추적을 위해 해당 시스템을 실제로 사용하고 있지만, +전체 커널의 버그들이 그곳에 정리된다. 메일링 리스트들 diff --git a/Documentation/translations/zh_CN/admin-guide/README.rst b/Documentation/translations/zh_CN/admin-guide/README.rst new file mode 100644 index 000000000000..669a022f6817 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/README.rst @@ -0,0 +1,347 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/README.rst + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +Linux内核5.x版本 <http://kernel.org/> +========================================= + +以下是Linux版本5的发行注记。仔细阅读它们， +它们会告诉你这些都是什么，解释如何安装内核，以及遇到问题时该如何做。 + +什么是Linux？ +--------------- + + Linux是Unix操作系统的克隆版本，由Linus Torvalds在一个松散的网络黑客 + （Hacker，无贬义）团队的帮助下从头开始编写。它旨在实现兼容POSIX和 + 单一UNIX规范。 + + 它具有在现代成熟的Unix中应当具有的所有功能，包括真正的多任务处理、虚拟内存、 + 共享库、按需加载、共享的写时拷贝（COW）可执行文件、恰当的内存管理以及包括 + IPv4和IPv6在内的复合网络栈。 + + Linux在GNU通用公共许可证，版本2（GNU GPLv2）下分发，详见随附的COPYING文件。 + +它能在什么样的硬件上运行？ +----------------------------- + + 虽然Linux最初是为32位的x86 PC机（386或更高版本）开发的，但今天它也能运行在 + （至少）Compaq Alpha AXP、Sun SPARC与UltraSPARC、Motorola 68000、PowerPC、 + PowerPC64、ARM、Hitachi SuperH、Cell、IBM S/390、MIPS、HP PA-RISC、Intel + IA-64、DEC VAX、AMD x86-64 Xtensa和ARC架构上。 + + Linux很容易移植到大多数通用的32位或64位体系架构，只要它们有一个分页内存管理 + 单元（PMMU）和一个移植的GNU C编译器（gcc；GNU Compiler Collection，GCC的一 + 部分）。Linux也被移植到许多没有PMMU的体系架构中，尽管功能显然受到了一定的 + 限制。 + Linux也被移植到了其自己上。现在可以将内核作为用户空间应用程序运行——这被 + 称为用户模式Linux（UML）。 + +文档 +----- +因特网上和书籍上都有大量的电子文档，既有Linux专属文档，也有与一般UNIX问题相关 +的文档。我建议在任何Linux FTP站点上查找LDP（Linux文档项目）书籍的文档子目录。 +本自述文件并不是关于系统的文档：有更好的可用资源。 + + - 因特网上和书籍上都有大量的（电子）文档，既有Linux专属文档，也有与普通 + UNIX问题相关的文档。我建议在任何有LDP（Linux文档项目）书籍的Linux FTP + 站点上查找文档子目录。本自述文件并不是关于系统的文档：有更好的可用资源。 + + - 文档/子目录中有各种自述文件：例如，这些文件通常包含一些特定驱动程序的 + 内核安装说明。请阅读 + :ref:`Documentation/process/changes.rst <changes>` 文件，它包含了升级内核 + 可能会导致的问题的相关信息。 + +安装内核源代码 +--------------- + + - 如果您要安装完整的源代码，请把内核tar档案包放在您有权限的目录中（例如您 + 的主目录）并将其解包:: + + xz -cd linux-5.x.tar.xz | tar xvf - + + 将“X”替换成最新内核的版本号。 + + 【不要】使用 /usr/src/linux 目录！这里有一组库头文件使用的内核头文件 + （通常是不完整的）。它们应该与库匹配，而不是被内核的变化搞得一团糟。 + + - 您还可以通过打补丁在5.x版本之间升级。补丁以xz格式分发。要通过打补丁进行 + 安装，请获取所有较新的补丁文件，进入内核源代码（linux-5.x）的目录并 + 执行:: + + xz -cd ../patch-5.x.xz | patch -p1 + + 请【按顺序】替换所有大于当前源代码树版本的“x”，这样就可以了。您可能想要 + 删除备份文件（文件名类似xxx~ 或 xxx.orig)，并确保没有失败的补丁（文件名 + 类似xxx# 或 xxx.rej）。如果有，不是你就是我犯了错误。 + + 与5.x内核的补丁不同，5.x.y内核（也称为稳定版内核）的补丁不是增量的，而是 + 直接应用于基本的5.x内核。例如，如果您的基本内核是5.0，并且希望应用5.0.3 + 补丁，则不应先应用5.0.1和5.0.2的补丁。类似地，如果您运行的是5.0.2内核， + 并且希望跳转到5.0.3，那么在应用5.0.3补丁之前，必须首先撤销5.0.2补丁 + （即patch -R）。更多关于这方面的内容，请阅读 + :ref:`Documentation/process/applying-patches.rst <applying_patches>` 。 + + 或者，脚本 patch-kernel 可以用来自动化这个过程。它能确定当前内核版本并 + 应用找到的所有补丁:: + + linux/scripts/patch-kernel linux + + 上面命令中的第一个参数是内核源代码的位置。补丁是在当前目录应用的，但是 + 可以将另一个目录指定为第二个参数。 + + - 确保没有过时的 .o 文件和依赖项:: + + cd linux + make mrproper + + 现在您应该已经正确安装了源代码。 + +软件要求 +--------- + + 编译和运行5.x内核需要各种软件包的最新版本。请参考 + :ref:`Documentation/process/changes.rst <changes>` + 来了解最低版本要求以及如何升级软件包。请注意，使用过旧版本的这些包可能会 + 导致很难追踪的间接错误，因此不要以为在生成或操作过程中出现明显问题时可以 + 只更新包。 + +为内核建立目录 +--------------- + + 编译内核时，默认情况下所有输出文件都将与内核源代码放在一起。使用 + ``make O=output/dir`` 选项可以为输出文件（包括 .config）指定备用位置。 + 例如:: + + kernel source code: /usr/src/linux-5.x + build directory: /home/name/build/kernel + + 要配置和构建内核，请使用:: + + cd /usr/src/linux-5.x + make O=/home/name/build/kernel menuconfig + make O=/home/name/build/kernel + sudo make O=/home/name/build/kernel modules_install install + + 请注意：如果使用了 ``O=output/dir`` 选项，那么它必须用于make的所有调用。 + +配置内核 +--------- + + 即使只升级一个小版本，也不要跳过此步骤。每个版本中都会添加新的配置选项， + 如果配置文件没有按预定设置，就会出现奇怪的问题。如果您想以最少的工作量 + 将现有配置升级到新版本，请使用 ``makeoldconfig`` ，它只会询问您新配置 + 选项的答案。 + + - 其他配置命令包括:: + + "make config" 纯文本界面。 + + "make menuconfig" 基于文本的彩色菜单、选项列表和对话框。 + + "make nconfig" 增强的基于文本的彩色菜单。 + + "make xconfig" 基于Qt的配置工具。 + + "make gconfig" 基于GTK+的配置工具。 + + "make oldconfig" 基于现有的 ./.config 文件选择所有选项，并询问 + 新配置选项。 + + "make olddefconfig" + 类似上一个，但不询问直接将新选项设置为默认值。 + + "make defconfig" 根据体系架构，使用arch/$arch/defconfig或 + arch/$arch/configs/${PLATFORM}_defconfig中的 + 默认选项值创建./.config文件。 + + "make ${PLATFORM}_defconfig" + 使用arch/$arch/configs/${PLATFORM}_defconfig中 + 的默认选项值创建一个./.config文件。 + 用“makehelp”来获取您体系架构中所有可用平台的列表。 + + "make allyesconfig" + 通过尽可能将选项值设置为“y”，创建一个 + ./.config文件。 + + "make allmodconfig" + 通过尽可能将选项值设置为“m”，创建一个 + ./.config文件。 + + "make allnoconfig" 通过尽可能将选项值设置为“n”，创建一个 + ./.config文件。 + + "make randconfig" 通过随机设置选项值来创建./.config文件。 + + "make localmodconfig" 基于当前配置和加载的模块（lsmod）创建配置。禁用 + 已加载的模块不需要的任何模块选项。 + + 要为另一台计算机创建localmodconfig，请将该计算机 + 的lsmod存储到一个文件中，并将其作为lsmod参数传入。 + + 此外，通过在参数LMC_KEEP中指定模块的路径，可以将 + 模块保留在某些文件夹或kconfig文件中。 + + target$ lsmod > /tmp/mylsmod + target$ scp /tmp/mylsmod host:/tmp + + host$ make LSMOD=/tmp/mylsmod \ + LMC_KEEP="drivers/usb:drivers/gpu:fs" \ + localmodconfig + + 上述方法在交叉编译时也适用。 + + "make localyesconfig" 与localmodconfig类似，只是它会将所有模块选项转换 + 为内置（=y）。你可以同时通过LMC_KEEP保留模块。 + + "make kvmconfig" 为kvm客体内核支持启用其他选项。 + + "make xenconfig" 为xen dom0客体内核支持启用其他选项。 + + "make tinyconfig" 配置尽可能小的内核。 + + 更多关于使用Linux内核配置工具的信息，见文档 + Documentation/kbuild/kconfig.rst。 + + - ``make config`` 注意事项: + + - 包含不必要的驱动程序会使内核变大，并且在某些情况下会导致问题： + 探测不存在的控制器卡可能会混淆其他控制器。 + + - 如果存在协处理器，则编译了数学仿真的内核仍将使用协处理器：在 + 这种情况下，数学仿真永远不会被使用。内核会稍微大一点，但不管 + 是否有数学协处理器，都可以在不同的机器上工作。 + + - “kernel hacking”配置细节通常会导致更大或更慢的内核（或两者 + 兼而有之），甚至可以通过配置一些例程来主动尝试破坏坏代码以发现 + 内核问题，从而降低内核的稳定性（kmalloc()）。因此，您可能应该 + 用于研究“开发”、“实验”或“调试”特性相关问题。 + +编译内核 +--------- + + - 确保您至少有gcc 4.9可用。 + 有关更多信息，请参阅 :ref:`Documentation/process/changes.rst <changes>` 。 + + 请注意，您仍然可以使用此内核运行a.out用户程序。 + + - 执行 ``make`` 来创建压缩内核映像。如果您安装了lilo以适配内核makefile， + 那么也可以进行 ``makeinstall`` ，但是您可能需要先检查特定的lilo设置。 + + 实际安装必须以root身份执行，但任何正常构建都不需要。 + 无须徒然使用root身份。 + + - 如果您将内核的任何部分配置为模块，那么还必须执行 ``make modules_install`` 。 + + - 详细的内核编译/生成输出： + + 通常，内核构建系统在相当安静的模式下运行（但不是完全安静）。但是有时您或 + 其他内核开发人员需要看到编译、链接或其他命令的执行过程。为此，可使用 + “verbose（详细）”构建模式。 + 向 ``make`` 命令传递 ``V=1`` 来实现，例如:: + + make V=1 all + + 如需构建系统也给出内个目标重建的愿意，请使用 ``V=2`` 。默认为 ``V=0`` 。 + + - 准备一个备份内核以防出错。对于开发版本尤其如此，因为每个新版本都包含 + 尚未调试的新代码。也要确保保留与该内核对应的模块的备份。如果要安装 + 与工作内核版本号相同的新内核，请在进行 ``make modules_install`` 安装 + 之前备份modules目录。 + + 或者，在编译之前，使用内核配置选项“LOCALVERSION”向常规内核版本附加 + 一个唯一的后缀。LOCALVERSION可以在“General Setup”菜单中设置。 + + - 为了引导新内核，您需要将内核映像（例如编译后的 + .../linux/arch/x86/boot/bzImage）复制到常规可引导内核的位置。 + + - 不再支持在没有LILO等启动装载程序帮助的情况下直接从软盘引导内核。 + + 如果从硬盘引导Linux，很可能使用LILO，它使用/etc/lilo.conf文件中 + 指定的内核映像文件。内核映像文件通常是/vmlinuz、/boot/vmlinuz、 + /bzImage或/boot/bzImage。使用新内核前，请保存旧映像的副本，并复制 + 新映像覆盖旧映像。然后您【必须重新运行LILO】来更新加载映射！否则， + 将无法启动新的内核映像。 + + 重新安装LILO通常需要运行/sbin/LILO。您可能希望编辑/etc/lilo.conf + 文件为旧内核映像指定一个条目（例如/vmlinux.old)防止新的不能正常 + 工作。有关更多信息，请参阅LILO文档。 + + 重新安装LILO之后，您应该就已经准备好了。关闭系统，重新启动，尽情 + 享受吧！ + + 如果需要更改内核映像中的默认根设备、视频模式等，请在适当的地方使用 + 启动装载程序的引导选项。无需重新编译内核即可更改这些参数。 + + - 使用新内核重新启动并享受它吧。 + +若遇到问题 +----------- + + - 如果您发现了一些可能由于内核缺陷所导致的问题，请检查MAINTAINERS（维护者） + 文件看看是否有人与令您遇到麻烦的内核部分相关。如果无人在此列出，那么第二 + 个最好的方案就是把它们发给我（torvalds@linux-foundation.org），也可能发送 + 到任何其他相关的邮件列表或新闻组。 + + - 在所有的缺陷报告中，【请】告诉我们您在说什么内核，如何复现问题，以及您的 + 设置是什么的（使用您的常识）。如果问题是新的，请告诉我；如果问题是旧的， + 请尝试告诉我您什么时候首次注意到它。 + + - 如果缺陷导致如下消息:: + + unable to handle kernel paging request at address C0000010 + Oops: 0002 + EIP: 0010:XXXXXXXX + eax: xxxxxxxx ebx: xxxxxxxx ecx: xxxxxxxx edx: xxxxxxxx + esi: xxxxxxxx edi: xxxxxxxx ebp: xxxxxxxx + ds: xxxx es: xxxx fs: xxxx gs: xxxx + Pid: xx, process nr: xx + xx xx xx xx xx xx xx xx xx xx + + 或者类似的内核调试信息显示在屏幕上或在系统日志里，请【如实】复制它。 + 可能对你来说转储（dump）看起来不可理解，但它确实包含可能有助于调试问题的 + 信息。转储上方的文本也很重要：它说明了内核转储代码的原因（在上面的示例中， + 是由于内核指针错误）。更多关于如何理解转储的信息，请参见 + Documentation/admin-guide/bug-hunting.rst。 + + - 如果使用 CONFIG_KALLSYMS 编译内核，则可以按原样发送转储，否则必须使用 + ``ksymoops`` 程序来理解转储（但通常首选使用CONFIG_KALLSYMS编译）。 + 此实用程序可从 + https://www.kernel.org/pub/linux/utils/kernel/ksymoops/ 下载。 + 或者，您可以手动执行转储查找： + + - 在调试像上面这样的转储时，如果您可以查找EIP值的含义，这将非常有帮助。 + 十六进制值本身对我或其他任何人都没有太大帮助：它会取决于特定的内核设置。 + 您应该做的是从EIP行获取十六进制值（忽略 ``0010:`` ），然后在内核名字列表 + 中查找它，以查看哪个内核函数包含有问题的地址。 + + 要找到内核函数名，您需要找到与显示症状的内核相关联的系统二进制文件。就是 + 文件“linux/vmlinux”。要提取名字列表并将其与内核崩溃中的EIP进行匹配， + 请执行:: + + nm vmlinux | sort | less + + 这将为您提供一个按升序排序的内核地址列表，从中很容易找到包含有问题的地址 + 的函数。请注意，内核调试消息提供的地址不一定与函数地址完全匹配（事实上， + 这是不可能的），因此您不能只“grep”列表：不过列表将为您提供每个内核函数 + 的起点，因此通过查找起始地址低于你正在搜索的地址，但后一个函数的高于的 + 函数，你会找到您想要的。实际上，在您的问题报告中加入一些“上下文”可能是 + 一个好主意，给出相关的上下几行。 + + 如果您由于某些原因无法完成上述操作（如您使用预编译的内核映像或类似的映像）， + 请尽可能多地告诉我您的相关设置信息，这会有所帮助。有关详细信息请阅读 + ‘Documentation/admin-guide/reporting-issues.rst’。 + + - 或者，您可以在正在运行的内核上使用gdb（只读的；即不能更改值或设置断点）。 + 为此，请首先使用-g编译内核；适当地编辑arch/x86/Makefile，然后执行 ``make + clean`` 。您还需要启用CONFIG_PROC_FS（通过 ``make config`` ）。 + + 使用新内核重新启动后，执行 ``gdb vmlinux /proc/kcore`` 。现在可以使用所有 + 普通的gdb命令。查找系统崩溃点的命令是 ``l *0xXXXXXXXX`` （将xxx替换为EIP + 值）。 + + 用gdb无法调试一个当前未运行的内核是由于gdb（错误地）忽略了编译内核的起始 + 偏移量。 diff --git a/Documentation/translations/zh_CN/admin-guide/bug-bisect.rst b/Documentation/translations/zh_CN/admin-guide/bug-bisect.rst new file mode 100644 index 000000000000..662eb5b46e84 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/bug-bisect.rst @@ -0,0 +1,81 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../admin-guide/bug-bisect` + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +二分（bisect）缺陷 ++++++++++++++++++++ + +（英文版）最后更新：2016年10月28日 + +引言 +===== + +始终尝试由来自kernel.org的源代码构建的最新内核。如果您没有信心这样做，请将 +错误报告给您的发行版供应商，而不是内核开发人员。 + +找到缺陷（bug）并不总是那么容易，不过仍然得去找。如果你找不到它，不要放弃。 +尽可能多的向相关维护人员报告您发现的信息。请参阅MAINTAINERS文件以了解您所 +关注的子系统的维护人员。 + +在提交错误报告之前，请阅读“Documentation/admin-guide/reporting-issues.rst”。 + +设备未出现（Devices not appearing） +==================================== + +这通常是由udev/systemd引起的。在将其归咎于内核之前先检查一下。 + +查找导致缺陷的补丁 +=================== + +使用 ``git`` 提供的工具可以很容易地找到缺陷，只要缺陷是可复现的。 + +操作步骤： + +- 从git源代码构建内核 +- 以此开始二分 [#f1]_:: + + $ git bisect start + +- 标记损坏的变更集:: + + $ git bisect bad [commit] + +- 标记正常工作的变更集:: + + $ git bisect good [commit] + +- 重新构建内核并测试 +- 使用以下任一与git bisect进行交互:: + + $ git bisect good + + 或:: + + $ git bisect bad + + 这取决于您测试的变更集上是否有缺陷 +- 在一些交互之后，git bisect将给出可能导致缺陷的变更集。 + +- 例如，如果您知道当前版本有问题，而4.8版本是正常的，则可以执行以下操作:: + + $ git bisect start + $ git bisect bad # Current version is bad + $ git bisect good v4.8 + + +.. [#f1] 您可以（可选地）在开始git bisect的时候提供good或bad参数 + ``git bisect start [BAD] [GOOD]`` + +如需进一步参考，请阅读： + +- ``git-bisect`` 的手册页 +- `Fighting regressions with git bisect（用git bisect解决回归） + <https://www.kernel.org/pub/software/scm/git/docs/git-bisect-lk2009.html>`_ +- `Fully automated bisecting with "git bisect run"（使用git bisect run + 来全自动二分） <https://lwn.net/Articles/317154>`_ +- `Using Git bisect to figure out when brokenness was introduced + （使用Git二分来找出何时引入了错误） <http://webchick.net/node/99>`_ diff --git a/Documentation/translations/zh_CN/admin-guide/bug-hunting.rst b/Documentation/translations/zh_CN/admin-guide/bug-hunting.rst new file mode 100644 index 000000000000..decb9b26d2f1 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/bug-hunting.rst @@ -0,0 +1,340 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../admin-guide/bug-hunting` + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +追踪缺陷 +========= + +内核错误报告通常附带如下堆栈转储:: + + ------------[ cut here ]------------ + WARNING: CPU: 1 PID: 28102 at kernel/module.c:1108 module_put+0x57/0x70 + Modules linked in: dvb_usb_gp8psk(-) dvb_usb dvb_core nvidia_drm(PO) nvidia_modeset(PO) snd_hda_codec_hdmi snd_hda_intel snd_hda_codec snd_hwdep snd_hda_core snd_pcm snd_timer snd soundcore nvidia(PO) [last unloaded: rc_core] + CPU: 1 PID: 28102 Comm: rmmod Tainted: P WC O 4.8.4-build.1 #1 + Hardware name: MSI MS-7309/MS-7309, BIOS V1.12 02/23/2009 + 00000000 c12ba080 00000000 00000000 c103ed6a c1616014 00000001 00006dc6 + c1615862 00000454 c109e8a7 c109e8a7 00000009 ffffffff 00000000 f13f6a10 + f5f5a600 c103ee33 00000009 00000000 00000000 c109e8a7 f80ca4d0 c109f617 + Call Trace: + [<c12ba080>] ? dump_stack+0x44/0x64 + [<c103ed6a>] ? __warn+0xfa/0x120 + [<c109e8a7>] ? module_put+0x57/0x70 + [<c109e8a7>] ? module_put+0x57/0x70 + [<c103ee33>] ? warn_slowpath_null+0x23/0x30 + [<c109e8a7>] ? module_put+0x57/0x70 + [<f80ca4d0>] ? gp8psk_fe_set_frontend+0x460/0x460 [dvb_usb_gp8psk] + [<c109f617>] ? symbol_put_addr+0x27/0x50 + [<f80bc9ca>] ? dvb_usb_adapter_frontend_exit+0x3a/0x70 [dvb_usb] + [<f80bb3bf>] ? dvb_usb_exit+0x2f/0xd0 [dvb_usb] + [<c13d03bc>] ? usb_disable_endpoint+0x7c/0xb0 + [<f80bb48a>] ? dvb_usb_device_exit+0x2a/0x50 [dvb_usb] + [<c13d2882>] ? usb_unbind_interface+0x62/0x250 + [<c136b514>] ? __pm_runtime_idle+0x44/0x70 + [<c13620d8>] ? __device_release_driver+0x78/0x120 + [<c1362907>] ? driver_detach+0x87/0x90 + [<c1361c48>] ? bus_remove_driver+0x38/0x90 + [<c13d1c18>] ? usb_deregister+0x58/0xb0 + [<c109fbb0>] ? SyS_delete_module+0x130/0x1f0 + [<c1055654>] ? task_work_run+0x64/0x80 + [<c1000fa5>] ? exit_to_usermode_loop+0x85/0x90 + [<c10013f0>] ? do_fast_syscall_32+0x80/0x130 + [<c1549f43>] ? sysenter_past_esp+0x40/0x6a + ---[ end trace 6ebc60ef3981792f ]--- + +这样的堆栈跟踪提供了足够的信息来识别内核源代码中发生错误的那一行。根据问题的 +严重性，它还可能包含 **“Oops”** 一词，比如:: + + BUG: unable to handle kernel NULL pointer dereference at (null) + IP: [<c06969d4>] iret_exc+0x7d0/0xa59 + *pdpt = 000000002258a001 *pde = 0000000000000000 + Oops: 0002 [#1] PREEMPT SMP + ... + +尽管有 **Oops** 或其他类型的堆栈跟踪，但通常需要找到出问题的行来识别和处理缺 +陷。在本章中，我们将参考“Oops”来了解需要分析的各种堆栈跟踪。 + +如果内核是用 ``CONFIG_DEBUG_INFO`` 编译的，那么可以使用文件： +`scripts/decode_stacktrace.sh` 。 + +链接的模块 +----------- + +受到污染或正在加载/卸载的模块用“（…）”标记，污染标志在 +`Documentation/admin-guide/tainted-kernels.rst` 文件中进行了描述，“正在被加 +载”用“+”标注，“正在被卸载”用“-”标注。 + + +Oops消息在哪？ +--------------- + +通常，Oops文本由klogd从内核缓冲区读取，然后交给 ``syslogd`` ，后者将其写入 +syslog文件，通常是 ``/var/log/messages`` （取决于 ``/etc/syslog.conf`` ）。 +在使用systemd的系统上，它也可以由 ``journald`` 守护进程存储，并通过运行 +``journalctl`` 命令进行访问。 + +有时 ``klogd`` 会挂掉，这种情况下您可以运行 ``dmesg > file`` 从内核缓冲区 +读取数据并保存它。或者您可以 ``cat /proc/kmsg > file`` ，但是您必须适时 +中断以停止传输，因为 ``kmsg`` 是一个“永无止境的文件”。 + +如果机器严重崩溃，无法输入命令或磁盘不可用，那还有三个选项： + +(1) 手动复制屏幕上的文本，并在机器重新启动后输入。很难受，但这是突然崩溃下 + 唯一的选择。或者你可以用数码相机拍下屏幕——虽然不那么好，但总比什么都没 + 有好。如果消息滚动超出控制台顶部，使用更高分辨率（例如 ``vga=791`` ） + 引导启动将允许您阅读更多文本。（警告：这需要 ``vesafb`` ，因此对“早期” + 的Oppses没有帮助） + +(2) 从串口终端启动（参见 + :ref:`Documentation/admin-guide/serial-console.rst <serial_console>` ）， + 在另一台机器上运行调制解调器然后用你喜欢的通信程序捕获输出。 + Minicom运行良好。 + +(3) 使用Kdump（参阅 Documentation/admin-guide/kdump/kdump.rst ），使用 + Documentation/admin-guide/kdump/gdbmacros.txt 中的dmesg gdbmacro从旧内存 + 中提取内核环形缓冲区。 + +找到缺陷位置 +------------- + +如果你能指出缺陷在内核源代码中的位置，则报告缺陷的效果会非常好。这有两种方法。 +通常来说使用 ``gdb`` 会比较容易，不过内核需要用调试信息来预编译。 + +gdb +^^^^ + +GNU 调试器（GNU debugger， ``gdb`` ）是从 ``vmlinux`` 文件中找出OOPS的确切 +文件和行号的最佳方法。 + +在使用 ``CONFIG_DEBUG_INFO`` 编译的内核上使用gdb效果最好。可通过运行以下命令 +进行设置:: + + $ ./scripts/config -d COMPILE_TEST -e DEBUG_KERNEL -e DEBUG_INFO + +在用 ``CONFIG_DEBUG_INFO`` 编译的内核上，你可以直接从OOPS复制EIP值:: + + EIP: 0060:[<c021e50e>] Not tainted VLI + +并使用GDB来将其翻译成可读形式:: + + $ gdb vmlinux + (gdb) l *0xc021e50e + +如果没有启用 ``CONFIG_DEBUG_INFO`` ，则使用OOPS的函数偏移:: + + EIP is at vt_ioctl+0xda8/0x1482 + +并在启用 ``CONFIG_DEBUG_INFO`` 的情况下重新编译内核:: + + $ ./scripts/config -d COMPILE_TEST -e DEBUG_KERNEL -e DEBUG_INFO + $ make vmlinux + $ gdb vmlinux + (gdb) l *vt_ioctl+0xda8 + 0x1888 is in vt_ioctl (drivers/tty/vt/vt_ioctl.c:293). + 288 { + 289 struct vc_data *vc = NULL; + 290 int ret = 0; + 291 + 292 console_lock(); + 293 if (VT_BUSY(vc_num)) + 294 ret = -EBUSY; + 295 else if (vc_num) + 296 vc = vc_deallocate(vc_num); + 297 console_unlock(); + +或者若您想要更详细的显示:: + + (gdb) p vt_ioctl + $1 = {int (struct tty_struct *, unsigned int, unsigned long)} 0xae0 <vt_ioctl> + (gdb) l *0xae0+0xda8 + +您也可以使用对象文件作为替代:: + + $ make drivers/tty/ + $ gdb drivers/tty/vt/vt_ioctl.o + (gdb) l *vt_ioctl+0xda8 + +如果你有调用跟踪，类似:: + + Call Trace: + [<ffffffff8802c8e9>] :jbd:log_wait_commit+0xa3/0xf5 + [<ffffffff810482d9>] autoremove_wake_function+0x0/0x2e + [<ffffffff8802770b>] :jbd:journal_stop+0x1be/0x1ee + ... + +这表明问题可能在 :jbd: 模块中。您可以在gdb中加载该模块并列出相关代码:: + + $ gdb fs/jbd/jbd.ko + (gdb) l *log_wait_commit+0xa3 + +.. note:: + + 您还可以对堆栈跟踪处的任何函数调用执行相同的操作，例如:: + + [<f80bc9ca>] ? dvb_usb_adapter_frontend_exit+0x3a/0x70 [dvb_usb] + + 上述调用发生的位置可以通过以下方式看到:: + + $ gdb drivers/media/usb/dvb-usb/dvb-usb.o + (gdb) l *dvb_usb_adapter_frontend_exit+0x3a + +objdump +^^^^^^^^ + +要调试内核，请使用objdump并从崩溃输出中查找十六进制偏移，以找到有效的代码/汇 +编行。如果没有调试符号，您将看到所示例程的汇编程序代码，但是如果内核有调试 +符号，C代码也将可见（调试符号可以在内核配置菜单的hacking项中启用）。例如:: + + $ objdump -r -S -l --disassemble net/dccp/ipv4.o + +.. note:: + + 您需要处于内核树的顶层以便此获得您的C文件。 + +如果您无法访问源代码，仍然可以使用以下方法调试一些崩溃转储（如Dave Miller的 +示例崩溃转储输出所示）:: + + EIP is at +0x14/0x4c0 + ... + Code: 44 24 04 e8 6f 05 00 00 e9 e8 fe ff ff 8d 76 00 8d bc 27 00 00 + 00 00 55 57 56 53 81 ec bc 00 00 00 8b ac 24 d0 00 00 00 8b 5d 08 + <8b> 83 3c 01 00 00 89 44 24 14 8b 45 28 85 c0 89 44 24 18 0f 85 + + Put the bytes into a "foo.s" file like this: + + .text + .globl foo + foo: + .byte .... /* bytes from Code: part of OOPS dump */ + + Compile it with "gcc -c -o foo.o foo.s" then look at the output of + "objdump --disassemble foo.o". + + Output: + + ip_queue_xmit: + push %ebp + push %edi + push %esi + push %ebx + sub $0xbc, %esp + mov 0xd0(%esp), %ebp ! %ebp = arg0 (skb) + mov 0x8(%ebp), %ebx ! %ebx = skb->sk + mov 0x13c(%ebx), %eax ! %eax = inet_sk(sk)->opt + +`scripts/decodecode` 文件可以用来自动完成大部分工作，这取决于正在调试的CPU +体系结构。 + +报告缺陷 +--------- + +一旦你通过定位缺陷找到了其发生的地方，你可以尝试自己修复它或者向上游报告它。 + +为了向上游报告，您应该找出用于开发受影响代码的邮件列表。这可以使用 ``get_maintainer.pl`` 。 + + +例如，您在gspca的sonixj.c文件中发现一个缺陷，则可以通过以下方法找到它的维护者:: + + $ ./scripts/get_maintainer.pl -f drivers/media/usb/gspca/sonixj.c + Hans Verkuil <hverkuil@xs4all.nl> (odd fixer:GSPCA USB WEBCAM DRIVER,commit_signer:1/1=100%) + Mauro Carvalho Chehab <mchehab@kernel.org> (maintainer:MEDIA INPUT INFRASTRUCTURE (V4L/DVB),commit_signer:1/1=100%) + Tejun Heo <tj@kernel.org> (commit_signer:1/1=100%) + Bhaktipriya Shridhar <bhaktipriya96@gmail.com> (commit_signer:1/1=100%,authored:1/1=100%,added_lines:4/4=100%,removed_lines:9/9=100%) + linux-media@vger.kernel.org (open list:GSPCA USB WEBCAM DRIVER) + linux-kernel@vger.kernel.org (open list) + +请注意它将指出： + +- 最后接触源代码的开发人员（如果这是在git树中完成的）。在上面的例子中是Tejun + 和Bhaktipriya（在这个特定的案例中，没有人真正参与这个文件的开发）； +- 驱动维护人员（Hans Verkuil）； +- 子系统维护人员（Mauro Carvalho Chehab）； +- 驱动程序和/或子系统邮件列表（linux-media@vger.kernel.org）； +- Linux内核邮件列表（linux-kernel@vger.kernel.org）。 + +通常，修复缺陷的最快方法是将它报告给用于开发相关代码的邮件列表（linux-media +ML），抄送驱动程序维护者（Hans）。 + +如果你完全不知道该把报告寄给谁，且 ``get_maintainer.pl`` 也没有提供任何有用 +的信息，请发送到linux-kernel@vger.kernel.org。 + +感谢您的帮助，这使Linux尽可能稳定:-) + +修复缺陷 +--------- + +如果你懂得编程，你不仅可以通过报告错误来帮助我们，还可以提供一个解决方案。 +毕竟，开源就是分享你的工作，你不想因为你的天才而被认可吗？ + +如果你决定这样做，请在制定解决方案后将其提交到上游。 + +请务必阅读 +:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` ， +以帮助您的代码被接受。 + + +--------------------------------------------------------------------------- + +用 ``klogd`` 进行Oops跟踪的注意事项 +------------------------------------ + +为了帮助Linus和其他内核开发人员， ``klogd`` 对保护故障的处理提供了大量支持。 +为了完整支持地址解析，至少应该使用 ``sysklogd`` 包的1.3-pl3版本。 + +当发生保护故障时， ``klogd`` 守护进程会自动将内核日志消息中的重要地址转换为 +它们的等效符号。然后通过 ``klogd`` 使用的任何报告机制来转发这个已翻译的内核 +消息。保护错误消息可以直接从消息文件中剪切出来并转发给内核开发人员。 + +``klogd`` 执行两种类型的地址解析，静态翻译和动态翻译。静态翻译使用System.map +文件。为了进行静态转换， ``klogd`` 守护进程必须能够在守护进程初始化时找到系 +统映射文件。有关 ``klogd`` 如何搜索映射文件的信息，请参见klogd手册页。 + +当使用内核可加载模块时，动态地址转换非常重要。由于内核模块的内存是从内核的 +动态内存池中分配的，因此无论是模块的开头还是模块中的函数和符号都没有固定的 +位置。 + +内核支持系统调用，允许程序确定加载哪些模块及其在内存中的位置。klogd守护进程 +使用这些系统调用构建了一个符号表，可用于调试可加载内核模块中发生的保护错误。 + +klogd至少会提供产生保护故障的模块的名称。如果可加载模块的开发人员选择从模块 +导出符号信息，则可能会有其他可用的符号信息。 + +由于内核模块环境可以是动态的，因此当模块环境发生变化时，必须有一种通知 +``klogd`` 守护进程的机制。有一些可用的命令行选项允许klogd向当前正在执行的守 +护进程发出信号示意应该刷新符号信息。有关更多信息，请参阅 ``klogd`` 手册页。 + +sysklogd发行版附带了一个补丁，它修改了 ``modules-2.0.0`` 包，以便在加载或 +卸载模块时自动向klogd发送信号。应用此补丁基本上可无缝支持调试内核可加载模块 +发生的保护故障。 + +以下是 ``klogd`` 处理的可加载模块中的保护故障示例:: + + Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc + Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000 + Aug 29 09:51:01 blizard kernel: *pde = 00000000 + Aug 29 09:51:01 blizard kernel: Oops: 0002 + Aug 29 09:51:01 blizard kernel: CPU: 0 + Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868] + Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212 + Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c + Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c + Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018 + Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000) + Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001 + Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00 + Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036 + Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128] + Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3 + +--------------------------------------------------------------------------- + +:: + + Dr. G.W. Wettstein Oncology Research Div. Computing Facility + Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com + 820 4th St. N. + Fargo, ND 58122 + Phone: 701-234-7556 diff --git a/Documentation/translations/zh_CN/admin-guide/index.rst b/Documentation/translations/zh_CN/admin-guide/index.rst index 48bbd3ebad48..be835ec8e632 100644 --- a/Documentation/translations/zh_CN/admin-guide/index.rst +++ b/Documentation/translations/zh_CN/admin-guide/index.rst @@ -13,9 +13,13 @@ Linux 内核用户和管理员指南 这个初始部分包含总体信息，包括描述内核的README， 关于内核参数的文档等。 -Todolist: +.. toctree:: + :maxdepth: 1 README + +Todolist: + kernel-parameters devices sysctl/index @@ -28,16 +32,21 @@ Todolist: 下面的一组文档，针对的是试图跟踪问题和bug的用户。 -Todolist: +.. toctree:: + :maxdepth: 1 - reporting-bugs + reporting-issues security-bugs bug-hunting bug-bisect tainted-kernels + init + +Todolist: + + reporting-bugs ramoops dynamic-debug-howto - init kdump/index perf/index @@ -56,6 +65,7 @@ Todolist: clearing-warn-once cpu-load + unicode Todolist: @@ -111,7 +121,6 @@ Todolist: sysrq thunderbolt ufs - unicode vga-softcursor video-output xfs diff --git a/Documentation/translations/zh_CN/admin-guide/init.rst b/Documentation/translations/zh_CN/admin-guide/init.rst new file mode 100644 index 000000000000..fbaf6d97f86c --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/init.rst @@ -0,0 +1,54 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../admin-guide/init` + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +解释“No working init found.”启动挂起消息 +========================================= + +:作者: + + Andreas Mohr <andi at lisas period de> + + Cristian Souza <cristianmsbr at gmail period com> + +本文档提供了加载初始化二进制（init binary）失败的一些高层级原因（大致按执行 +顺序列出）。 + +1) **无法挂载根文件系统Unable to mount root FS** ：请设置“debug”内核参数（在 + 引导加载程序bootloader配置文件或CONFIG_CMDLINE）以获取更详细的内核消息。 + +2) **初始化二进制不存在于根文件系统上init binary doesn't exist on rootfs** ： + 确保您的根文件系统类型正确（并且 ``root=`` 内核参数指向正确的分区）；拥有 + 所需的驱动程序，例如SCSI或USB等存储硬件；文件系统（ext3、jffs2等）是内建的 + （或者作为模块由initrd预加载）。 + +3) **控制台设备损坏Broken console device** ： ``console= setup`` 中可能存在 + 冲突 --> 初始控制台不可用（initial console unavailable）。例如，由于串行 + IRQ问题（如缺少基于中断的配置）导致的某些串行控制台不可靠。尝试使用不同的 + ``console= device`` 或像 ``netconsole=`` 。 + +4) **二进制存在但依赖项不可用Binary exists but dependencies not available** ： + 例如初始化二进制的必需库依赖项，像 ``/lib/ld-linux.so.2`` 丢失或损坏。使用 + ``readelf -d <INIT>|grep NEEDED`` 找出需要哪些库。 + +5) **无法加载二进制Binary cannot be loaded** ：请确保二进制的体系结构与您的 + 硬件匹配。例如i386不匹配x86_64，或者尝试在ARM硬件上加载x86。如果您尝试在 + 此处加载非二进制文件（shell脚本？），您应该确保脚本在其工作头（shebang + header）行 ``#!/...`` 中指定能正常工作的解释器（包括其库依赖项）。在处理 + 脚本之前，最好先测试一个简单的非脚本二进制文件，比如 ``/bin/sh`` ，并确认 + 它能成功执行。要了解更多信息，请将代码添加到 ``init/main.c`` 以显示 + kernel_execve()的返回值。 + +当您发现新的失败原因时，请扩展本解释（毕竟加载初始化二进制是一个 **关键** 且 +艰难的过渡步骤，需要尽可能无痛地进行），然后向LKML提交一个补丁。 + +待办事项： + +- 通过一个可以存储 ``kernel_execve()`` 结果值的结构体数组实现各种 + ``run_init_process()`` 调用，并在失败时通过迭代 **所有** 结果来记录一切 + （非常重要的可用性修复）。 +- 试着使实现本身在一般情况下更有帮助，例如在受影响的地方提供额外的错误消息。 diff --git a/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst b/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst new file mode 100644 index 000000000000..6b4988da2c5a --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst @@ -0,0 +1,1335 @@ +.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0) +.. + If you want to distribute this text under CC-BY-4.0 only, please use 'The + Linux kernel developers' for author attribution and link this as source: + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-issues.rst +.. + Note: Only the content of this RST file as found in the Linux kernel sources + is available under CC-BY-4.0, as versions of this text that were processed + (for example by the kernel's build system) might contain content taken from + files which use a more restrictive license. + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/reporting-issues.rst + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + + +报告问题 ++++++++++ + + +简明指南（亦即 太长不看） +========================== + +您面临的是否为同系列稳定版或长期支持内核的普通内核的回归？是否仍然受支持？ +请搜索 `LKML内核邮件列表 <https://lore.kernel.org/lkml/>`_ 和 +`Linux稳定版邮件列表 <https://lore.kernel.org/stable/>`_ 存档中匹配的报告并 +加入讨论。如果找不到匹配的报告，请安装该系列的最新版本。如果它仍然出现问题， +报告给稳定版邮件列表（stable@vger.kernel.org）。 + +在所有其他情况下，请尽可能猜测是哪个内核部分导致了问题。查看MAINTAINERS文件， +了解开发人员希望如何得知问题，大多数情况下，报告问题都是通过电子邮件和抄送 +相关邮件列表进行的。检查报告目的地的存档中是否已有匹配的报告；也请搜索 +`LKML <https://lore.kernel.org/lkml/>`_ 和网络。如果找不到可加入的讨论，请 +安装 `最新的主线内核 <https://kernel.org/>`_ 。如果仍存在问题，请发送报告。 + +问题已经解决了，但是您希望看到它在一个仍然支持的稳定版或长期支持系列中得到 +解决？请安装其最新版本。如果它出现了问题，那么在主线中搜索修复它的更改，并 +检查是否正在回传（backporting）或者已放弃；如果两者都没有，那么可询问处理 +更改的人员。 + +**通用提醒** ：当安装和测试上述内核时，请确保它是普通的（即：没有补丁，也没 +有使用附加模块）。还要确保它是在一个正常的环境中构建和运行，并且在问题发生 +之前没有被污染（tainted）。 + +在编写报告时，要涵盖与问题相关的所有信息，如使用的内核和发行版。在碰见回归时， +尝试给出引入它的更改的提交ID，二分可以找到它。如果您同时面临Linux内核的多个 +问题，请分别报告每个问题。 + +一旦报告发出，请回答任何出现的问题，并尽可能地提供帮助。这包括通过不时重新 +测试新版本并发送状态更新来推动进展。 + + +如何向内核维护人员报告问题的逐步指南 +===================================== + +上面的简明指南概述了如何向Linux内核开发人员报告问题。对于已经熟悉向自由和开 +源软件（FLOSS）项目报告问题的人来说，这可能是他们所需要的全部内容。对于其他 +人，本部分更为详细，并一步一步地描述。为了便于阅读，它仍然尽量简洁，并省略 +了许多细节；这些在逐步指南后的参考章节中进行了描述，该章节更详细地解释了每 +个步骤。 + +注意：本节涉及的方面比简明指南多，顺序也稍有不同。这符合你的利益，以确保您 +尽早意识到看起来像Linux内核毛病的问题可能实际上是由其他原因引起的。这些步骤 +可以确保你最终不会觉得在这一过程中投入的时间是浪费： + + * 您是否面临硬件或软件供应商提供的Linux内核的问题？那么基本上您最好停止阅读 + 本文档，转而向您的供应商报告问题，除非您愿意自己安装最新的Linux版本。寻找 + 和解决问题往往需要后者。 + + * 使用您喜爱的网络搜索引擎对现有报告进行粗略搜索；此外，请检查 + `Linux内核邮件列表（LKML） <https://lore.kernel.org/lkml/>`_ 的存档。如果 + 找到匹配的报告，请加入讨论而不是发送新报告。 + + * 看看你正在处理的问题是否为回归问题、安全问题或非常严重的问题：这些都是需 + 要在接下来的一些步骤中特别处理的“高优先级问题”。 + + * 确保不是内核环境导致了您面临的问题。 + + * 创建一个新的备份，并将系统修复和恢复工具放在手边。 + + * 确保您的系统不会通过动态构建额外的内核模块来增强其内核，像DKMS这样的解决 + 方案可能在您不知情的情况下就在本地进行了这样的工作。 + + * 当问题发生时，检查您的内核是否被“污染”，因为使内核设置这个标志的事件可能 + 会导致您面临的问题。 + + * 粗略地写下如何重现这个问题。如果您同时处理多个问题，请为每个问题单独写注 + 释，并确保它们在新启动的系统上独立出现。这是必要的，因为每个问题都需要分 + 别报告给内核开发人员，除非它们严重纠缠在一起。 + + * 如果您正面临稳定版或长期支持版本线的回归（例如从5.10.4更新到5.10.5时出现 + 故障），请查看后文“报告稳定版和长期支持内核线的回归”小节。 + + * 定位可能引起问题的驱动程序或内核子系统。找出其开发人员期望的报告的方式和 + 位置。注意：大多数情况下不会是 bugzilla.kernel.org，因为问题通常需要通 + 过邮件发送给维护人员和公共邮件列表。 + + * 在缺陷追踪器或问题相关邮件列表的存档中彻底搜索可能与您的问题匹配的报告。 + 如果你发现了一些相关讨论，请加入讨论而不是发送新的报告。 + +在完成这些准备之后，你将进入主要部分： + + * 除非您已经在运行最新的“主线”Linux内核，否则最好在报告流程前安装它。在某些 + 情况下，使用最新的“稳定版”Linux进行测试和报告也是可以接受的替代方案；在 + 合并窗口期间，这实际上可能是最好的方法，但在开发阶段最好还是暂停几天。无论 + 你选择什么版本，最好使用“普通”构建。忽略这些建议会大大增加您的报告被拒绝 + 或忽略的风险。 + + * 确保您刚刚安装的内核在运行时不会“污染”自己。 + + * 在您刚刚安装的内核中复现这个问题。如果它没有出现，请查看下方只发生在 + 稳定版和长期支持内核的问题的说明。 + + * 优化你的笔记：试着找到并写出最直接的复现问题的方法。确保最终结果包含所有 + 重要的细节，同时让第一次听说的人容易阅读和理解。如果您在此过程中学到了一 + 些东西，请考虑再次搜索关于该问题的现有报告。 + + * 如果失败涉及“panic”、“Oops”、“warning”或“BUG”，请考虑解码内核日志以查找触 + 发错误的代码行。 + + * 如果您的问题是回归问题，请尽可能缩小引入问题时的范围。 + + * 通过详细描述问题来开始编写报告。记得包括以下条目：您为复现而安装的最新内 + 核版本、使用的Linux发行版以及关于如何复现该问题的说明。如果可能，将内核 + 构建配置（.config）和 ``dmesg`` 的输出放在网上的某个地方，并链接到它。包 + 含或上传所有其他可能相关的信息，如Oops的输出/截图或来自 ``lspci`` 的输出 + 。一旦你写完了这个主要部分，请在上方插入一个正常长度的段落快速概述问题和 + 影响。再在此之上添加一个简单描述问题的句子，以得到人们的阅读。现在给出一 + 个更短的描述性标题或主题。然后就可以像MAINTAINERS文件告诉你的那样发送或 + 提交报告了，除非你在处理一个“高优先级问题”：它们需要按照下面“高优先级问 + 题的特殊处理”所述特别关照。 + + * 等待别人的反应，继续推进事情，直到你能够接受这样或那样的结果。因此，请公 + 开和及时地回应任何询问。测试提出的修复。积极地测试：至少重新测试每个新主 + 线版本的首个候选版本（RC），并报告你的结果。如果出现拖延，就友好地提醒一 + 下。如果你没有得到任何帮助或者未能满意，请试着自己帮助自己。 + + +报告稳定版和长期支持内核线的回归 +---------------------------------- + +如果您发现了稳定版或长期支持内核版本线中的回归问题并按上述流程跳到这里，那么 +请阅读本小节。即例如您在从5.10.4更新到5.10.5时出现了问题（从5.9.15到5.10.5则 +不是）。开发人员希望尽快修复此类回归，因此有一个简化流程来报告它们： + + * 检查内核开发人员是否仍然维护你关心的Linux内核版本线：去 `kernel.org 的首页 + <https://kernel.org/>`_ ，确保此特定版本线的最新版没有“[EOL]”标记。 + + * 检查 `Linux稳定版邮件列表 <https://lore.kernel.org/stable/>`_ 中的现有报告。 + + * 从特定的版本线安装最新版本作为纯净内核。确保这个内核没有被污染，并且仍然 + 存在问题，因为问题可能已经在那里被修复了。如果您第一次发现供应商内核的问题， + 请检查已知最新版本的普通构建是否可以正常运行。 + + * 向Linux稳定版邮件列表发送一个简短的问题报告(stable@vger.kernel.org)。大致 + 描述问题，并解释如何复现。讲清楚首个出现问题的版本和最后一个工作正常的版本。 + 然后等待进一步的指示。 + +下面的参考章节部分详细解释了这些步骤中的每一步。 + + +报告只发生在较旧内核版本线的问题 +---------------------------------- + +若您尝试了上述的最新主线内核，但未能在那里复现问题，那么本小节适用于您；以下 +流程有助于使问题在仍然支持的稳定版或长期支持版本线，或者定期基于最新稳定版或 +长期支持内核的供应商内核中得到修复。如果是这种情况，请执行以下步骤： + + * 请做好准备，接下来的几个步骤可能无法在旧版本中解决问题：修复可能太大或太 + 冒险，无法移植到那里。 + + * 执行前节“报告稳定版和长期支持内核线的回归”中的前三个步骤。 + + * 在Linux内核版本控制系统中搜索修复主线问题的更改，因为它的提交消息可能会 + 告诉你修复是否已经计划好了支持。如果你没有找到，搜索适当的邮件列表，寻找 + 讨论此类问题或同行评议可能修复的帖子；然后检查讨论是否认为修复不适合支持。 + 如果支持根本不被考虑，加入最新的讨论，询问是否有可能。 + + * 前面的步骤之一应该会给出一个解决方案。如果仍未能成功，请向可能引起问题的 + 子系统的维护人员询问建议；抄送特定子系统的邮件列表以及稳定版邮件列表 + +下面的参考章节部分详细解释了这些步骤中的每一步。 + + +参考章节：向内核维护者报告问题 +=============================== + +上面的详细指南简要地列出了所有主要步骤，这对大多数人来说应该足够了。但有时， +即使是有经验的用户也可能想知道如何实际执行这些步骤之一。这就是本节的目的， +因为它将提供关于上述每个步骤的更多细节。请将此作为参考文档：可以从头到尾 +阅读它。但它主要是为了浏览和查找如何实际执行这些步骤的详细信息。 + +在深入挖掘细节之前，我想先给你一些一般性建议： + + * Linux内核开发人员很清楚这个过程很复杂，比其他的FLOSS项目要求更多。我们很 + 希望让它更简单。但这需要在不同的地方以及一些基础设施上付诸努力，这些基础 + 设施需要持续的维护；尚未有人站出来做这些工作，所以目前情况就是这样。 + + * 与某些供应商签订的保证或支持合同并不能使您有权要求上游Linux内核社区的开 + 发人员进行修复：这样的合同完全在Linux内核、其开发社区和本文档的范围之外。 + 这就是为什么在这种情况下，你不能要求任何契约保证，即使开发人员处理的问 + 题对供应商有效。如果您想主张您的权利，使用供应商的支持渠道代替。当这样做 + 的时候，你可能想提出你希望看到这个问题在上游Linux内核中修复；可以这是确 + 保最终修复将被纳入所有Linux发行版的唯一方法来鼓励他们。 + + * 如果您从未向FLOSS项目报告过任何问题，那么您应该考虑阅读 `如何有效地报告 + 缺陷 <https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_ ， `如何 + 以明智的方式提问 <http://www.catb.org/esr/faqs/smart-questions.html>`_ ， + 和 `如何提出好问题 <https://jvns.ca/blog/good-questions/>`_ 。 + +解决这些问题之后，可以在下面找到如何正确地向Linux内核报告问题的详细信息。 + + +确保您使用的是上游Linux内核 +---------------------------- + + *您是否面临硬件或软件供应商提供的Linux内核的问题？那么基本上您最好停止阅 + 读本文档，转而向您的供应商报告问题，除非您愿意自己安装最新的Linux版本。 + 寻找和解决问题往往需要后者。* + +与大多数程序员一样，Linux内核开发人员不喜欢花时间处理他们维护的源代码中根本 +不会发生的问题的报告。这只会浪费每个人的时间，尤其是你的时间。不幸的是，当 +涉及到内核时，这样的情况很容易发生，并且常常导致双方气馁。这是因为几乎所有预 +装在设备（台式机、笔记本电脑、智能手机、路由器等）上的Linux内核，以及大多数 +由Linux发行商提供的内核，都与由kernel.org发行的官方Linux内核相距甚远：从Linux +开发的角度来看，这些供应商提供的内核通常是古老的或者经过了大量修改，通常两点 +兼具。 + +大多数供应商内核都不适合用来向Linux内核开发人员报告问题：您在其中遇到的问题 +可能已经由Linux内核开发人员在数月或数年前修复；此外，供应商的修改和增强可能 +会导致您面临的问题，即使它们看起来很小或者完全不相关。这就是为什么您应该向 +供应商报告这些内核的问题。它的开发者应该查看报告，如果它是一个上游问题，直接 +于上游修复或将报告转发到那里。在实践中，这有时行不通。因此，您可能需要考虑 +通过自己安装最新的Linux内核内核来绕过供应商。如果如果您选择此方法，那么本指 +南后面的步骤将解释如何在排除了其他可能导致您的问题的原因后执行此操作。 + +注意前段使用的词语是“大多数”，因为有时候开发人员实际上愿意处理供应商内核出现 +的问题报告。他们是否这么做很大程度上取决于开发人员和相关问题。如果发行版只 +根据最近的Linux版本对内核进行了较小修改，那么机会就比较大；例如对于Debian +GNU/Linux Sid或Fedora Rawhide所提供的主线内核。一些开发人员还将接受基于最新 +稳定内核的发行版内核问题报告，只要它改动不大；例如Arch Linux、常规Fedora版本 +和openSUSE Turboweed。但是请记住，您最好使用主线Linux，并避免在此流程中使用 +稳定版内核，如“安装一个新的内核进行测试”一节中所详述。 + +当然，您可以忽略所有这些建议，并向上游Linux开发人员报告旧的或经过大量修改的 +供应商内核的问题。但是注意，这样的报告经常被拒绝或忽视，所以自行小心考虑一下。 +不过这还是比根本不报告问题要好：有时候这样的报告会直接或间接地帮助解决之后的 +问题。 + + +搜索现有报告（第一部分） +------------------------- + + *使用您喜爱的网络搜索引擎对现有报告进行粗略搜索；此外，请检查Linux内核 + 邮件列表（LKML）的存档。如果找到匹配的报告，请加入讨论而不是发送新报告。* + +报告一个别人已经提出的问题，对每个人来说都是浪费时间，尤其是作为报告人的你。 +所以彻底检查是否有人已经报告了这个问题，这对你自己是有利的。在流程中的这一步， +可以只执行一个粗略的搜索：一旦您知道您的问题需要报告到哪里，稍后的步骤将告诉 +您如何详细搜索。尽管如此，不要仓促完成这一步，它可以节省您的时间和减少麻烦。 + +只需先用你最喜欢的搜索引擎在互联网上搜索。然后再搜索Linux内核邮件列表（LKML） +存档。 + +如果搜索结果实在太多，可以考虑让你的搜索引擎将搜索时间范围限制在过去的一个 +月或一年。而且无论你在哪里搜索，一定要用恰当的搜索关键词；也要变化几次关键 +词。同时，试着从别人的角度看问题：这将帮助你想出其他的关键词。另外，一定不 +要同时使用过多的关键词。记住搜索时要同时尝试包含和不包含内核驱动程序的名称 +或受影响的硬件组件的名称等信息。但其确切的品牌名称（比如说“华硕红魔 Radeon +RX 5700 XT Gaming OC”）往往帮助不大，因为它太具体了。相反，尝试搜索术语，如 +型号（Radeon 5700 或 Radeon 5000）和核心代号（“Navi”或“Navi10”），以及包含 +和不包含其制造商（“AMD”）。 + +如果你发现了关于你的问题的现有报告，请加入讨论，因为你可能会提供有价值的额 +外信息。这一点很重要，即使是在修复程序已经准备好或处于最后阶段，因为开发人 +员可能会寻找能够提供额外信息或测试建议修复程序的人。跳到“发布报告后的责任” +一节，了解有关如何正确参与的细节。 + +注意，搜索 `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_ 网站可能 +也是一个好主意，因为这可能会提供有价值的见解或找到匹配的报告。如果您发现后者， +请记住：大多数子系统都希望在不同的位置报告，如下面“你需要将问题报告到何处” +一节中所述。因此本应处理这个问题的开发人员甚至可能不知道bugzilla的工单。所以 +请检查工单中的问题是否已经按照本文档所述得到报告，如果没有，请考虑这样做。 + +高优先级的问题？ +----------------- + + *看看你正在处理的问题是否是回归问题、安全问题或非常严重的问题：这些都是 + 需要在接下来的一些步骤中特别处理的“高优先级问题”。* + +Linus Torvalds和主要的Linux内核开发人员希望看到一些问题尽快得到解决，因此在 +报告过程中有一些“高优先级问题”的处理略有不同。有三种情况符合条件:回归、安全 +问题和非常严重的问题。 + +如果在旧版本的Linux内核中工作的东西不能在新版本的Linux内核中工作，或者某种 +程度上在新版本的Linux内核中工作得更差，那么你就需要处理“回归”。因此，当一个 +在Linux 5.7中表现良好的WiFi驱动程序在5.8中表现不佳或根本不能工作时，这是一 +种回归。如果应用程序在新的内核中出现不稳定的现象，这也是一种回归，这可能是 +由于内核和用户空间之间的接口（如procfs和sysfs）发生不兼容的更改造成的。显著 +的性能降低或功耗增加也可以称为回归。但是请记住:新内核需要使用与旧内核相似的 +配置来构建（参见下面如何实现这一点）。这是因为内核开发人员在实现新特性时有 +时无法避免不兼容性；但是为了避免回归，这些特性必须在构建配置期间显式地启用。 + +什么是安全问题留给您自己判断。在继续之前，请考虑阅读 +“Documentation/translations/zh_CN/admin-guide/security-bugs.rst”， +因为它提供了如何最恰当地处理安全问题的额外细节。 + +当发生了完全无法接受的糟糕事情时，此问题就是一个“非常严重的问题”。例如， +Linux内核破坏了它处理的数据或损坏了它运行的硬件。当内核突然显示错误消息 +（“kernel panic”）并停止工作，或者根本没有任何停止信息时，您也在处理一个严重 +的问题。注意：不要混淆“panic”（内核停止自身的致命错误）和“Oops”（可恢复错误）， +因为显示后者之后内核仍然在运行。 + + +确保环境健康 +-------------- + + *确保不是内核所处环境导致了你所面临的问题。* + +看起来很像内核问题的问题有时是由构建或运行时环境引起的。很难完全排除这种问 +题，但你应该尽量减少这种问题： + + * 构建内核时，请使用经过验证的工具，因为编译器或二进制文件中的错误可能会导 + 致内核出现错误行为。 + + * 确保您的计算机组件在其设计规范内运行；这对处理器、内存和主板尤为重要。因 + 此，当面临潜在的内核问题时，停止低电压或超频。 + + * 尽量确保不是硬件故障导致了你的问题。例如，内存损坏会导致大量的问题，这些 + 问题会表现为看起来像内核问题。 + + * 如果你正在处理一个文件系统问题，你可能需要用 ``fsck`` 检查一下文件系统， + 因为它可能会以某种方式被损坏，从而导致无法预期的内核行为。 + + * 在处理回归问题时，要确保没有在更新内核的同时发生了其他变化。例如，这个问 + 题可能是由同时更新的其他软件引起的。也有可能是在你第一次重启进入新内核时， + 某个硬件巧合地坏了。更新系统 BIOS 或改变 BIOS 设置中的某些内容也会导致 + 一些看起来很像内核回归的问题。 + + +为紧急情况做好准备 +------------------- + + *创建一个全新的备份，并将系统修复和还原工具放在手边* + +我得提醒您，您正在和计算机打交道，计算机有时会出现意想不到的事情，尤其是当 +您折腾其操作系统的内核等关键部件时。而这就是你在这个过程中要做的事情。因此， +一定要创建一个全新的备份；还要确保你手头有修复或重装操作系统的所有工具， +以及恢复备份所需的一切。 + + +确保你的内核不会被增强 +------------------------ + + *确保您的系统不会通过动态构建额外的内核模块来增强其内核，像DKMS这样的解 + 决方案可能在您不知情的情况下就在本地进行了这样的工作。* + +如果内核以任何方式得到增强，那么问题报告被忽略或拒绝的风险就会急剧增加。这就 +是为什么您应该删除或禁用像akmods和DKMS这样的机制：这些机制会自动构建额外内核 +模块，例如当您安装新的Linux内核或第一次引导它时。也要记得同时删除他们可能安装 +的任何模块。然后重新启动再继续。 + +注意，你可能不知道你的系统正在使用这些解决方案之一：当你安装 Nvidia 专有图 +形驱动程序、VirtualBox 或其他需要 Linux 内核以外的模块支持的软件时，它们通 +常会静默设置。这就是为什么你可能需要卸载这些软件的软件包，以摆脱任何第三方 +内核模块。 + + +检查“污染”标志 +---------------- + + *当问题发生时，检查您的内核是否被“污染”，因为使内核设置这个标志的事件可 + 能会导致您面临的问题。* + +当某些可能会导致看起来完全不相关的后续错误的事情发生时，内核会用“污染 +（taint）”标志标记自己。如果您的内核受到污染，那么您面临的可能是这样的错误。 +因此在投入更多时间到这个过程中之前，尽早排除此情况可能对你有好处。这是这个 +步骤出现在这里的唯一原因，因为这个过程稍后会告诉您安装最新的主线内核；然后 +您将需要再次检查污染标志，因为当它出问题的时候内核报告会关注它。 + +在正在运行的系统上检查内核是否污染非常容易：如果 ``cat /proc/sys/kernel/tainted`` +返回“0”，那么内核没有被污染，一切正常。在某些情况下无法检查该文件；这就是 +为什么当内核报告内部问题（“kernel bug”）、可恢复错误（“kernel Oops”）或停止 +操作前不可恢复的错误（“kernel panic”）时，它也会提到污染状态。当其中一个错 +误发生时，查看打印的错误消息的顶部，搜索以“CPU:”开头的行。如果发现问题时内 +核未被污染，那么它应该以“Not infected”结束；如果你看到“Tainted:”且后跟一些 +空格和字母，那就被污染了。 + +如果你的内核被污染了，请阅读“Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst” +以找出原因。设法消除污染因素。通常是由以下三种因素之一引起的： + + 1. 发生了一个可恢复的错误（“kernel Oops”），内核污染了自己，因为内核知道在 + 此之后它可能会出现奇怪的行为错乱。在这种情况下，检查您的内核或系统日志， + 并寻找以下列文字开头的部分:: + + Oops: 0000 [#1] SMP + + 如方括号中的“#1”所示，这是自启动以来的第一次Oops。每个Oops和此后发生的 + 任何其他问题都可能是首个Oops的后续问题，即使这两个问题看起来完全不相关。 + 通过消除首个Oops的原因并在之后复现该问题，可以排除这种情况。有时仅仅 + 重新启动就足够了，有时更改配置后重新启动可以消除Oops。但是在这个流程中 + 不要花费太多时间在这一点上，因为引起Oops的原因可能已经在您稍后将按流程 + 安装的新Linux内核版本中修复了。 + + 2. 您的系统使用的软件安装了自己的内核模块，例如Nvidia的专有图形驱动程序或 + VirtualBox。当内核从外部源（即使它们是开源的）加载此类模块时，它会污染 + 自己：它们有时会在不相关的内核区域导致错误，从而可能导致您面临的问题。 + 因此，当您想要向Linux内核开发人员报告问题时，您必须阻止这些模块加载。 + 大多数情况下最简单的方法是：临时卸载这些软件，包括它们可能已经安装的任 + 何模块。之后重新启动。 + + 3. 当内核加载驻留在Linux内核源代码staging树中的模块时，它也会污染自身。这 + 是一个特殊的区域，代码（主要是驱动程序）还没有达到正常Linux内核的质量 + 标准。当您报告此种模块的问题时，内核受到污染显然是没有问题的；只需确保 + 问题模块是造成污染的唯一原因。如果问题发生在一个不相关的区域，重新启动 + 并通过指定 ``foo.blacklist=1`` 作为内核参数临时阻止该模块被加载（用有 + 问题的模块名替换“foo”）。 + + +记录如何重现问题 +------------------ + + *粗略地写下如何重现这个问题。如果您同时处理多个问题，请为每个问题单独写 + 注释，并确保它们在新启动的系统上独立出现。这是必要的，因为每个问题都需 + 要分别报告给内核开发人员，除非它们严重纠缠在一起。* + +如果你同时处理多个问题，必须分别报告每个问题，因为它们可能由不同的开发人员 +处理。在一份报告中描述多种问题，也会让其他人难以将其分开。因此只有在问题严 +重纠缠的情况下，才能将问题合并在一份报告中。 + +此外，在报告过程中，你必须测试该问题是否发生在其他内核版本上。因此，如果您 +知道如何在一个新启动的系统上快速重现问题，将使您的工作更加轻松。 + +注意：报告只发生过一次的问题往往是没有结果的，因为它们可能是由于宇宙辐射导 +致的位翻转。所以你应该尝试通过重现问题来排除这种情况，然后再继续。如果你有 +足够的经验来区分由于硬件故障引起的一次性错误和难以重现的罕见内核问题，可以 +忽略这个建议。 + + +稳定版或长期支持内核的回归？ +----------------------------- + + *如果您正面临稳定版或长期支持版本线的回归（例如从5.10.4更新到5.10.5时出现 + 故障），请查看后文“报告稳定版和长期支持内核线的回归”小节。* + +稳定版和长期支持内核版本线中的回归是Linux开发人员非常希望解决的问题，这样的 +问题甚至比主线开发分支中的回归更不应出现，因为它们会很快影响到很多人。开发人员 +希望尽快了解此类问题，因此有一个简化流程来报告这些问题。注意，使用更新内核版 +本线的回归（比如从5.9.15切换到5.10.5时出现故障）不符合条件。 + + +你需要将问题报告到何处 +------------------------ + + *定位可能引起问题的驱动程序或内核子系统。找出其开发人员期望的报告的方式 + 和位置。注意：大多数情况下不会是bugzilla.kernel.org，因为问题通常需要通 + 过邮件发送给维护人员和公共邮件列表。* + +将报告发送给合适的人是至关重要的，因为Linux内核是一个大项目，大多数开发人员 +只熟悉其中的一小部分。例如，相当多的程序员只关心一个驱动程序，比如一个WiFi +芯片驱动程序；它的开发人员可能对疏远的或不相关的“子系统”（如TCP堆栈、 +PCIe/PCI子系统、内存管理或文件系统）的内部知识了解很少或完全不了解。 + +问题在于：Linux内核缺少一个，可以简单地将问题归档并让需要了解它的开发人员了 +解它的，中心化缺陷跟踪器。这就是为什么你必须找到正确的途径来自己报告问题。 +您可以在脚本的帮助下做到这一点（见下文），但它主要针对的是内核开发人员和专 +家。对于其他人来说，MAINTAINERS（维护人员）文件是更好的选择。 + +如何阅读MAINTAINERS维护者文件 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +为了说明如何使用 :ref:`MAINTAINERS <maintainers>` 文件，让我们假设您的笔记 +本电脑中的WiFi在更新内核后突然出现了错误行为。这种情况下可能是WiFi驱动的问 +题。显然，它也可能由于驱动基于的某些代码，但除非你怀疑有这样的东西会附着在 +驱动程序上。如果真的是其他的问题，驱动程序的开发人员会让合适的人参与进来。 + +遗憾的是，没有通用且简单的办法来检查哪个代码驱动了特定硬件组件。 + +在WiFi驱动出现问题的情况下，你可能想查看 ``lspci -k`` 的输出，因为它列出了 +PCI/PCIe总线上的设备和驱动它的内核模块:: + + [user@something ~]$ lspci -k + [...] + 3a:00.0 Network controller: Qualcomm Atheros QCA6174 802.11ac Wireless Network Adapter (rev 32) + Subsystem: Bigfoot Networks, Inc. Device 1535 + Kernel driver in use: ath10k_pci + Kernel modules: ath10k_pci + [...] + +但如果你的WiFi芯片通过USB或其他内部总线连接，这种方法就行不通了。在这种情况 +下，您可能需要检查您的WiFi管理器或 ``ip link`` 的输出。寻找有问题的网络接口 +的名称，它可能类似于“wlp58s0”。此名称可以用来找到驱动它的模块:: + + [user@something ~]$ realpath --relative-to=/sys/module//sys/class/net/wlp58s0/device/driver/module + ath10k_pci + +如果这些技巧不能进一步帮助您，请尝试在网上搜索如何缩小相关驱动程序或子系统 +的范围。如果你不确定是哪一个：试着猜一下，即使你猜得不好，也会有人会帮助你 +的。 + +一旦您知道了相应的驱动程序或子系统，您就希望在MAINTAINERS文件中搜索它。如果 +是“ath10k_pci”，您不会找到任何东西，因为名称太具体了。有时你需要在网上寻找 +帮助；但在此之前，请尝试使用一个稍短或修改过的名称来搜索MAINTAINERS文件，因 +为这样你可能会发现类似这样的东西:: + + QUALCOMM ATHEROS ATH10K WIRELESS DRIVER + Mail: A. Some Human <shuman@example.com> + Mailing list: ath10k@lists.infradead.org + Status: Supported + Web-page: https://wireless.wiki.kernel.org/en/users/Drivers/ath10k + SCM: git git://git.kernel.org/pub/scm/linux/kernel/git/kvalo/ath.git + Files: drivers/net/wireless/ath/ath10k/ + +注意：如果您阅读在Linux源代码树的根目录中找到的原始维护者文件，则行描述将是 +缩写。例如，“Mail:（邮件）”将是“M:”，“Mailing list:（邮件列表）”将是“L”， +“Status:（状态）”将是“S:”。此文件顶部有一段解释了这些和其他缩写。 + +首先查看“Status”状态行。理想情况下，它应该得到“Supported（支持）”或 +“Maintained（维护）”。如果状态为“Obsolete（过时的）”，那么你在使用一些过时的 +方法，需要转换到新的解决方案上。有时候，只有在感到有动力时，才会有人为代码 +提供“Odd Fixes”。如果碰见“Orphan”，你就完全不走运了，因为再也没有人关心代码 +了，只剩下这些选项:准备好与问题共存，自己修复它，或者找一个愿意修复它的程序员。 + +检查状态后，寻找以“bug:”开头的一行：它将告诉你在哪里可以找到子系统特定的缺 +陷跟踪器来提交你的问题。上面的例子没有此行。大多数部分都是这样，因为 Linux +内核的开发完全是由邮件驱动的。很少有子系统使用缺陷跟踪器，且其中只有一部分 +依赖于 bugzilla.kernel.org。 + +在这种以及其他很多情况下，你必须寻找以“Mail:”开头的行。这些行提到了特定代码 +的维护者的名字和电子邮件地址。也可以查找以“Mailing list:”开头的行，它告诉你 +开发代码的公共邮件列表。你的报告之后需要通过邮件发到这些地址。另外，对于所有 +通过电子邮件发送的问题报告，一定要抄送 Linux Kernel Mailing List（LKML） +<linux-kernel@vger.kernel.org>。在以后通过邮件发送问题报告时，不要遗漏任何 +一个邮件列表!维护者都是大忙人，可能会把一些工作留给子系统特定列表上的其他开 +发者；而 LKML 很重要，因为需要一个可以找到所有问题报告的地方。 + + +借助脚本找到维护者 +~~~~~~~~~~~~~~~~~~~~ + +对于手头有Linux源码的人来说，有第二个可以找到合适的报告地点的选择：脚本 +“scripts/get_maintainer.pl”，它尝试找到所有要联系的人。它会查询MAINTAINERS +文件，并需要用相关源代码的路径来调用。对于编译成模块的驱动程序，经常可以用 +这样的命令找到:: + + $ modinfo ath10k_pci | grep filename | sed 's!/lib/modules/.*/kernel/!!; s!filename:!!; s!\.ko\(\|\.xz\)!!' + drivers/net/wireless/ath/ath10k/ath10k_pci.ko + +将其中的部分内容传递给脚本:: + + $ ./scripts/get_maintainer.pl -f drivers/net/wireless/ath/ath10k* + Some Human <shuman@example.com> (supporter:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER) + Another S. Human <asomehuman@example.com> (maintainer:NETWORKING DRIVERS) + ath10k@lists.infradead.org (open list:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER) + linux-wireless@vger.kernel.org (open list:NETWORKING DRIVERS (WIRELESS)) + netdev@vger.kernel.org (open list:NETWORKING DRIVERS) + linux-kernel@vger.kernel.org (open list) + +不要把你的报告发给所有的人。发送给维护者，脚本称之为“supporter:”；另外抄送 +代码最相关的邮件列表，以及 Linux 内核邮件列表（LKML）。在此例中，你需要将报 +告发送给 “Some Human <shuman@example.com>” ，并抄送 +“ath10k@lists.infradead.org”和“linux-kernel@vger.kernel.org”。 + +注意：如果你用 git 克隆了 Linux 源代码，你可能需要用--git 再次调用 +get_maintainer.pl。脚本会查看提交历史，以找到最近哪些人参与了相关代码的编写， +因为他们可能会提供帮助。但要小心使用这些结果，因为它很容易让你误入歧途。 +例如，这种情况常常会发生在很少被修改的地方（比如老旧的或未维护的驱动程序）： +有时这样的代码会在树级清理期间被根本不关心此驱动程序的开发者修改。 + + +搜索现有报告（第二部分） +-------------------------- + + *在缺陷追踪器或问题相关邮件列表的存档中彻底搜索可能与您的问题匹配的报告。 + 如果找到匹配的报告，请加入讨论而不是发送新报告。* + +如前所述：报告一个别人已经提出的问题，对每个人来说都是浪费时间，尤其是作为报告 +人的你。这就是为什么你应该再次搜索现有的报告。现在你已经知道问题需要报告到哪里。 +如果是邮件列表，那么一般在 `lore.kernel.org <https://lore.kernel.org/>`_ 可以 +找到相应存档。 + +但有些列表运行在其他地方。例如前面步骤中当例子的ath10k WiFi驱动程序就是这种 +情况。但是你通常可以在网上很容易地找到这些列表的档案。例如搜索“archive +ath10k@lists.infradead.org”，将引导您到ath10k邮件列表的信息页，该页面顶部链接 +到其 `列表存档 <https://lists.infradead.org/pipermail/ath10k/>`_ 。遗憾的是， +这个列表和其他一些列表缺乏搜索其存档的功能。在这种情况下可以使用常规的互联网 +搜索引擎，并添加类似“site:lists.infadead.org/pipermail/ath10k/”这 +样的搜索条件，这会把结果限制在该链接中的档案。 + +也请进一步搜索网络、LKML和bugzilla.kernel.org网站。 + +有关如何搜索以及在找到匹配报告时如何操作的详细信息，请参阅上面的“搜索现有报告 +（第一部分）”。 + +不要急着完成报告过程的这一步：花30到60分钟甚至更多的时间可以为你和其他人节省 / +减少相当多的时间和麻烦。 + + +安装一个新的内核进行测试 +-------------------------- + + *除非您已经在运行最新的“主线”Linux内核，否则最好在报告流程前安装它。在 + 某些情况下，使用最新的“稳定版”Linux进行测试和报告也是可以接受的替代方案； + 在合并窗口期间，这实际上可能是最好的方法，但在开发阶段最好还是暂停几天。 + 无论你选择什么版本，最好使用“普通”构建。忽略这些建议会大大增加您的报告 + 被拒绝或忽略的风险。* + +正如第一步的详细解释中所提到的：与大多数程序员一样，与大多数程序员一样，Linux +内核开发人员不喜欢花时间处理他们维护的源代码中根本不会发生的问题的报告。这只 +会浪费每个人的时间，尤其是你的时间。这就是为什么在报告问题之前，您必须先确认 +问题仍然存在于最新的上游代码中，这符合每个人的利益。您可以忽略此建议，但如前 +所述：这样做会极大地增加问题报告被拒绝或被忽略的风险。 + +内核“最新上游”的范围通常指： + + * 安装一个主线内核；最新的稳定版内核也可以是一个选择，但大多数时候都最好避免。 + 长期支持内核（有时称为“LTS内核”）不适合此流程。下一小节将更详细地解释所有 + 这些。 + + * 下一小节描述获取和安装这样一个内核的方法。它还指出了使用预编译内核是可以的， + 但普通的内核更好，这意味着：它是直接使用从 `kernel.org <https://kernel.org/>`_ + 获得的Linux源代码构建并且没有任何方式修改或增强。 + + +选择适合测试的版本 +~~~~~~~~~~~~~~~~~~~~ + +前往 `kernel.org <https://kernel.org/>`_ 来决定使用哪个版本。忽略那个写着 +“Latest release最新版本”的巨大黄色按钮，往下看有一个表格。在表格的顶部，你会 +看到一行以“mainline”开头的字样，大多数情况下它会指向一个版本号类似“5.8-rc2” +的预发布版本。如果是这样的话，你将需要使用这个主线内核进行测试。不要让“rc” +吓到你，这些“开发版内核”实际上非常可靠——而且你已经按照上面的指示做了备份， +不是吗？ + +大概每九到十周，“mainline”可能会给你指出一个版本号类似“5.7”的正式版本。如果 +碰见这种情况，请考虑暂停报告过程，直到下一个版本的第一个预发布（5.8-rc1）出 +现在 `kernel.org <https://kernel.org/>`_ 上。这是因为 Linux 的开发周期正在 +两周的“合并窗口”内。大部分的改动和所有干扰性的改动都会在这段时间内被合并到 +下一个版本中。在此期间使用主线是比较危险的。内核开发者通常也很忙，可能没有 +多余的时间来处理问题报告。这也是很有可能在合并窗口中应用了许多修改来修复你 +所面临的问题；这就是为什么你很快就得用一个新的内核版本重新测试，就像下面“发 +布报告后的责任”一节中所述的那样。 + +这就是为什么要等到合并窗口结束后才去做。但是如果你处理的是一些不应该等待的 +东西，则无需这样做。在这种情况下，可以考虑通过 git 获取最新的主线内核（见下 +文），或者使用 kernel.org 上提供的最新稳定版本。如果 mainline 因为某些原因 +不无法正常工作，那么使用它也是可以接受的。总的来说：用它来重现问题也比完全 +不报告问题要好。 + +最好避免在合并窗口外使用最新的稳定版内核，因为所有修复都必须首先应用于主线。 +这就是为什么检查最新的主线内核是如此重要：你希望看到在旧版本线修复的任何问题 +需要先在主线修复，然后才能得到回传，这可能需要几天或几周。另一个原因是：您 +希望的修复对于回传来说可能太难或太冒险；因此再次报告问题不太可能改变任何事情。 + +这些方面也部分表明了为什么长期支持内核（有时称为“LTS内核”）不适合报告流程： +它们与当前代码的距离太远。因此，先去测试主线，然后再按流程走：如果主线没有 +出现问题，流程将指导您如何在旧版本线中修复它。 + +如何获得新的 Linux 内核 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +你可以使用预编译或自编译的内核进行测试；如果你选择后者，可以使用 git 获取源 +代码，或者下载其 tar 存档包。 + +**使用预编译的内核** ：这往往是最快速、最简单、最安全的方法——尤其是在你不熟 +悉 Linux 内核的情况下。问题是：发行商或附加存储库提供的大多数版本都是从修改 +过的Linux源代码构建的。因此它们不是普通的，通常不适合于测试和问题报告：这些 +更改可能会导致您面临的问题或以某种方式影响问题。 + +但是如果您使用的是流行的Linux发行版，那么您就很幸运了：对于大部分的发行版， +您可以在网上找到包含最新主线或稳定版本Linux内核包的存储库。使用这些是完全可 +以的，只要从存储库的描述中确认它们是普通的或者至少接近普通。此外，请确保软件 +包包含kernel.org上提供的最新版本内核。如果这些软件包的时间超过一周，那么它们 +可能就不合适了，因为新的主线和稳定版内核通常至少每周发布一次。 + +请注意，您以后可能需要手动构建自己的内核：有时这是调试或测试修复程序所必需的， +如后文所述。还要注意，预编译的内核可能缺少在出现panic、Oops、warning或BUG时 +解码内核打印的消息所需的调试符号；如果您计划解码这些消息，最好自己编译内核 +（有关详细信息，请参阅本小节结尾和“解码失败信息”小节）。 + +**使用git** ：熟悉 git 的开发者和有经验的 Linux 用户通常最好直接从 +`kernel.org 上的官方开发仓库 +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_ +中获取最新的 Linux 内核源代码。这些很可能比最新的主线预发布版本更新一些。不 +用担心：它们和正式的预发布版本一样可靠，除非内核的开发周期目前正处于合并窗 +口中。不过即便如此，它们也是相当可靠的。 + +**常规方法** ：不熟悉 git 的人通常最好从 `kernel.org <https://kernel.org/>`_ +下载源码的tar 存档包。 + +如何实际构建一个内核并不在这里描述，因为许多网站已经解释了必要的步骤。如果 +你是新手，可以考虑按照那些建议使用 ``make localmodconfig`` 来做，它将尝试获 +取你当前内核的配置，然后根据你的系统进行一些调整。这样做并不能使编译出来的 +内核更好，但可以更快地编译。 + +注意：如果您正在处理来自内核的pannc、Oops、warning或BUG，请在配置内核时尝试 +启用 CONFIG_KALLSYMS 选项。此外，还可以启用 CONFIG_DEBUG_KERNEL 和 +CONFIG_DEBUG_INFO；后者是相关选项，但只有启用前者才能开启。请注意， +CONFIG_DEBUG_INFO 会需要更多储存空间来构建内核。但这是值得的，因为这些选项将 +允许您稍后精确定位触发问题的确切代码行。下面的“解码失败信息”一节对此进行了更 +详细的解释。 + +但请记住：始终记录遇到的问题，以防难以重现。发送未解码的报告总比不报告要好。 + + +检查“污染”标志 +---------------- + + *确保您刚刚安装的内核在运行时不会“污染”自己。* + +正如上面已经详细介绍过的：当发生一些可能会导致一些看起来完全不相关的后续错 +误的事情时，内核会设置一个“污染”标志。这就是为什么你需要检查你刚刚安装的内 +核是否有设置此标志。如果有的话，几乎在任何情况下你都需要在报告问题之前先消 +除它。详细的操作方法请看上面的章节。 + + +用新内核重现问题 +------------------ + + *在您刚刚安装的内核中复现这个问题。如果它没有出现，请查看下方只发生在 + 稳定版和长期支持内核的问题的说明。* + +检查这个问题是否发生在你刚刚安装的新 Linux 内核版本上。如果新内核已经修复了， +可以考虑使用此版本线，放弃报告问题。但是请记住，只要它没有在 `kernel.org +<https://kernel.org/>`_ 的稳定版和长期版（以及由这些版本衍生出来的厂商内核） +中得到修复，其他用户可能仍然会受到它的困扰。如果你喜欢使用其中的一个，或 +者只是想帮助它们的用户，请前往下面的“报告只发生在较旧内核版本线的问题”一节。 + + +优化复现问题的描述 +-------------------- + + *优化你的笔记：试着找到并写出最直接的复现问题的方法。确保最终结果包含所 + 有重要的细节，同时让第一次听说的人容易阅读和理解。如果您在此过程中学到 + 了一些东西，请考虑再次搜索关于该问题的现有报告。* + +过于复杂的报告会让别人很难理解。因此请尽量找到一个可以直接描述、易于以书面 +形式理解的再现方法。包含所有重要的细节，但同时也要尽量保持简短。 + +在这在前面的步骤中，你很可能已经了解了一些关于你所面临的问题的点。利用这些 +知识，再次搜索可以转而加入的现有报告。 + + +解码失败信息 +------------- + + *如果失败涉及“panic”、“Oops”、“warning”或“BUG”，请考虑解码内核日志以查找 + 触发错误的代码行。* + +当内核检测到内部问题时，它会记录一些有关已执行代码的信息。这使得在源代码中精 +确定位触发问题的行并显示如何调用它成为可能。但只有在配置内核时启用了 +CONFIG_DEBUG_INFO 和 CONFIG_KALLSYMS选项时，这种方法才起效。如果已启用此选项， +请考虑解码内核日志中的信息。这将使我们更容易理解是什么导致了“panic”、“Oops”、 +“warning”或“BUG”，从而增加了有人提供修复的几率。 + +解码可以通过Linux源代码树中的脚本来完成。如果您运行的内核是之前自己编译的， +这样这样调用它:: + + [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh ./linux-5.10.5/vmlinux + /usr/lib/debug/lib/modules/5.10.10-4.1.x86_64/vmlinux /usr/src/kernels/5.10.10-4.1.x86_64/ + +如果您运行的是打包好的普通内核，则可能需要安装带有调试符号的相应包。然后按以下 +方式调用脚本（如果发行版未打包，则可能需要从Linux源代码获取）:: + + [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh \ + /usr/lib/debug/lib/modules/5.10.10-4.1.x86_64/vmlinux /usr/src/kernels/5.10.10-4.1.x86_64/ + +脚本将解码如下的日志行，这些日志行显示内核在发生错误时正在执行的代码的地址:: + + [ 68.387301] RIP: 0010:test_module_init+0x5/0xffa [test_module] + +解码之后，这些行将变成这样:: + + [ 68.387301] RIP: 0010:test_module_init (/home/username/linux-5.10.5/test-module/test-module.c:16) test_module + +在本例中，执行的代码是从文件“~/linux-5.10.5/test-module/test-module.c”构建的， +错误出现在第16行的指令中。 + +该脚本也会如此解码以“Call trace”开头的部分中提到的地址，该部分显示出现问题的 +函数的路径。此外，脚本还会显示内核正在执行的代码部分的汇编输出。 + +注意，如果你没法做到这一点，只需跳过这一步，并在报告中说明原因。如果你幸运的 +话，可能无需解码。如果需要的话，也许有人会帮你做这件事情。还要注意，这只是解 +码内核堆栈跟踪的几种方法之一。有时需要采取不同的步骤来检索相关的详细信息。 +别担心，如果您碰到的情况需要这样做，开发人员会告诉您该怎么做。 + + +对回归的特别关照 +----------------- + + *如果您的问题是回归问题，请尽可能缩小引入问题时的范围。* + +Linux 首席开发者 Linus Torvalds 认为 Linux 内核永远不应恶化，这就是为什么他 +认为回归是不可接受的，并希望看到它们被迅速修复。这就是为什么引入了回归的改 +动导致的问题若无法通过其他方式快速解决，通常会被迅速撤销。因此，报告回归有 +点像“王炸”，会迅速得到修复。但要做到这一点，需要知道导致回归的变化。通常情 +况下，要由报告者来追查罪魁祸首，因为维护者往往没有时间或手头设置不便来自行 +重现它。 + +有一个叫做“二分”的过程可以来寻找变化，这在 +“Documentation/translations/zh_CN/admin-guide/bug-bisect.rst”文档中进行了详细 +的描述，这个过程通常需要你构建十到二十个内核镜像，每次都尝试在构建下一个镜像 +之前重现问题。是的，这需要花费一些时间，但不用担心，它比大多数人想象的要快得多。 +多亏了“binary search二进制搜索”，这将引导你在源代码管理系统中找到导致回归的提交。 +一旦你找到它，就在网上搜索其主题、提交ID和缩短的提交ID（提交ID的前12个字符）。 +如果有的话，这将引导您找到关于它的现有报告。 + +需要注意的是，二分法需要一点窍门，不是每个人都懂得诀窍，也需要相当多的努力， +不是每个人都愿意投入。尽管如此，还是强烈建议自己进行一次二分。如果你真的 +不能或者不想走这条路，至少要找出是哪个主线内核引入的回归。比如说从 5.5.15 +切换到 5.8.4 的时候出现了一些问题，那么至少可以尝试一下相近的所有的主线版本 +（5.6、5.7 和 5.8）来检查它是什么时候出现的。除非你想在一个稳定版或长期支持 +内核中找到一个回归，否则要避免测试那些编号有三段的版本（5.6.12、5.7.8），因 +为那会使结果难以解释，可能会让你的测试变得无用。一旦你找到了引入回归的主要 +版本，就可以放心地继续报告了。但请记住：在不知道罪魁祸首的情况下，开发人员 +是否能够提供帮助取决于手头的问题。有时他们可能会从报告中确认是什么出现了问 +题，并能修复它；有时他们可能无法提供帮助，除非你进行二分。 + +当处理回归问题时，请确保你所面临的问题真的是由内核引起的，而不是由其他东西 +引起的，如上文所述。 + +在整个过程中，请记住：只有当旧内核和新内核的配置相似时，问题才算回归。最好 +的方法是：把配置文件（``.config``）从旧的工作内核直接复制到你尝试的每个新内 +核版本。之后运行 ``make oldnoconfig`` 来调整它以适应新版本的需要，而不启用 +任何新的功能，因为那些功能也可能导致回归。 + + +撰写并发送报告 +--------------- + + *通过详细描述问题来开始编写报告。记得包括以下条目：您为复现而安装的最新 + 内核版本、使用的Linux发行版以及关于如何复现该问题的说明。如果可能，将内 + 核构建配置（.config）和 ``dmesg`` 的输出放在网上的某个地方，并链接到它。 + 包含或上传所有其他可能相关的信息，如Oops的输出/截图或来自 ``lspci`` + 的输出。一旦你写完了这个主要部分，请在上方插入一个正常长度的段落快速概 + 述问题和影响。再在此之上添加一个简单描述问题的句子，以得到人们的阅读。 + 现在给出一个更短的描述性标题或主题。然后就可以像MAINTAINERS文件告诉你的 + 那样发送或提交报告了，除非你在处理一个“高优先级问题”：它们需要按照下面 + “高优先级问题的特殊处理”所述特别关照。* + +现在你已经准备好了一切，是时候写你的报告了。上文前言中链接的三篇文档对如何 +写报告做了部分解释。这就是为什么本文将只提到一些基本的内容以及 Linux 内核特 +有的东西。 + +有一点是符合这两类的：你的报告中最关键的部分是标题/主题、第一句话和第一段。 +开发者经常会收到许多邮件。因此，他们往往只是花几秒钟的时间浏览一下邮件，然 +后再决定继续下一封或仔细查看。因此，你报告的开头越好，有人研究并帮助你的机 +会就越大。这就是为什么你应该暂时忽略他们，先写出详细的报告。;-) + +每份报告都应提及的事项 +~~~~~~~~~~~~~~~~~~~~~~~~ + +详细描述你的问题是如何发生在你安装的新纯净内核上的。试着包含你之前写的和优 +化过的分步说明，概述你和其他人如何重现这个问题；在极少数无法重现的情况下， +尽量描述你做了什么来触发它。 + +还应包括其他人为了解该问题及其环境而可能需要的所有相关信息。实际需要的东西 +在很大程度上取决于具体问题，但有些事项你总是应该包括在内： + + * ``cat /proc/version`` 的输出，其中包含 Linux 内核版本号和构建时的编译器。 + + * 机器正在运行的 Linux 发行版（ ``hostnamectl | grep “Operating System“`` ） + + * CPU 和操作系统的架构（ ``uname -mi`` ） + + * 如果您正在处理回归，并进行了二分，请提及导致回归的变更的主题和提交ID。 + +许多情况下，让读你报告的人多了解两件事也是明智之举： + + * 用于构建 Linux 内核的配置（“.config”文件） + + * 内核的信息，你从 ``dmesg`` 得到的信息写到一个文件里。确保它以像“Linux + version 5.8-1 (foobar@example.com) (gcc (GCC) 10.2.1, GNU ld version + 2.34) #1 SMP Mon Aug 3 14:54:37 UTC 2020”这样的行开始，如果没有，那么第 + 一次启动阶段的重要信息已经被丢弃了。在这种情况下，可以考虑使用 + ``journalctl -b 0 -k`` ；或者你也可以重启，重现这个问题，然后调用 + ``dmesg`` 。 + +这两个文件很大，所以直接把它们放到你的报告中是个坏主意。如果你是在缺陷跟踪 +器中提交问题，那么将它们附加到工单中。如果你通过邮件报告问题，不要用附件附 +上它们，因为那会使邮件变得太大，可以按下列之一做： + + * 将文件上传到某个公开的地方（你的网站，公共文件粘贴服务，在 + `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_ 上创建的工单……）， + 并在你的报告中放上链接。理想情况下请使用允许这些文件保存很多年的地方，因 + 为它们可能在很多年后对别人有用；例如 5 年或 10 年后，一个开发者正在修改 + 一些代码，而这些代码正是为了修复你的问题。 + + * 把文件放在一边，然后说明你会在他人回复时再单独发送。只要记得报告发出去后， + 真正做到这一点就可以了。;-) + +提供这些东西可能是明智的 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +根据问题的不同，你可能需要提供更多的背景数据。这里有一些关于提供什么比较好 +的建议： + + * 如果你处理的是内核的“warning”、“OOPS”或“panic”，请包含它。如果你不能复制 + 粘贴它，试着用netconsole网络终端远程跟踪或者至少拍一张屏幕的照片。 + + * 如果问题可能与你的电脑硬件有关，请说明你使用的是什么系统。例如，如果你的 + 显卡有问题，请提及它的制造商，显卡的型号，以及使用的芯片。如果是笔记本电 + 脑，请提及它的型号名称，但尽量确保意义明确。例如“戴尔 XPS 13”就不很明确， + 因为它可能是 2012 年的那款，那款除了看起来和现在销售的没有什么不同之外， + 两者没有任何共同之处。因此，在这种情况下，要加上准确的型号，例如 2019 + 年内推出的 XPS 13 型号为“9380”或“7390”。像“联想 Thinkpad T590”这样的名字 + 也有些含糊不清：这款笔记本有带独立显卡和不带的子型号，所以要尽量找到准确 + 的型号名称或注明主要部件。 + + * 说明正在使用的相关软件。如果你在加载模块时遇到了问题，你要说明正在使用的 + kmod、systemd 和 udev 的版本。如果其中一个 DRM 驱动出现问题，你要说明 + libdrm 和 Mesa 的版本；还要说明你的 Wayland 合成器或 X-Server 及其驱动。 + 如果你有文件系统问题，请注明相应的文件系统实用程序的版本（e2fsprogs, + btrfs-progs, xfsprogs……）。 + + * 从内核中收集可能有用的额外信息。例如， ``lspci -nn`` 的输出可以帮助别人 + 识别你使用的硬件。如果你的硬件有问题，你甚至可以给出 ``sudo lspci -vvv`` + 的结果，因为它提供了组件是如何配置的信息。对于一些问题，可能最好包含 + ``/proc/cpuinfo`` ， ``/proc/ioports`` ， ``/proc/iomem`` ， + ``/proc/modules`` 或 ``/proc/scsi/scsi`` 等文件的内容。一些子系统还提 + 供了收集相关信息的工具。 ``alsa-info.sh`` `就是这样一个工具，它是音频/声 + 音子系统开发者提供的 <https://www.alsa-project.org/wiki/AlsaInfo>`_ 。 + +这些例子应该会给你一些知识点，让你知道附上什么数据可能是明智的，但你自己也 +要想一想，哪些数据对别人会有帮助。不要太担心忘记一些东西，因为开发人员会要 +求提供他们需要的额外细节。但从一开始就把所有重要的东西都提供出来，会增加别 +人仔细查看的机会。 + + +重要部分：报告的开头 +~~~~~~~~~~~~~~~~~~~~~~ + +现在你已经准备好了报告的详细部分，让我们进入最重要的部分：开头几句。现在到 +报告的最前面，在你刚才写的部分之前加上类似“The detailed description:”（详细 +描述）这样的内容，并在最前面插入两个新行。现在写一个正常长度的段落，大致概 +述这个问题。去掉所有枯燥的细节，把重点放在读者需要知道的关键部分，以让人了 +解这是怎么回事；如果你认为这个缺陷影响了很多用户，就提一下这点来吸引大家关 +注。 + +做好这一点后，在顶部再插入两行，写一句话的摘要，快速解释报告的内容。之后你 +要更加抽象，为报告写一个更短的主题/标题。 + +现在你已经写好了这部分，请花点时间来优化它，因为它是你的报告中最重要的部分： +很多人会先读这部分，然后才会决定是否值得花时间阅读其他部分。 + +现在就像 :ref:`MAINTAINERS <maintainers>` 维护者文件告诉你的那样发送或提交 +报告，除非它是前面概述的那些“高优先级问题”之一：在这种情况下，请先阅读下一 +小节，然后再发送报告。 + +高优先级问题的特殊处理 +~~~~~~~~~~~~~~~~~~~~~~~~ + +高优先级问题的报告需要特殊处理。 + +**非常严重的缺陷** ：确保在主题或工单标题以及第一段中明显标出 severeness +（非常严重的）。 + +**回归** ：如果问题是一个回归，请在邮件的主题或缺陷跟踪器的标题中添加 +[REGRESSION]。如果您没有进行二分，请至少注明您测试的最新主线版本（比如 5.7） +和出现问题的最新版本（比如 5.8）。如果您成功地进行了二分，请注明导致回归 +的提交ID和主题。也请添加该变更的作者到你的报告中；如果您需要将您的缺陷提交 +到缺陷跟踪器中，请将报告以私人邮件的形式转发给他，并注明报告提交地点。 + +**安全问题** ：对于这种问题，你将必须评估：如果细节被公开披露，是否会对其他 +用户产生短期风险。如果不会，只需按照所述继续报告问题。如果有此风险，你需要 +稍微调整一下报告流程。 + + * 如果 MAINTAINERS 文件指示您通过邮件报告问题，请不要抄送任何公共邮件列表。 + + * 如果你应该在缺陷跟踪器中提交问题，请确保将工单标记为“私有”或“安全问题”。 + 如果缺陷跟踪器没有提供保持报告私密性的方法，那就别想了，把你的报告以私人 + 邮件的形式发送给维护者吧。 + +在这两种情况下，都一定要将报告发到 MAINTAINERS 文件中“安全联络”部分列出的 +地址。理想的情况是在发送报告的时候直接抄送他们。如果您在缺陷跟踪器中提交了 +报告，请将报告的文本转发到这些地址；但请在报告的顶部加上注释，表明您提交了 +报告，并附上工单链接。 + +更多信息请参见“Documentation/translations/zh_CN/admin-guide/security-bugs.rst”。 + + +发布报告后的责任 +------------------ + + *等待别人的反应，继续推进事情，直到你能够接受这样或那样的结果。因此，请 + 公开和及时地回应任何询问。测试提出的修复。积极地测试：至少重新测试每个 + 新主线版本的首个候选版本（RC），并报告你的结果。如果出现拖延，就友好地 + 提醒一下。如果你没有得到任何帮助或者未能满意，请试着自己帮助自己。* + +如果你的报告非常优秀，而且你真的很幸运，那么某个开发者可能会立即发现导致问 +题的原因；然后他们可能会写一个补丁来修复、测试它，并直接发送给主线集成，同 +时标记它以便以后回溯到需要它的稳定版和长期支持内核。那么你需要做的就是回复 +一句“Thank you very much”（非常感谢），然后在发布后换上修复好的版本。 + +但这种理想状况很少发生。这就是为什么你把报告拿出来之后工作才开始。你要做的 +事情要视情况而定，但通常会是下面列出的事情。但在深入研究细节之前，这里有几 +件重要的事情，你需要记住这部分的过程。 + + +关于进一步互动的一般建议 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**总是公开回复** ：当你在缺陷跟踪器中提交问题时，一定要在那里回复，不要私下 +联系任何开发者。对于邮件报告，在回复您收到的任何邮件时，总是使用“全部回复” +功能。这包括带有任何你可能想要添加到你的报告中的额外数据的邮件：进入邮件应 +用程序“已发送”文件夹，并在邮件上使用“全部回复”来回复报告。这种方法可以确保 +公共邮件列表和其他所有参与者都能及时了解情况；它还能保持邮件线程的完整性， +这对于邮件列表将所有相关邮件归为一类是非常重要的。 + +只有两种情况不适合在缺陷跟踪器或“全部回复”中发表评论： + + * 有人让你私下发东西。 + + * 你被告知要发送一些东西，但注意到其中包含需要保密的敏感信息。在这种情况下， + 可以私下发送给要求发送的开发者。但要在工单或邮件中注明你是这么做的，这 + 样其他人就知道你尊重了这个要求。 + +**在请求解释或帮助之前先研究一下** ：在这部分过程中，有人可能会告诉你用尚未 +掌握的技能做一些事情。例如你可能会被要求使用一些你从未听说过的测试工具；或 +者你可能会被要求在 Linux 内核源代码上应用一个补丁来测试它是否有帮助。在某些 +情况下，发个回复询问如何做就可以了。但在走这条路之前，尽量通过在互联网上搜 +索自行找到答案；或者考虑在其他地方询问建议。比如询问朋友，或者到你平时常去 +的聊天室或论坛发帖咨询。 + +**要有耐心** ：如果你真的很幸运，你可能会在几个小时内收到对你的报告的答复。 +但大多数情况下会花费更多的时间，因为维护者分散在全球各地，因此可能在不同的 +时区——在那里他们已经享受着远离键盘的夜晚。 + +一般来说，内核开发者需要一到五个工作日来回复报告。有时会花费更长的时间，因 +为他们可能正忙于合并窗口、其他工作、参加开发者会议，或者只是在享受一个漫长 +的暑假。 + +“高优先级的问题”（见上面的解释）例外：维护者应该尽快解决这些问题；这就是为 +什么你应该最多等待一个星期（如果是紧急的事情，则只需两天），然后再发送友好 +的提醒。 + +有时维护者可能没有及时回复；有时候可能会出现分歧，例如一个问题是否符合回归 +的条件。在这种情况下，在邮件列表上提出你的顾虑，并请求其他人公开或私下回复 +如何继续推进。如果失败了，可能应该让更高级别的维护者介入。如果是 WiFi 驱动， +那就是无线维护者；如果没有更高级别的维护者，或者其他一切努力都失败了，那 +这可能是一种罕见的、可以让 Linus Torvalds 参与进来的情况。 + +**主动测试** ：每当一个新的主线内核版本的第一个预发布版本（rc1）发布的时候， +去检查一下这个问题是否得到了解决，或者是否有什么重要的变化。在工单中或在 +回复报告的邮件中提及结果（确保所有参与讨论的人都被抄送）。这将表明你的承诺 +和你愿意帮忙。如果问题持续存在，它也会提醒开发者确保他们不会忘记它。其他一 +些不定期的重新测试（例如用rc3、rc5 和最终版本）也是一个好主意，但只有在相关 +的东西发生变化或者你正在写什么东西的时候才报告你的结果。 + +这些些常规的事情就不说了，我们来谈谈报告后如何帮助解决问题的细节。 + +查询和测试请求 +~~~~~~~~~~~~~~~ + +如果你的报告得到了回复则需履行以下责任： + +**检查与你打交道的人** ：大多数情况下，会是维护者或特定代码区域的开发人员对 +你的报告做出回应。但由于问题通常是公开报告的，所以回复的可能是任何人——包括 +那些想要帮忙的人，但最后可能会用他们的问题或请求引导你完全偏离轨道。这很少 +发生，但这是快速上网搜搜看你正在与谁互动是明智之举的许多原因之一。通过这样 +做，你也可以知道你的报告是否被正确的人听到，因为如果讨论没有导致满意的问题 +解决方案而淡出，之后可能需要提醒维护者（见下文）。 + +**查询数据** ：通常你会被要求测试一些东西或提供更多细节。尽快提供所要求的信 +息，因为你已经得到了可能会帮助你的人的注意，你等待的时间越长就有越可能失去 +关注；如果你不在数个工作日内提供信息，甚至可能出现这种结果。 + +**测试请求** ：当你被要求测试一个诊断补丁或可能的修复时，也要尽量及时测试。 +但要做得恰当，一定不要急于求成：混淆事情很容易发生，这会给所有人带来许多困 +惑。例如一个常见的错误是以为应用了一个带修复的建议补丁，但事实上并没有。即 +使是有经验的测试人员也会偶尔发生这样的事情，但当有修复的内核和没有修复的内 +核表现得一样时，他们大多时候会注意到。 + +当没有任何实质性进展时该怎么办 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +有些报告不会得到负有相关责任的 Linux 内核开发者的任何反应；或者围绕这个问题 +的讨论有所发展，但渐渐淡出，没有任何实质内容产出。 + +在这种情况下，要等两个星期（最好是三个星期）后再发出友好的提醒：也许当你的 +报告到达时，维护者刚刚离开键盘一段时间，或者有更重要的事情要处理。在写提醒 +信的时候，要善意地问一下，是否还需要你这边提供什么来让事情推进下去。如果报 +告是通过邮件发出来的，那就在邮件的第一行回复你的初始邮件（见上文），其中包 +括下方的原始报告的完整引用：这是少数几种情况下，这样的“TOFU”（Text Over, +Fullquote Under文字在上，完整引用在下）是正确的做法，因为这样所有的收件人都 +会以适当的顺序立即让细节到手头上来。 + +在提醒之后，再等三周的回复。如果你仍然没有得到适当的反馈，你首先应该重新考 +虑你的方法。你是否可能尝试接触了错误的人？是不是报告也许令人反感或者太混乱， +以至于人们决定完全远离它？排除这些因素的最好方法是：把报告给一两个熟悉 +FLOSS 问题报告的人看，询问他们的意见。同时征求他们关于如何继续推进的建议。 +这可能意味着：准备一份更好的报告，让这些人在你发出去之前对它进行审查。这样 +的方法完全可以；只需说明这是关于这个问题的第二份改进的报告，并附上第一份报 +告的链接。 + +如果报告是恰当的，你可以发送第二封提醒信；在其中询问为什么报告没有得到任何 +回复。第二封提醒邮件的好时机是在新 Linux 内核版本的首个预发布版本（'rc1'） +发布后不久，因为无论如何你都应该在那个时候重新测试并提供状态更新（见上文）。 + +如果第二次提醒的结果又在一周内没有任何反应，可以尝试联系上级维护者询问意见： +即使再忙的维护者在这时候也至少应该发过某种确认。 + +记住要做好失望的准备：理想状况下维护者最好对每一个问题报告做出回应，但他们 +只有义务解决之前列出的“高优先级问题”。所以，如果你得到的回复是“谢谢你的报告， +我目前有更重要的问题要处理，在可预见的未来没有时间去研究这个问题”，那请不 +要太沮丧。 + +也有可能在缺陷跟踪器或列表中进行了一些讨论之后，什么都没有发生，提醒也无助 +于激励大家进行修复。这种情况可能是毁灭性的，但在 Linux 内核开发中确实会发生。 +这些和其他得不到帮助的原因在本文结尾处的“为什么有些问题在被报告后没有得到 +任何回应或者仍然没有修复”中进行了解释。 + +如果你没有得到任何帮助或问题最终没有得到解决，不要沮丧：Linux 内核是 FLOSS， +因此你仍然可以自己帮助自己。例如，你可以试着找到其他受影响的人，和他们一 +起合作来解决这个问题。这样的团队可以一起准备一份新的报告，提到团队有多少人， +为什么你们认为这是应该得到解决的事情。也许你们还可以一起缩小确切原因或引 +入回归的变化，这往往会使修复更容易。而且如果运气好的话，团队中可能会有懂点 +编程的人，也许能写出一个修复方案。 + + + +“报告稳定版和长期支持内核线的回归”的参考 +------------------------------------------ + +本小节提供了在稳定版和长期支持内核线中面对回归时需要执行的步骤的详细信息。 + +确保特定版本线仍然受支持 +~~~~~~~~~~~~~~~~~~~~~~~~~ + + *检查内核开发人员是否仍然维护你关心的Linux内核版本线：去 kernel.org 的 + 首页，确保此特定版本线的最新版没有“[EOL]”标记。* + +大多数内核版本线只支持三个月左右，因为延长维护时间会带来相当多的工作。因此， +每年只会选择一个版本来支持至少两年（通常是六年）。这就是为什么你需要检查 +内核开发者是否还支持你关心的版本线。 + +注意，如果 `kernel.org <https://kernel.org/>`_ 在首页上列出了两个“稳定”版本， +你应该考虑切换到较新的版本，而忘掉较旧的版本：对它的支持可能很快就会结束。 +然后，它将被标记为“生命周期结束”（EOL）。达到这个程度的版本线仍然会在 +`kernel.org <https://kernel.org/>`_ 首页上被显示一两周，但不适合用于测试和 +报告。 + +搜索稳定版邮件列表 +~~~~~~~~~~~~~~~~~~~ + + *检查Linux稳定版邮件列表中的现有报告。* + +也许你所面临的问题已经被发现，并且已经或即将被修复。因此，请在 `Linux 稳定 +版邮件列表的档案 <https://lore.kernel.org/stable/>`_ 中搜索类似问题的报告。 +如果你找到任何匹配的问题，可以考虑加入讨论，除非修复工作已经完成并计划很快 +得到应用。 + +用最新版本复现问题 +~~~~~~~~~~~~~~~~~~~ + + *从特定的版本线安装最新版本作为纯净内核。确保这个内核没有被污染，并且仍 + 然存在问题，因为问题可能已经在那里被修复了。* + +在投入更多时间到这个过程中之前，你要检查这个问题是否在你关注的版本线的最新 +版本中已经得到了修复。这个内核需要是纯净的，在问题发生之前不应该被污染，正 +如上面已经在测试主线的过程中详细介绍过的一样。 + +您是否是第一次注意到供应商内核的回归？供应商的更改可能会发生变化。你需要重新 +检查排除来这个问题。当您从5.10.4-vendor.42更新到5.10.5-vendor.43时，记录损坏 +的信息。然后在测试了前一段中所述的最新5.10版本之后，检查Linux 5.10.4的普通版本 +是否也可以正常工作。如果问题在那里出现，那就不符合上游回归的条件，您需要切换 +回主逐步指南来报告问题。 + +报告回归 +~~~~~~~~~~ + + *向Linux稳定版邮件列表发送一个简短的问题报告(stable@vger.kernel.org)。 + 大致描述问题，并解释如何复现。讲清楚首个出现问题的版本和最后一个工作正常 + 的版本。然后等待进一步的指示。* + +当报告在稳定版或长期支持内核线内发生的回归（例如在从5.10.4更新到5.10.5时）， +一份简短的报告足以快速报告问题。因此只需要粗略的描述。 + +但是请注意，如果您能够指明引入问题的确切版本，这将对开发人员有很大帮助。因此 +如果有时间的话，请尝试使用普通内核找到该版本。让我们假设发行版发布Linux内核 +5.10.5到5.10.8的更新时发生了故障。那么按照上面的指示，去检查该版本线中的最新 +内核，比如5.10.9。如果问题出现，请尝试普通5.10.5，以确保供应商应用的补丁不会 +干扰。如果问题没有出现，那么尝试5.10.7，然后直到5.10.8或5.10.6（取决于结果） +找到第一个引入问题的版本。在报告中写明这一点，并指出5.10.9仍然存在故障。 + +前一段基本粗略地概述了“二分”方法。一旦报告出来，您可能会被要求做一个正确的 +报告，因为它允许精确地定位导致问题的确切更改（然后很容易被恢复以快速修复问题）。 +因此如果时间允许，考虑立即进行适当的二分。有关如何详细信息，请参阅“对回归的 +特别关照”部分和文档“Documentation/translations/zh_CN/admin-guide/bug-bisect.rst”。 + + +“报告仅在旧内核版本线中发生的问题”的参考 +---------------------------------------- + +本节详细介绍了如果无法用主线内核重现问题，但希望在旧版本线（又称稳定版内核和 +长期支持内核）中修复问题时需要采取的步骤。 + +有些修复太复杂 +~~~~~~~~~~~~~~~ + + *请做好准备，接下来的几个步骤可能无法在旧版本中解决问题：修复可能太大或 + 太冒险，无法移植到那里。* + +即使是微小的、看似明显的代码变化，有时也会带来新的、完全意想不到的问题。稳 +定版和长期支持内核的维护者非常清楚这一点，因此他们只对这些内核进行符合 +“Documentation/translations/zh_CN/process/stable-kernel-rules.rst”中所列出的 +规则的修改。 + +复杂或有风险的修改不符合条件，因此只能应用于主线。其他的修复很容易被回溯到 +最新的稳定版和长期支持内核，但是风险太大，无法集成到旧版内核中。所以要注意 +你所希望的修复可能是那些不会被回溯到你所关心的版本线的修复之一。在这种情况 +下，你将别无选择，要么忍受这个问题，要么切换到一个较新的 Linux 版本，除非你 +想自己把修复补丁应用到你的内核中。 + +通用准备 +~~~~~~~~~~ + + *执行上面“报告仅在旧内核版本线中发生的问题”一节中的前三个步骤。* + +您需要执行本指南另一节中已经描述的几个步骤。这些步骤将让您： + + * 检查内核开发人员是否仍然维护您关心的Linux内核版本行。 + + * 在Linux稳定邮件列表中搜索退出的报告。 + + * 检查最新版本。 + + +检查代码历史和搜索现有的讨论 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + *在Linux内核版本控制系统中搜索修复主线问题的更改，因为它的提交消息可能 + 会告诉你修复是否已经计划好了支持。如果你没有找到，搜索适当的邮件列表， + 寻找讨论此类问题或同行评议可能修复的帖子；然后检查讨论是否认为修复不适 + 合支持。如果支持根本不被考虑，加入最新的讨论，询问是否有可能。* + +在许多情况下，你所处理的问题会发生在主线上，但已在主线上得到了解决。修正它 +的提交也需要被回溯才能解决这个问题。这就是为什么你要搜索它或任何相关讨论。 + + * 首先尝试在存放 Linux 内核源代码的 Git 仓库中找到修复。你可以通过 + `kernel.org 上的网页 + <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_ + 或 `GitHub 上的镜像 <https://github.com/torvalds/linux>`_ 来实现；如果你 + 有一个本地克隆，你也可以在命令行用 ``git log --grep=<pattern>`` 来搜索。 + + 如果你找到了修复，请查看提交消息的尾部是否包含了类似这样的“稳定版标签”： + + Cc: <stable@vger.kernel.org> # 5.4+ + + 像上面这行，开发者标记了安全修复可以回传到 5.4 及以后的版本。大多数情况 + 下，它会在两周内被应用到那里，但有时需要更长的时间。 + + * 如果提交没有告诉你任何东西，或者你找不到修复，请再找找关于这个问题的讨论。 + 用你最喜欢的搜索引擎搜索网络，以及 `Linux kernel developers mailing + list 内核开发者邮件列表 <https://lore.kernel.org/lkml/>`_ 的档案。也可以 + 阅读上面的 `定位导致问题的内核区域` 一节，然后按照说明找到导致问题的子系 + 统：它的缺陷跟踪器或邮件列表存档中可能有你要找的答案。 + + * 如果你看到了一个计划的修复，请按上所述在版本控制系统中搜索它，因为提交可 + 能会告诉你是否可以进行回溯。 + + * 检查讨论中是否有任何迹象表明，该修复程序可能风险太大，无法回溯到你关心 + 的版本线。如果是这样的话，你必须忍受这个问题，或者切换到应用了修复的内 + 核版本线。 + + * 如果修复的问题未包含稳定版标签，并且没有讨论过回溯问题，请加入讨论：如 + 果合适的话，请提及你所面对的问题的版本，以及你希望看到它被修复。 + + +请求建议 +~~~~~~~~~ + + *前面的步骤之一应该会给出一个解决方案。如果仍未能成功，请向可能引起问题 + 的子系统的维护人员询问建议；抄送特定子系统的邮件列表以及稳定版邮件列表。* + +如果前面的三个步骤都没有让你更接近解决方案，那么只剩下一个选择：请求建议。 +在你发给可能是问题根源的子系统的维护者的邮件中这样做；抄送子系统的邮件列表 +以及稳定版邮件列表（stable@vger.kernel.org）。 + + +为什么有些问题在报告后没有任何回应或仍未解决？ +=============================================== + +当向 Linux 开发者报告问题时，要注意只有“高优先级的问题”（回归、安全问题、严 +重问题）才一定会得到解决。如果维护者或其他人都失败了，Linus Torvalds 他自己 +会确保这一点。他们和其他内核开发者也会解决很多其他问题。但是要知道，有时他 +们也会不能或不愿帮忙；有时甚至没有人发报告给他们。 + +最好的解释就是那些内核开发者常常是在业余时间为 Linux 内核做出贡献。内核中的 +不少驱动程序都是由这样的程序员编写的，往往只是因为他们想让自己的硬件可以在 +自己喜欢的操作系统上使用。 + +这些程序员大多数时候会很乐意修复别人报告的问题。但是没有人可以强迫他们这样 +做，因为他们是自愿贡献的。 + +还有一些情况下，这些开发者真的很想解决一个问题，但却不能解决：有时他们缺乏 +硬件编程文档来解决问题。这种情况往往由于公开的文档太简陋，或者驱动程序是通 +过逆向工程编写的。 + +业余开发者迟早也会不再关心某驱动。也许他们的测试硬件坏了，被更高级的玩意取 +代了，或者是太老了以至于只能在计算机博物馆里找到。有时开发者根本就不关心他 +们的代码和 Linux 了，因为在他们的生活中一些不同的东西变得更重要了。在某些情 +况下，没有人愿意接手维护者的工作——也没有人可以被强迫，因为对 Linux 内核的贡 +献是自愿的。然而被遗弃的驱动程序仍然存在于内核中：它们对人们仍然有用，删除 +它们可能导致回归。 + +对于那些为 Linux 内核工作而获得报酬的开发者来说，情况并没有什么不同。这些人 +现在贡献了大部分的变更。但是他们的雇主迟早也会停止关注他们的代码或者让程序 +员专注于其他事情。例如，硬件厂商主要通过销售新硬件来赚钱；因此，他们中的不 +少人并没有投入太多时间和精力来维护他们多年前就停止销售的东西的 Linux 内核驱 +动。企业级 Linux 发行商往往持续维护的时间比较长，但在新版本中往往会把对老旧 +和稀有硬件的支持放在一边，以限制范围。一旦公司抛弃了一些代码，往往由业余贡 +献者接手，但正如上面提到的：他们迟早也会放下代码。 + +优先级是一些问题没有被修复的另一个原因，因为维护者相当多的时候是被迫设置这 +些优先级的，因为在 Linux 上工作的时间是有限的。对于业余时间或者雇主给予他们 +的开发人员用于上游内核维护工作的时间也是如此。有时维护人员也会被报告淹没， +即使一个驱动程序几乎完美地工作。为了不被完全缠住，程序员可能别无选择，只能 +对问题报告进行优先级排序而拒绝其中的一些报告。 + +不过这些都不用太过担心，很多驱动都有积极的维护者，他们对尽可能多的解决问题 +相当感兴趣。 + + +结束语 +======= + +与其他免费/自由&开源软件（Free/Libre & Open Source Software，FLOSS）相比， +向 Linux 内核开发者报告问题是很难的：这个文档的长度和复杂性以及字里行间的内 +涵都说明了这一点。但目前就是这样了。这篇文字的主要作者希望通过记录现状来为 +以后改善这种状况打下一些基础。 diff --git a/Documentation/translations/zh_CN/admin-guide/security-bugs.rst b/Documentation/translations/zh_CN/admin-guide/security-bugs.rst new file mode 100644 index 000000000000..b8120391755d --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/security-bugs.rst @@ -0,0 +1,74 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../admin-guide/security-bugs` + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +安全缺陷 +========= + +Linux内核开发人员非常重视安全性。因此我们想知道何时发现了安全漏洞，以便尽快 +修复和披露。请向Linux内核安全团队报告安全漏洞。 + +联络 +----- + +可以通过电子邮件<security@kernel.org>联系Linux内核安全团队。这是一个安全人员 +的私有列表，他们将帮助验证错误报告并开发和发布修复程序。如果您已经有了一个 +修复，请将其包含在您的报告中，这样可以大大加快进程。安全团队可能会从区域维护 +人员那里获得额外的帮助，以理解和修复安全漏洞。 + +与任何缺陷一样，提供的信息越多，诊断和修复就越容易。如果您不清楚哪些信息有用， +请查看“Documentation/translations/zh_CN/admin-guide/reporting-issues.rst”中 +概述的步骤。任何利用漏洞的攻击代码都非常有用，未经报告者同意不会对外发布，除 +非已经公开。 + +请尽可能发送无附件的纯文本电子邮件。如果所有的细节都藏在附件里，那么就很难对 +一个复杂的问题进行上下文引用的讨论。把它想象成一个 +:doc:`常规的补丁提交 <../process/submitting-patches>` （即使你还没有补丁）： +描述问题和影响，列出复现步骤，然后给出一个建议的解决方案，所有这些都是纯文本的。 + +披露和限制信息 +--------------- + +安全列表不是公开渠道。为此，请参见下面的协作。 + +一旦开发出了健壮的补丁，发布过程就开始了。对公开的缺陷的修复会立即发布。 + +尽管我们倾向于在未公开缺陷的修复可用时即发布补丁，但应报告者或受影响方的请求， +这可能会被推迟到发布过程开始后的7日内，如果根据缺陷的严重性需要更多的时间， +则可额外延长到14天。推迟发布修复的唯一有效原因是为了适应QA的逻辑和需要发布 +协调的大规模部署。 + +虽然可能与受信任的个人共享受限信息以开发修复，但未经报告者许可，此类信息不会 +与修复程序一起发布或发布在任何其他披露渠道上。这包括但不限于原始错误报告和 +后续讨论（如有）、漏洞、CVE信息或报告者的身份。 + +换句话说，我们唯一感兴趣的是修复缺陷。提交给安全列表的所有其他资料以及对报告 +的任何后续讨论，即使在解除限制之后，也将永久保密。 + +协调 +------ + +对敏感缺陷（例如那些可能导致权限提升的缺陷）的修复可能需要与私有邮件列表 +<linux-distros@vs.openwall.org>进行协调，以便分发供应商做好准备，在公开披露 +上游补丁时发布一个已修复的内核。发行版将需要一些时间来测试建议的补丁，通常 +会要求至少几天的限制，而供应商更新发布更倾向于周二至周四。若合适，安全团队 +可以协助这种协调，或者报告者可以从一开始就包括linux发行版。在这种情况下，请 +记住在电子邮件主题行前面加上“[vs]”，如linux发行版wiki中所述： +<http://oss-security.openwall.org/wiki/mailing-lists/distros#how-to-use-the-lists>。 + +CVE分配 +-------- + +安全团队通常不分配CVE，我们也不需要它们来进行报告或修复，因为这会使过程不必 +要的复杂化，并可能耽误缺陷处理。如果报告者希望在公开披露之前分配一个CVE编号， +他们需要联系上述的私有linux-distros列表。当在提供补丁之前已有这样的CVE编号时， +如报告者愿意，最好在提交消息中提及它。 + +保密协议 +--------- + +Linux内核安全团队不是一个正式的机构实体，因此无法签订任何保密协议。 diff --git a/Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst b/Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst new file mode 100644 index 000000000000..bc51d7cff9b0 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst @@ -0,0 +1,157 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../admin-guide/tainted-kernels` + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +受污染的内核 +------------- + +当发生一些在稍后调查问题时可能相关的事件时，内核会将自己标记为“受污染 +（tainted）”的。不用太过担心，大多数情况下运行受污染的内核没有问题；这些信息 +主要在有人想调查某个问题时才有意义的，因为问题的真正原因可能是导致内核受污染 +的事件。这就是为什么来自受污染内核的缺陷报告常常被开发人员忽略，因此请尝试用 +未受污染的内核重现问题。 + +请注意，即使在您消除导致污染的原因（亦即卸载专有内核模块）之后，内核仍将保持 +污染状态，以表示内核仍然不可信。这也是为什么内核在注意到内部问题（“kernel +bug”）、可恢复错误（“kernel oops”）或不可恢复错误（“kernel panic”）时会打印 +受污染状态，并将有关此的调试信息写入日志 ``dmesg`` 输出。也可以通过 +``/proc/`` 中的文件在运行时检查受污染的状态。 + + +BUG、Oops或Panics消息中的污染标志 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +在顶部以“CPU:”开头的一行中可以找到受污染的状态；内核是否受到污染和原因会显示 +在进程ID（“PID:”）和触发事件命令的缩写名称（“Comm:”）之后:: + + BUG: unable to handle kernel NULL pointer dereference at 0000000000000000 + Oops: 0002 [#1] SMP PTI + CPU: 0 PID: 4424 Comm: insmod Tainted: P W O 4.20.0-0.rc6.fc30 #1 + Hardware name: Red Hat KVM, BIOS 0.5.1 01/01/2011 + RIP: 0010:my_oops_init+0x13/0x1000 [kpanic] + [...] + +如果内核在事件发生时没有被污染，您将在那里看到“Not-tainted:”；如果被污染，那 +么它将是“Tainted:”以及字母或空格。在上面的例子中，它看起来是这样的:: + + Tainted: P W O + +下表解释了这些字符的含义。在本例中，由于加载了专有模块（ ``P`` ），出现了 +警告（ ``W`` ），并且加载了外部构建的模块（ ``O`` ），所以内核早些时候受到 +了污染。要解码其他字符，请使用下表。 + + +解码运行时的污染状态 +~~~~~~~~~~~~~~~~~~~~~ + +在运行时，您可以通过读取 ``cat /proc/sys/kernel/tainted`` 来查询受污染状态。 +如果返回 ``0`` ，则内核没有受到污染；任何其他数字都表示受到污染的原因。解码 +这个数字的最简单方法是使用脚本 ``tools/debugging/kernel-chktaint`` ，您的 +发行版可能会将其作为名为 ``linux-tools`` 或 ``kernel-tools`` 的包的一部分提 +供；如果没有，您可以从 +`git.kernel.org <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/tools/debugging/kernel-chktaint>`_ +网站下载此脚本并用 ``sh kernel-chktaint`` 执行，它会在上面引用的日志中有类似 +语句的机器上打印这样的内容:: + + Kernel is Tainted for following reasons: + * Proprietary module was loaded (#0) + * Kernel issued warning (#9) + * Externally-built ('out-of-tree') module was loaded (#12) + See Documentation/admin-guide/tainted-kernels.rst in the Linux kernel or + https://www.kernel.org/doc/html/latest/admin-guide/tainted-kernels.html for + a more details explanation of the various taint flags. + Raw taint value as int/string: 4609/'P W O ' + +你也可以试着自己解码这个数字。如果内核被污染的原因只有一个，那么这很简单， +在本例中您可以通过下表找到数字。如果你需要解码有多个原因的数字，因为它是一 +个位域（bitfield），其中每个位表示一个特定类型的污染的存在或不存在，最好让 +前面提到的脚本来处理。但是如果您需要快速看一下，可以使用这个shell命令来检查 +设置了哪些位:: + + $ for i in $(seq 18); do echo $(($i-1)) $(($(cat /proc/sys/kernel/tainted)>>($i-1)&1));done + +污染状态代码表 +~~~~~~~~~~~~~~~ + +=== ===== ====== ======================================================== + 位 日志 数字 内核被污染的原因 +=== ===== ====== ======================================================== + 0 G/P 1 已加载专用模块 + 1 _/F 2 模块被强制加载 + 2 _/S 4 内核运行在不合规范的系统上 + 3 _/R 8 模块被强制卸载 + 4 _/M 16 处理器报告了机器检测异常（MCE） + 5 _/B 32 引用了错误的页或某些意外的页标志 + 6 _/U 64 用户空间应用程序请求的污染 + 7 _/D 128 内核最近死机了，即曾出现OOPS或BUG + 8 _/A 256 ACPI表被用户覆盖 + 9 _/W 512 内核发出警告 + 10 _/C 1024 已加载staging驱动程序 + 11 _/I 2048 已应用平台固件缺陷的解决方案 + 12 _/O 4096 已加载外部构建（“树外”）模块 + 13 _/E 8192 已加载未签名的模块 + 14 _/L 16384 发生软锁定 + 15 _/K 32768 内核已实时打补丁 + 16 _/X 65536 备用污染，为发行版定义并使用 + 17 _/T 131072 内核是用结构随机化插件构建的 +=== ===== ====== ======================================================== + +注：字符 ``_`` 表示空白，以便于阅读表。 + +污染的更详细解释 +~~~~~~~~~~~~~~~~~ + + 0) ``G`` 加载的所有模块都有GPL或兼容许可证， ``P`` 加载了任何专有模块。 + 没有MODULE_LICENSE（模块许可证）或MODULE_LICENSE未被insmod认可为GPL + 兼容的模块被认为是专有的。 + + + 1) ``F`` 任何模块被 ``insmod -f`` 强制加载， ``' '`` 所有模块正常加载。 + + 2) ``S`` 内核运行在不合规范的处理器或系统上：硬件已运行在不受支持的配置中， + 因此无法保证正确执行。内核将被污染，例如： + + - 在x86上：PAE是通过intel CPU（如Pentium M）上的forcepae强制执行的，这些 + CPU不报告PAE，但可能有功能实现，SMP内核在非官方支持的SMP Athlon CPU上 + 运行，MSR被暴露到用户空间中。 + - 在arm上：在某些CPU（如Keystone 2）上运行的内核，没有启用某些内核特性。 + - 在arm64上：CPU之间存在不匹配的硬件特性，引导加载程序以不同的模式引导CPU。 + - 某些驱动程序正在被用在不受支持的体系结构上（例如x86_64以外的其他系统 + 上的scsi/snic，非x86/x86_64/itanium上的scsi/ips，已经损坏了arm64上 + irqchip/irq-gic的固件设置…）。 + + 3) ``R`` 模块被 ``rmmod -f`` 强制卸载， ``' '`` 所有模块都正常卸载。 + + 4) ``M`` 任何处理器报告了机器检测异常， ``' '`` 未发生机器检测异常。 + + 5) ``B`` 页面释放函数发现错误的页面引用或某些意外的页面标志。这表示硬件问题 + 或内核错误；日志中应该有其他信息指示发生此污染的原因。 + + 6) ``U`` 用户或用户应用程序特意请求设置受污染标志，否则应为 ``' '`` 。 + + 7) ``D`` 内核最近死机了，即出现了OOPS或BUG。 + + 8) ``A`` ACPI表被重写。 + + 9) ``W`` 内核之前已发出过警告（尽管有些警告可能会设置更具体的污染标志）。 + + 10) ``C`` 已加载staging驱动程序。 + + 11) ``I`` 内核正在处理平台固件（BIOS或类似软件）中的严重错误。 + + 12) ``O`` 已加载外部构建（“树外”）模块。 + + 13) ``E`` 在支持模块签名的内核中加载了未签名的模块。 + + 14) ``L`` 系统上先前发生过软锁定。 + + 15) ``K`` 内核已经实时打了补丁。 + + 16) ``X`` 备用污染，由Linux发行版定义和使用。 + + 17) ``T`` 内核构建时使用了randstruct插件，它可以有意生成非常不寻常的内核结构 + 布局（甚至是性能病态的布局），这在调试时非常有用。于构建时设置。 diff --git a/Documentation/translations/zh_CN/admin-guide/unicode.rst b/Documentation/translations/zh_CN/admin-guide/unicode.rst new file mode 100644 index 000000000000..b0b08d2b6eb7 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/unicode.rst @@ -0,0 +1,170 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/unicode.rst + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +Unicode（统一码）支持 +====================== + + （英文版）上次更新：2005-01-17，版本号 1.4 + +此文档由H. Peter Anvin <unicode@lanana.org>管理，是Linux注册名称与编号管理局 +（Linux Assigned Names And Numbers Authority，LANANA）项目的一部分。 +现行版本请见： + + http://www.lanana.org/docs/unicode/admin-guide/unicode.rst + +简介 +----- + +Linux内核代码已被重写以使用Unicode来将字符映射到字体。下载一个Unicode到字体 +（Unicode-to-font）表，八位字符集与UTF-8模式都将改用此字体来显示。 + +这微妙地改变了八位字符表的语义。现在的四个字符表是： + +=============== =============================== ================ +映射代号 映射名称 Escape代码 (G0) +=============== =============================== ================ +LAT1_MAP Latin-1 (ISO 8859-1) ESC ( B +GRAF_MAP DEC VT100 pseudographics ESC ( 0 +IBMPC_MAP IBM code page 437 ESC ( U +USER_MAP User defined ESC ( K +=============== =============================== ================ + +特别是 ESC ( U 不再是“直通字体”，因为字体可能与IBM字符集完全不同。 +例如，即使加载了一个Latin-1字体，也允许使用块图形（block graphics）。 + +请注意，尽管这些代码与ISO 2022类似，但这些代码及其用途都与ISO 2022不匹配； +Linux有两个八位代码（G0和G1），而ISO 2022有四个七位代码（G0-G3）。 + +根据Unicode标准/ISO 10646，U+F000到U+F8FF被保留用于操作系统范围内的分配 +（Unicode标准将其称为“团体区域（Corporate Zone）”，因为这对于Linux是不准确 +的，所以我们称之为“Linux区域”）。选择U+F000作为起点，因为它允许直接映射 +区域以2的大倍数开始（以防需要1024或2048个字符的字体）。这就留下U+E000到 +U+EFFF作为最终用户区。 + +[v1.2]：Unicodes范围从U+F000到U+F7FF已经被硬编码为直接映射到加载的字体， +绕过了翻译表。用户定义的映射现在默认为U+F000到U+F0FF，模拟前述行为。实际上， +此范围可能较短；例如，vgacon只能处理256字符（U+F000..U+F0FF）或512字符 +（U+F000..U+F1FF）字体。 + +Linux 区域中定义的实际字符 +--------------------------- + +此外，还定义了Unicode 1.1.4中不存在的以下字符；这些字符由DEC VT图形映射使用。 +[v1.2]此用法已过时，不应再使用；请参见下文。 + +====== ====================================== +U+F800 DEC VT GRAPHICS HORIZONTAL LINE SCAN 1 +U+F801 DEC VT GRAPHICS HORIZONTAL LINE SCAN 3 +U+F803 DEC VT GRAPHICS HORIZONTAL LINE SCAN 7 +U+F804 DEC VT GRAPHICS HORIZONTAL LINE SCAN 9 +====== ====================================== + +DEC VT220使用6x10字符矩阵，这些字符在DEC VT图形字符集中形成一个平滑的过渡。 +我省略了扫描5行，因为它也被用作块图形字符，因此被编码为U+2500 FORMS LIGHT +HORIZONTAL。 + +[v1.3]：这些字符已正式添加到Unicode 3.2.0中；它们在U+23BA、U+23BB、U+23BC、 +U+23BD处添加。Linux现在使用新值。 + +[v1.2]：添加了以下字符来表示常见的键盘符号，这些符号不太可能被添加到Unicode +中，因为它们非常讨厌地取决于特定供应商。当然，这是糟糕设计的一个好例子。 + +====== ====================================== +U+F810 KEYBOARD SYMBOL FLYING FLAG +U+F811 KEYBOARD SYMBOL PULLDOWN MENU +U+F812 KEYBOARD SYMBOL OPEN APPLE +U+F813 KEYBOARD SYMBOL SOLID APPLE +====== ====================================== + +克林贡（Klingon）语支持 +------------------------ + +1996年，Linux是世界上第一个添加对人工语言克林贡支持的操作系统，克林贡是由 +Marc Okrand为《星际迷航》电视连续剧创造的。这种编码后来被征募Unicode注册表 +（ConScript Unicode Registry，CSUR）采用，并建议（但最终被拒绝）纳入Unicode +平面一。不过，它仍然是Linux区域中的Linux/CSUR私有分配。 + +这种编码已经得到克林贡语言研究所（Klingon Language Institute）的认可。 +有关更多信息，请联系他们： + + http://www.kli.org/ + +由于Linux CZ开头部分的字符大多是dingbats/symbols/forms类型，而且这是一种 +语言，因此根据标准Unicode惯例，我将它放置在16单元的边界上。 + +.. note:: + + 这个范围现在由征募Unicode注册表正式管理。规范性引用文件为： + + https://www.evertype.com/standards/csur/klingon.html + +克林贡语有一个26个字符的字母表，一个10位数的位置数字书写系统，从左到右 +，从上到下书写。 + +克林贡字母的几种字形已经被提出。但是由于这组符号看起来始终是一致的，只有实际 +的形状不同，因此按照标准Unicode惯例，这些差异被认为是字体变体。 + +====== ======================================================= +U+F8D0 KLINGON LETTER A +U+F8D1 KLINGON LETTER B +U+F8D2 KLINGON LETTER CH +U+F8D3 KLINGON LETTER D +U+F8D4 KLINGON LETTER E +U+F8D5 KLINGON LETTER GH +U+F8D6 KLINGON LETTER H +U+F8D7 KLINGON LETTER I +U+F8D8 KLINGON LETTER J +U+F8D9 KLINGON LETTER L +U+F8DA KLINGON LETTER M +U+F8DB KLINGON LETTER N +U+F8DC KLINGON LETTER NG +U+F8DD KLINGON LETTER O +U+F8DE KLINGON LETTER P +U+F8DF KLINGON LETTER Q + - Written <q> in standard Okrand Latin transliteration +U+F8E0 KLINGON LETTER QH + - Written <Q> in standard Okrand Latin transliteration +U+F8E1 KLINGON LETTER R +U+F8E2 KLINGON LETTER S +U+F8E3 KLINGON LETTER T +U+F8E4 KLINGON LETTER TLH +U+F8E5 KLINGON LETTER U +U+F8E6 KLINGON LETTER V +U+F8E7 KLINGON LETTER W +U+F8E8 KLINGON LETTER Y +U+F8E9 KLINGON LETTER GLOTTAL STOP + +U+F8F0 KLINGON DIGIT ZERO +U+F8F1 KLINGON DIGIT ONE +U+F8F2 KLINGON DIGIT TWO +U+F8F3 KLINGON DIGIT THREE +U+F8F4 KLINGON DIGIT FOUR +U+F8F5 KLINGON DIGIT FIVE +U+F8F6 KLINGON DIGIT SIX +U+F8F7 KLINGON DIGIT SEVEN +U+F8F8 KLINGON DIGIT EIGHT +U+F8F9 KLINGON DIGIT NINE + +U+F8FD KLINGON COMMA +U+F8FE KLINGON FULL STOP +U+F8FF KLINGON SYMBOL FOR EMPIRE +====== ======================================================= + +其他虚构和人工字母 +------------------- + +自从分配了克林贡Linux Unicode块之后，John Cowan <jcowan@reutershealth.com> +和 Michael Everson <everson@evertype.com> 建立了一个虚构和人工字母的注册表。 +征募Unicode注册表请访问： + + https://www.evertype.com/standards/csur/ + +所使用的范围位于最终用户区域的低端，因此无法进行规范化分配，但建议希望对虚构 +字母进行编码的人员使用这些代码，以实现互操作性。对于克林贡语，CSUR采用了Linux +编码。CSUR的人正在推动将Tengwar和Cirth添加到Unicode平面一；将克林贡添加到 +Unicode平面一被拒绝，因此上述编码仍然是官方的。 diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst new file mode 100644 index 000000000000..f1fa71e45c77 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/index.rst @@ -0,0 +1,126 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../core-api/irq/index` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_core-api_index.rst: + + +=========== +核心API文档 +=========== + +这是核心内核API手册的首页。 非常感谢为本手册转换(和编写!)的文档! + +核心实用程序 +============ + +本节包含通用的和“核心中的核心”文档。 第一部分是 docbook 时期遗留下 +来的大量 kerneldoc 信息；有朝一日，若有人有动力的话，应当把它们拆分 +出来。 + +Todolist: + + kernel-api + workqueue + printk-basics + printk-formats + symbol-namespaces + +数据结构和低级实用程序 +====================== + +在整个内核中使用的函数库。 + +Todolist: + + kobject + kref + assoc_array + xarray + idr + circular-buffers + rbtree + generic-radix-tree + packing + bus-virt-phys-mapping + this_cpu_ops + timekeeping + errseq + +并发原语 +======== + +Linux如何让一切同时发生。 详情请参阅 +:doc:`/locking/index` + +.. toctree:: + :maxdepth: 1 + + irq/index + +Todolist: + + refcount-vs-atomic + local_ops + padata + ../RCU/index + +低级硬件管理 +============ + +缓存管理，CPU热插拔管理等。 + +Todolist: + + cachetlb + cpu_hotplug + memory-hotplug + genericirq + protection-keys + + +内存管理 +======== + +如何在内核中分配和使用内存。请注意，在 +:doc:`/vm/index` 中有更多的内存管理文档。 + +Todolist: + + memory-allocation + unaligned-memory-access + dma-api + dma-api-howto + dma-attributes + dma-isa-lpc + mm-api + genalloc + pin_user_pages + boot-time-mm + gfp_mask-from-fs-io + +内核调试的接口 +============== + +Todolist: + + debug-objects + tracepoint + debugging-via-ohci1394 + +其它文档 +======== + +不适合放在其它地方或尚未归类的文件； + +Todolist: + + librs + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/core-api/irq/concepts.rst b/Documentation/translations/zh_CN/core-api/irq/concepts.rst new file mode 100644 index 000000000000..41455bf0f783 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/irq/concepts.rst @@ -0,0 +1,24 @@ +.. include:: ../../disclaimer-zh_CN.rst + +:Original: :doc:`../../../../core-api/irq/concepts` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_concepts.rst: + + +=========== +什么是IRQ？ +=========== + +IRQ (Interrupt ReQuest) 指来自设备的中断请求。 +目前，它们可以通过一个引脚或通过一个数据包进入。 +多个设备可以连接到同一个引脚，从而共享一个IRQ。 + +IRQ编号是用来描述硬件中断源的内核标识符。通常它是一个到全局irq_desc数组的索引， +但是除了在linux/interrupt.h中实现的之外，其它细节是体系结构特征相关的。 + +IRQ编号是对机器上可能的中断源的枚举。通常枚举的是系统中所有中断控制器的输入引脚 +编号。在ISA（工业标准体系结构）的情况下所枚举的是两个i8259中断控制器的16个输入引脚。 + +体系结构可以给IRQ号赋予额外的含义，在涉及到硬件手动配置的情况下，我们鼓励这样做。 +ISA IRQ是赋予这种额外含义的一个典型例子。 diff --git a/Documentation/translations/zh_CN/core-api/irq/index.rst b/Documentation/translations/zh_CN/core-api/irq/index.rst new file mode 100644 index 000000000000..910ccabf041f --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/irq/index.rst @@ -0,0 +1,19 @@ +.. include:: ../../disclaimer-zh_CN.rst + +:Original: :doc:`../../../../core-api/irq/index` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_irq_index.rst: + + +==== +IRQs +==== + +.. toctree:: + :maxdepth: 1 + + concepts + irq-affinity + irq-domain + irqflags-tracing diff --git a/Documentation/translations/zh_CN/core-api/irq/irq-affinity.rst b/Documentation/translations/zh_CN/core-api/irq/irq-affinity.rst new file mode 100644 index 000000000000..82a4428f22fd --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/irq/irq-affinity.rst @@ -0,0 +1,76 @@ +.. include:: ../../disclaimer-zh_CN.rst + +:Original: :doc:`../../../../core-api/irq/irq-affinity` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_irq-affinity.rst: + + +============== +SMP IRQ 亲和性 +============== + +变更记录: + - 作者：最初由Ingo Molnar <mingo@redhat.com>开始撰写 + - 后期更新维护： Max Krasnyansky <maxk@qualcomm.com> + + +/proc/irq/IRQ#/smp_affinity和/proc/irq/IRQ#/smp_affinity_list指定了哪些CPU能 +够关联到一个给定的IRQ源，这两个文件包含了这些指定cpu的cpu位掩码(smp_affinity)和cpu列 +表(smp_affinity_list)。它不允许关闭所有CPU， 同时如果IRQ控制器不支持中断请求亲和 +(IRQ affinity)，那么所有cpu的默认值将保持不变(即关联到所有CPU). + +/proc/irq/default_smp_affinity指明了适用于所有非激活IRQ的默认亲和性掩码。一旦IRQ被 +分配/激活，它的亲和位掩码将被设置为默认掩码。然后可以如上所述改变它。默认掩码是0xffffffff。 + +下面是一个先将IRQ44(eth1)限制在CPU0-3上，然后限制在CPU4-7上的例子(这是一个8CPU的SMP box) + +:: + + [root@moon 44]# cd /proc/irq/44 + [root@moon 44]# cat smp_affinity + ffffffff + + [root@moon 44]# echo 0f > smp_affinity + [root@moon 44]# cat smp_affinity + 0000000f + [root@moon 44]# ping -f h + PING hell (195.4.7.3): 56 data bytes + ... + --- hell ping statistics --- + 6029 packets transmitted, 6027 packets received, 0% packet loss + round-trip min/avg/max = 0.1/0.1/0.4 ms + [root@moon 44]# cat /proc/interrupts | grep 'CPU\|44:' + CPU0 CPU1 CPU2 CPU3 CPU4 CPU5 CPU6 CPU7 + 44: 1068 1785 1785 1783 0 0 0 0 IO-APIC-level eth1 + +从上面一行可以看出，IRQ44只传递给前四个处理器（0-3）。 +现在让我们把这个IRQ限制在CPU(4-7)。 + +:: + + [root@moon 44]# echo f0 > smp_affinity + [root@moon 44]# cat smp_affinity + 000000f0 + [root@moon 44]# ping -f h + PING hell (195.4.7.3): 56 data bytes + .. + --- hell ping statistics --- + 2779 packets transmitted, 2777 packets received, 0% packet loss + round-trip min/avg/max = 0.1/0.5/585.4 ms + [root@moon 44]# cat /proc/interrupts | 'CPU\|44:' + CPU0 CPU1 CPU2 CPU3 CPU4 CPU5 CPU6 CPU7 + 44: 1068 1785 1785 1783 1784 1069 1070 1069 IO-APIC-level eth1 + +这次IRQ44只传递给最后四个处理器。 +即CPU0-3的计数器没有变化。 + +下面是一个将相同的irq(44)限制在cpus 1024到1031的例子 + +:: + + [root@moon 44]# echo 1024-1031 > smp_affinity_list + [root@moon 44]# cat smp_affinity_list + 1024-1031 + +需要注意的是，如果要用位掩码来做这件事，就需要32个为0的位掩码来追踪其相关的一个。 diff --git a/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst b/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst new file mode 100644 index 000000000000..3c82dd307a46 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst @@ -0,0 +1,227 @@ +.. include:: ../../disclaimer-zh_CN.rst + +:Original: :doc:`../../../../core-api/irq/irq-domain` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_irq-domain.rst: + + +======================= +irq_domain 中断号映射库 +======================= + +目前Linux内核的设计使用了一个巨大的数字空间，每个独立的IRQ源都被分配了一个不 +同的数字。 +当只有一个中断控制器时，这很简单，但在有多个中断控制器的系统中，内核必须确保每 +个中断控制器都能得到非重复的Linux IRQ号（数字）分配。 + +注册为唯一的irqchips的中断控制器编号呈现出上升的趋势：例如GPIO控制器等不同 +种类的子驱动程序通过将其中断处理程序建模为irqchips，即实际上是级联中断控制器， +避免了重新实现与IRQ核心系统相同的回调机制。 + +在这里，中断号与硬件中断号离散了所有种类的对应关系：而在过去，IRQ号可以选择， +使它们与硬件IRQ线进入根中断控制器（即实际向CPU发射中断线的组件）相匹配，现 +在这个编号仅仅是一个数字。 + +出于这个原因，我们需要一种机制将控制器本地中断号（即硬件irq编号）与Linux IRQ +号分开。 + +irq_alloc_desc*() 和 irq_free_desc*() API 提供了对irq号的分配，但它们不 +提供任何对控制器本地IRQ(hwirq)号到Linux IRQ号空间的反向映射的支持。 + +irq_domain 库在 irq_alloc_desc*() API 的基础上增加了 hwirq 和 IRQ 号码 +之间的映射。 相比于中断控制器驱动开放编码自己的反向映射方案，我们更喜欢用 +irq_domain来管理映射。 + +irq_domain还实现了从抽象的irq_fwspec结构体到hwirq号的转换（到目前为止是 +Device Tree和ACPI GSI），并且可以很容易地扩展以支持其它IRQ拓扑数据源。 + +irq_domain的用法 +================ + +中断控制器驱动程序通过以下方式创建并注册一个irq_domain。调用 +irq_domain_add_*() 或 irq_domain_create_*()函数之一（每个映射方法都有不 +同的分配器函数，后面会详细介绍）。 函数成功后会返回一个指向irq_domain的指针。 +调用者必须向分配器函数提供一个irq_domain_ops结构体。 + +在大多数情况下，irq_domain在开始时是空的，没有任何hwirq和IRQ号之间的映射。 +通过调用irq_create_mapping()将映射添加到irq_domain中，该函数接受 +irq_domain和一个hwirq号作为参数。 如果hwirq的映射还不存在，那么它将分配 +一个新的Linux irq_desc，将其与hwirq关联起来，并调用.map()回调，这样驱动 +程序就可以执行任何必要的硬件设置。 + +当接收到一个中断时，应该使用irq_find_mapping()函数从hwirq号中找到 +Linux IRQ号。 + +在调用irq_find_mapping()之前，至少要调用一次irq_create_mapping()函数， +以免描述符不能被分配。 + +如果驱动程序有Linux的IRQ号或irq_data指针，并且需要知道相关的hwirq号（比 +如在irq_chip回调中），那么可以直接从irq_data->hwirq中获得。 + +irq_domain映射的类型 +==================== + +从hwirq到Linux irq的反向映射有几种机制，每种机制使用不同的分配函数。应该 +使用哪种反向映射类型取决于用例。 下面介绍每一种反向映射类型： + +线性映射 +-------- + +:: + + irq_domain_add_linear() + irq_domain_create_linear() + +线性反向映射维护了一个固定大小的表，该表以hwirq号为索引。 当一个hwirq被映射 +时，会给hwirq分配一个irq_desc，并将irq号存储在表中。 + +当最大的hwirq号固定且数量相对较少时，线性图是一个很好的选择（~<256）。 这种 +映射的优点是固定时间查找IRQ号，而且irq_descs只分配给在用的IRQ。 缺点是该表 +必须尽可能大的hwirq号。 + +irq_domain_add_linear()和irq_domain_create_linear()在功能上是等价的， +除了第一个参数不同--前者接受一个Open Firmware特定的 'struct device_node' 而 +后者接受一个更通用的抽象 'struct fwnode_handle' 。 + +大多数驱动应该使用线性映射 + +树状映射 +-------- + +:: + + irq_domain_add_tree() + irq_domain_create_tree() + +irq_domain维护着从hwirq号到Linux IRQ的radix的树状映射。 当一个hwirq被映射时， +一个irq_desc被分配，hwirq被用作radix树的查找键。 + +如果hwirq号可以非常大，树状映射是一个很好的选择，因为它不需要分配一个和最大hwirq +号一样大的表。 缺点是，hwirq到IRQ号的查找取决于表中有多少条目。 + +irq_domain_add_tree()和irq_domain_create_tree()在功能上是等价的，除了第一 +个参数不同——前者接受一个Open Firmware特定的 'struct device_node' ，而后者接受 +一个更通用的抽象 'struct fwnode_handle' 。 + +很少有驱动应该需要这个映射。 + +无映射 +------ + +:: + + irq_domain_add_nomap() + +当硬件中的hwirq号是可编程的时候，就可以采用无映射类型。 在这种情况下，最好将 +Linux IRQ号编入硬件本身，这样就不需要映射了。 调用irq_create_direct_mapping() +会分配一个Linux IRQ号，并调用.map()回调，这样驱动就可以将Linux IRQ号编入硬件中。 + +大多数驱动程序不能使用这个映射。 + +传统映射类型 +------------ + +:: + + irq_domain_add_simple() + irq_domain_add_legacy() + irq_domain_add_legacy_isa() + irq_domain_create_simple() + irq_domain_create_legacy() + +传统映射是已经为 hwirqs 分配了一系列 irq_descs 的驱动程序的特殊情况。 当驱动程 +序不能立即转换为使用线性映射时，就会使用它。 例如，许多嵌入式系统板卡支持文件使用 +一组用于IRQ号的定义（#define），这些定义被传递给struct设备注册。 在这种情况下， +不能动态分配Linux IRQ号，应该使用传统映射。 + +传统映射假设已经为控制器分配了一个连续的IRQ号范围，并且可以通过向hwirq号添加一 +个固定的偏移来计算IRQ号，反之亦然。 缺点是需要中断控制器管理IRQ分配，并且需要为每 +个hwirq分配一个irq_desc，即使它没有被使用。 + +只有在必须支持固定的IRQ映射时，才应使用传统映射。 例如，ISA控制器将使用传统映射来 +映射Linux IRQ 0-15，这样现有的ISA驱动程序就能得到正确的IRQ号。 + +大多数使用传统映射的用户应该使用irq_domain_add_simple()或 +irq_domain_create_simple()，只有在系统提供IRQ范围时才会使用传统域，否则将使用 +线性域映射。这个调用的语义是这样的：如果指定了一个IRQ范围，那么 描述符将被即时分配 +给它，如果没有范围被分配，它将不会执行 irq_domain_add_linear() 或 +irq_domain_create_linear()，这意味着 *no* irq 描述符将被分配。 + +一个简单域的典型用例是，irqchip供应商同时支持动态和静态IRQ分配。 + +为了避免最终出现使用线性域而没有描述符被分配的情况，确保使用简单域的驱动程序在任何 +irq_find_mapping()之前调用irq_create_mapping()是非常重要的，因为后者实际上 +将用于静态IRQ分配情况。 + +irq_domain_add_simple()和irq_domain_create_simple()以及 +irq_domain_add_legacy()和irq_domain_create_legacy()在功能上是等价的，只 +是第一个参数不同--前者接受Open Firmware特定的 'struct device_node' ，而后者 +接受一个更通用的抽象 'struct fwnode_handle' 。 + +IRQ域层级结构 +------------- + +在某些架构上，可能有多个中断控制器参与将一个中断从设备传送到目标CPU。 +让我们来看看x86平台上典型的中断传递路径吧 +:: + + Device --> IOAPIC -> Interrupt remapping Controller -> Local APIC -> CPU + +涉及到的中断控制器有三个: + +1) IOAPIC 控制器 +2) 中断重映射控制器 +3) Local APIC 控制器 + +为了支持这样的硬件拓扑结构，使软件架构与硬件架构相匹配，为每个中断控制器建立一 +个irq_domain数据结构，并将这些irq_domain组织成层次结构。 + +在建立irq_domain层次结构时，靠近设备的irq_domain为子域，靠近CPU的 +irq_domain为父域。所以在上面的例子中，将建立如下的层次结构。 +:: + + CPU Vector irq_domain (root irq_domain to manage CPU vectors) + ^ + | + Interrupt Remapping irq_domain (manage irq_remapping entries) + ^ + | + IOAPIC irq_domain (manage IOAPIC delivery entries/pins) + +使用irq_domain层次结构的主要接口有四个: + +1) irq_domain_alloc_irqs(): 分配IRQ描述符和与中断控制器相关的资源来传递这些中断。 +2) irq_domain_free_irqs(): 释放IRQ描述符和与这些中断相关的中断控制器资源。 +3) irq_domain_activate_irq(): 激活中断控制器硬件以传递中断。 +4) irq_domain_deactivate_irq(): 停用中断控制器硬件，停止传递中断。 + +为了支持irq_domain层次结构，需要做如下修改: + +1) 一个新的字段 'parent' 被添加到irq_domain结构中；它用于维护irq_domain的层次信息。 +2) 一个新的字段 'parent_data' 被添加到irq_data结构中；它用于建立层次结构irq_data以 + 匹配irq_domain层次结构。irq_data用于存储irq_domain指针和硬件irq号。 +3) 新的回调被添加到irq_domain_ops结构中，以支持层次结构的irq_domain操作。 + +在支持分层irq_domain和分层irq_data准备就绪后，为每个中断控制器建立一个irq_domain结 +构，并为每个与IRQ相关联的irq_domain分配一个irq_data结构。现在我们可以再进一步支持堆 +栈式(层次结构)的irq_chip。也就是说，一个irq_chip与层次结构中的每个irq_data相关联。 +一个子irq_chip可以自己或通过与它的父irq_chip合作来实现一个所需的操作。 + +通过堆栈式的irq_chip，中断控制器驱动只需要处理自己管理的硬件，在需要的时候可以向其父 +irq_chip请求服务。所以我们可以实现更简洁的软件架构。 + +为了让中断控制器驱动程序支持irq_domain层次结构，它需要做到以下几点: + +1) 实现 irq_domain_ops.alloc 和 irq_domain_ops.free +2) 可选择地实现 irq_domain_ops.activate 和 irq_domain_ops.deactivate. +3) 可选择地实现一个irq_chip来管理中断控制器硬件。 +4) 不需要实现irq_domain_ops.map和irq_domain_ops.unmap，它们在层次结构 + irq_domain中是不用的。 + +irq_domain层次结构绝不是x86特有的，大量用于支持其他架构，如ARM、ARM64等。 + +调试功能 +======== + +打开CONFIG_GENERIC_IRQ_DEBUGFS，可让IRQ子系统的大部分内部结构都在debugfs中暴露出来。 diff --git a/Documentation/translations/zh_CN/core-api/irq/irqflags-tracing.rst b/Documentation/translations/zh_CN/core-api/irq/irqflags-tracing.rst new file mode 100644 index 000000000000..c889bd0f65d9 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/irq/irqflags-tracing.rst @@ -0,0 +1,45 @@ +.. include:: ../../disclaimer-zh_CN.rst + +:Original: :doc:`../../../../core-api/irq/irqflags-tracing` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_irqflags-tracing.rst: + + +================= +IRQ-flags状态追踪 +================= + +:Author: 最初由Ingo Molnar <mingo@redhat.com>开始撰写 + +“irq-flags tracing”（中断标志追踪）功能可以 “追踪” hardirq和softirq的状态，它让 +感兴趣的子系统有机会了解到到内核中发生的每一个 +hardirqs-off/hardirqs-on、softirqs-off/softirqs-on事件。 + +CONFIG_TRACE_IRQFLAGS_SUPPORT是通用锁调试代码提供的CONFIG_PROVE_SPIN_LOCKING +和CONFIG_PROVE_RW_LOCKING所需要的。否则将只有CONFIG_PROVE_MUTEX_LOCKING和 +CONFIG_PROVE_RWSEM_LOCKING在一个架构上被提供--这些都是不在IRQ上下文中使用的 +锁API。（rwsems的一个异常是可以解决的） + +架构对这一点的支持当然不属于“微不足道”的范畴，因为很多低级的汇编代码都要处理irq-flags +的状态变化。但是一个架构可以以一种相当直接且无风险的方式启用irq-flags-tracing。 + +架构如果想支持这个，需要先做一些代码组织上的改变: + +- 在他们的arch级Kconfig文件中添加并启用TRACE_IRQFLAGS_SUPPORT。 + +然后还需要做一些功能上的改变来实现对irq-flags-tracing的支持: + +- 在低级入口代码中增加（构建条件）对trace_hardirqs_off()/trace_hardirqs_on() + 函数的调用。锁验证器会密切关注 “real”的irq-flags是否与 “virtual”的irq-flags + 状态相匹配，如果两者不匹配，则会发出警告（并关闭自己）。通常维护arch中 + irq-flags-track的大部分时间都是在这种状态下度过的：看看lockdep的警告，试着 + 找出我们还没有搞定的汇编代码。修复并重复。一旦系统启动，并且在irq-flags跟踪功 + 能中没有出现lockdep警告的情况下，arch支持就完成了。 + +- 如果该架构有不可屏蔽的中断，那么需要通过lockdep_off()/lockdep_on()将这些中 + 断从irq跟踪[和锁验证]机制中排除。 + + 一般来说，在一个架构中，不完整的irq-flags-tracing实现是没有风险的：lockdep + 会检测到这一点，并将自己关闭。即锁验证器仍然可靠。应该不会因为irq-tracing的错 + 误而崩溃。（除非通过修改不该修改的条件来更改汇编或寄存器而破坏其他代码） diff --git a/Documentation/translations/zh_CN/cpu-freq/core.rst b/Documentation/translations/zh_CN/cpu-freq/core.rst new file mode 100644 index 000000000000..19fb9c029cfe --- /dev/null +++ b/Documentation/translations/zh_CN/cpu-freq/core.rst @@ -0,0 +1,105 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../cpu-freq/core` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_core.rst: + + +==================================== +CPUFreq核心和CPUFreq通知器的通用说明 +==================================== + +作者: + - Dominik Brodowski <linux@brodo.de> + - David Kimdon <dwhedon@debian.org> + - Rafael J. Wysocki <rafael.j.wysocki@intel.com> + - Viresh Kumar <viresh.kumar@linaro.org> + +.. 目录: + + 1. CPUFreq核心和接口 + 2. CPUFreq通知器 + 3. 含有Operating Performance Point (OPP)的CPUFreq表的生成 + +1. CPUFreq核心和接口 +====================== + +cpufreq核心代码位于drivers/cpufreq/cpufreq.c中。这些cpufreq代码为CPUFreq架构的驱 +动程序（那些操作硬件切换频率的代码）以及 "通知器 "提供了一个标准化的接口。 +这些是设备驱动程序或需要了解策略变化的其它内核部分（如 ACPI 热量管理）或所有频率更改（除 +计时代码外），甚至需要强制确定速度限制的通知器（如 ARM 架构上的 LCD 驱动程序）。 +此外， 内核 "常数" loops_per_jiffy会根据频率变化而更新。 + +cpufreq策略的引用计数由 cpufreq_cpu_get 和 cpufreq_cpu_put 来完成，以确保 cpufreq 驱 +动程序被正确地注册到核心中，并且驱动程序在 cpufreq_put_cpu 被调用之前不会被卸载。这也保证 +了每个CPU核的cpufreq 策略在使用期间不会被释放。 + +2. CPUFreq 通知器 +==================== + +CPUFreq通知器符合标准的内核通知器接口。 +关于通知器的细节请参阅 linux/include/linux/notifier.h。 + +这里有两个不同的CPUfreq通知器 - 策略通知器和转换通知器。 + + +2.1 CPUFreq策略通知器 +---------------------------- + +当创建或移除策略时，这些都会被通知。 + +阶段是在通知器的第二个参数中指定的。当第一次创建策略时，阶段是CPUFREQ_CREATE_POLICY，当 +策略被移除时，阶段是CPUFREQ_REMOVE_POLICY。 + +第三个参数 ``void *pointer`` 指向一个结构体cpufreq_policy，其包括min，max(新策略的下限和 +上限（单位为kHz）)这几个值。 + + +2.2 CPUFreq转换通知器 +-------------------------------- + +当CPUfreq驱动切换CPU核心频率时，策略中的每个在线CPU都会收到两次通知，这些变化没有任何外部干 +预。 + +第二个参数指定阶段 - CPUFREQ_PRECHANGE or CPUFREQ_POSTCHANGE. + +第三个参数是一个包含如下值的结构体cpufreq_freqs： + +===== ==================== +cpu 受影响cpu的编号 +old 旧频率 +new 新频率 +flags cpufreq驱动的标志 +===== ==================== + +3. 含有Operating Performance Point (OPP)的CPUFreq表的生成 +================================================================== +关于OPP的细节请参阅 Documentation/power/opp.rst + +dev_pm_opp_init_cpufreq_table - + 这个功能提供了一个随时可用的转换程序，用来将OPP层关于可用频率的内部信息翻译成一种容易提供给 + cpufreq的格式。 + + .. Warning:: + + 不要在中断上下文中使用此函数。 + + 例如:: + + soc_pm_init() + { + /* Do things */ + r = dev_pm_opp_init_cpufreq_table(dev, &freq_table); + if (!r) + policy->freq_table = freq_table; + /* Do other things */ + } + + .. note:: + + 该函数只有在CONFIG_PM_OPP之外还启用了CONFIG_CPU_FREQ时才可用。 + +dev_pm_opp_free_cpufreq_table + 释放dev_pm_opp_init_cpufreq_table分配的表。 diff --git a/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst b/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst new file mode 100644 index 000000000000..0ca2cb646666 --- /dev/null +++ b/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst @@ -0,0 +1,259 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../cpu-freq/cpu-drivers` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_cpu-drivers.rst: + + +======================================= +如何实现一个新的CPUFreq处理器驱动程序？ +======================================= + +作者: + + + - Dominik Brodowski <linux@brodo.de> + - Rafael J. Wysocki <rafael.j.wysocki@intel.com> + - Viresh Kumar <viresh.kumar@linaro.org> + +.. Contents + + 1. 怎么做？ + 1.1 初始化 + 1.2 Per-CPU 初始化 + 1.3 验证 + 1.4 target/target_index 或 setpolicy? + 1.5 target/target_index + 1.6 setpolicy + 1.7 get_intermediate 与 target_intermediate + 2. 频率表助手 + + + +1. 怎么做？ +=========== + +如此，你刚刚得到了一个全新的CPU/芯片组及其数据手册，并希望为这个CPU/芯片组添加cpufreq +支持？很好，这里有一些至关重要的提示： + + +1.1 初始化 +---------- + +首先，在__initcall_level_7 (module_init())或更靠后的函数中检查这个内核是否 +运行在正确的CPU和正确的芯片组上。如果是，则使用cpufreq_register_driver()向 +CPUfreq核心层注册一个cpufreq_driver结构体。 + +结构体cpufreq_driver应该包含什么成员? + + .name - 驱动的名字。 + + .init - 一个指向per-policy初始化函数的指针。 + + .verify - 一个指向"verification"函数的指针。 + + .setpolicy 或 .fast_switch 或 .target 或 .target_index - 差异见 + 下文。 + +并且可选择 + + .flags - cpufreq核的提示。 + + .driver_data - cpufreq驱动程序的特定数据。 + + .resolve_freq - 返回最适合目标频率的频率。不过并不能改变频率。 + + .get_intermediate 和 target_intermediate - 用于在改变CPU频率时切换到稳定 + 的频率。 + + .get - 返回CPU的当前频率。 + + .bios_limit - 返回HW/BIOS对CPU的最大频率限制值。 + + .exit - 一个指向per-policy清理函数的指针，该函数在cpu热插拔过程的CPU_POST_DEAD + 阶段被调用。 + + .stop_cpu - 一个指向per-policy停止函数的指针，该函数在cpu热插拔过程的CPU_DOWN_PREPARE + 阶段被调用。 + + .suspend - 一个指向per-policy暂停函数的指针，该函数在关中断且在该策略的调节器停止 + 后被调用。 + + .resume - 一个指向per-policy恢复函数的指针，该函数在关中断且在调节器再一次开始前被 + 调用。 + + .ready - 一个指向per-policy准备函数的指针，该函数在策略完全初始化之后被调用。 + + .attr - 一个指向NULL结尾的"struct freq_attr"列表的指针，该函数允许导出值到 + sysfs。 + + .boost_enabled - 如果设置，则启用提升(boost)频率。 + + .set_boost - 一个指向per-policy函数的指针，该函数用来开启/关闭提升(boost)频率功能。 + + +1.2 Per-CPU 初始化 +------------------ + +每当一个新的CPU被注册到设备模型中，或者在cpufreq驱动注册自己之后，如果此CPU的cpufreq策 +略不存在，则会调用per-policy的初始化函数cpufreq_driver.init。请注意，.init()和.exit()程序 +只对策略调用一次，而不是对策略管理的每个CPU调用一次。它需要一个 ``struct cpufreq_policy +*policy`` 作为参数。现在该怎么做呢？ + +如果有必要，请在你的CPU上激活CPUfreq功能支持。 + +然后，驱动程序必须填写以下数值: + ++-----------------------------------+--------------------------------------+ +|policy->cpuinfo.min_freq 和 | | +|policy->cpuinfo.max_freq | 该CPU支持的最低和最高频率（kHz） | +| | | +| | | ++-----------------------------------+--------------------------------------+ +|policy->cpuinfo.transition_latency | | +| | CPU在两个频率之间切换所需的时间，以 | +| | 纳秒为单位（如适用，否则指定 | +| | CPUFREQ_ETERNAL） | ++-----------------------------------+--------------------------------------+ +|policy->cur | 该CPU当前的工作频率(如适用) | +| | | ++-----------------------------------+--------------------------------------+ +|policy->min, | | +|policy->max, | | +|policy->policy and, if necessary, | | +|policy->governor | 必须包含该cpu的 “默认策略”。稍后 | +| | 会用这些值调用 | +| | cpufreq_driver.verify and either | +| | cpufreq_driver.setpolicy or | +| | cpufreq_driver.target/target_index | +| | | ++-----------------------------------+--------------------------------------+ +|policy->cpus | 用与这个CPU一起做DVFS的(在线+离线) | +| | CPU(即与它共享时钟/电压轨)的掩码更新 | +| | 这个 | +| | | ++-----------------------------------+--------------------------------------+ + +对于设置其中的一些值(cpuinfo.min[max]_freq, policy->min[max])，频率表助手可能会有帮 +助。关于它们的更多信息，请参见第2节。 + + +1.3 验证 +-------- + +当用户决定设置一个新的策略(由 “policy,governor,min,max组成”)时，必须对这个策略进行验证， +以便纠正不兼容的值。为了验证这些值，cpufreq_verify_within_limits(``struct cpufreq_policy +*policy``, ``unsigned int min_freq``, ``unsigned int max_freq``)函数可能会有帮助。 +关于频率表助手的详细内容请参见第2节。 + +您需要确保至少有一个有效频率（或工作范围）在 policy->min 和 policy->max 范围内。如果有必 +要，先增加policy->max，只有在没有办法的情况下，才减少policy->min。 + + +1.4 target 或 target_index 或 setpolicy 或 fast_switch? +------------------------------------------------------- + +大多数cpufreq驱动甚至大多数cpu频率升降算法只允许将CPU频率设置为预定义的固定值。对于这些，你 +可以使用->target()，->target_index()或->fast_switch()回调。 + +有些cpufreq功能的处理器可以自己在某些限制之间切换频率。这些应使用->setpolicy()回调。 + + +1.5. target/target_index +------------------------ + +target_index调用有两个参数：``struct cpufreq_policy * policy``和``unsigned int`` +索引(于列出的频率表)。 + +当调用这里时，CPUfreq驱动必须设置新的频率。实际频率必须由freq_table[index].frequency决定。 + +它应该总是在错误的情况下恢复到之前的频率(即policy->restore_freq)，即使我们之前切换到中间频率。 + +已弃用 +---------- +目标调用有三个参数。``struct cpufreq_policy * policy``, unsigned int target_frequency, +unsigned int relation. + +CPUfreq驱动在调用这里时必须设置新的频率。实际的频率必须使用以下规则来确定。 + +- 紧跟 "目标频率"。 +- policy->min <= new_freq <= policy->max (这必须是有效的!!!) +- 如果 relation==CPUFREQ_REL_L，尝试选择一个高于或等于 target_freq 的 new_freq。("L代表 + 最低，但不能低于") +- 如果 relation==CPUFREQ_REL_H，尝试选择一个低于或等于 target_freq 的 new_freq。("H代表 + 最高，但不能高于") + +这里，频率表助手可能会帮助你--详见第2节。 + +1.6. fast_switch +---------------- + +这个函数用于从调度器的上下文进行频率切换。并非所有的驱动都要实现它，因为不允许在这个回调中睡眠。这 +个回调必须经过高度优化，以尽可能快地进行切换。 + +这个函数有两个参数： ``struct cpufreq_policy *policy`` 和 ``unsigned int target_frequency``。 + + +1.7 setpolicy +------------- + +setpolicy调用只需要一个``struct cpufreq_policy * policy``作为参数。需要将处理器内或芯片组内动态频 +率切换的下限设置为policy->min，上限设置为policy->max，如果支持的话，当policy->policy为 +CPUFREQ_POLICY_PERFORMANCE时选择面向性能的设置，当CPUFREQ_POLICY_POWERSAVE时选择面向省电的设置。 +也可以查看drivers/cpufreq/longrun.c中的参考实现。 + +1.8 get_intermediate 和 target_intermediate +-------------------------------------------- + +仅适用于 target_index() 和 CPUFREQ_ASYNC_NOTIFICATION 未设置的驱动。 + +get_intermediate应该返回一个平台想要切换到的稳定的中间频率，target_intermediate()应该将CPU设置为 +该频率，然后再跳转到'index'对应的频率。核心会负责发送通知，驱动不必在target_intermediate()或 +target_index()中处理。 + +在驱动程序不想因为某个目标频率切换到中间频率的情况下，它们可以从get_intermediate()中返回'0'。在这种情况 +下，核心将直接调用->target_index()。 + +注意：->target_index()应该在失败的情况下恢复到policy->restore_freq，因为core会为此发送通知。 + + +2. 频率表助手 +============= + +由于大多数cpufreq处理器只允许被设置为几个特定的频率，因此，一个带有一些函数的 “频率表”可能会辅助处理器驱动 +程序的一些工作。这样的 "频率表" 由一个cpufreq_frequency_table条目构成的数组组成，"driver_data" 中包 +含了驱动程序的具体数值，"frequency" 中包含了相应的频率，并设置了标志。在表的最后，需要添加一个 +cpufreq_frequency_table条目，频率设置为CPUFREQ_TABLE_END。而如果想跳过表中的一个条目，则将频率设置为 +CPUFREQ_ENTRY_INVALID。这些条目不需要按照任何特定的顺序排序，但如果它们是cpufreq 核心会对它们进行快速的DVFS， +因为搜索最佳匹配会更快。 + +如果策略在其policy->freq_table字段中包含一个有效的指针，cpufreq表就会被核心自动验证。 + +cpufreq_frequency_table_verify()保证至少有一个有效的频率在policy->min和policy->max范围内，并且所有其他 +标准都被满足。这对->verify调用很有帮助。 + +cpufreq_frequency_table_target()是对应于->target阶段的频率表助手。只要把数值传递给这个函数，这个函数就会返 +回包含CPU要设置的频率的频率表条目。 + +以下宏可以作为cpufreq_frequency_table的迭代器。 + +cpufreq_for_each_entry(pos, table) - 遍历频率表的所有条目。 + +cpufreq_for_each_valid_entry(pos, table) - 该函数遍历所有条目，不包括CPUFREQ_ENTRY_INVALID频率。 +使用参数 "pos"-一个``cpufreq_frequency_table * `` 作为循环变量，使用参数 "table"-作为你想迭代 +的``cpufreq_frequency_table * `` 。 + +例如:: + + struct cpufreq_frequency_table *pos, *driver_freq_table; + + cpufreq_for_each_entry(pos, driver_freq_table) { + /* Do something with pos */ + pos->frequency = ... + } + +如果你需要在driver_freq_table中处理pos的位置，不要减去指针，因为它的代价相当高。相反，使用宏 +cpufreq_for_each_entry_idx() 和 cpufreq_for_each_valid_entry_idx() 。 diff --git a/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst b/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst new file mode 100644 index 000000000000..c90d1d8353ed --- /dev/null +++ b/Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst @@ -0,0 +1,130 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../cpu-freq/cpufreq-stats` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_cpufreq-stats.rst: + + +========================================== +sysfs CPUFreq Stats的一般说明 +========================================== + +用户信息 + + +作者: Venkatesh Pallipadi <venkatesh.pallipadi@intel.com> + +.. Contents + + 1. 简介 + 2. 提供的统计数据(举例说明) + 3. 配置cpufreq-stats + + +1. 简介 +=============== + +cpufreq-stats是一个为每个CPU提供CPU频率统计的驱动。 +这些统计数据在/sysfs中以一堆只读接口的形式提供。这个接口（在配置好后）将出现在 +/sysfs（<sysfs root>/devices/system/cpu/cpuX/cpufreq/stats/）中cpufreq下的一个单 +独的目录中，提供给每个CPU。 +各种统计数据将在此目录下形成只读文件。 + +此驱动是独立于任何可能运行在你所用CPU上的特定cpufreq_driver而设计的。因此，它将与所有 +cpufreq_driver一起工作。 + + +2. 提供的统计数据(举例说明) +===================================== + +cpufreq stats提供了以下统计数据（在下面详细解释）。 + +- time_in_state +- total_trans +- trans_table + +所有的统计数据将从统计驱动被载入的时间（或统计被重置的时间）开始，到某一统计数据被读取的时间为止。 +显然，统计驱动不会有任何关于统计驱动载入之前的频率转换信息。 + +:: + + <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # ls -l + total 0 + drwxr-xr-x 2 root root 0 May 14 16:06 . + drwxr-xr-x 3 root root 0 May 14 15:58 .. + --w------- 1 root root 4096 May 14 16:06 reset + -r--r--r-- 1 root root 4096 May 14 16:06 time_in_state + -r--r--r-- 1 root root 4096 May 14 16:06 total_trans + -r--r--r-- 1 root root 4096 May 14 16:06 trans_table + +- **reset** + +只写属性，可用于重置统计计数器。这对于评估不同调节器下的系统行为非常有用，且无需重启。 + + +- **time_in_state** + +此项给出了这个CPU所支持的每个频率所花费的时间。cat输出的每一行都会有"<frequency> +<time>"对，表示这个CPU在<frequency>上花费了<time>个usertime单位的时间。这里的 +usertime单位是10mS（类似于/proc中输出的其他时间）。 + +:: + + <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat time_in_state + 3600000 2089 + 3400000 136 + 3200000 34 + 3000000 67 + 2800000 172488 + + +- **total_trans** + +给出了这个CPU上频率转换的总次数。cat的输出将有一个单一的计数，这就是频率转换的总数。 + +:: + + <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat total_trans + 20 + +- **trans_table** + +这将提供所有CPU频率转换的细粒度信息。这里的cat输出是一个二维矩阵，其中一个条目<i, j>（第 +i行，第j列）代表从Freq_i到Freq_j的转换次数。Freq_i行和Freq_j列遵循驱动最初提供给cpufreq +核的频率表的排序顺序，因此可以排序（升序或降序）或不排序。 这里的输出也包含了每行每列的实际 +频率值，以便更好地阅读。 + +如果转换表大于PAGE_SIZE，读取时将返回一个-EFBIG错误。 + +:: + + <mysystem>:/sys/devices/system/cpu/cpu0/cpufreq/stats # cat trans_table + From : To + : 3600000 3400000 3200000 3000000 2800000 + 3600000: 0 5 0 0 0 + 3400000: 4 0 2 0 0 + 3200000: 0 1 0 2 0 + 3000000: 0 0 1 0 3 + 2800000: 0 0 0 2 0 + +3. 配置cpufreq-stats +============================ + +要在你的内核中配置cpufreq-stats:: + + Config Main Menu + Power management options (ACPI, APM) ---> + CPU Frequency scaling ---> + [*] CPU Frequency scaling + [*] CPU frequency translation statistics + + +"CPU Frequency scaling" (CONFIG_CPU_FREQ) 应该被启用以配置cpufreq-stats。 + +"CPU frequency translation statistics" (CONFIG_CPU_FREQ_STAT)提供了包括 +time_in_state、total_trans和trans_table的统计数据。 + +一旦启用了这个选项，并且你的CPU支持cpufrequency，你就可以在/sysfs中看到CPU频率统计。 diff --git a/Documentation/translations/zh_CN/cpu-freq/index.rst b/Documentation/translations/zh_CN/cpu-freq/index.rst new file mode 100644 index 000000000000..65074e211940 --- /dev/null +++ b/Documentation/translations/zh_CN/cpu-freq/index.rst @@ -0,0 +1,45 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../cpu-freq/index` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_index.rst: + + +======================================================= +Linux CPUFreq - Linux(TM)内核中的CPU频率和电压升降代码 +======================================================= + +Author: Dominik Brodowski <linux@brodo.de> + + 时钟升降允许你在运行中改变CPU的时钟速度。这是一个很好的节省电池电量的方法，因为时 + 钟速度越低，CPU消耗的电量越少。 + + +.. toctree:: + :maxdepth: 1 + + core + cpu-drivers + cpufreq-stats + +邮件列表 +------------ +这里有一个 CPU 频率变化的 CVS 提交和通用列表，您可以在这里报告bug、问题或提交补丁。要发 +布消息，请发送电子邮件到 linux-pm@vger.kernel.org。 + +链接 +----- +FTP档案: +* ftp://ftp.linux.org.uk/pub/linux/cpufreq/ + +如何访问CVS仓库: +* http://cvs.arm.linux.org.uk/ + +CPUFreq邮件列表: +* http://vger.kernel.org/vger-lists.html#linux-pm + +SA-1100的时钟和电压标度: +* http://www.lartmaker.nl/projects/scaling diff --git a/Documentation/translations/zh_CN/dev-tools/gcov.rst b/Documentation/translations/zh_CN/dev-tools/gcov.rst new file mode 100644 index 000000000000..3158c9da1318 --- /dev/null +++ b/Documentation/translations/zh_CN/dev-tools/gcov.rst @@ -0,0 +1,264 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/dev-tools/gcov.rst +:Translator: 赵军奎 Bernard Zhao <bernard@vivo.com> + +在Linux内核里使用gcov做代码覆盖率检查 +===================================== + +gcov分析核心支持在Linux内核中启用GCC的覆盖率测试工具 gcov_ ，Linux内核 +运行时的代码覆盖率数据会以gcov兼容的格式导出到“gcov”debugfs目录中，可 +以通过gcov的 ``-o`` 选项（如下示例）获得指定文件的代码运行覆盖率统计数据 +（需要跳转到内核编译路径下并且要有root权限）:: + + # cd /tmp/linux-out + # gcov -o /sys/kernel/debug/gcov/tmp/linux-out/kernel spinlock.c + +这将在当前目录中创建带有执行计数注释的源代码文件。 +在获得这些统计文件后，可以使用图形化的gcov前端工具（比如 lcov_ ），来实现 +自动化处理Linux内核的覆盖率运行数据，同时生成易于阅读的HTML格式文件。 + +可能的用途: + +* 调试（用来判断每一行的代码是否已经运行过） +* 测试改进（如何修改测试代码，尽可能地覆盖到没有运行过的代码） +* 内核最小化配置（对于某一个选项配置，如果关联的代码从来没有运行过， + 是否还需要这个配置） + +.. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html +.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php + + +准备 +---- + +内核打开如下配置:: + + CONFIG_DEBUG_FS=y + CONFIG_GCOV_KERNEL=y + +获取整个内核的覆盖率数据，还需要打开:: + + CONFIG_GCOV_PROFILE_ALL=y + +需要注意的是，整个内核开启覆盖率统计会造成内核镜像文件尺寸的增大， +同时内核运行也会变慢一些。 +另外，并不是所有的架构都支持整个内核开启覆盖率统计。 + +代码运行覆盖率数据只在debugfs挂载完成后才可以访问:: + + mount -t debugfs none /sys/kernel/debug + + +定制化 +------ + +如果要单独针对某一个路径或者文件进行代码覆盖率统计，可以在内核相应路 +径的Makefile中增加如下的配置: + +- 单独统计单个文件（例如main.o）:: + + GCOV_PROFILE_main.o := y + +- 单独统计某一个路径:: + + GCOV_PROFILE := y + +如果要在整个内核的覆盖率统计（开启CONFIG_GCOV_PROFILE_ALL）中单独排除 +某一个文件或者路径，可以使用如下的方法:: + + GCOV_PROFILE_main.o := n + +和:: + + GCOV_PROFILE := n + +此机制仅支持链接到内核镜像或编译为内核模块的文件。 + + +相关文件 +-------- + +gcov功能需要在debugfs中创建如下文件: + +``/sys/kernel/debug/gcov`` + gcov相关功能的根路径 + +``/sys/kernel/debug/gcov/reset`` + 全局复位文件:向该文件写入数据后会将所有的gcov统计数据清0 + +``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcda`` + gcov工具可以识别的覆盖率统计数据文件，向该文件写入数据后 + 会将本文件的gcov统计数据清0 + +``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcno`` + gcov工具需要的软连接文件（指向编译时生成的信息统计文件），这个文件是 + 在gcc编译时如果配置了选项 ``-ftest-coverage`` 时生成的。 + + +针对模块的统计 +-------------- + +内核中的模块会动态的加载和卸载，模块卸载时对应的数据会被清除掉。 +gcov提供了一种机制，通过保留相关数据的副本来收集这部分卸载模块的覆盖率数据。 +模块卸载后这些备份数据在debugfs中会继续存在。 +一旦这个模块重新加载，模块关联的运行统计会被初始化成debugfs中备份的数据。 + +可以通过对内核参数gcov_persist的修改来停用gcov对模块的备份机制:: + + gcov_persist = 0 + +在运行时，用户还可以通过写入模块的数据文件或者写入gcov复位文件来丢弃已卸 +载模块的数据。 + + +编译机和测试机分离 +------------------ + +gcov的内核分析插桩支持内核的编译和运行是在同一台机器上，也可以编译和运 +行是在不同的机器上。 +如果内核编译和运行是不同的机器，那么需要额外的准备工作，这取决于gcov工具 +是在哪里使用的: + +.. _gcov-test_zh: + +a) 若gcov运行在测试机上 + + 测试机上面gcov工具的版本必须要跟内核编译机器使用的gcc版本相兼容， + 同时下面的文件要从编译机拷贝到测试机上: + + 从源代码中: + - 所有的C文件和头文件 + + 从编译目录中: + - 所有的C文件和头文件 + - 所有的.gcda文件和.gcno文件 + - 所有目录的链接 + + 特别需要注意，测试机器上面的目录结构跟编译机器上面的目录机构必须 + 完全一致。 + 如果文件是软链接，需要替换成真正的目录文件（这是由make的当前工作 + 目录变量CURDIR引起的）。 + +.. _gcov-build_zh: + +b) 若gcov运行在编译机上 + + 测试用例运行结束后，如下的文件需要从测试机中拷贝到编译机上: + + 从sysfs中的gcov目录中: + - 所有的.gcda文件 + - 所有的.gcno文件软链接 + + 这些文件可以拷贝到编译机的任意目录下，gcov使用-o选项指定拷贝的 + 目录。 + + 比如一个是示例的目录结构如下:: + + /tmp/linux: 内核源码目录 + /tmp/out: 内核编译文件路径（make O=指定） + /tmp/coverage: 从测试机器上面拷贝的数据文件路径 + + [user@build] cd /tmp/out + [user@build] gcov -o /tmp/coverage/tmp/out/init main.c + + +关于编译器的注意事项 +-------------------- + +GCC和LLVM gcov工具不一定兼容。 +如果编译器是GCC，使用 gcov_ 来处理.gcno和.gcda文件，如果是Clang编译器， +则使用 llvm-cov_ 。 + +.. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html +.. _llvm-cov: https://llvm.org/docs/CommandGuide/llvm-cov.html + +GCC和Clang gcov之间的版本差异由Kconfig处理的。 +kconfig会根据编译工具链的检查自动选择合适的gcov格式。 + +问题定位 +-------- + +可能出现的问题1 + 编译到链接阶段报错终止 + +问题原因 + 分析标志指定在了源文件但是没有链接到主内核，或者客制化了链接程序 + +解决方法 + 通过在相应的Makefile中使用 ``GCOV_PROFILE := n`` + 或者 ``GCOV_PROFILE_basename.o := n`` 来将链接报错的文件排除掉 + +可能出现的问题2 + 从sysfs复制的文件显示为空或不完整 + +问题原因 + 由于seq_file的工作方式，某些工具（例如cp或tar）可能无法正确地从 + sysfs复制文件。 + +解决方法 + 使用 ``cat`` 读取 ``.gcda`` 文件，使用 ``cp -d`` 复制链接，或者使用附录B + 中所示的机制。 + + +附录A：collect_on_build.sh +-------------------------- + +用于在编译机上收集覆盖率元文件的示例脚本 +（见 :ref:`编译机和测试机分离 a. <gcov-test_zh>` ） + +.. code-block:: sh + + #!/bin/bash + + KSRC=$1 + KOBJ=$2 + DEST=$3 + + if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then + echo "Usage: $0 <ksrc directory> <kobj directory> <output.tar.gz>" >&2 + exit 1 + fi + + KSRC=$(cd $KSRC; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) + KOBJ=$(cd $KOBJ; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) + + find $KSRC $KOBJ \( -name '*.gcno' -o -name '*.[ch]' -o -type l \) -a \ + -perm /u+r,g+r | tar cfz $DEST -P -T - + + if [ $? -eq 0 ] ; then + echo "$DEST successfully created, copy to test system and unpack with:" + echo " tar xfz $DEST -P" + else + echo "Could not create file $DEST" + fi + + +附录B：collect_on_test.sh +------------------------- + +用于在测试机上收集覆盖率数据文件的示例脚本 +（见 :ref:`编译机和测试机分离 b. <gcov-build_zh>` ） + +.. code-block:: sh + + #!/bin/bash -e + + DEST=$1 + GCDA=/sys/kernel/debug/gcov + + if [ -z "$DEST" ] ; then + echo "Usage: $0 <output.tar.gz>" >&2 + exit 1 + fi + + TEMPDIR=$(mktemp -d) + echo Collecting data.. + find $GCDA -type d -exec mkdir -p $TEMPDIR/\{\} \; + find $GCDA -name '*.gcda' -exec sh -c 'cat < $0 > '$TEMPDIR'/$0' {} \; + find $GCDA -name '*.gcno' -exec sh -c 'cp -d $0 '$TEMPDIR'/$0' {} \; + tar czf $DEST -C $TEMPDIR sys + rm -rf $TEMPDIR + + echo "$DEST successfully created, copy to build system and unpack with:" + echo " tar xfz $DEST" diff --git a/Documentation/translations/zh_CN/dev-tools/index.rst b/Documentation/translations/zh_CN/dev-tools/index.rst new file mode 100644 index 000000000000..fd73c479917b --- /dev/null +++ b/Documentation/translations/zh_CN/dev-tools/index.rst @@ -0,0 +1,35 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/dev-tools/index.rst +:Translator: 赵军奎 Bernard Zhao <bernard@vivo.com> + +============ +内核开发工具 +============ + +本文档是有关内核开发工具文档的合集。 +目前这些文档已经整理在一起，不需要再花费额外的精力。 +欢迎任何补丁。 + +.. class:: toc-title + + 目录 + +.. toctree:: + :maxdepth: 2 + + gcov + +Todolist: + + - coccinelle + - sparse + - kcov + - kasan + - ubsan + - kmemleak + - kcsan + - gdb-kernel-debugging + - kgdb + - kselftest + - kunit/index diff --git a/Documentation/translations/zh_CN/disclaimer-zh_CN.rst b/Documentation/translations/zh_CN/disclaimer-zh_CN.rst index dcf803ede85a..3c6db094a63c 100644 --- a/Documentation/translations/zh_CN/disclaimer-zh_CN.rst +++ b/Documentation/translations/zh_CN/disclaimer-zh_CN.rst @@ -6,4 +6,4 @@ .. note:: 如果您发现本文档与原始文件有任何不同或者有翻译问题，请联系该文件的译者， - 或者请求时奎亮的帮助：<alex.shi@linux.alibaba.com>。 + 或者请求时奎亮的帮助：<alexs@kernel.org>。 diff --git a/Documentation/translations/zh_CN/doc-guide/contributing.rst b/Documentation/translations/zh_CN/doc-guide/contributing.rst new file mode 100644 index 000000000000..394a13b438b0 --- /dev/null +++ b/Documentation/translations/zh_CN/doc-guide/contributing.rst @@ -0,0 +1,238 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/doc-guide/contributing.rst + +:译者: 吴想成 Wu XiangCheng <bobwxc@email.cn> + +如何帮助改进内核文档 +==================== + +在任何软件开发项目中，文档都是重要组成部分。好的文档有助于引入新的开发人员， +并帮助已有的开发人员更有效地工作。如果缺少高质量的文档，大量的时间就会浪费在 +代码的逆向工程和犯本可避免的错误上。 + +不幸的是，内核的文档目前远远不能满足支持如此规模和重要性的项目的需要。 + +本指南适用于希望帮助改善这种状况的贡献者。内核文档的改进可以由开发者在不同的 +技能层级上进行；这也是一条相对简单可以帮助您了解内核过程并在社区中找到一席之 +地的路径。下面的大部分内容是文档维护人员列出的最迫切需要完成的任务。 + +文档待办事项列表 +---------------- + +为了使我们的文档达到应有的水平，需要完成的任务数不胜数。此列表包含许多重要的 +项目，但还远远不够详尽；如果您知道改进文档的其他方法，请不要羞于启齿。 + +消除警告（WARNING） +~~~~~~~~~~~~~~~~~~~ + +文档构建目前出现了数量惊人的警告。虱子多了不痒，债多了不愁；大伙儿忽略了它们， +他们永远不会注意到他们的工作增加了新的警告。因此，消除警告是文档待办事项列表 +中优先级最高的任务之一。这项任务本身相当简单，但必须以正确的方式进行，才能取 +得成功。 + +C代码编译器发出的警告常常会被视为误报，从而导致出现了旨在让编译器闭嘴的补丁。 +文档构建中的警告几乎总是指向真正的问题；要消除这些警告，需要理解问题并从源头上 +解决问题。因此，修复文档警告的补丁不应在标题中直接写“修复警告”；它们应该指明 +真正修复的问题。 + +另一个重点是，文档警告常常由C代码里kernel-doc注释中的问题引起。虽然文档维护 +人员对收到这些修复补丁的副本表示感谢，但是文档树实际上通常并不适合接受这些 +补丁；它们应该被交给相关子系统的维护人员。 + +例如，在一次文档构建中，我几乎是随意选取了一对警告:: + + ./drivers/devfreq/devfreq.c:1818: warning: bad line: + - Resource-managed devfreq_register_notifier() + ./drivers/devfreq/devfreq.c:1854: warning: bad line: + - Resource-managed devfreq_unregister_notifier() + +（作了断行以便于阅读） + +简单看一下上面给出的源文件，会发现几个kernel-doc注释，如下所示:: + + /** + * devm_devfreq_register_notifier() + - Resource-managed devfreq_register_notifier() + * @dev: The devfreq user device. (parent of devfreq) + * @devfreq: The devfreq object. + * @nb: The notifier block to be unregistered. + * @list: DEVFREQ_TRANSITION_NOTIFIER. + */ + +问题在于缺了一个“*”，这不符合构建系统对C注释块的格式要求。此问题自2016年注释 +被添加以来一直存在——整整四年之久。修复它只需要添加丢失的星号。看一眼该文件的 +历史记录以了解主题行的常规格式是什么样，再使用 ``scripts/get_maintainer.pl`` +来搞清谁应当收到此补丁。生成的补丁如下所示:: + + [PATCH] PM / devfreq: Fix two malformed kerneldoc comments + + Two kerneldoc comments in devfreq.c fail to adhere to the required format, + resulting in these doc-build warnings: + + ./drivers/devfreq/devfreq.c:1818: warning: bad line: + - Resource-managed devfreq_register_notifier() + ./drivers/devfreq/devfreq.c:1854: warning: bad line: + - Resource-managed devfreq_unregister_notifier() + + Add a couple of missing asterisks and make kerneldoc a little happier. + + Signed-off-by: Jonathan Corbet <corbet@lwn.net> + --- + drivers/devfreq/devfreq.c | 4 ++-- + 1 file changed, 2 insertions(+), 2 deletions(-) + + diff --git a/drivers/devfreq/devfreq.c b/drivers/devfreq/devfreq.c + index 57f6944d65a6..00c9b80b3d33 100644 + --- a/drivers/devfreq/devfreq.c + +++ b/drivers/devfreq/devfreq.c + @@ -1814,7 +1814,7 @@ static void devm_devfreq_notifier_release(struct device *dev, void *res) + + /** + * devm_devfreq_register_notifier() + - - Resource-managed devfreq_register_notifier() + + * - Resource-managed devfreq_register_notifier() + * @dev: The devfreq user device. (parent of devfreq) + * @devfreq: The devfreq object. + * @nb: The notifier block to be unregistered. + @@ -1850,7 +1850,7 @@ EXPORT_SYMBOL(devm_devfreq_register_notifier); + + /** + * devm_devfreq_unregister_notifier() + - - Resource-managed devfreq_unregister_notifier() + + * - Resource-managed devfreq_unregister_notifier() + * @dev: The devfreq user device. (parent of devfreq) + * @devfreq: The devfreq object. + * @nb: The notifier block to be unregistered. + -- + 2.24.1 + +整个过程只花了几分钟。当然，我后来发现有人在另一个树中修复了它，这亮出了另一 +个教训：在深入研究问题之前，一定要检查linux-next树，看看问题是否已经修复。 + +其他修复可能需要更长的时间，尤其是那些与缺少文档的结构体成员或函数参数相关的 +修复。这种情况下，需要找出这些成员或参数的作用，并正确描述它们。总之，这种 +任务有时会有点乏味，但它非常重要。如果我们真的可以从文档构建中消除警告，那么 +我们就可以开始期望开发人员开始注意避免添加新的警告了。 + +“迷失的”kernel-doc注释 +~~~~~~~~~~~~~~~~~~~~~~ + +开发者被鼓励去为他们的代码写kernel-doc注释，但是许多注释从未被引入文档构建。 +这使得这些信息更难找到，例如使Sphinx无法生成指向该文档的链接。将 ``kernel-doc`` +指令添加到文档中以引入这些注释可以帮助社区获得为编写注释所做工作的全部价值。 + +``scripts/find-unused-docs.sh`` 工具可以用来找到这些被忽略的评论。 + +请注意，将导出的函数和数据结构引入文档是最有价值的。许多子系统还具有供内部 +使用的kernel-doc注释；除非这些注释放在专门针对相关子系统开发人员的文档中， +否则不应将其引入文档构建中。 + + +修正错字 +~~~~~~~~ + + +修复文档中的排版或格式错误是一种快速学习如何创建和发送修补程序的方法，也是 +一项有用的服务。我总是愿意接受这样的补丁。这也意味着，一旦你修复了一些这种 +错误，请考虑转移到更高级的任务，留下一些拼写错误给下一个初学者解决。 + +请注意，有些并 **不是** 拼写错误，不应该被“修复”： + + - 内核文档中用美式和英式英语拼写皆可，没有必要互相倒换。 + + - 在内核文档中，没必要讨论句点后面应该跟一个还是两个空格的问题。其他一些有 + 合理分歧的地方，比如“牛津逗号”，在这也是跑题的。 + +与对任何项目的任何补丁一样，请考虑您的更改是否真的让事情变得更好。 + +“上古”文档 +~~~~~~~~~~ + +一些内核文档是最新的、被维护的，并且非常有用，有些文件确并非如此。尘封、陈旧 +和不准确的文档可能会误导读者，并对我们的整个文档产生怀疑。任何解决这些问题的 +事情都是非常受欢迎的。 + +无论何时处理文档，请考虑它是否是最新的，是否需要更新，或者是否应该完全删除。 +您可以注意以下几个警告标志： + + - 对2.x内核的引用 + - 指向SourceForge存储库 + - 历史记录除了拼写错误啥也没有持续几年 + - 讨论Git之前时代的工作流 + +当然，最好的办法是更新文档，添加所需的任何信息。这样的工作通常需要与熟悉相关 +子系统的开发人员合作。当有人善意地询问开发人员，并听取他们的回答然后采取 +行动时，开发人员通常更愿意与这些致力于改进文档的人员合作。 + +有些文档已经没希望了；例如，我们偶尔会发现引用了很久以前从内核中删除的代码的 +文档。删除过时的文档会碰见令人惊讶的阻力，但我们无论如何都应该这样做。文档中 +多余的粗枝大叶对任何人都没有帮助。 + +如果一个严重过时的文档中可能有一些有用的信息，而您又无法更新它，那么最好在 +开头添加一个警告。建议使用以下文本:: + + .. warning :: + This document is outdated and in need of attention. Please use + this information with caution, and please consider sending patches + to update it. + +这样的话，至少我们长期受苦的读者会得到文件可能会把他们引入歧途的警告。 + +文档一致性 +~~~~~~~~~~ + +这里的老前辈们会记得上世纪90年代出现在书架上的Linux书籍，它们只是从网上不同 +位置搜来的文档文件的集合。在此之后，（大部分）这些书都得到了改进，但是内核的 +文档仍然主要是建立在这种模型上。它有数千个文件，几乎每个文件都是与其他文件相 +独立编写的。我们没有一个连贯的内核文档；只有数千个独立的文档。 + +我们一直试图通过编篡一套“书籍”来改善这种情况，以为特定读者提供成套文档。这 +包括： + + - Documentation/translations/zh_CN/admin-guide/index.rst + - Documentation/core-api/index.rst + - Documentation/driver-api/index.rst + - Documentation/userspace-api/index.rst + +以及文档本身这本“书”。 + +将文档移到适当的书中是一项重要的任务，需要继续进行。不过这项工作还是有一些 +挑战性。移动文档会给处理这些文档的人带来短期的痛苦；他们对这些更改无甚热情 +也是可以理解的。通常情况下，可以将一个文档移动一下；不过我们真的不想一直移动 +它们。 + +即使所有文件都在正确的位置，我们也只是把一大堆文件变成一群小堆文件。试图将 +所有这些文件组合成一个整体的工作尚未开始。如果你对如何在这方面取得进展有好的 +想法，我们将很高兴了解。 + +样式表（Stylesheet）改进 +~~~~~~~~~~~~~~~~~~~~~~~~ + +随着Sphinx的采用，我们得到了比以前更好的HTML输出。但它仍然需要很大的改进； +Donald Knuth和Edward Tufte可能是映像平平的。这需要调整我们的样式表，以创建 +更具排版效果、可访问性和可读性的输出。 + +请注意：如果你承担这个任务，你将进入经典的两难领域。即使是相对明显的变化， +也会有很多意见和讨论。唉，这就是我们生活的世界的本质。 + +无LaTeX的PDF构建 +~~~~~~~~~~~~~~~~ + +对于拥有大量时间和Python技能的人来说，这绝对是一项不平凡的任务。Sphinx工具链 +相对较小且包含良好；很容易添加到开发系统中。但是构建PDF或EPUB输出需要安装 +LaTeX，它绝对称不上小或包含良好的。消除Latex将是一件很好的事情。 + +最初是希望使用 `rst2pdf <https://rst2pdf.org/>`_ 工具来生成PDF，但结果发现 +无法胜任这项任务。不过rst2pdf的开发工作最近似乎又有了起色，这是个充满希望的 +迹象。如果有开发人员愿意与该项目合作，使rst2pdf可与内核文档构建一起工作， +大家会非常感激。 + +编写更多文档 +~~~~~~~~~~~~ + +当然，内核中许多部分的文档严重不足。如果您有编写一个特定内核子系统文档的相应 +知识并愿意这样做，请不要犹豫，编写并向内核贡献结果吧！数不清的内核开发人员和 +用户会感谢你。 diff --git a/Documentation/translations/zh_CN/doc-guide/index.rst b/Documentation/translations/zh_CN/doc-guide/index.rst new file mode 100644 index 000000000000..5151953c196f --- /dev/null +++ b/Documentation/translations/zh_CN/doc-guide/index.rst @@ -0,0 +1,27 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/doc-guide/index.rst + +:译者: 吴想成 Wu XiangCheng <bobwxc@email.cn> + +.. _doc_guide_zh: + +================ +如何编写内核文档 +================ + +.. toctree:: + :maxdepth: 1 + + sphinx + kernel-doc + parse-headers + contributing + maintainer-profile + +.. only:: 子项目与HTML + + 目录 + ==== + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst new file mode 100644 index 000000000000..82ec84470c0b --- /dev/null +++ b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst @@ -0,0 +1,499 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/doc-guide/kernel-doc.rst + +:译者: 吴想成 Wu XiangCheng <bobwxc@email.cn> + +编写kernel-doc注释 +================== + +Linux内核源文件可以包含kernel-doc格式的结构化文档注释，用以描述代码的函数、 +类型和设计。将文档嵌入源文件更容易保持文档最新。 + +.. note:: 内核文档格式与javadoc、gtk-doc或Doxygen看似很相似，但由于历史原因， + 实际有着明显的不同。内核源包含成千上万个kernel-doc注释。请坚持遵循 + 此处描述的风格。 + +.. note:: kernel-doc无法包含Rust代码：请参考 Documentation/rust/docs.rst 。 + +从注释中提取kernel-doc结构，并从中生成适当的 `Sphinx C 域`_ 函数和带有锚点的 +类型描述。这些注释将被过滤以生成特殊kernel-doc高亮和交叉引用。详见下文。 + +.. _Sphinx C 域: http://www.sphinx-doc.org/en/stable/domains.html + +使用 ``EXPORT_SYMBOL`` 或 ``EXPORT_SYMBOL_GPL`` 导出到可加载模块的每个函数都 +应该有一个kernel-doc注释。模块使用的头文件中的函数和数据结构也应该有 +kernel-doc注释。 + +对于其他内核文件（未标记为 ``static`` ）中外部可见的函数，提供kernel-doc格式 +的文档是一个很好的实践。我们也建议为私有（文件 ``static`` ）程序提供kernel-doc +格式的文档，以确保内核源代码布局的一致性。此建议优先级较低，由内核源文件的 +维护者自行决定。 + +如何格式化kernel-doc注释 +------------------------ + +kernel-doc注释用 ``/**`` 作为开始标记。 ``kernel-doc`` 工具将提取以这种方式 +标记的注释。注释其余部分的格式类似于一个普通的多行注释，左侧有一列星号，以 +``*/`` 行结束。 + +函数和类型的kernel-doc注释应该放在所描述的函数或类型之前，以便最大限度地提高 +更改代码的人同时更改文档的可能性。概述kernel-doc注释可以放在最顶部的任何地方。 + +用详细模式和不生成实际输出来运行 ``kernel-doc`` 工具，可以验证文档注释的格式 +是否正确。例如:: + + scripts/kernel-doc -v -none drivers/foo/bar.c + +当请求执行额外的gcc检查时，内核构建将验证文档格式:: + + make W=n + +函数文档 +-------- + +函数和函数式宏的kernel-doc注释的一般格式是:: + + /** + * 函数名() - 函数简要说明. + * @参数1: 描述第一个参数. + * @参数2: 描述第二个参数. + * 可以为参数提供一段 + * 多行描述. + * + * 更详细的描述，进一步讨论函数 函数名(), 这可能对使用或修改它的人有用. + * 以空注释行开始, 内部可以包含空注释行. + * + * 详细描述可以有多个段落. + * + * Context: 描述函数是否可以休眠, 它需要、释放或期望持有什么锁. + * 可以写多行. + * Return: 描述函数返回值. + * + * 返回值描述也可以有多个段落, + * 并且应该放在注释块的末尾. + */ + +函数名后面的简短描述可以跨多行，并以参数描述、空注释行或注释块结尾结束。 + +函数参数 +~~~~~~~~ + +每个函数参数都应该按照顺序描述，紧跟在函数简要说明之后。不要在函数描述和参数 +之间，也不要在参数之间留空。 + +每个 ``@参数:`` 描述可以跨多行。 + +.. note:: + + 如果 ``@参数`` 描述有多行，则说明的续行应该从上一行的同一列开始:: + + * @参数: 较长说明 + * 的续行 + + 或:: + + * @参数: + * 较长说明 + * 的续行 + +如果函数的参数数目可变，则需用kernel-doc格式对其进行描述:: + + * @...: 描述 + +函数上下文 +~~~~~~~~~~ + +可调用函数的上下文应该在 ``Context`` 节中描述。此节应该包括函数是休眠的还是 +可以从中断上下文调用的，以及它需要什么锁、释放什么锁和期望它的调用者持有什么 +锁。 + +例如:: + + * Context: Any context. + * Context: Any context. Takes and releases the RCU lock. + * Context: Any context. Expects <lock> to be held by caller. + * Context: Process context. May sleep if @gfp flags permit. + * Context: Process context. Takes and releases <mutex>. + * Context: Softirq or process context. Takes and releases <lock>, BH-safe. + * Context: Interrupt context. + +返回值 +~~~~~~ + +如有返回值，应在 ``Return`` 节中描述。 + +.. note:: + + #) 您提供的多行描述文本 *不会* 识别换行符，因此如果您想将某些文本预格式化， + 如:: + + * Return: + * 0 - OK + * -EINVAL - invalid argument + * -ENOMEM - out of memory + + 它们在最终文档中变成一行:: + + Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory + + 因此，为了在需要的地方换行，您需要使用ReST列表，例如:: + + * Return: + * * 0 - OK to runtime suspend the device + * * -EBUSY - Device should not be runtime suspended + + #) 如果您提供的描述性文本中的行以某个后跟冒号的短语开头，则每一个这种短语 + 都将被视为新的节标题，可能会产生意料不到的效果。 + +结构体、共用体、枚举类型文档 +---------------------------- + +结构体（struct）、共用体（union）、枚举（enum）类型kernel-doc注释的一般格式为:: + + /** + * struct 结构体名 - 简要描述. + * @成员1: 成员1描述. + * @成员2: 成员2描述. + * 可以为成员提供 + * 多行描述. + * + * 结构体的描述. + */ + +可以用 ``union`` 或 ``enum`` 替换上面示例中的 ``struct`` ，以描述共用体或枚举。 +``成员`` 用于表示枚举中的元素或共用体成员。 + +结构体名称后面的简要说明可以跨多行，并以成员说明、空白注释行或注释块结尾结束。 + +成员 +~~~~ + +结构体、共用体和枚举的成员应以与函数参数相同的方式记录；它们后紧跟简短的描述， +并且为多行。 + +在结构体或共用体描述中，可以使用 ``private:`` 和 ``public:`` 注释标签。 +``private:`` 域内的字段不会列在生成的文档中。 + +``private:`` 和 ``public:`` 标签必须紧跟在 ``/*`` 注释标记之后。可以选择是否 +在 ``:`` 和 ``*/`` 结束标记之间包含注释。 + +例子:: + + /** + * struct 张三 - 简短描述 + * @a: 第一个成员 + * @b: 第二个成员 + * @d: 第三个成员 + * + * 详细描述 + */ + struct 张三 { + int a; + int b; + /* private: 仅内部使用 */ + int c; + /* public: 下一个是公有的 */ + int d; + }; + +嵌套的结构体/共用体 +~~~~~~~~~~~~~~~~~~~ + +嵌套的结构体/共用体可像这样记录:: + + /** + * struct nested_foobar - a struct with nested unions and structs + * @memb1: first member of anonymous union/anonymous struct + * @memb2: second member of anonymous union/anonymous struct + * @memb3: third member of anonymous union/anonymous struct + * @memb4: fourth member of anonymous union/anonymous struct + * @bar: non-anonymous union + * @bar.st1: struct st1 inside @bar + * @bar.st2: struct st2 inside @bar + * @bar.st1.memb1: first member of struct st1 on union bar + * @bar.st1.memb2: second member of struct st1 on union bar + * @bar.st2.memb1: first member of struct st2 on union bar + * @bar.st2.memb2: second member of struct st2 on union bar + */ + struct nested_foobar { + /* Anonymous union/struct*/ + union { + struct { + int memb1; + int memb2; + }; + struct { + void *memb3; + int memb4; + }; + }; + union { + struct { + int memb1; + int memb2; + } st1; + struct { + void *memb1; + int memb2; + } st2; + } bar; + }; + +.. note:: + + #) 在记录嵌套结构体或共用体时，如果结构体/共用体 ``张三`` 已命名，则其中 + 的成员 ``李四`` 应记录为 ``@张三.李四:`` + + #) 当嵌套结构体/共用体是匿名的时，其中的成员 ``李四`` 应记录为 ``@李四:`` + +行间注释文档 +~~~~~~~~~~~~ + +结构成员也可在定义时以行间注释形式记录。有两种样式，一种是单行注释，其中开始 +``/**`` 和结束 ``*/`` 位于同一行；另一种是多行注释，开头结尾各自位于一行，就 +像所有其他核心文档注释一样:: + + /** + * struct 张三 - 简短描述. + * @张三: 成员张三. + */ + struct 张三 { + int 张三; + /** + * @李四: 成员李四. + */ + int 李四; + /** + * @王五: 成员王五. + * + * 此处，成员描述可以为好几段. + */ + int 王五; + union { + /** @儿子: 单行描述. */ + int 儿子; + }; + /** @赵六: 描述@张三里面的结构体@赵六 */ + struct { + /** + * @赵六.女儿: 描述@张三.赵六里面的@女儿 + */ + int 女儿; + } 赵六; + }; + +Typedef文档 +----------- + +Typedef的kernel-doc文档注释的一般格式为:: + + /** + * typedef 类型名称 - 简短描述. + * + * 类型描述. + */ + +还可以记录带有函数原型的typedef:: + + /** + * typedef 类型名称 - 简短描述. + * @参数1: 参数1的描述 + * @参数2: 参数2的描述 + * + * 类型描述. + * + * Context: 锁（Locking）上下文. + * Return: 返回值的意义. + */ + typedef void (*类型名称)(struct v4l2_ctrl *参数1, void *参数2); + +高亮与交叉引用 +-------------- + +在kernel-doc注释的描述文本中可以识别以下特殊模式，并将其转换为正确的 +reStructuredText标记和 `Sphinx C 域`_ 引用。 + +.. attention:: 以下内容 **仅** 在kernel-doc注释中识别， **不会** 在普通的 + reStructuredText文档中识别。 + +``funcname()`` + 函数引用。 + +``@parameter`` + 函数参数的名称（未交叉引用，仅格式化）。 + +``%CONST`` + 常量的名称（未交叉引用，仅格式化）。 + +````literal```` + 预格式化文本块。输出将使用等距字体。 + + 若你需要使用在kernel-doc脚本或reStructuredText中有特殊含义的字符，则此功能 + 非常有用。 + + 若你需要在函数描述中使用类似于 ``%ph`` 的东西，这特别有用。 + +``$ENVVAR`` + 环境变量名称（未交叉引用，仅格式化）。 + +``&struct name`` + 结构体引用。 + +``&enum name`` + 枚举引用。 + +``&typedef name`` + Typedef引用。 + +``&struct_name->member`` or ``&struct_name.member`` + 结构体或共用体成员引用。交叉引用将链接到结构体或共用体定义，而不是直接到成员。 + +``&name`` + 泛类型引用。请首选上面描述的完整引用方式。此法主要是为了可能未描述的注释。 + +从reStructuredText交叉引用 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +无需额外的语法来从reStructuredText文档交叉引用kernel-do注释中定义的函数和类型。 +只需以 ``()`` 结束函数名，并在类型之前写上 ``struct`` ， ``union`` ， ``enum`` +或 ``typedef`` 。 +例如:: + + See foo(). + See struct foo. + See union bar. + See enum baz. + See typedef meh. + +若要在交叉引用链接中使用自定义文本，可以通过以下语法进行:: + + See :c:func:`my custom link text for function foo <foo>`. + See :c:type:`my custom link text for struct bar <bar>`. + +有关更多详细信息，请参阅 `Sphinx C 域`_ 文档。 + +总述性文档注释 +-------------- + +为了促进源代码和注释紧密联合，可以将kernel-doc文档块作为自由形式的注释，而 +不是函数、结构、联合、枚举或typedef的绑定kernel-doc。例如，这可以用于解释 +驱动程序或库代码的操作理论。 + +这是通过使用带有节标题的 ``DOC:`` 节关键字来实现的。 + +总述或高层级文档注释的一般格式为:: + + /** + * DOC: Theory of Operation + * + * The whizbang foobar is a dilly of a gizmo. It can do whatever you + * want it to do, at any time. It reads your mind. Here's how it works. + * + * foo bar splat + * + * The only drawback to this gizmo is that is can sometimes damage + * hardware, software, or its subject(s). + */ + +``DOC:`` 后面的标题用作源文件中的标题，但也用作提取文档注释的标识符。因此， +文件中的标题必须是唯一的。 + +包含kernel-doc注释 +================== + +文档注释可以被包含在任何使用专用kernel-doc Sphinx指令扩展的reStructuredText +文档中。 + +kernel-doc指令的格式如下:: + + .. kernel-doc:: source + :option: + +*source* 是相对于内核源代码树的源文件路径。 +支持以下指令选项： + +export: *[source-pattern ...]* + 包括 *source* 中使用 ``EXPORT_SYMBOL`` 或 ``EXPORT_SYMBOL_GPL`` 导出的所有 + 函数的文档，无论是在 *source* 中还是在 *source-pattern* 指定的任何文件中。 + + 当kernel-doc注释被放置在头文件中，而 ``EXPORT_SYMBOL`` 和 ``EXPORT_SYMBOL_GPL`` + 位于函数定义旁边时， *source-pattern* 非常有用。 + + 例子:: + + .. kernel-doc:: lib/bitmap.c + :export: + + .. kernel-doc:: include/net/mac80211.h + :export: net/mac80211/*.c + +internal: *[source-pattern ...]* + 包括 *source* 中所有在 *source* 或 *source-pattern* 的任何文件中都没有使用 + ``EXPORT_SYMBOL`` 或 ``EXPORT_SYMBOL_GPL`` 导出的函数和类型的文档。 + + 例子:: + + .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c + :internal: + +identifiers: *[ function/type ...]* + 在 *source* 中包含每个 *function* 和 *type* 的文档。如果没有指定 *function* ， + 则 *source* 中所有函数和类型的文档都将包含在内。 + + 例子:: + + .. kernel-doc:: lib/bitmap.c + :identifiers: bitmap_parselist bitmap_parselist_user + + .. kernel-doc:: lib/idr.c + :identifiers: + +no-identifiers: *[ function/type ...]* + 排除 *source* 中所有 *function* 和 *type* 的文档。 + + 例子:: + + .. kernel-doc:: lib/bitmap.c + :no-identifiers: bitmap_parselist + +functions: *[ function/type ...]* + 这是“identifiers”指令的别名，已弃用。 + +doc: *title* + 包含 *source* 中由 *title* 标题标识的 ``DOC:`` 文档段落。 *title* 中允许 + 空格；不要在 *title* 上加引号。 *title* 仅用作段落的标识符，不包含在输出中。 + 请确保在所附的reStructuredText文档中有适当的标题。 + + 例子:: + + .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c + :doc: High Definition Audio over HDMI and Display Port + +如果没有选项，kernel-doc指令将包含源文件中的所有文档注释。 + +kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/kerneldoc.py`` 。 +在内部，它使用 ``scripts/kernel-doc`` 脚本从源代码中提取文档注释。 + +.. _kernel_doc_zh: + +如何使用kernel-doc生成手册（man）页 +----------------------------------- + +如果您只想使用kernel-doc生成手册页，可以从内核git树这样做:: + + $ scripts/kernel-doc -man \ + $(git grep -l '/\*\*' -- :^Documentation :^tools) \ + | scripts/split-man.pl /tmp/man + +一些旧版本的git不支持路径排除语法的某些变体。 +以下命令之一可能适用于这些版本:: + + $ scripts/kernel-doc -man \ + $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \ + | scripts/split-man.pl /tmp/man + + $ scripts/kernel-doc -man \ + $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \ + | scripts/split-man.pl /tmp/man + diff --git a/Documentation/translations/zh_CN/doc-guide/maintainer-profile.rst b/Documentation/translations/zh_CN/doc-guide/maintainer-profile.rst new file mode 100644 index 000000000000..35c88e5b3d83 --- /dev/null +++ b/Documentation/translations/zh_CN/doc-guide/maintainer-profile.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/doc-guide/maintainer-profile.rst + +:译者: 吴想成 Wu XiangCheng <bobwxc@email.cn> + +文档子系统维护人员条目概述 +========================== + +文档“子系统”是内核文档和相关基础设施的中心协调点。它涵盖了 Documentation/ 下 +的文件层级（Documentation/devicetree 除外）、scripts/ 下的各种实用程序，并且 +在某些情况下的也包括 LICENSES/ 。 + +不过值得注意的是，这个子系统的边界比通常更加模糊。许多其他子系统维护人员需要 +保持对 Documentation/ 某些部分的控制，以便于可以更自由地做更改。除此之外， +许多内核文档都以kernel-doc注释的形式出现在源代码中；这些注释通常（但不总是） +由相关的子系统维护人员维护。 + +文档子系统的邮件列表是<linux-doc@vger.kernel.org>。 +补丁应尽量针对docs-next树。 + +提交检查单补遗 +-------------- + +在进行文档更改时，您应当构建文档以测试，并确保没有引入新的错误或警告。生成 +HTML文档并查看结果将有助于避免对文档渲染结果的不必要争执。 + +开发周期的关键节点 +------------------ + +补丁可以随时发送，但在合并窗口期间，响应将比通常慢。文档树往往在合并窗口打开 +之前关闭得比较晚，因为文档补丁导致回归的风险很小。 + +审阅节奏 +-------- + +我（译注：指Jonathan Corbet <corbet@lwn.net>）是文档子系统的唯一维护者，我在 +自己的时间里完成这项工作，所以对补丁的响应有时会很慢。当补丁被合并时（或当我 +决定拒绝合并补丁时），我都会发送通知。如果您在发送补丁后一周内没有收到回复， +请不要犹豫，发送提醒就好。 + diff --git a/Documentation/translations/zh_CN/doc-guide/parse-headers.rst b/Documentation/translations/zh_CN/doc-guide/parse-headers.rst new file mode 100644 index 000000000000..a08819e904ed --- /dev/null +++ b/Documentation/translations/zh_CN/doc-guide/parse-headers.rst @@ -0,0 +1,187 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/doc-guide/parse-headers.rst + +:译者: 吴想成 Wu XiangCheng <bobwxc@email.cn> + +===================== +包含用户空间API头文件 +===================== + +有时，为了描述用户空间API并在代码和文档之间生成交叉引用，需要包含头文件和示例 +C代码。为用户空间API文件添加交叉引用还有一个好处：如果在文档中找不到相应符号， +Sphinx将生成警告。这有助于保持用户空间API文档与内核更改同步。 +:ref:`parse_headers.pl <parse_headers_zh>` 提供了生成此类交叉引用的一种方法。 +在构建文档时，必须通过Makefile调用它。有关如何在内核树中使用它的示例，请参阅 +``Documentation/userspace-api/media/Makefile`` 。 + +.. _parse_headers_zh: + +parse_headers.pl +---------------- + +脚本名称 +~~~~~~~~ + + +parse_headers.pl——解析一个C文件，识别函数、结构体、枚举、定义并对Sphinx文档 +创建交叉引用。 + + +用法概要 +~~~~~~~~ + + +\ **parse_headers.pl**\ [<选项>] <C文件> <输出文件> [<例外文件>] + +<选项> 可以是： --debug, --help 或 --usage 。 + + +选项 +~~~~ + + + +\ **--debug**\ + + 开启脚本详细模式，在调试时很有用。 + + +\ **--usage**\ + + 打印简短的帮助信息并退出。 + + + +\ **--help**\ + + 打印更详细的帮助信息并退出。 + + +说明 +~~~~ + +通过C头文件或源文件（<C文件>）中为描述API的文档编写的带交叉引用的 ..预格式化 +文本 块将文件转换成重构文本（RST）。它接受一个可选的<例外文件>，其中描述了 +哪些元素将被忽略或指向非默认引用。 + +输出被写入到<输出文件>。 + +它能够识别定义、函数、结构体、typedef、枚举和枚举符号，并为它们创建交叉引用。 +它还能够区分用于指定Linux ioctl的 ``#define`` 。 + +<例外文件> 包含两种类型的语句： \ **ignore**\ 或 \ **replace**\ . + +ignore标记的语法为： + + +ignore \ **type**\ \ **name**\ + +The \ **ignore**\ 意味着它不会为类型为 \ **type**\ 的 \ **name**\ 符号生成 +交叉引用。 + + +replace标记的语法为： + + +replace \ **type**\ \ **name**\ \ **new_value**\ + +The \ **replace**\ 味着它将为 \ **type**\ 类型的 \ **name**\ 符号生成交叉引 +用，但是它将使用 \ **new_value**\ 来取代默认的替换规则。 + + +这两种语句中， \ **type**\ 可以是以下任一项： + + +\ **ioctl**\ + + ignore 或 replace 语句应用于ioctl定义，如： + + #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register) + + + +\ **define**\ + + ignore 或 replace 语句应用于在<C文件>中找到的任何其他 ``#define`` 。 + + + +\ **typedef**\ + + ignore 和 replace 语句应用于<C文件>中的typedef语句。 + + + +\ **struct**\ + + ignore 和 replace 语句应用于<C文件>中的结构体名称语句。 + + + +\ **enum**\ + + ignore 和 replace 语句应用于<C文件>中的枚举名称语句。 + + + +\ **symbol**\ + + ignore 和 replace 语句应用于<C文件>中的枚举值名称语句。 + + replace语句中， \ **new_value**\ 会自动使用 \ **typedef**\ , \ **enum**\ + 和 \ **struct**\ 类型的 :c:type: 引用；以及 \ **ioctl**\ , \ **define**\ 和 + \ **symbol**\ 类型的 :ref: 。引用的类型也可以在replace语句中显式定义。 + + +示例 +~~~~ + + +ignore define _VIDEODEV2_H + + +忽略<C文件>中的 #define _VIDEODEV2_H 。 + +ignore symbol PRIVATE + + +如下结构体： + +enum foo { BAR1, BAR2, PRIVATE }; + +不会为 \ **PRIVATE**\ 生成交叉引用。 + +replace symbol BAR1 :c:type:\`foo\` +replace symbol BAR2 :c:type:\`foo\` + + +如下结构体： + +enum foo { BAR1, BAR2, PRIVATE }; + +它会让BAR1和BAR2枚举符号交叉引用C域中的foo符号。 + + + +缺陷 +~~~~ + + +请向Mauro Carvalho Chehab <mchehab@kernel.org>报告有关缺陷。 + +中文翻译问题请找中文翻译维护者。 + + +版权 +~~~~ + + +版权所有 (c) 2016 Mauro Carvalho Chehab <mchehab+samsung@kernel.org> + +许可证 GPLv2：GNU GPL version 2 <https://gnu.org/licenses/gpl.html> + +这是自由软件：你可以自由地修改和重新发布它。 +在法律允许的范围内，**不提供任何保证**。 diff --git a/Documentation/translations/zh_CN/doc-guide/sphinx.rst b/Documentation/translations/zh_CN/doc-guide/sphinx.rst new file mode 100644 index 000000000000..951595c7d599 --- /dev/null +++ b/Documentation/translations/zh_CN/doc-guide/sphinx.rst @@ -0,0 +1,415 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/doc-guide/sphinx.rst + +:译者: 吴想成 Wu XiangCheng <bobwxc@email.cn> + +.. _sphinxdoc_zh: + +简介 +==== + +Linux内核使用 `Sphinx <http://www.sphinx-doc.org/>`_ 来把 ``Documentation`` +下的 `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ 文件转 +换成漂亮的文档。使用 ``make htmldocs`` 或 ``make pdfdocs`` 命令即可构建HTML +或PDF格式的文档。生成的文档放在 ``Documentation/output`` 文件夹中。 + +reStructuredText文件可能包含包含来自源文件的结构化文档注释或kernel-doc注释。 +通常它们用于描述代码的功能、类型和设计。kernel-doc注释有一些特殊的结构和 +格式，但除此之外，它们还被作为reStructuredText处理。 + +最后，有成千上万的纯文本文档文件散布在 ``Documentation`` 里。随着时间推移， +其中一些可能会转换为reStructuredText，但其中大部分仍保持纯文本。 + +.. _sphinx_install_zh: + +安装Sphinx +========== + +Documentation/ 下的ReST文件现在使用sphinx1.3或更高版本构建。 + +这有一个脚本可以检查Sphinx的依赖项。更多详细信息见 +:ref:`sphinx-pre-install_zh` 。 + +大多数发行版都附带了Sphinx，但是它的工具链比较脆弱，而且在您的机器上升级它 +或其他一些Python包导致文档构建中断的情况并不少见。 + +避免此情况的一种方法是使用与发行版附带的不同的版本。因此，建议使用 +``virtualenv-3`` 或 ``virtualenv`` 在虚拟环境中安装Sphinx，具体取决于发行版 +如何打包Python3。 + +.. note:: + + #) 低于1.5版本的Sphinx无法与Python的0.13.1或更高版本docutils一起正常工作。 + 如果您想使用这些版本，那么应该运行 ``pip install 'docutils==0.12'`` 。 + + #) html输出建议使用RTD主题。根据Sphinx版本的不同，它应该用 + ``pip install sphinx_rtd_theme`` 单独安装。 + + #) 一些ReST页面包含数学表达式。由于Sphinx的工作方式，这些表达式是使用 LaTeX + 编写的。它需要安装amsfonts和amsmath宏包，以便显示。 + +总之，如您要安装Sphinx 1.7.9版本，应执行:: + + $ virtualenv sphinx_1.7.9 + $ . sphinx_1.7.9/bin/activate + (sphinx_1.7.9) $ pip install -r Documentation/sphinx/requirements.txt + +在运行 ``. sphinx_1.7.9/bin/activate`` 之后，提示符将变化，以指示您正在使用新 +环境。如果您打开了一个新的shell，那么在构建文档之前，您需要重新运行此命令以再 +次进入虚拟环境中。 + +图片输出 +-------- + +内核文档构建系统包含一个扩展，可以处理GraphViz和SVG格式的图像（参见 +:ref:`sphinx_kfigure_zh` ）。 + +为了让它工作，您需要同时安装GraphViz和ImageMagick包。如果没有安装这些软件包， +构建系统仍将构建文档，但不会在输出中包含任何图像。 + +PDF和LaTeX构建 +-------------- + +目前只有Sphinx 1.4及更高版本才支持这种构建。 + +对于PDF和LaTeX输出，还需要 ``XeLaTeX`` 3.14159265版本。（译注：此版本号真实 +存在） + +根据发行版的不同，您可能还需要安装一系列 ``texlive`` 软件包，这些软件包提供了 +``XeLaTeX`` 工作所需的最小功能集。 + +.. _sphinx-pre-install_zh: + +检查Sphinx依赖项 +---------------- + +这有一个脚本可以自动检查Sphinx依赖项。如果它认得您的发行版，还会提示您所用发行 +版的安装命令:: + + $ ./scripts/sphinx-pre-install + Checking if the needed tools for Fedora release 26 (Twenty Six) are available + Warning: better to also install "texlive-luatex85". + You should run: + + sudo dnf install -y texlive-luatex85 + /usr/bin/virtualenv sphinx_1.7.9 + . sphinx_1.7.9/bin/activate + pip install -r Documentation/sphinx/requirements.txt + + Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468. + +默认情况下，它会检查html和PDF的所有依赖项，包括图像、数学表达式和LaTeX构建的 +需求，并假设将使用虚拟Python环境。html构建所需的依赖项被认为是必需的，其他依 +赖项则是可选的。 + +它支持两个可选参数： + +``--no-pdf`` + + 禁用PDF检查； + +``--no-virtualenv`` + + 使用Sphinx的系统打包，而不是Python虚拟环境。 + +Sphinx构建 +========== + +生成文档的常用方法是运行 ``make htmldocs`` 或 ``make pdfdocs`` 。还有其它可用 +的格式：请参阅 ``make help`` 的文档部分。生成的文档放在 ``Documentation/output`` +下相应格式的子目录中。 + +要生成文档，显然必须安装Sphinx（ ``sphinx-build`` ）。要让HTML输出更漂亮，可以 +使用Read the Docs Sphinx主题（ ``sphinx_rtd_theme`` ）。对于PDF输出，您还需要 +``XeLaTeX`` 和来自ImageMagick（https://www.imagemagick.org）的 ``convert(1)`` 。 +所有这些软件在大多发行版中都可用或已打包。 + +要传递额外的选项给Sphinx，可以使用make变量 ``SPHINXOPTS`` 。例如，使用 +``make SPHINXOPTS=-v htmldocs`` 获得更详细的输出。 + + +要删除生成的文档，请运行 ``make cleandocs`` 。 + +编写文档 +======== + +添加新文档很容易，只需： + +1. 在 ``Documentation`` 下某处添加一个新的 ``.rst`` 文件。 +2. 从 ``Documentation/index.rst`` 中的Sphinx `主目录树`_ 链接到它。 + +.. _主目录树: http://www.sphinx-doc.org/en/stable/markup/toctree.html + +对于简单的文档（比如您现在正在阅读的文档），这通常已经足够好了，但是对于较大 +的文档，最好创建一个子目录（或者使用现有的子目录）。例如，图形子系统文档位于 +``Documentation/gpu`` 下，拆分为多个 ``.rst`` 文件，并具有从主目录链接来的单 +独索引 ``index.rst`` （有自己的目录树 ``toctree`` ）。 + +请参阅 `Sphinx <http://www.sphinx-doc.org/>`_ 和 `reStructuredText +<http://docutils.sourceforge.net/rst.html>`_ 的文档，以了解如何使用它们。 +特别是Sphinx `reStructuredText 基础`_ 这是开始学习使用reStructuredText的 +好地方。还有一些 `Sphinx 特殊标记结构`_ 。 + +.. _reStructuredText 基础: http://www.sphinx-doc.org/en/stable/rest.html +.. _Sphinx 特殊标记结构: http://www.sphinx-doc.org/en/stable/markup/index.html + +内核文档的具体指南 +------------------ + +这是一些内核文档的具体指南： + +* 请不要过于痴迷转换格式到reStructuredText。保持简单。在大多数情况下，文档 + 应该是纯文本，格式应足够一致，以便可以转换为其他格式。 + +* 将现有文档转换为reStructuredText时，请尽量减少格式更改。 + +* 在转换文档时，还要更新内容，而不仅仅是格式。 + +* 请遵循标题修饰符的顺序： + + 1. ``=`` 文档标题，要有上线:: + + ======== + 文档标题 + ======== + + 2. ``=`` 章:: + + 章标题 + ====== + + 3. ``-`` 节:: + + 节标题 + ------ + + 4. ``~`` 小节:: + + 小节标题 + ~~~~~~~~ + + 尽管RST没有规定具体的顺序（“没有强加一个固定数量和顺序的节标题装饰风格，最终 + 按照的顺序将是实际遇到的顺序。”），但是拥有一个通用级别的文档更容易遵循。 + +* 对于插入固定宽度的文本块（用于代码样例、用例等）： ``::`` 用于语法高亮意义不 + 大的内容，尤其是短代码段； ``.. code-block:: <language>`` 用于需要语法高亮的 + 较长代码块。对于嵌入到文本中的简短代码片段，请使用 \`\` 。 + + +C域 +--- + +**Sphinx C域（Domain）** （name c）适用于C API文档。例如，函数原型： + +.. code-block:: rst + + .. c:function:: int ioctl( int fd, int request ) + +内核文档的C域有一些附加特性。例如，您可以使用诸如 ``open`` 或 ``ioctl`` 这样的 +通用名称重命名函数的引用名称： + +.. code-block:: rst + + .. c:function:: int ioctl( int fd, int request ) + :name: VIDIOC_LOG_STATUS + +函数名称（例如ioctl）仍保留在输出中，但引用名称从 ``ioctl`` 变为 +``VIDIOC_LOG_STATUS`` 。此函数的索引项也变为 ``VIDIOC_LOG_STATUS`` 。 + +请注意，不需要使用 ``c:func:`` 生成函数文档的交叉引用。由于一些Sphinx扩展的 +神奇力量，如果给定函数名的索引项存在，文档构建系统会自动将对 ``function()`` +的引用转换为交叉引用。如果在内核文档中看到 ``c:func:`` 的用法，请删除它。 + + +列表 +---- + +我们建议使用 *列式表* 格式。 *列式表* 格式是二级列表。与ASCII艺术相比，它们对 +文本文件的读者来说可能没有那么舒适。但其优点是易于创建或修改，而且修改的差异 +（diff）更有意义，因为差异仅限于修改的内容。 + +*平铺表* 也是一个二级列表，类似于 *列式表* ，但具有一些额外特性： + +* 列范围：使用 ``cspan`` 修饰，可以通过其他列扩展单元格 + +* 行范围：使用 ``rspan`` 修饰，可以通过其他行扩展单元格 + +* 自动将表格行最右边的单元格扩展到该行右侧空缺的单元格上。若使用 + ``:fill-cells:`` 选项，此行为可以从 *自动合并* 更改为 *自动插入* ，自动 + 插入（空）单元格，而不是扩展合并到最后一个单元格。 + +选项： + +* ``:header-rows:`` [int] 标题行计数 +* ``:stub-columns:`` [int] 标题列计数 +* ``:widths:`` [[int] [int] ... ] 列宽 +* ``:fill-cells:`` 插入缺少的单元格，而不是自动合并缺少的单元格 + +修饰： + +* ``:cspan:`` [int] 扩展列 +* ``:rspan:`` [int] 扩展行 + +下面的例子演示了如何使用这些标记。分级列表的第一级是 *表格行* 。 *表格行* 中 +只允许一个标记，即该 *表格行* 中的单元格列表。 *comments* （ ``..`` ）和 +*targets* 例外（例如引用 ``:ref:`最后一行 <last row_zh>``` / :ref:`最后一行 +<last row_zh>` ）。 + +.. code-block:: rst + + .. flat-table:: 表格标题 + :widths: 2 1 1 3 + + * - 表头 列1 + - 表头 列2 + - 表头 列3 + - 表头 列4 + + * - 行1 + - 字段1.1 + - 字段1.2（自动扩展） + + * - 行2 + - 字段2.1 + - :rspan:`1` :cspan:`1` 字段2.2~3.3 + + * .. _`last row_zh`: + + - 行3 + +渲染效果： + + .. flat-table:: 表格标题 + :widths: 2 1 1 3 + + * - 表头 列1 + - 表头 列2 + - 表头 列3 + - 表头 列4 + + * - 行1 + - 字段1.1 + - 字段1.2（自动扩展） + + * - 行2 + - 字段2.1 + - :rspan:`1` :cspan:`1` 字段2.2~3.3 + + * .. _`last row_zh`: + + - 行3 + +交叉引用 +-------- + +从一页文档到另一页文档的交叉引用可以通过简单地写出文件路径来完成，无特殊格式 +要求。路径可以是绝对路径或相对路径。绝对路径从“Documentation/”开始。例如，要 +交叉引用此页，以下写法皆可，取决于具体的文档目录（注意 ``.rst`` 扩展名是可选 +的）:: + + 参见 Documentation/doc-guide/sphinx.rst 。此法始终可用。 + 请查看 sphinx.rst ，仅在同级目录中有效。 + 请阅读 ../sphinx.rst ，上级目录中的文件。 + +如果要使用相对路径，则需要使用Sphinx的 ``doc`` 修饰。例如，从同一目录引用此页 +的操作如下:: + + 参见 :doc:`sphinx文档的自定义链接文本 <sphinx>`. + +对于大多数用例，前者是首选，因为它更干净，更适合阅读源文件的人。如果您遇到一 +个没有任何特殊作用的 ``:doc:`` 用法，请将其转换为文档路径。 + +有关交叉引用kernel-doc函数或类型的信息，请参阅 +Documentation/doc-guide/kernel-doc.rst 。 + +.. _sphinx_kfigure_zh: + +图形图片 +======== + +如果要添加图片，应该使用 ``kernel-figure`` 和 ``kernel-image`` 指令。例如， +要插入具有可缩放图像格式的图形，请使用SVG（:ref:`svg_image_example_zh` ）:: + + .. kernel-figure:: ../../../doc-guide/svg_image.svg + :alt: 简易 SVG 图片 + + SVG 图片示例 + +.. _svg_image_example_zh: + +.. kernel-figure:: ../../../doc-guide/svg_image.svg + :alt: 简易 SVG 图片 + + SVG 图片示例 + +内核figure（和image）指令支持 DOT 格式文件，请参阅 + +* DOT：http://graphviz.org/pdf/dotguide.pdf +* Graphviz：http://www.graphviz.org/content/dot-language + +一个简单的例子（:ref:`hello_dot_file_zh` ）:: + + .. kernel-figure:: ../../../doc-guide/hello.dot + :alt: 你好，世界 + + DOT 示例 + +.. _hello_dot_file_zh: + +.. kernel-figure:: ../../../doc-guide/hello.dot + :alt: 你好，世界 + + DOT 示例 + +嵌入的渲染标记（或语言），如Graphviz的 **DOT** 由 ``kernel-render`` 指令提供:: + + .. kernel-render:: DOT + :alt: 有向图 + :caption: 嵌入式 **DOT** (Graphviz) 代码 + + digraph foo { + "五棵松" -> "国贸"; + } + +如何渲染取决于安装的工具。如果安装了Graphviz，您将看到一个矢量图像。否则，原始 +标记将作为 *文字块* 插入（:ref:`hello_dot_render_zh` ）。 + +.. _hello_dot_render_zh: + +.. kernel-render:: DOT + :alt: 有向图 + :caption: 嵌入式 **DOT** (Graphviz) 代码 + + digraph foo { + "五棵松" -> "国贸"; + } + +*render* 指令包含 *figure* 指令中已知的所有选项，以及选项 ``caption`` 。如果 +``caption`` 有值，则插入一个 *figure* 节点，若无，则插入一个 *image* 节点。 +如果您想引用它，还需要一个 ``caption`` （:ref:`hello_svg_render_zh` ）。 + +嵌入式 **SVG**:: + + .. kernel-render:: SVG + :caption: 嵌入式 **SVG** 标记 + :alt: 右上箭头 + + <?xml version="1.0" encoding="UTF-8"?> + <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...> + ... + </svg> + +.. _hello_svg_render_zh: + +.. kernel-render:: SVG + :caption: 嵌入式 **SVG** 标记 + :alt: 右上箭头 + + <?xml version="1.0" encoding="UTF-8"?> + <svg xmlns="http://www.w3.org/2000/svg" + version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400"> + <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/> + <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/> + </svg> + diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst index be6f11176200..ee6b20ca9080 100644 --- a/Documentation/translations/zh_CN/index.rst +++ b/Documentation/translations/zh_CN/index.rst @@ -18,8 +18,18 @@ admin-guide/index process/index + dev-tools/index + doc-guide/index + kernel-hacking/index filesystems/index arm64/index + sound/index + cpu-freq/index + mips/index + iio/index + riscv/index + core-api/index + openrisc/index 目录和表格 ---------- diff --git a/Documentation/translations/zh_CN/kernel-hacking/hacking.rst b/Documentation/translations/zh_CN/kernel-hacking/hacking.rst new file mode 100644 index 000000000000..ab974faddecf --- /dev/null +++ b/Documentation/translations/zh_CN/kernel-hacking/hacking.rst @@ -0,0 +1,708 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/kernel-hacking/hacking.rst + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +============== +内核骇客指北 +============== + +:作者: Rusty Russell + +引言 +===== + +欢迎咱优雅的读者们来阅读Rusty的非常不靠谱的Linux内核骇客（Hacking）指南。本文 +描述了内核代码的常见例程和一般要求：其目标是引导有经验的C程序员入门Linux内核 +开发。我回避了实现细节：这是代码要做的，也忽略了很多有用的例程。 + +在你读这篇文章之前，请理解我从来没有想过要写这篇文章，因为我的资历太低了； +但我一直想读这样的文章，自己写是唯一的方法。我希望它能成长为一个最佳实践、 +通用起点和其他信息的汇编。 + +玩家 +======= + +在任何时候，系统中的每个CPU都可以： + +- 与任何进程无关，服务于硬件中断； + +- 与任何进程无关，服务于软件中断（softirq）或子任务（tasklet）； + +- 运行于内核空间中，与进程（用户上下文）相关联； + +- 在用户空间中运行进程。 + +它们之间有优先级顺序。最下面的两个可以互相抢占，但上面为严格的层次结构： +每个层级只能被上方的抢占。例如，当一个软中断在CPU上运行时，没有其他软中断 +会抢占它，但是硬件中断可以抢占它。不过，系统中的任何其他CPU都是独立执行的。 + +我们将会看到许多方法，用户上下文可以阻止中断，从而成为真正的不可抢占。 + +用户上下文 +------------ + +用户上下文是指当您从系统调用或其他陷阱进入时：就像用户空间一样，您可以被更 +重要的任务和中断抢占。您可以通过调用 :c:func:`schedule()` 进行睡眠。 + +.. note:: + + 在模块加载和卸载以及块设备层上的操作时，你始终处于用户上下文中。 + +在用户上下文中，当前 ``current`` 指针（指示我们当前正在执行的任务）是有效的， +且 :c:func:`in_interrupt()` （ ``include/linux/preempt.h`` ）值为非（false）。 + +.. warning:: + + 请注意，如果您禁用了抢占或软中断（见下文），:c:func:`in_interrupt()` 会 + 返回假阳性。 + +硬件中断（Hard IRQs） +---------------------- + +像定时器、网卡和键盘等都是可能在任意时刻产生中断的真实硬件。内核运行中断 +处理程序，为硬件提供服务。内核确保处理程序永远不会重入：如果相同的中断到达， +它将被排队（或丢弃）。因为它会关闭中断，所以处理程序必须很快：通常它只是 +确认中断，标记一个“软件中断”以执行并退出。 + +您可以通过 :c:func:`in_irq()` 返回真来判断您处于硬件中断状态。 + +.. warning:: + + 请注意，如果中断被禁用，这将返回假阳性（见下文）。 + +软件中断上下文：软中断（Softirqs）与子任务（Tasklets） +------------------------------------------------------- + +当系统调用即将返回用户空间或硬件中断处理程序退出时，任何标记为挂起（通常通 +过硬件中断）的“软件中断”将运行（ ``kernel/softirq.c`` ）。 + +此处完成了许多真正的中断处理工作。在向SMP过渡的早期，只有“bottom halves下半 +部”（BHs）机制，无法利用多个CPU的优势。在从那些一团糟的就电脑切换过来后不久， +我们放弃了这个限制，转而使用“软中断”。 + +``include/linux/interrupt.h`` 列出了不同的软中断。定时器软中断是一个非常重要 +的软中断（ ``include/linux/timer.h`` ）：您可以注册它以在给定时间后为您调用 +函数。 + +软中断通常是一个很难处理的问题，因为同一个软中断将同时在多个CPU上运行。因此， +子任务（ ``include/linux/interrupt.h`` ）更常用：它们是动态可注册的（意味着 +您可以拥有任意数量），并且它们还保证任何子任务都只能在一个CPU上运行，不同的 +子任务也可以同时运行。 + +.. warning:: + + “tasklet”这个名字是误导性的：它们与“任务”无关，可能更多与当时 + 阿列克谢·库兹涅佐夫享用的糟糕伏特加有关。 + +你可以使用 :c:func:`in_softirq()` 宏（ ``include/linux/preempt.h`` ）来确认 +是否处于软中断（或子任务）中。 + +.. warning:: + + 注意，如果持有 :ref:`bottom half lock <local_bh_disable_zh>` 锁，这将返回 + 假阳性。 + +一些基本规则 +================ + +缺少内存保护 + 如果你损坏了内存，无论是在用户上下文还是中断上下文中，整个机器都会崩溃。 + 你确定你不能在用户空间里做你想做的事吗？ + +缺少浮点或MMX + FPU上下文不会被保存；即使在用户上下文中，FPU状态也可能与当前进程不一致： + 您会弄乱某些用户进程的FPU状态。如果真的要这样做，就必须显式地保存/恢复 + 完整的FPU状态（并避免上下文切换）。这通常不是个好主意；请优先用定点算法。 + +严格的堆栈限制 + 对于大多数32位体系结构，根据配置选项的不同内核堆栈大约为3K到6K；对于大 + 多数64位机器，内核堆栈大约为14K，并且经常与中断共享，因此你无法使用全部。 + 应避免深度递归和栈上的巨型本地数组（用动态分配它们来代替）。 + +Linux内核是可移植的 + 就这样吧。您的代码应该是纯64位的，并且不依赖于字节序（endian）。您还应该 + 尽量减少CPU特定的东西，例如内联汇编（inline assembly）应该被干净地封装和 + 最小化以便于移植。一般来说，它应该局限于内核树中有体系结构依赖的部分。 + +输入输出控制（ioctls）：避免编写新的系统调用 +============================================== + +系统调用（system call）通常看起来像这样:: + + asmlinkage long sys_mycall(int arg) + { + return 0; + } + + +首先，在大多数情况下，您无需创建新的系统调用。创建一个字符设备并为其实现适当 +的输入输出控制（ioctls）。这比系统调用灵活得多，不必写进每个体系结构的 +``include/asm/unistd.h`` 和 ``arch/kernel/entry.S`` 文件里，而且更容易被Linus +接受。 + +如果您的程序所做的只是读取或写入一些参数，请考虑实现 :c:func:`sysfs()` 接口。 + +在输入输出控制中，您处于进程的用户上下文。出现错误时，返回一个负的错误参数 +（errno，请参阅 ``include/uapi/asm-generic/errno-base.h`` 、 +``include/uapi/asm-generic/errno.h`` 和 ``include/linux/errno.h`` ），否则返 +回0。 + +在睡眠之后，您应该检查是否出现了信号：Unix/Linux处理信号的方法是暂时退出系统 +调用，并返回 ``-ERESTARTSYS`` 错误。系统调用入口代码将切换回用户上下文，处理 +信号处理程序，然后系统调用将重新启动（除非用户禁用了该功能）。因此，您应该准 +备好处理重新启动，例如若您处理某些数据结构到一半。 + +:: + + if (signal_pending(current)) + return -ERESTARTSYS; + + +如果你要做更长时间的计算：优先考虑用户空间。如果你真的想在内核中做这件事，你 +应该定期检查你是否需要让出CPU（请记得每个CPU都有协作多任务）。 +习惯用法:: + + cond_resched(); /* Will sleep */ + + +接口设计的小注释：UNIX系统调用的格言是“提供机制而不是策略 +Provide mechanism not policy”。 + +死锁的“配方” +==================== + +您不能调用任何可能睡眠的程序，除非： + +- 您处于用户上下文中。 + +- 你未拥有任何自旋锁。 + +- 您已经启用中断（实际上，Andi Kleen说调度代码将为您启用它们，但这可能不是 + 您想要的）。 + +注意，有些函数可能隐式地睡眠：常见的是用户空间访问函数（\*_user）和没有 +``GFP_ATOMIC`` 的内存分配函数。 + +您应该始终打开 ``CONFIG_DEBUG_ATOMIC_SLEEP`` 项来编译内核，如果您违反这些 +规则，它将警告您。如果你 **真的** 违反了规则，你最终会锁住你的电脑。 + +真的会这样。 + + +常用函数/程序 +=============== + +:c:func:`printk()` +------------------ + +定义于 ``include/linux/printk.h`` + +:c:func:`printk()` 将内核消息提供给控制台、dmesg和syslog守护进程。它对于调 +试和报告错误很有用，并且可以在中断上下文中使用，但是使用时要小心：如果机器 +的控制台中充斥着printk消息则会无法使用。它使用与ANSI C printf基本兼容的格式 +字符串，并通过C字符串串联为其提供第一个“优先”参数:: + + printk(KERN_INFO "i = %u\n", i); + + +参见 ``include/linux/kern_levels.h`` ；了解其他 ``KERN_`` 值；syslog将这些值 +解释为级别。特殊用法：打印IP地址使用:: + + __be32 ipaddress; + printk(KERN_INFO "my ip: %pI4\n", &ipaddress); + + +:c:func:`printk()` 内部使用的1K缓冲区，不捕获溢出。请确保足够使用。 + +.. note:: + + 当您开始在用户程序中将printf打成printk时，就知道自己是真正的内核程序员了 + :) + +.. note:: + + 另一个注释：最初的unix第六版源代码在其printf函数的顶部有一个注释：“printf + 不应该用于叽叽喳喳”。你也应该遵循此建议。 + +:c:func:`copy_to_user()` / :c:func:`copy_from_user()` / :c:func:`get_user()` / :c:func:`put_user()` +--------------------------------------------------------------------------------------------------- + +定义于 ``include/linux/uaccess.h`` / ``asm/uaccess.h`` + +**[睡眠]** + +:c:func:`put_user()` 和 :c:func:`get_user()` 用于从用户空间中获取和向用户空 +间中传出单个值（如int、char或long）。指向用户空间的指针永远不应该直接取消 +引用：应该使用这些程序复制数据。两者都返回 ``-EFAULT`` 或 0。 + +:c:func:`copy_to_user()` 和 :c:func:`copy_from_user()` 更通用：它们从/向用户 +空间复制任意数量的数据。 + +.. warning:: + + 与 :c:func:`put_user()` 和 :c:func:`get_user()` 不同，它们返回未复制的 + 数据量（即0仍然意味着成功）。 + +【是的，这个愚蠢的接口真心让我尴尬。火爆的口水仗大概每年都会发生。 +—— Rusty Russell】 + +这些函数可以隐式睡眠。它不应该在用户上下文之外调用（没有意义）、调用时禁用中断 +或获得自旋锁。 + +:c:func:`kmalloc()`/:c:func:`kfree()` +------------------------------------- + +定义于 ``include/linux/slab.h`` + +**[可能睡眠：见下]** + +这些函数用于动态请求指针对齐的内存块，类似用户空间中的malloc和free，但 +:c:func:`kmalloc()` 需要额外的标志词。重要的值： + +``GFP_KERNEL`` + 可以睡眠和交换以释放内存。只允许在用户上下文中使用，但这是分配内存最可靠 + 的方法。 + +``GFP_ATOMIC`` + 不会睡眠。较 ``GFP_KERNEL`` 更不可靠，但可以从中断上下文调用。你 **应该** + 有一个很好的内存不足错误处理策略。 + +``GFP_DMA`` + 分配低于16MB的ISA DMA。如果你不知道那是什么，那你就不需要了。非常不可靠。 + +如果您看到一个从无效上下文警告消息调用的睡眠的函数，那么您可能在没有 +``GFP_ATOMIC`` 的情况下从中断上下文调用了一个睡眠的分配函数。你必须立即修复， +快点！ + +如果你要分配至少 ``PAGE_SIZE`` （ ``asm/page.h`` 或 ``asm/page_types.h`` ） +字节，请考虑使用 :c:func:`__get_free_pages()` （ ``include/linux/gfp.h`` ）。 +它采用顺序参数（0表示页面大小，1表示双页，2表示四页……）和与上述相同的内存 +优先级标志字。 + +如果分配的字节数超过一页，可以使用 :c:func:`vmalloc()` 。它将在内核映射中分 +配虚拟内存。此块在物理内存中不是连续的，但是MMU（内存管理单元）使它看起来像 +是为您准备好的连续空间（因此它只是看起来对cpu连续，对外部设备驱动程序则不然）。 +如果您真的需要为一些奇怪的设备提供大量物理上连续的内存，那么您就会遇到问题： +Linux对此支持很差，因为正在运行的内核中的内存碎片化会使它变得很困难。最好的 +方法是在引导过程的早期通过 :c:func:`alloc_bootmem()` 函数分配。 + +在创建自己的常用对象缓存之前，请考虑使用 ``include/linux/slab.h`` 中的slab +缓存。 + +:c:macro:`current` +------------------ + +定义于 ``include/asm/current.h`` + +此全局变量（其实是宏）包含指向当前任务结构（task structure）的指针，因此仅在 +用户上下文中有效。例如，当进程进行系统调用时，这将指向调用进程的任务结构。 +在中断上下文中不为空（**not NULL**）。 + +:c:func:`mdelay()`/:c:func:`udelay()` +------------------------------------- + +定义于 ``include/asm/delay.h`` / ``include/linux/delay.h`` + +:c:func:`udelay()` 和 :c:func:`ndelay()` 函数可被用于小暂停。不要对它们使用 +大的值，因为这样会导致溢出——帮助函数 :c:func:`mdelay()` 在这里很有用，或者 +考虑 :c:func:`msleep()`。 + +:c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()` +----------------------------------------------------------------------------------------------- + +定义于 ``include/asm/byteorder.h`` + +:c:func:`cpu_to_be32()` 系列函数（其中“32”可以替换为64或16，“be”可以替换为 +“le”）是在内核中进行字节序转换的常用方法：它们返回转换后的值。所有的变体也 +提供反向转换函数： +:c:func:`be32_to_cpu()` 等。 + +这些函数有两个主要的变体：指针变体，例如 :c:func:`cpu_to_be32p()` ，它获取 +指向给定类型的指针，并返回转换后的值。另一个变体是“in-situ”系列，例如 +:c:func:`cpu_to_be32s()` ，它转换指针引用的值，并返回void。 + +:c:func:`local_irq_save()`/:c:func:`local_irq_restore()` +-------------------------------------------------------- + +定义于 ``include/linux/irqflags.h`` + + +这些程序禁用本地CPU上的硬中断，并还原它们。它们是可重入的；在其一个 +``unsigned long flags`` 参数中保存以前的状态。如果您知道中断已启用，那么可 +直接使用 :c:func:`local_irq_disable()` 和 :c:func:`local_irq_enable()`。 + +.. _local_bh_disable_zh: + +:c:func:`local_bh_disable()`/:c:func:`local_bh_enable()` +-------------------------------------------------------- + +定义于 ``include/linux/bottom_half.h`` + + +这些程序禁用本地CPU上的软中断，并还原它们。它们是可重入的；如果之前禁用了 +软中断，那么在调用这对函数之后仍然会禁用它们。它们阻止软中断和子任务在当前 +CPU上运行。 + +:c:func:`smp_processor_id()` +---------------------------- + +定义于 ``include/linux/smp.h`` + +:c:func:`get_cpu()` 禁用抢占（这样您就不会突然移动到另一个cpu）并返回当前 +处理器号，介于0和 ``NR_CPUS`` 之间。请注意，CPU编号不一定是连续的。完成后， +使用 :c:func:`put_cpu()` 再次返回。 + +如果您知道您不能被另一个任务抢占（即您处于中断上下文中，或已禁用抢占），您 +可以使用 :c:func:`smp_processor_id()`。 + +``__init``/``__exit``/``__initdata`` +------------------------------------ + +定义于 ``include/linux/init.h`` + +引导之后，内核释放一个特殊的部分；用 ``__init`` 标记的函数和用 ``__initdata`` +标记的数据结构在引导完成后被丢弃：同样地，模块在初始化后丢弃此内存。 +``__exit`` 用于声明只在退出时需要的函数：如果此文件未编译为模块，则该函数将 +被删除。请参阅头文件以使用。请注意，使用 :c:func:`EXPORT_SYMBOL()` 或 +:c:func:`EXPORT_SYMBOL_GPL()` 将标记为 ``__init`` 的函数导出到模块是没有意义 +的——这将出问题。 + + +:c:func:`__initcall()`/:c:func:`module_init()` +---------------------------------------------- + +定义于 ``include/linux/init.h`` / ``include/linux/module.h`` + +内核的许多部分都作为模块（内核的可动态加载部分）良好服务。使用 +:c:func:`module_init()` 和 :c:func:`module_exit()` 宏可以简化代码编写，无需 +``#ifdef`` ，即可以作为模块运行或内置在内核中。 + +:c:func:`module_init()` 宏定义在模块插入时（如果文件编译为模块）或在引导时 +调用哪个函数：如果文件未编译为模块，:c:func:`module_init()` 宏将等效于 +:c:func:`__initcall()` ，它通过链接器的魔力确保在引导时调用该函数。 + +该函数可以返回一个错误值，以导致模块加载失败（不幸的是，如果将模块编译到内核 +中，则此操作无效）。此函数在启用中断的用户上下文中调用，因此可以睡眠。 + +:c:func:`module_exit()` +----------------------- + + +定义于 ``include/linux/module.h`` + +这个宏定义了在模块删除时要调用的函数（如果是编译到内核中的文件，则无用武之地）。 +只有在模块使用计数到零时才会调用它。这个函数也可以睡眠，但不能失败：当它返回 +时，所有的东西都必须清理干净。 + +注意，这个宏是可选的：如果它不存在，您的模块将不可移除（除非 ``rmmod -f`` ）。 + +:c:func:`try_module_get()`/:c:func:`module_put()` +------------------------------------------------- + +定义于 ``include/linux/module.h`` + +这些函数会操作模块使用计数，以防止删除（如果另一个模块使用其导出的符号之一， +则无法删除模块，参见下文）。在调用模块代码之前，您应该在该模块上调用 +:c:func:`try_module_get()` ：若失败，那么该模块将被删除，您应该将其视为不存在。 +若成功，您就可以安全地进入模块，并在完成后调用模块 :c:func:`module_put()` 。 + +大多数可注册结构体都有所有者字段，例如在 +:c:type:`struct file_operations <file_operations>` 结构体中，此字段应设置为 +宏 ``THIS_MODULE`` 。 + +等待队列 ``include/linux/wait.h`` +==================================== + +**[睡眠]** + +等待队列用于等待某程序在条件为真时唤醒另一程序。必须小心使用，以确保没有竞争 +条件。先声明一个 :c:type:`wait_queue_head_t` ，然后对希望等待该条件的进程声明 +一个关于它们自己的 :c:type:`wait_queue_entry_t` ，并将其放入队列中。 + +声明 +----- + +使用 :c:func:`DECLARE_WAIT_QUEUE_HEAD()` 宏声明一个 ``wait_queue_head_t`` ， +或者在初始化代码中使用 :c:func:`init_waitqueue_head()` 程序。 + +排队 +----- + +将自己放在等待队列中相当复杂，因为你必须在检查条件之前将自己放入队列中。有一 +个宏可以来执行此操作： :c:func:`wait_event_interruptible()` +（ ``include/linux/wait.h`` ）第一个参数是等待队列头，第二个参数是计算的表达 +式；当该表达式为true时宏返回0，或者在接收到信号时返回 ``-ERESTARTSYS`` 。 +:c:func:`wait_event()` 版本会忽略信号。 + +唤醒排队任务 +------------- + +调用 :c:func:`wake_up()` （ ``include/linux/wait.h`` ），它将唤醒队列中的所有 +进程。例外情况：如果有一个进程设置了 ``TASK_EXCLUSIVE`` ，队列的其余部分将不 +会被唤醒。这个基本函数的其他变体也可以在同一个头文件中使用。 + +原子操作 +========= + +某些操作在所有平台上都有保证。第一类为操作 :c:type:`atomic_t` +（ ``include/asm/atomic.h`` ）的函数；它包含一个有符号整数（至少32位长）， +您必须使用这些函数来操作或读取 :c:type:`atomic_t` 变量。 +:c:func:`atomic_read()` 和 :c:func:`atomic_set()` 获取并设置计数器，还有 +:c:func:`atomic_add()` ，:c:func:`atomic_sub()` ，:c:func:`atomic_inc()` ， +:c:func:`atomic_dec()` 和 :c:func:`atomic_dec_and_test()` （如果递减为零， +则返回true）。 + +是的。它在原子变量为零时返回true（即!=0）。 + +请注意，这些函数比普通的算术运算速度慢，因此不应过度使用。 + +第二类原子操作是在 ``unsigned long`` （ ``include/linux/bitops.h`` ）上的 +原子位操作。这些操作通常采用指向位模式（bit pattern）的指针，第0位是最低有效 +位。:c:func:`set_bit()`，:c:func:`clear_bit()` 和 :c:func:`change_bit()` 设置、 +清除和更改给定位。:c:func:`test_and_set_bit()` ，:c:func:`test_and_clear_bit()` +和 :c:func:`test_and_change_bit()` 执行相同的操作，但如果之前设置了位，则返回 +true；这些对于原子设置标志特别有用。 + +可以使用大于 ``BITS_PER_LONG`` 位的位索引调用这些操作。但结果在大端序平台上 +不太正常，所以最好不要这样做。 + +符号 +===== + +在内核内部，正常的链接规则仍然适用（即除非用static关键字将符号声明为文件范围， +否则它可以在内核中的任何位置使用）。但是对于模块，会保留一个特殊可导出符号表， +该表将入口点限制为内核内部。模块也可以导出符号。 + +:c:func:`EXPORT_SYMBOL()` +------------------------- + +定义于 ``include/linux/export.h`` + +这是导出符号的经典方法：动态加载的模块将能够正常使用符号。 + +:c:func:`EXPORT_SYMBOL_GPL()` +----------------------------- + +定义于 ``include/linux/export.h`` + + +类似于 :c:func:`EXPORT_SYMBOL()`，只是 :c:func:`EXPORT_SYMBOL_GPL()` 导出的 +符号只能由具有由 :c:func:`MODULE_LICENSE()` 指定GPL兼容许可证的模块看到。这 +意味着此函数被认为是一个内部实现问题，而不是一个真正的接口。一些维护人员和 +开发人员在添加一些新的API或功能时可能却需要导出 EXPORT_SYMBOL_GPL()。 + +:c:func:`EXPORT_SYMBOL_NS()` +---------------------------- + +定义于 ``include/linux/export.h`` + +这是 ``EXPORT_SYMBOL()`` 的变体，允许指定符号命名空间。符号名称空间记录于 +Documentation/core-api/symbol-namespaces.rst 。 + +:c:func:`EXPORT_SYMBOL_NS_GPL()` +-------------------------------- + +定义于 ``include/linux/export.h`` + +这是 ``EXPORT_SYMBOL_GPL()`` 的变体，允许指定符号命名空间。符号名称空间记录于 +Documentation/core-api/symbol-namespaces.rst 。 + +程序与惯例 +=========== + +双向链表 ``include/linux/list.h`` +----------------------------------- + +内核头文件中曾经有三组链表程序，但这一组是赢家。如果你对一个单链表没有特别迫切的 +需求，那么这是一个不错的选择。 + +通常 :c:func:`list_for_each_entry()` 很有用。 + +返回值惯例 +------------ + +对于在用户上下文中调用的代码，违背C语言惯例是很常见的，即返回0表示成功，返回 +负错误值（例如 ``-EFAULT`` ）表示失败。这在一开始可能是不直观的，但在内核中 +相当普遍。 + +使用 :c:func:`ERR_PTR()` （ ``include/linux/err.h`` ）将负错误值编码到指针中， +然后使用 :c:func:`IS_ERR()` 和 :c:func:`PTR_ERR()` 将其再取出：避免为错误值 +使用单独的指针参数。挺讨厌的，但的确是个好方式。 + +破坏编译 +---------- + +Linus和其他开发人员有时会更改开发内核中的函数或结构体名称；这样做不仅是为了 +让每个人都保持警惕，还反映了一个重大的更改（例如，不能再在打开中断的情况下 +调用，或者执行额外的检查，或者不执行以前捕获的检查）。通常这会附带一个linux +内核邮件列表中相当全面的注释；请搜索存档以查看。简单地对文件进行全局替换通常 +会让事情变得 **更糟** 。 + +初始化结构体成员 +------------------ + +初始化结构体的首选方法是使用指定的初始化器，如ISO C99所述。 +例如:: + + static struct block_device_operations opt_fops = { + .open = opt_open, + .release = opt_release, + .ioctl = opt_ioctl, + .check_media_change = opt_media_change, + }; + + +这使得很容易查找（grep），并且可以清楚地看到设置了哪些结构字段。你应该这样做， +因为它看起来很酷。 + +GNU 扩展 +---------- + +Linux内核中明确允许GNU扩展。请注意，由于缺乏通用性，一些更复杂的版本并没有 +得到很好的支持，但以下内容被认为是标准的（有关更多详细信息，请参阅GCC info页 +的“C 扩展”部分——是的，实际上是info页，手册页只是info中内容的简短摘要）。 + +- 内联函数 + +- 语句表达式（Statement expressions）（即（{ 和 }）结构）。 + + +- 声明函数/变量/类型的属性（__attribute__） + +- typeof + +- 零长度数组 + +- 宏变量 + +- 空指针运算 + +- 非常量（Non-Constant）初始化程序 + +- 汇编程序指令（在 arch/ 和 include/asm/ 之内） + +- 字符串函数名（__func__）。 + +- __builtin_constant_p() + +在内核中使用long long时要小心，gcc为其生成的代码非常糟糕：除法和乘法在i386上 +不能工作，因为内核环境中缺少用于它的gcc运行时函数。 + +C++ +--- + +在内核中使用C++通常是个坏主意，因为内核不提供必要的运行时环境，并且不为其 +测试包含文件。不过这仍然是可能的，但不建议。如果你真的想这么做，至少别用 +异常处理（exceptions）。 + +#if +--- + +通常认为，在头文件（或.c文件顶部）中使用宏来抽象函数比在源代码中使用“if”预 +处理器语句更干净。 + +把你的东西放进内核里 +====================== + +为了让你的东西更正式、补丁更整洁，还有一些工作要做： + +- 搞清楚你在谁的地界儿上干活。查看源文件的顶部、 ``MAINTAINERS`` 文件以及 + ``CREDITS`` 文件的最后一部分。你应该和此人协调，确保你没有重新发明轮子， + 或者尝试一些已经被拒绝的东西。 + + 确保你把你的名字和电子邮件地址放在你创建或修改的任何文件的顶部。当人们发 + 现一个缺陷，或者想要做出修改时，这是他们首先会看的地方。 + +- 通常你需要一个配置选项来支持你的内核编程。在适当的目录中编辑 ``Kconfig`` 。 + 配置语言很容易通过剪切和粘贴来使用，在 + Documentation/kbuild/kconfig-language.rst 中有完整的文档。 + + 在您对选项的描述中，请确保同时照顾到了专家用户和对此功能一无所知的用户。 + 在此说明任何不兼容和问题。结尾一定要写上“如有疑问，就选N”（或者是“Y”）； + 这是针对那些看不懂你在说什么的人的。 + +- 编辑 ``Makefile`` ：配置变量在这里导出，因此通常你只需添加一行 + “obj-$(CONFIG_xxx) += xxx.o”。语法记录在 + Documentation/kbuild/makefiles.rst 。 + +- 如果你做了一些有意义的事情，那可以把自己放进 ``CREDITS`` ，通常不止一个 + 文件（无论如何你的名字都应该在源文件的顶部）。维护人员意味着您希望在对 + 子系统进行更改时得到询问，并了解缺陷；这意味着对某部分代码做出更多承诺。 + +- 最后，别忘记去阅读 Documentation/process/submitting-patches.rst ， + 也许还有 Documentation/process/submitting-drivers.rst 。 + +Kernel 仙女棒 +=============== + +浏览源代码时的一些收藏。请随意添加到此列表。 + +``arch/x86/include/asm/delay.h``:: + + #define ndelay(n) (__builtin_constant_p(n) ? \ + ((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \ + __ndelay(n)) + + +``include/linux/fs.h``:: + + /* + * Kernel pointers have redundant information, so we can use a + * scheme where we can return either an error code or a dentry + * pointer with the same return value. + * + * This should be a per-architecture thing, to allow different + * error and pointer decisions. + */ + #define ERR_PTR(err) ((void *)((long)(err))) + #define PTR_ERR(ptr) ((long)(ptr)) + #define IS_ERR(ptr) ((unsigned long)(ptr) > (unsigned long)(-1000)) + +``arch/x86/include/asm/uaccess_32.h:``:: + + #define copy_to_user(to,from,n) \ + (__builtin_constant_p(n) ? \ + __constant_copy_to_user((to),(from),(n)) : \ + __generic_copy_to_user((to),(from),(n))) + + +``arch/sparc/kernel/head.S:``:: + + /* + * Sun people can't spell worth damn. "compatibility" indeed. + * At least we *know* we can't spell, and use a spell-checker. + */ + + /* Uh, actually Linus it is I who cannot spell. Too much murky + * Sparc assembly will do this to ya. + */ + C_LABEL(cputypvar): + .asciz "compatibility" + + /* Tested on SS-5, SS-10. Probably someone at Sun applied a spell-checker. */ + .align 4 + C_LABEL(cputypvar_sun4m): + .asciz "compatible" + + +``arch/sparc/lib/checksum.S:``:: + + /* Sun, you just can't beat me, you just can't. Stop trying, + * give up. I'm serious, I am going to kick the living shit + * out of you, game over, lights out. + */ + + +致谢 +===== + +感谢Andi Kleen提出点子，回答我的问题，纠正我的错误，充实内容等帮助。 +感谢Philipp Rumpf做了许多拼写和清晰度修复，以及一些优秀的不明显的点。 +感谢Werner Almesberger对 :c:func:`disable_irq()` 做了一个很好的总结， +Jes Sorensen和Andrea Arcangeli补充了一些注意事项。 +感谢Michael Elizabeth Chastain检查并补充了配置部分。 +感谢Telsa Gwynne教我DocBook。 diff --git a/Documentation/translations/zh_CN/kernel-hacking/index.rst b/Documentation/translations/zh_CN/kernel-hacking/index.rst new file mode 100644 index 000000000000..df530de2278d --- /dev/null +++ b/Documentation/translations/zh_CN/kernel-hacking/index.rst @@ -0,0 +1,22 @@ +.. _kernel_hacking_zh: + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/kernel-hacking/index.rst + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +============= +内核骇客指南 +============= + +.. toctree:: + :maxdepth: 2 + + hacking + +TODO + +- locking diff --git a/Documentation/translations/zh_CN/openrisc/index.rst b/Documentation/translations/zh_CN/openrisc/index.rst new file mode 100644 index 000000000000..d722642796c8 --- /dev/null +++ b/Documentation/translations/zh_CN/openrisc/index.rst @@ -0,0 +1,30 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../openrisc/index` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_openrisc_index: + + +================= +OpenRISC 体系架构 +================= + +.. toctree:: + :maxdepth: 2 + + openrisc_port + todo + +Todolist: + features + + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/openrisc/openrisc_port.rst b/Documentation/translations/zh_CN/openrisc/openrisc_port.rst new file mode 100644 index 000000000000..e87d0eec281d --- /dev/null +++ b/Documentation/translations/zh_CN/openrisc/openrisc_port.rst @@ -0,0 +1,124 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../openrisc/openrisc_port` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_openrisc_port: + +============== +OpenRISC Linux +============== + +这是Linux对OpenRISC类微处理器的移植；具体来说，最早移植目标是32位 +OpenRISC 1000系列（或1k）。 + +关于OpenRISC处理器和正在进行中的开发的信息: + + ======= ============================= + 网站 https://openrisc.io + 邮箱 openrisc@lists.librecores.org + ======= ============================= + +--------------------------------------------------------------------- + +OpenRISC工具链和Linux的构建指南 +=============================== + +为了构建和运行Linux for OpenRISC，你至少需要一个基本的工具链，或许 +还需要架构模拟器。 这里概述了准备就位这些部分的步骤。 + +1) 工具链 + +工具链二进制文件可以从openrisc.io或我们的github发布页面获得。不同 +工具链的构建指南可以在openrisc.io或Stafford的工具链构建和发布脚本 +中找到。 + + ====== ================================================= + 二进制 https://github.com/openrisc/or1k-gcc/releases + 工具链 https://openrisc.io/software + 构建 https://github.com/stffrdhrn/or1k-toolchain-build + ====== ================================================= + +2) 构建 + +像往常一样构建Linux内核:: + + make ARCH=openrisc CROSS_COMPILE="or1k-linux-" defconfig + make ARCH=openrisc CROSS_COMPILE="or1k-linux-" + +3) 在FPGA上运行（可选) + +OpenRISC社区通常使用FuseSoC来管理构建和编程SoC到FPGA中。 下面是用 +OpenRISC SoC对De0 Nano开发板进行编程的一个例子。 在构建过程中， +FPGA RTL是从FuseSoC IP核库中下载的代码，并使用FPGA供应商工具构建。 +二进制文件用openocd加载到电路板上。 + +:: + + git clone https://github.com/olofk/fusesoc + cd fusesoc + sudo pip install -e . + + fusesoc init + fusesoc build de0_nano + fusesoc pgm de0_nano + + openocd -f interface/altera-usb-blaster.cfg \ + -f board/or1k_generic.cfg + + telnet localhost 4444 + > init + > halt; load_image vmlinux ; reset + +4) 在模拟器上运行（可选） + +QEMU是一个处理器仿真器，我们推荐它来模拟OpenRISC平台。 请按照QEMU网 +站上的OpenRISC说明，让Linux在QEMU上运行。 你可以自己构建QEMU，但你的 +Linux发行版可能提供了支持OpenRISC的二进制包。 + + ============= ====================================================== + qemu openrisc https://wiki.qemu.org/Documentation/Platforms/OpenRISC + ============= ====================================================== + +--------------------------------------------------------------------- + +术语表 +====== + +代码中使用了以下符号约定以将范围限制在几个特定处理器实现上： + +========= ======================= +openrisc: OpenRISC类型处理器 +or1k: OpenRISC 1000系列处理器 +or1200: OpenRISC 1200处理器 +========= ======================= + +--------------------------------------------------------------------- + +历史 +==== + +2003-11-18 Matjaz Breskvar (phoenix@bsemi.com) + 将linux初步移植到OpenRISC或32架构。 + 所有的核心功能都实现了，并且可以使用。 + +2003-12-08 Matjaz Breskvar (phoenix@bsemi.com) + 彻底改变TLB失误处理。 + 重写异常处理。 + 在默认的initrd中实现了sash-3.6的所有功能。 + 大幅改进的版本。 + +2004-04-10 Matjaz Breskvar (phoenix@bsemi.com) + 大量的bug修复。 + 支持以太网，http和telnet服务器功能。 + 可以运行许多标准的linux应用程序。 + +2004-06-26 Matjaz Breskvar (phoenix@bsemi.com) + 移植到2.6.x。 + +2004-11-30 Matjaz Breskvar (phoenix@bsemi.com) + 大量的bug修复和增强功能。 + 增加了opencores framebuffer驱动。 + +2010-10-09 Jonas Bonn (jonas@southpole.se) + 重大重写，使其与上游的Linux 2.6.36看齐。 diff --git a/Documentation/translations/zh_CN/openrisc/todo.rst b/Documentation/translations/zh_CN/openrisc/todo.rst new file mode 100644 index 000000000000..9944ad05473b --- /dev/null +++ b/Documentation/translations/zh_CN/openrisc/todo.rst @@ -0,0 +1,20 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../openrisc/todo` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_openrisc_todo.rst: + +======== +待办事项 +======== + +OpenRISC Linux的移植已经完全投入使用，并且从 2.6.35 开始就一直在上游同步。 +然而，还有一些剩余的项目需要在未来几个月内完成。 下面是一个即将进行调查的已知 +不尽完美的项目列表，即我们的待办事项列表。 + +- 实现其余的DMA API……dma_map_sg等。 + +- 完成重命名清理工作……代码中提到了or32，这是架构的一个老名字。 我们 + 已经确定的名字是or1k，这个改变正在以缓慢积累的方式进行。 目前，or32相当 + 于or1k。 diff --git a/Documentation/translations/zh_CN/process/1.Intro.rst b/Documentation/translations/zh_CN/process/1.Intro.rst index 10a15f3dc282..4f9284cbe33b 100644 --- a/Documentation/translations/zh_CN/process/1.Intro.rst +++ b/Documentation/translations/zh_CN/process/1.Intro.rst @@ -1,162 +1,170 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/1.Intro.rst <development_process_intro>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> .. _cn_development_process_intro: -介绍 +引言 ==== -执行摘要 +内容提要 -------- -本节的其余部分涵盖了内核开发过程的范围，以及开发人员及其雇主在这方面可能遇 -到的各种挫折。内核代码应该合并到正式的（“主线”）内核中有很多原因，包括对用 -户的自动可用性、多种形式的社区支持以及影响内核开发方向的能力。提供给Linux -内核的代码必须在与GPL兼容的许可证下可用。 +本节的其余部分涵盖了内核开发的过程，以及开发人员及其雇主在这方面可能遇到的 +各种问题。有很多原因使内核代码应被合并到正式的（“主线”）内核中，包括对用户 +的自动可用性、多种形式的社区支持以及影响内核开发方向的能力。提供给Linux内核 +的代码必须在与GPL兼容的许可证下可用。 :ref:`cn_development_process` 介绍了开发过程、内核发布周期和合并窗口的机制。 -涵盖了补丁开发、审查和合并周期中的各个阶段。有一些关于工具和邮件列表的讨论。 -鼓励希望开始内核开发的开发人员作为初始练习跟踪并修复bug。 +涵盖了补丁开发、审查和合并周期中的各个阶段。还有一些关于工具和邮件列表的讨论？ +鼓励希望开始内核开发的开发人员跟踪并修复缺陷以作为初步练习。 -:ref:`cn_development_early_stage` 包括早期项目规划，重点是尽快让开发社区参与 +:ref:`cn_development_early_stage` 包括项目的早期规划，重点是尽快让开发社区 +参与进来。 -:ref:`cn_development_coding` 是关于编码过程的；讨论了其他开发人员遇到的几个 -陷阱。对补丁的一些要求已经涵盖，并且介绍了一些工具，这些工具有助于确保内核 +:ref:`cn_development_coding` 是关于编程过程的；介绍了其他开发人员遇到的几个 +陷阱。也涵盖了对补丁的一些要求，并且介绍了一些工具，这些工具有助于确保内核 补丁是正确的。 -:ref:`cn_development_posting` 讨论发布补丁以供评审的过程。为了让开发社区 -认真对待，补丁必须正确格式化和描述，并且必须发送到正确的地方。遵循本节中的 -建议有助于确保为您的工作提供最好的接纳。 +:ref:`cn_development_posting` 描述发布补丁以供评审的过程。为了让开发社区能 +认真对待，补丁必须被正确格式化和描述，并且必须发送到正确的地方。遵循本节中的 +建议有助于确保您的工作能被较好地接纳。 -:ref:`cn_development_followthrough` 介绍了发布补丁之后发生的事情；该工作 -在这一点上还远远没有完成。与审阅者一起工作是开发过程中的一个重要部分；本节 -提供了一些关于如何在这个重要阶段避免问题的提示。当补丁被合并到主线中时， -开发人员要注意不要假定任务已经完成。 +:ref:`cn_development_followthrough` 介绍了发布补丁之后发生的事情；工作在这时 +还远远没有完成。与审阅者一起工作是开发过程中的一个重要部分；本节提供了一些 +关于如何在这个重要阶段避免问题的提示。当补丁被合并到主线中时，开发人员要注意 +不要假定任务已经完成。 -:ref:`cn_development_advancedtopics` 介绍了两个“高级”主题： -使用Git管理补丁和查看其他人发布的补丁。 +:ref:`cn_development_advancedtopics` 介绍了两个“高级”主题：使用Git管理补丁 +和查看其他人发布的补丁。 -:ref:`cn_development_conclusion` 总结了有关内核开发的更多信息，附带有带有 -指向资源的链接. +:ref:`cn_development_conclusion` 总结了有关内核开发的更多信息，附带有相关资源 +链接。 -这个文件是关于什么的 +这个文档是关于什么的 -------------------- -Linux内核有超过800万行代码，每个版本的贡献者超过1000人，是现存最大、最活跃 -的免费软件项目之一。从1991年开始，这个内核已经发展成为一个最好的操作系统 -组件，运行在袖珍数字音乐播放器、台式PC、现存最大的超级计算机以及所有类型的 -系统上。它是一种适用于几乎任何情况的健壮、高效和可扩展的解决方案。 +Linux内核有超过800万行代码，每个版本的贡献者超过1000人，是现存最大、最活跃的 +免费软件项目之一。从1991年开始，这个内核已经发展成为一个最好的操作系统组件， +运行在袖珍数字音乐播放器、台式电脑、现存最大的超级计算机以及所有类型的系统上。 +它是一种适用于几乎任何情况的健壮、高效和可扩展的解决方案。 随着Linux的发展，希望参与其开发的开发人员（和公司）的数量也在增加。硬件供应商 希望确保Linux能够很好地支持他们的产品，使这些产品对Linux用户具有吸引力。嵌入 式系统供应商使用Linux作为集成产品的组件，希望Linux能够尽可能地胜任手头的任务。 -分销商和其他基于Linux的软件供应商对Linux内核的功能、性能和可靠性有着明确的 -兴趣。最终用户也常常希望修改Linux，使之更好地满足他们的需求。 +分销商和其他基于Linux的软件供应商切实关心Linux内核的功能、性能和可靠性。最终 +用户也常常希望修改Linux，使之能更好地满足他们的需求。 Linux最引人注目的特性之一是这些开发人员可以访问它；任何具备必要技能的人都可以 改进Linux并影响其开发方向。专有产品不能提供这种开放性，这是自由软件的一个特点。 -但是，如果有什么不同的话，内核比大多数其他自由软件项目更开放。一个典型的三个月 -内核开发周期可以涉及1000多个开发人员，他们为100多个不同的公司 -（或者根本没有公司）工作。 +如果有什么不同的话，那就是内核比大多数其他自由软件项目更开放。一个典型的三个 +月内核开发周期可以涉及1000多个开发人员，他们为100多个不同的公司（或者根本不 +隶属公司）工作。 -与内核开发社区合作并不是特别困难。但是，尽管如此，许多潜在的贡献者在尝试做 -内核工作时遇到了困难。内核社区已经发展了自己独特的操作方式，使其能够在每天 +与内核开发社区合作并不是特别困难。但尽管如此，仍有许多潜在的贡献者在尝试做 +内核工作时遇到了困难。内核社区已经发展出自己独特的操作方式，使其能够在每天 都要更改数千行代码的环境中顺利运行（并生成高质量的产品）。因此，Linux内核开发 -过程与专有的开发方法有很大的不同也就不足为奇了。 +过程与专有的开发模式有很大的不同也就不足为奇了。 -对于新开发人员来说，内核的开发过程可能会让人感到奇怪和恐惧，但这个背后有充分的 -理由和坚实的经验。一个不了解内核社区的方式的开发人员（或者更糟的是，他们试图 -抛弃或规避内核社区的方式）会有一个令人沮丧的体验。开发社区, 在帮助那些试图学习 -的人的同时，没有时间帮助那些不愿意倾听或不关心开发过程的人。 +对于新开发人员来说，内核的开发过程可能会让人感到奇怪和恐惧，但这背后有充分的 +理由和坚实的经验。一个不了解内核社区工作方式的开发人员（或者更糟的是，他们 +试图抛弃或规避之）会得到令人沮丧的体验。开发社区在帮助那些试图学习的人的同时， +没有时间帮助那些不愿意倾听或不关心开发过程的人。 -希望阅读本文的人能够避免这种令人沮丧的经历。这里有很多材料，但阅读时所做的 +希望阅读本文的人能够避免这种令人沮丧的经历。这些材料很长，但阅读它们时所做的 努力会在短时间内得到回报。开发社区总是需要能让内核变更好的开发人员；下面的 -文本应该帮助您或为您工作的人员加入我们的社区。 +文字应该帮助您或为您工作的人员加入我们的社区。 致谢 ---- -本文件由Jonathan Corbet撰写，corbet@lwn.net。以下人员的建议使之更为完善： +本文档由Jonathan Corbet <corbet@lwn.net> 撰写。以下人员的建议使之更为完善： Johannes Berg, James Berry, Alex Chiang, Roland Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh, Amanda McPherson, -Andrew Morton, Andrew Price, Tsugikazu Shibata, 和 Jochen Voß. +Andrew Morton, Andrew Price, Tsugikazu Shibata 和 Jochen Voß 。 这项工作得到了Linux基金会的支持，特别感谢Amanda McPherson，他看到了这项工作 -的价值并把它变成现实。 +的价值并将其变成现实。 代码进入主线的重要性 -------------------- 有些公司和开发人员偶尔会想，为什么他们要费心学习如何与内核社区合作，并将代码 放入主线内核（“主线”是由Linus Torvalds维护的内核，Linux发行商将其用作基础）。 -在短期内，贡献代码看起来像是一种可以避免的开销；仅仅将代码分开并直接支持用户 +在短期内，贡献代码看起来像是一种可以避免的开销；维护独立代码并直接支持用户 似乎更容易。事实上，保持代码独立（“树外”）是在经济上是错误的。 -作为说明树外代码成本的一种方法，下面是内核开发过程的一些相关方面；本文稍后将 -更详细地讨论其中的大部分内容。考虑： +为了说明树外代码成本，下面给出内核开发过程的一些相关方面；本文稍后将更详细地 +讨论其中的大部分内容。请考虑： - 所有Linux用户都可以使用合并到主线内核中的代码。它将自动出现在所有启用它的 - 发行版上。不需要驱动程序磁盘、下载，也不需要为多个发行版的多个版本提供支持； - 对于开发人员和用户来说，这一切都是可行的。并入主线解决了大量的分布和支持问题 + 发行版上。无需驱动程序磁盘、额外下载，也不需要为多个发行版的多个版本提供 + 支持；这一切将方便所有开发人员和用户。并入主线解决了大量的分发和支持问题。 -- 当内核开发人员努力维护一个稳定的用户空间接口时，内部内核API处于不断变化之中. - 缺乏一个稳定的内部接口是一个深思熟虑的设计决策；它允许在任何时候进行基本的改 - 进，并产生更高质量的代码。但该策略的一个结果是，如果要使用新的内核，任何树外 - 代码都需要持续的维护。维护树外代码需要大量的工作才能使代码保持工作状态。 +- 当内核开发人员努力维护一个稳定的用户空间接口时，内核内部API处于不断变化之中。 + 不维持稳定的内部接口是一个慎重的设计决策；它允许在任何时候进行基本的改进， + 并产出更高质量的代码。但该策略导致结果是，若要使用新的内核，任何树外代码都 + 需要持续的维护。维护树外代码会需要大量的工作才能使代码保持正常运行。 - 相反，位于主线中的代码不需要这样做，因为一个简单的规则要求进行API更改的任何 - 开发人员也必须修复由于该更改而破坏的任何代码。因此，合并到主线中的代码大大 - 降低了维护成本。 + 相反，位于主线中的代码不需要这样做，因为基本规则要求进行API更改的任何开发 + 人员也必须修复由于该更改而破坏的任何代码。因此，合并到主线中的代码大大降低 + 了维护成本。 -- 除此之外，内核中的代码通常会被其他开发人员改进。令人惊讶的结果可能来自授权 - 您的用户社区和客户改进您的产品。 +- 除此之外，内核中的代码通常会被其他开发人员改进。您授权的用户社区和客户对您 + 产品的改进可能会令人惊喜。 -- 内核代码在合并到主线之前和之后都要经过审查。不管原始开发人员的技能有多强， +- 内核代码在合并到主线之前和之后都要经过审查。无论原始开发人员的技能有多强， 这个审查过程总是能找到改进代码的方法。审查经常发现严重的错误和安全问题。 - 这对于在封闭环境中开发的代码尤其如此；这种代码从外部开发人员的审查中获益 - 匪浅。树外代码是低质量代码。 + 对于在封闭环境中开发的代码尤其如此；这种代码从外部开发人员的审查中获益匪浅。 + 树外代码是低质量代码。 - 参与开发过程是您影响内核开发方向的方式。旁观者的抱怨会被听到，但是活跃的 开发人员有更强的声音——并且能够实现使内核更好地满足其需求的更改。 - 当单独维护代码时，总是存在第三方为类似功能提供不同实现的可能性。如果发生 - 这种情况，合并代码将变得更加困难——甚至到了不可能的地步。然后，您将面临以下 - 令人不快的选择：（1）无限期地维护树外的非标准特性，或（2）放弃代码并将用户 - 迁移到树内版本。 + 这种情况，合并代码将变得更加困难——甚至成为不可能。之后，您将面临以下令人 + 不快的选择：（1）无限期地维护树外的非标准特性，或（2）放弃代码并将用户迁移 + 到树内版本。 -- 代码的贡献是使整个过程工作的根本。通过贡献代码，您可以向内核添加新功能，并 - 提供其他内核开发人员使用的功能和示例。如果您已经为Linux开发了代码（或者 - 正在考虑这样做），那么您显然对这个平台的持续成功感兴趣；贡献代码是确保成功 - 的最好方法之一。 +- 代码的贡献是使整个流程工作的根本。通过贡献代码，您可以向内核添加新功能，并 + 提供其他内核开发人员使用的功能和示例。如果您已经为Linux开发了代码（或者正在 + 考虑这样做），那么您显然对这个平台的持续成功感兴趣；贡献代码是确保成功的 + 最好方法之一。 上述所有理由都适用于任何树外内核代码，包括以专有的、仅二进制形式分发的代码。 -然而，在考虑任何类型的纯二进制内核代码分布之前，还需要考虑其他因素。这些包括： +然而，在考虑任何类型的纯二进制内核代码分布之前，还需要考虑其他因素。包括： -- 围绕专有内核模块分发的法律问题充其量是模糊的；相当多的内核版权所有者认为， - 大多数仅限二进制的模块是内核的派生产品，因此，它们的分发违反了GNU通用公共 - 许可证（下面将详细介绍）。您的作者不是律师，本文档中的任何内容都不可能被 +- 围绕专有内核模块分发的法律问题其实较为模糊；相当多的内核版权所有者认为， + 大多数仅二进制的模块是内核的派生产品，因此，它们的分发违反了GNU通用公共 + 许可证（下面将详细介绍）。本文作者不是律师，本文档中的任何内容都不可能被 视为法律建议。封闭源代码模块的真实法律地位只能由法院决定。但不管怎样，困扰 这些模块的不确定性仍然存在。 - 二进制模块大大增加了调试内核问题的难度，以至于大多数内核开发人员甚至都不会 尝试。因此，只分发二进制模块将使您的用户更难从社区获得支持。 -- 对于只支持二进制的模块的发行者来说，支持也更加困难，他们必须为他们希望支持 - 的每个发行版和每个内核版本提供一个版本的模块。为了提供相当全面的覆盖范围， +- 对于仅二进制的模块的发行者来说，支持也更加困难，他们必须为他们希望支持的 + 每个发行版和每个内核版本提供不同版本的模块。为了提供较为全面的覆盖范围， 可能需要一个模块的几十个构建，并且每次升级内核时，您的用户都必须单独升级 - 您的模块。 + 这些模块。 -- 上面提到的关于代码评审的所有问题都更加存在于封闭源代码。由于该代码根本不可 - 用，因此社区无法对其进行审查，毫无疑问，它将存在严重问题。 +- 上面提到的关于代码评审的所有问题都更加存在于封闭源代码中。由于该代码根本 + 不可得，因此社区无法对其进行审查，毫无疑问，它将存在严重问题。 -尤其是嵌入式系统的制造商，可能会倾向于忽视本节中所说的大部分内容，因为他们 +尤其是嵌入式系统的制造商，可能会倾向于忽视本节中所说的大部分内容；因为他们 相信自己正在商用一种使用冻结内核版本的独立产品，在发布后不需要再进行开发。 这个论点忽略了广泛的代码审查的价值以及允许用户向产品添加功能的价值。但这些 -产品也有有限的商业寿命，之后必须发布新版本的产品。在这一点上，代码在主线上 -并得到良好维护的供应商将能够更好地占位，以使新产品快速上市。 +产品的商业寿命有限，之后必须发布新版本的产品。在这一点上，代码在主线上并得到 +良好维护的供应商将能够更好地占位，以使新产品快速上市。 许可 ---- @@ -164,23 +172,24 @@ Andrew Morton, Andrew Price, Tsugikazu Shibata, 和 Jochen Voß. 代码是根据一些许可证提供给Linux内核的，但是所有代码都必须与GNU通用公共许可 证（GPLV2）的版本2兼容，该版本是覆盖整个内核分发的许可证。在实践中，这意味 着所有代码贡献都由GPLv2（可选地，语言允许在更高版本的GPL下分发）或3子句BSD -许可（New BSD License, 译者注）覆盖。任何不包含在兼容许可证中的贡献都不会 +许可（New BSD License，译者注）覆盖。任何不包含在兼容许可证中的贡献都不会 被接受到内核中。 贡献给内核的代码不需要（或请求）版权分配。合并到主线内核中的所有代码都保留 其原始所有权；因此，内核现在拥有数千个所有者。 -这种所有权结构的一个暗示是，任何改变内核许可的尝试都注定会失败。很少有实际 -的场景可以获得所有版权所有者的同意（或者从内核中删除他们的代码）。因此，特 -别是，在可预见的将来，不可能迁移到GPL的版本3。 +这种所有权结构也暗示着，任何改变内核许可的尝试都注定会失败。很少有实际情况 +可以获得所有版权所有者的同意（或者从内核中删除他们的代码）。因此，尤其是在 +可预见的将来，许可证不大可能迁移到GPL的版本3。 -所有贡献给内核的代码都必须是合法的免费软件。因此，不接受匿名（或匿名）贡献 -者的代码。所有贡献者都需要在他们的代码上“sign off”，声明代码可以在GPL下与内 -核一起分发。无法提供未被其所有者许可为免费软件的代码，或可能为内核造成版权 -相关问题的代码（例如，由缺乏适当保护的反向工程工作派生的代码）不能被接受。 +所有贡献给内核的代码都必须是合法的免费软件。因此，不接受匿名（或化名）贡献 +者的代码。所有贡献者都需要在他们的代码上“sign off（签发）”，声明代码可以 +在GPL下与内核一起分发。无法提供未被其所有者许可为免费软件的代码，或可能为 +内核造成版权相关问题的代码（例如，由缺乏适当保护的反向工程工作派生的代码） +不能被接受。 -有关版权相关问题的问题在Linux开发邮件列表中很常见。这样的问题通常会得到不少 -答案，但要记住，回答这些问题的人不是律师，不能提供法律咨询。如果您有关于 -Linux源代码的法律问题，那么与了解该领域的律师交流是无法替代的。依靠从技术 -邮件列表中获得的答案是一件冒险的事情。 +有关版权问题的提问在Linux开发邮件列表中很常见。这样的问题通常会得到不少答案， +但请记住，回答这些问题的人不是律师，不能提供法律咨询。如果您有关于Linux源代码 +的法律问题，没有什么可以代替咨询了解这一领域的律师。依赖从技术邮件列表中获得 +的答案是一件冒险的事情。 diff --git a/Documentation/translations/zh_CN/process/2.Process.rst b/Documentation/translations/zh_CN/process/2.Process.rst index ebe2e0254b3e..229629e305ca 100644 --- a/Documentation/translations/zh_CN/process/2.Process.rst +++ b/Documentation/translations/zh_CN/process/2.Process.rst @@ -1,17 +1,24 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/2.Process.rst <development_process>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> .. _cn_development_process: -开发流程如何工作 +开发流程如何进行 ================ -90年代早期的Linux内核开发是一件相当松散的事情，涉及的用户和开发人员相对较 -少。由于拥有数以百万计的用户群，并且在一年的时间里有大约2000名开发人员参与 -进来，内核因此必须发展许多流程来保持开发的顺利进行。要成为流程的有效组成 -部分，需要对流程的工作方式有一个扎实的理解。 +90年代早期的Linux内核开发是一件相当松散的事情，涉及的用户和开发人员相对较少。 +由于拥有数以百万计的用户群，且每年有大约2000名开发人员参与进来，内核因此必须 +发展出许多既定流程来保证开发的顺利进行。要参与到流程中来，需要对此流程的进行 +方式有一个扎实的理解。 总览 ---- @@ -20,112 +27,113 @@ 内核版本。最近的发布历史记录如下： ====== ================= - 4.11 四月 30, 2017 - 4.12 七月 2, 2017 - 4.13 九月 3, 2017 - 4.14 十一月 12, 2017 - 4.15 一月 28, 2018 - 4.16 四月 1, 2018 + 5.0 2019年3月3日 + 5.1 2019年5月5日 + 5.2 2019年7月7日 + 5.3 2019年9月15日 + 5.4 2019年11月24日 + 5.5 2020年1月6日 ====== ================= -每4.x版本都是一个主要的内核版本，具有新特性、内部API更改等等。一个典型的4.x -版本包含大约13000个变更集，变更了几十万行代码。因此，4.x是Linux内核开发的前 +每个5.x版本都是一个主要的内核版本，具有新特性、内部API更改等等。一个典型的5.x +版本包含大约13000个变更集，变更了几十万行代码。因此，5.x是Linux内核开发的前 沿；内核使用滚动开发模型，不断集成重大变化。 -对于每个版本的补丁合并，遵循一个相对简单的规则。在每个开发周期的开始，“合并 -窗口”被打开。当时，被认为足够稳定（并且被开发社区接受）的代码被合并到主线内 +对于每个版本的补丁合并，遵循一个相对简单的规则。在每个开发周期的开头，“合并 +窗口”被打开。这时，被认为足够稳定（并且被开发社区接受）的代码被合并到主线内 核中。在这段时间内，新开发周期的大部分变更（以及所有主要变更）将以接近每天 1000次变更（“补丁”或“变更集”）的速度合并。 -（顺便说一句，值得注意的是，合并窗口期间集成的更改并不是凭空产生的；它们是 -提前收集、测试和分级的。稍后将详细描述该过程的工作方式）。 +（顺便说一句，值得注意的是，合并窗口期间集成的更改并不是凭空产生的；它们是经 +提前收集、测试和分级的。稍后将详细描述该过程的工作方式。） 合并窗口持续大约两周。在这段时间结束时，LinusTorvalds将声明窗口已关闭，并 -释放第一个“rc”内核。例如，对于目标为4.14的内核，在合并窗口结束时发生的释放 -将被称为4.14-rc1。RC1版本是一个信号，表示合并新特性的时间已经过去，稳定下一 -个内核的时间已经开始。 +释放第一个“rc”内核。例如，对于目标为5.6的内核，在合并窗口结束时发生的释放 +将被称为5.6-rc1。-rc1 版本是一个信号，表示合并新特性的时间已经过去，稳定下一 +个内核的时间已经到来。 在接下来的6到10周内，只有修复问题的补丁才应该提交给主线。有时会允许更大的 -更改，但这种情况很少发生；试图在合并窗口外合并新功能的开发人员往往会受到不 +更改，但这种情况很少发生；试图在合并窗口外合并新功能的开发人员往往受不到 友好的接待。一般来说，如果您错过了给定特性的合并窗口，最好的做法是等待下一 -个开发周期。（对于以前不支持的硬件，偶尔会对驱动程序进行例外；如果它们不 -改变已有代码，则不会导致回归，并且应该可以随时安全地添加）。 +个开发周期。（偶尔会对未支持硬件的驱动程序进行例外；如果它们不改变已有代码， +则不会导致回归，应该可以随时被安全地加入）。 随着修复程序进入主线，补丁速度将随着时间的推移而变慢。Linus大约每周发布一次 -新的-rc内核；一个正常的系列将在-rc6和-rc9之间，内核被认为足够稳定并最终发布。 +新的-rc内核；在内核被认为足够稳定并最终发布前，一般会达到-rc6到-rc9之间。 然后，整个过程又重新开始了。 -例如，这里是4.16的开发周期进行情况（2018年的所有日期）: +例如，这里是5.4的开发周期进行情况（2019年）: ============== ============================== - 一月 28 4.15 稳定版发布 - 二月 11 4.16-rc1, 合并窗口关闭 - 二月 18 4.16-rc2 - 二月 25 4.16-rc3 - 三月 4 4.16-rc4 - 三月 11 4.16-rc5 - 三月 18 4.16-rc6 - 三月 25 4.16-rc7 - 四月 1 4.16 稳定版发布 + 九月 15 5.3 稳定版发布 + 九月 30 5.4-rc1 合并窗口关闭 + 十月 6 5.4-rc2 + 十月 13 5.4-rc3 + 十月 20 5.4-rc4 + 十月 27 5.4-rc5 + 十一月 3 5.4-rc6 + 十一月 10 5.4-rc7 + 十一月 17 5.4-rc8 + 十一月 24 5.4 稳定版发布 ============== ============================== -开发人员如何决定何时结束开发周期并创建稳定的版本？使用的最重要的指标是以前 -版本的回归列表。不欢迎出现任何错误，但是那些破坏了以前能工作的系统的错误被 -认为是特别严重的。因此，导致回归的补丁是不受欢迎的，很可能在稳定期内删除。 +开发人员如何决定何时结束开发周期并创建稳定版本？最重要的指标是以前版本的 +回归列表。不欢迎出现任何错误，但是那些破坏了以前能工作的系统的错误被认为是 +特别严重的。因此，导致回归的补丁是不受欢迎的，很可能在稳定期内删除。 开发人员的目标是在稳定发布之前修复所有已知的回归。在现实世界中，这种完美是 -很难实现的；在这种规模的项目中，变量太多了。有一点，延迟最终版本只会使问题 -变得更糟；等待下一个合并窗口的一堆更改将变大，从而在下次创建更多的回归错误。 -因此，大多数4.x内核都有一些已知的回归错误，不过，希望没有一个是严重的。 +很难实现的；在这种规模的项目中，变数太多了。需要说明的是，延迟最终版本只会 +使问题变得更糟；等待下一个合并窗口的更改将变多，导致下次出现更多的回归错误。 +因此，大多数5.x内核都有一些已知的回归错误，不过，希望没有一个是严重的。 -一旦一个稳定的版本发布，它正在进行的维护工作就被移交给“稳定团队”，目前由 -Greg Kroah-Hartman组成。稳定团队将使用4.x.y编号方案不定期的发布稳定版本的更 -新。要加入更新版本，补丁程序必须（1）修复一个重要的bug，（2）已经合并到 -下一个开发主线中。内核通常会在超过其初始版本的一个以上的开发周期内接收稳定 -的更新。例如，4.13内核的历史如下 +一旦一个稳定的版本发布，它的持续维护工作就被移交给“稳定团队”，目前由 +Greg Kroah-Hartman领导。稳定团队将使用5.x.y编号方案不定期地发布稳定版本的 +更新。要合入更新版本，补丁必须（1）修复一个重要的缺陷，且（2）已经合并到 +下一个开发版本主线中。内核通常会在其初始版本后的一个以上的开发周期内收到 +稳定版更新。例如，5.2内核的历史如下（2019年）： ============== =============================== - 九月 3 4.13 稳定版发布 - 九月 13 4.13.1 - 九月 20 4.13.2 - 九月 27 4.13.3 - 十月 5 4.13.4 - 十月 12 4.13.5 + 七月 7 5.2 稳定版发布 + 七月 13 5.2.1 + 七月 21 5.2.2 + 七月 26 5.2.3 + 七月 28 5.2.4 + 七月 31 5.2.5 ... ... - 十一月 24 4.13.16 + 十月 11 5.2.21 ============== =============================== -4.13.16是4.13版本的最终稳定更新。 +5.2.21是5.2版本的最终稳定更新。 有些内核被指定为“长期”内核；它们将得到更长时间的支持。在本文中，当前的长期 内核及其维护者是： - ====== ====================== ============================== - 3.16 Ben Hutchings (长期稳定内核) - 4.1 Sasha Levin - 4.4 Greg Kroah-Hartman (长期稳定内核) - 4.9 Greg Kroah-Hartman - 4.14 Greg Kroah-Hartman - ====== ====================== ============================== + ====== ================================ ================ + 3.16 Ben Hutchings （长期稳定内核） + 4.4 Greg Kroah-Hartman & Sasha Levin （长期稳定内核） + 4.9 Greg Kroah-Hartman & Sasha Levin + 4.14 Greg Kroah-Hartman & Sasha Levin + 4.19 Greg Kroah-Hartman & Sasha Levin + 5.4 Greg Kroah-Hartman & Sasha Levin + ====== ================================ ================ -为长期支持选择内核纯粹是维护人员有必要和时间来维护该版本的问题。目前还没有 -为即将发布的任何特定版本提供长期支持的已知计划。 +长期支持内核的选择纯粹是维护人员是否有需求和时间来维护该版本的问题。 +目前还没有为即将发布的任何特定版本提供长期支持的已知计划。 补丁的生命周期 -------------- 补丁不会直接从开发人员的键盘进入主线内核。相反，有一个稍微复杂（如果有些非 正式）的过程，旨在确保对每个补丁进行质量审查，并确保每个补丁实现了一个在主线 -中需要的更改。对于小的修复，这个过程可能会很快发生，或者，在大的和有争议的 -变更的情况下，会持续数年。许多开发人员的挫折来自于对这个过程缺乏理解或者 -试图绕过它。 +中需要的更改。对于小的修复，这个过程可能会很快完成，，而对于较大或有争议的 +变更，可能会持续数年。许多开发人员的沮丧来自于对这个过程缺乏理解或者试图绕过它。 -为了减少这种挫折感，本文将描述补丁如何进入内核。下面是一个介绍，它以某种 -理想化的方式描述了这个过程。更详细的过程将在后面的章节中介绍。 +为了减少这种挫败，本文将描述补丁如何进入内核。下面的介绍以一种较为理想化的 +方式描述了这个过程。更详细的过程将在后面的章节中介绍。 -补丁程序经历的阶段通常是： +补丁通常要经历以下阶段： -- 设计。这就是补丁的真正需求——以及满足这些需求的方式——的所在。设计工作通常 +- 设计。这就是补丁的真正需求——以及满足这些需求的方式——所在。设计工作通常 是在不涉及社区的情况下完成的，但是如果可能的话，最好是在公开的情况下完成 这项工作；这样可以节省很多稍后再重新设计的时间。 @@ -134,53 +142,51 @@ Greg Kroah-Hartman组成。稳定团队将使用4.x.y编号方案不定期的发 - 更广泛的评审。当补丁接近准备好纳入主线时，它应该被相关的子系统维护人员 接受——尽管这种接受并不能保证补丁会一直延伸到主线。补丁将出现在维护人员的 - 子系统树中，并进入 -next 树（如下所述）。当流程工作时，此步骤将导致对补丁 - 进行更广泛的审查，并发现由于将此补丁与其他人所做的工作集成而导致的任何 + 子系统树中，并进入 -next 树（如下所述）。当流程进行时，此步骤将会对补丁 + 进行更广泛的审查，并发现由于将此补丁与其他人所做的工作合并而导致的任何 问题。 -- 请注意，大多数维护人员也有日常工作，因此合并补丁可能不是他们的最高优先级。 - 如果您的补丁程序得到了关于所需更改的反馈，那么您应该进行这些更改，或者为 - 不应该进行这些更改的原因辩护。如果您的补丁没有评审意见，但没有被其相应的 - 子系统或驱动程序维护者接受，那么您应该坚持不懈地将补丁更新到当前内核，使 - 其干净地应用，并不断地将其发送以供审查和合并。 +- 请注意，大多数维护人员也有日常工作，因此合并补丁可能不是他们的最优先工作。 + 如果您的补丁得到了需要更改的反馈，那么您应该进行这些更改，或者解释为何 + 不应该进行这些更改。如果您的补丁没有评审意见，也没有被其相应的子系统或 + 驱动程序维护者接受，那么您应该坚持不懈地将补丁更新到当前内核使其可被正常 + 应用，并不断地发送它以供审查和合并。 - 合并到主线。最终，一个成功的补丁将被合并到由LinusTorvalds管理的主线存储库 - 中。此时可能会出现更多的评论和/或问题；开发人员应对这些问题并解决出现的 - 任何问题很重要。 + 中。此时可能会出现更多的评论和/或问题；对开发人员来说应对这些问题并解决 + 出现的任何问题仍很重要。 -- 稳定版发布。可能受补丁影响的用户数量现在很大，因此可能再次出现新的问题。 +- 稳定版发布。大量用户可能受此补丁影响，因此可能再次出现新的问题。 - 长期维护。虽然开发人员在合并代码后可能会忘记代码，但这种行为往往会给开发 - 社区留下不良印象。合并代码消除了一些维护负担，因为其他代码将修复由API - 更改引起的问题。但是，如果代码要长期保持有用，原始开发人员应该继续为 - 代码负责。 + 社区留下不良印象。合并代码消除了一些维护负担，因为其他人将修复由API更改 + 引起的问题。但是，如果代码要长期保持可用，原始开发人员应该继续为代码负责。 -内核开发人员（或他们的雇主）犯的最大错误之一是试图将流程简化为一个 -“合并到主线”步骤。这种方法总是会让所有相关人员感到沮丧。 +内核开发人员（或他们的雇主）犯的最大错误之一是试图将流程简化为一个“合并到 +主线”步骤。这种方法总是会让所有相关人员感到沮丧。 补丁如何进入内核 ---------------- 只有一个人可以将补丁合并到主线内核存储库中：LinusTorvalds。但是，在进入 2.6.38内核的9500多个补丁中，只有112个（大约1.3%）是由Linus自己直接选择的。 -内核项目已经发展到一个规模，没有一个开发人员可以在没有支持的情况下检查和 -选择每个补丁。内核开发人员处理这种增长的方式是通过使用围绕信任链构建的 -助理系统。 +内核项目已经发展到一个没有一个开发人员可以在没有支持的情况下检查和选择每个 +补丁的规模。内核开发人员处理这种增长的方式是使用围绕信任链构建的助理系统。 -内核代码库在逻辑上被分解为一组子系统：网络、特定的体系结构支持、内存管理、 -视频设备等。大多数子系统都有一个指定的维护人员，开发人员对该子系统中的代码 -负有全部责任。这些子系统维护者（松散地）是他们所管理的内核部分的守护者； -他们（通常）会接受一个补丁以包含到主线内核中。 +内核代码库在逻辑上被分解为一组子系统：网络、特定体系结构支持、内存管理、视 +频设备等。大多数子系统都有一个指定的维护人员，其总体负责该子系统中的代码。 +这些子系统维护者（松散地）是他们所管理的内核部分的“守门员”；他们（通常） +会接受一个补丁以包含到主线内核中。 -子系统维护人员每个人都使用git源代码管理工具管理自己版本的内核源代码树。Git -等工具（以及Quilt或Mercurial等相关工具）允许维护人员跟踪补丁列表，包括作者 +子系统维护人员每个人都管理着自己版本的内核源代码树，通常（并非总是）使用Git。 +Git等工具（以及Quilt或Mercurial等相关工具）允许维护人员跟踪补丁列表，包括作者 信息和其他元数据。在任何给定的时间，维护人员都可以确定他或她的存储库中的哪 些补丁在主线中找不到。 -当合并窗口打开时，顶级维护人员将要求Linus从其存储库中“拉出”他们为合并选择 +当合并窗口打开时，顶级维护人员将要求Linus从存储库中“拉出”他们为合并选择 的补丁。如果Linus同意，补丁流将流向他的存储库，成为主线内核的一部分。 -Linus对拉操作中接收到的特定补丁的关注程度各不相同。很明显，有时他看起来很 -关注。但是，作为一般规则，Linus相信子系统维护人员不会向上游发送坏补丁。 +Linus对拉取中接收到的特定补丁的关注程度各不相同。很明显，有时他看起来很 +关注。但是一般来说，Linus相信子系统维护人员不会向上游发送坏补丁。 子系统维护人员反过来也可以从其他维护人员那里获取补丁。例如，网络树是由首先 在专用于网络设备驱动程序、无线网络等的树中积累的补丁构建的。此存储链可以 @@ -195,26 +201,26 @@ Next 树 子系统树链引导补丁流到内核，但它也提出了一个有趣的问题：如果有人想查看为 下一个合并窗口准备的所有补丁怎么办？开发人员将感兴趣的是，还有什么其他的 -更改有待解决，以查看是否存在需要担心的冲突；例如，更改核心内核函数原型的 +更改有待解决，以了解是否存在需要担心的冲突；例如，更改核心内核函数原型的 修补程序将与使用该函数旧形式的任何其他修补程序冲突。审查人员和测试人员希望 -在所有这些变更到达主线内核之前，能够访问它们的集成形式中的变更。您可以从所有 -有趣的子系统树中提取更改，但这将是一项大型且容易出错的工作。 +在所有这些变更到达主线内核之前，能够访问它们的集成形式的变更。您可以从所有 +相关的子系统树中提取更改，但这将是一项复杂且容易出错的工作。 -答案以-next树的形式出现，在这里子系统树被收集以供测试和审查。Andrew Morton -维护的这些旧树被称为“-mm”（用于内存管理，这就是它的启动名字）。-mm 树集成了 -一长串子系统树中的补丁；它还包含一些旨在帮助调试的补丁。 +解决方案以-next树的形式出现，在这里子系统树被收集以供测试和审查。这些树中 +由Andrew Morton维护的较老的一个，被称为“-mm”（用于内存管理，创建时为此）。 +-mm 树集成了一长串子系统树中的补丁；它还包含一些旨在帮助调试的补丁。 除此之外，-mm 还包含大量由Andrew直接选择的补丁。这些补丁可能已经发布在邮件 -列表上，或者它们可能应用于内核中没有指定子系统树的部分。结果，-mm 作为一种 -最后手段的子系统树运行；如果没有其他明显的路径可以让补丁进入主线，那么它很 -可能以-mm 结束。累积在-mm 中的各种补丁最终将被转发到适当的子系统树，或者直接 +列表上，或者它们可能应用于内核中未指定子系统树的部分。同时，-mm 作为最后 +手段的子系统树；如果没有其他明显的路径可以让补丁进入主线，那么它很可能最 +终选择-mm 树。累积在-mm 中的各种补丁最终将被转发到适当的子系统树，或者直接 发送到Linus。在典型的开发周期中，大约5-10%的补丁通过-mm 进入主线。 -当前-mm 补丁可在“mmotm”（-mm of the moment）目录中找到，地址： +当前-mm 补丁可在“mmotm”（-mm of the moment）目录中找到： https://www.ozlabs.org/~akpm/mmotm/ -然而，使用mmotm树可能是一种令人沮丧的体验；它甚至可能无法编译。 +然而，使用MMOTM树可能会十分令人头疼；它甚至可能无法编译。 下一个周期补丁合并的主要树是linux-next，由Stephen Rothwell 维护。根据设计 linux-next 是下一个合并窗口关闭后主线的快照。linux-next树在Linux-kernel 和 @@ -228,49 +234,48 @@ Linux-next 已经成为内核开发过程中不可或缺的一部分；在一个 Staging 树 ---------- -内核源代码树包含drivers/staging/directory，其中有许多驱动程序或文件系统的 -子目录正在被添加到内核树中。它们然需要更多的工作的时候可以保留在 -driver/staging目录中；一旦完成，就可以将它们移到内核中。这是一种跟踪不符合 -Linux内核编码或质量标准的驱动程序的方法，但人们可能希望使用它们并跟踪开发。 +内核源代码树包含drivers/staging/目录，其中有许多驱动程序或文件系统的子目录 +正在被添加到内核树中。它们在仍然需要更多的修正的时候可以保留在driver/staging/ +目录中；一旦完成，就可以将它们移到内核中。这是一种跟踪不符合Linux内核编码或 +质量标准的驱动程序的方法，人们可能希望使用它们并跟踪开发。 -Greg Kroah Hartman 目前负责维护staging 树。仍需要工作的驱动程序将发送给他， +Greg Kroah Hartman 目前负责维护staging 树。仍需要修正的驱动程序将发送给他， 每个驱动程序在drivers/staging/中都有自己的子目录。除了驱动程序源文件之外， -目录中还应该有一个TODO文件。todo文件列出了驱动程序需要接受的挂起的工作， +目录中还应该有一个TODO文件。TODO文件列出了驱动程序需要接受的暂停的工作， 以及驱动程序的任何补丁都应该抄送的人员列表。当前的规则要求，staging的驱动 程序必须至少正确编译。 -Staging 是一种相对容易的方法，可以让新的驱动程序进入主线，幸运的是，他们会 -引起其他开发人员的注意，并迅速改进。然而，进入staging并不是故事的结尾； -staging中没有看到常规进展的代码最终将被删除。经销商也倾向于相对不愿意使用 -staging驱动程序。因此，在成为一名合适的主线驱动的路上，staging 充其量只是 -一个停留。 +Staging 是一种让新的驱动程序进入主线的相对容易的方法，它们会幸运地引起其他 +开发人员的注意，并迅速改进。然而，进入staging并不是故事的结尾；staging中 +没有看到常规进展的代码最终将被删除。经销商也倾向于相对不愿意使用staging驱动 +程序。因此，在成为一个合适的主线驱动的路上，staging 仅是一个中转站。 工具 ---- 从上面的文本可以看出，内核开发过程在很大程度上依赖于在不同方向上聚集补丁的 能力。如果没有适当强大的工具，整个系统将无法在任何地方正常工作。关于如何使用 -这些工具的教程远远超出了本文档的范围，但是还是有一些指南的空间。 +这些工具的教程远远超出了本文档的范围，但还是用一点篇幅介绍一些关键点。 到目前为止，内核社区使用的主要源代码管理系统是git。Git是在自由软件社区中开发 的许多分布式版本控制系统之一。它非常适合内核开发，因为它在处理大型存储库和 -大量补丁时性能非常好。它还有一个难以学习和使用的名声，尽管随着时间的推移它 -变得更好了。对于内核开发人员来说，对Git的某种熟悉几乎是一种要求；即使他们不 -将它用于自己的工作，他们也需要Git来跟上其他开发人员（以及主线）正在做的事情。 +大量补丁时性能非常好。它也以难以学习和使用而著称，尽管随着时间的推移它变得 +更好了。对于内核开发人员来说，对Git的某种熟悉几乎是一种要求；即使他们不将它 +用于自己的工作，他们也需要Git来跟上其他开发人员（以及主线）正在做的事情。 -现在几乎所有的Linux发行版都打包了Git。主页位于： +现在几乎所有的Linux发行版都打包了Git。Git主页位于： https://git-scm.com/ -那个页面有指向文档和教程的指针。 +此页面包含了文档和教程的链接。 -在不使用git的内核开发人员中，最流行的选择几乎肯定是mercurial： +在不使用git的内核开发人员中，最流行的选择几乎肯定是Mercurial： http://www.seleric.com/mercurial/ Mercurial与Git共享许多特性，但它提供了一个界面，许多人觉得它更易于使用。 -另一个值得了解的工具是quilt: +另一个值得了解的工具是Quilt: https://savannah.nongnu.org/projects/quilt @@ -282,79 +287,79 @@ Quilt 是一个补丁管理系统，而不是源代码管理系统。它不会 邮件列表 -------- -大量的Linux内核开发工作是通过邮件列表完成的。如果不在某个地方加入至少一个列表， -就很难成为社区中一个功能完备的成员。但是，Linux邮件列表对开发人员来说也是一个 -潜在的危险，他们可能会被一堆电子邮件淹没，违反Linux列表上使用的约定，或者 -两者兼而有之。 +大量的Linux内核开发工作是通过邮件列表完成的。如果不加入至少一个某个列表， +就很难成为社区中的一个“全功能”成员。但是，Linux邮件列表对开发人员来说也是 +一个潜在的危险，他们可能会被一堆电子邮件淹没、违反Linux列表上使用的约定， +或者两者兼而有之。 大多数内核邮件列表都在vger.kernel.org上运行；主列表位于： http://vger.kernel.org/vger-lists.html -不过，也有一些列表托管在别处；其中一些列表位于lists.redhat.com。 +不过，也有一些列表托管在别处；其中一些列表位于 +redhat.com/mailman/listinfo。 -当然，内核开发的核心邮件列表是linux-kernel。这个名单是一个令人生畏的地方； -每天的信息量可以达到500条，噪音很高，谈话技术性很强，参与者并不总是表现出 +当然，内核开发的核心邮件列表是linux-kernel。这个列表是一个令人生畏的地方： +每天的信息量可以达到500条，噪音很高，谈话技术性很强，且参与者并不总是表现出 高度的礼貌。但是，没有其他地方可以让内核开发社区作为一个整体聚集在一起； -避免使用此列表的开发人员将错过重要信息。 +不使用此列表的开发人员将错过重要信息。 -有一些提示可以帮助在linux-kernel生存： +以下一些提示可以帮助在linux-kernel生存： -- 将邮件转移到单独的文件夹，而不是主邮箱。我们必须能够持续地忽略洪流。 +- 将邮件转移到单独的文件夹，而不是主邮箱文件夹。我们必须能够持续地忽略洪流。 -- 不要试图跟踪每一次谈话-其他人都不会。重要的是要对感兴趣的主题（尽管请 - 注意，长时间的对话可以在不更改电子邮件主题行的情况下偏离原始主题）和参与 - 的人进行筛选。 +- 不要试图跟上每一次谈话——没人会这样。重要的是要筛选感兴趣的主题（但请注意 + 长时间的对话可能会偏离原来的主题，尽管未改变电子邮件的主题）和参与的人。 -- 不要挑事。如果有人试图激起愤怒的反应，忽略他们。 +- 不要回复挑事的人。如果有人试图激起愤怒，请忽略他们。 -- 当响应Linux内核电子邮件（或其他列表上的电子邮件）时，请为所有相关人员保留 - cc:header。如果没有强有力的理由（如明确的请求），则不应删除收件人。一定要 - 确保你要回复的人在cc:list中。这个惯例也使你不必在回复邮件时明确要求被抄送。 +- 当回复Linux内核电子邮件（或其他列表上的电子邮件）时，请为所有相关人员保留 + Cc: 抄送头。如果没有确实的理由（如明确的请求），则不应删除收件人。一定要 + 确保你要回复的人在抄送列表中。这个惯例也使你不必在回复邮件时明确要求被抄送。 -- 在提出问题之前，搜索列表档案（和整个网络）。有些开发人员可能会对那些显然 +- 在提出问题之前，搜索列表存档（和整个网络）。有些开发人员可能会对那些显然 没有完成家庭作业的人感到不耐烦。 -- 避免贴顶帖（把你的答案放在你要回复的引文上面的做法）。这会让你的回答更难 +- 避免顶部回复（把你的答案放在你要回复的引文上面的做法）。这会让你的回答更难 理解，印象也很差。 -- 询问正确的邮件列表。linux-kernel 可能是通用的讨论点，但它不是从所有子系统 - 中寻找开发人员的最佳场所。 +- 在正确的邮件列表发问。linux-kernel 可能是通用的讨论场所，但它不是寻找所有 + 子系统开发人员的最佳场所。 -最后一点——找到正确的邮件列表——是开发人员出错的常见地方。在Linux内核上提出与 -网络相关的问题的人几乎肯定会收到一个礼貌的建议，转而在netdev列表上提出， -因为这是大多数网络开发人员经常出现的列表。还有其他列表可用于scsi、 -video4linux、ide、filesystem等子系统。查找邮件列表的最佳位置是与内核源代码 -一起打包的MAINTAINERS文件。 +最后一点——找到正确的邮件列表——是开发人员常出错的地方。在linux-kernel上 +提出与网络相关的问题的人几乎肯定会收到一个礼貌的建议，转到netdev列表上提出， +因为这是大多数网络开发人员经常出现的列表。还有其他列表可用于scsi、video4linux、 +ide、filesystem等子系统。查找邮件列表的最佳位置是与内核源代码一起打包的 +MAINTAINERS文件。 开始内核开发 ------------ -关于如何开始内核开发过程的问题很常见——来自个人和公司。同样常见的是错误，这 -使得关系的开始比必须的更困难。 +关于如何开始内核开发过程的问题很常见——个人和公司皆然。同样常见的是失误，这 +使得关系的开始比本应的更困难。 公司通常希望聘请知名的开发人员来启动开发团队。实际上，这是一种有效的技术。 -但它也往往是昂贵的，而且没有增长经验丰富的内核开发人员储备。考虑到时间的 -投入，可以让内部开发人员加快Linux内核的开发速度。花这个时间可以让雇主拥有 -一批了解内核和公司的开发人员，他们也可以帮助培训其他人。从中期来看，这往往 -是更有利可图的方法。 +但它也往往是昂贵的，而且对增加有经验的内核开发人员的数量没有多大帮助。考 +虑到时间投入，可以让内部开发人员加快Linux内核的开发速度。利用这段时间可以 +让雇主拥有一批既了解内核又了解公司的开发人员，还可以帮助培训其他人。从中期 +来看，这通常是更有利可图的方法。 可以理解的是，单个开发人员往往对起步感到茫然。从一个大型项目开始可能会很 -吓人；人们往往想先用一些较小的东西来测试水域。这是一些开发人员开始创建修补 -拼写错误或轻微编码风格问题的补丁的地方。不幸的是，这样的补丁会产生一定程度 -的噪音，这会分散整个开发社区的注意力，因此，越来越多的人看不起它们。希望向 -社区介绍自己的新开发人员将无法通过这些方式获得他们想要的那种接待。 +吓人；人们往往想先用一些较小的东西来试试水。由此，一些开发人员开始创建修补 +拼写错误或轻微编码风格问题的补丁。不幸的是，这样的补丁会产生一定程度的噪音， +这会分散整个开发社区的注意力，因此，它们越来越被人不看重。希望向社区介绍 +自己的新开发人员将无法通过这些方式获得他们期待的反响。 -Andrew Morton 为有抱负的内核开发人员提供了这个建议 +Andrew Morton 为有抱负的内核开发人员提供了如下建议 :: - 所有内核初学者的No.1项目肯定是“确保内核在所有的机器上，你可以触摸 - 到的，始终运行良好" 通常这样做的方法是与其他人一起解决问题（这 - 可能需要坚持！）但这很好——这是内核开发的一部分 + 所有内核开发者的第一个项目肯定应该是“确保内核在您可以操作的所有 + 机器上始终完美运行”。通常的方法是和其他人一起解决问题（这可能需 + 要坚持！），但就是如此——这是内核开发的一部分。 (http://lwn.net/articles/283982/) -在没有明显问题需要解决的情况下，建议开发人员查看当前的回归和开放式错误列表. -解决需要修复的问题没有任何缺点；通过解决这些问题，开发人员将获得处理过程的 -经验，同时与开发社区的其他人建立尊重。 +在没有明显问题需要解决的情况下，通常建议开发人员查看当前的回归和开放缺陷 +列表。从来都不缺少需要解决的问题；通过解决这些问题，开发人员将从该过程获得 +经验，同时与开发社区的其他成员建立相互尊重。 diff --git a/Documentation/translations/zh_CN/process/3.Early-stage.rst b/Documentation/translations/zh_CN/process/3.Early-stage.rst index b8676aec6005..de53dd12e911 100644 --- a/Documentation/translations/zh_CN/process/3.Early-stage.rst +++ b/Documentation/translations/zh_CN/process/3.Early-stage.rst @@ -1,7 +1,14 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/3.Early-stage.rst <development_early_stage>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> .. _cn_development_early_stage: @@ -9,45 +16,45 @@ ======== 当考虑一个Linux内核开发项目时，很可能会直接跳进去开始编码。然而，与任何重要 -的项目一样，成功的许多基础最好是在第一行代码编写之前就做好了。在早期计划和 -沟通中花费一些时间可以节省更多的时间。 +的项目一样，许多成功的基础最好是在第一行代码编写之前就打下。在早期计划和 +沟通中花费一些时间可以在之后节省更多的时间。 -详述问题 +搞清问题 -------- -与任何工程项目一样，成功的内核增强从要解决的问题的清晰描述开始。在某些情况 -下，这个步骤很容易：例如，当某个特定硬件需要驱动程序时。不过，在其他方面， -将实际问题与建议的解决方案混淆是很有诱惑力的，这可能会导致困难。 +与任何工程项目一样，成功的内核改善从清晰描述要解决的问题开始。在某些情况 +下，这个步骤很容易：例如当某个特定硬件需要驱动程序时。不过，在其他情况下， +很容易将实际问题与建议的解决方案混在一起，这可能会导致麻烦。 -举个例子：几年前，使用Linux音频的开发人员寻求一种方法来运行应用程序，而不因 -系统延迟过大而导致退出或其他工件。他们得到的解决方案是一个内核模块，旨在连 -接到Linux安全模块（LSM）框架中；这个模块可以配置为允许特定的应用程序访问 -实时调度程序。这个模块被实现并发送到Linux内核邮件列表，在那里它立即遇到问题。 +举个例子：几年前，Linux音频的开发人员寻求一种方法来运行应用程序，而不会因 +系统延迟过大而导致退出或其他问题。他们得到的解决方案是一个连接到Linux安全 +模块（LSM）框架中的内核模块；这个模块可以配置为允许特定的应用程序访问实时 +调度程序。这个模块被实现并发到linux-kernel邮件列表，在那里它立即遇到了麻烦。 对于音频开发人员来说，这个安全模块足以解决他们当前的问题。但是，对于更广泛的 内核社区来说，这被视为对LSM框架的滥用（LSM框架并不打算授予他们原本不具备的 进程特权），并对系统稳定性造成风险。他们首选的解决方案包括短期的通过rlimit 机制进行实时调度访问，以及长期的减少延迟的工作。 -然而，音频社区看不到他们实施的特定解决方案的过去；他们不愿意接受替代方案。 +然而，音频社区无法超越他们实施的特定解决方案来看问题；他们不愿意接受替代方案。 由此产生的分歧使这些开发人员对整个内核开发过程感到失望；其中一个开发人员返回 -到音频列表并发布了以下内容： +到audio列表并发布了以下内容： - 有很多非常好的Linux内核开发人员，但他们往往会被一群傲慢的傻瓜所压倒。 - 试图向这些人传达用户需求是浪费时间。他们太“聪明”了，根本听不到少数人 - 的话。 + 有很多非常好的Linux内核开发人员，但他们往往会被一群傲慢的傻瓜所压倒。 + 试图向这些人传达用户需求是浪费时间。他们太“聪明”了，根本听不到少数 + 人的话。 （http://lwn.net/articles/131776/） -实际情况不同；与特定模块相比，内核开发人员更关心系统稳定性、长期维护以及找到 -正确的问题解决方案。这个故事的寓意是把重点放在问题上——而不是具体的解决方案 -上——并在投入创建代码之前与开发社区讨论这个问题。 +实际情况却是不同的；与特定模块相比，内核开发人员更关心系统稳定性、长期维护 +以及找到问题的正确解决方案。这个故事的寓意是把重点放在问题上——而不是具体的 +解决方案上——并在开始编写代码之前与开发社区讨论这个问题。 因此，在考虑一个内核开发项目时，我们应该得到一组简短问题的答案： - - 究竟需要解决的问题是什么？ + - 需要解决的问题究竟是什么？ - - 受此问题影响的用户是谁？解决方案应该解决哪些用例？ + - 受此问题影响的用户有哪些？解决方案应该解决哪些使用案例？ - 内核现在为何没能解决这个问题？ @@ -62,100 +69,100 @@ - 很可能问题是由内核以您不理解的方式解决的。Linux内核很大，具有许多不明显 的特性和功能。并不是所有的内核功能都像人们所希望的那样有文档记录，而且很 - 容易遗漏一些东西。你的作者发出了一个完整的驱动程序，复制了一个新作者不 - 知道的现有驱动程序。重新设计现有轮子的代码不仅浪费，而且不会被接受到主线 + 容易遗漏一些东西。某作者发布了一个完整的驱动程序，重复了一个其不 + 知道的现有驱动程序。重新发明现有轮子的代码不仅浪费，而且不会被接受到主线 内核中。 - - 建议的解决方案中可能有一些元素不适用于主线合并。在编写代码之前，最好先 - 了解这样的问题。 + - 建议的解决方案中可能有一些要素不适合并入主线。在编写代码之前，最好先了解 + 这样的问题。 - 其他开发人员完全有可能考虑过这个问题；他们可能有更好的解决方案的想法，并且 可能愿意帮助创建这个解决方案。 在内核开发社区的多年经验给了我们一个明确的教训：闭门设计和开发的内核代码总是 有一些问题，这些问题只有在代码发布到社区中时才会被发现。有时这些问题很严重， -需要数月或数年的努力才能使代码达到内核社区的标准。一些例子包括： +需要数月或数年的努力才能使代码达到内核社区的标准。例如： - 设计并实现了单处理器系统的DeviceScape网络栈。只有使其适合于多处理器系统， - 才能将其合并到主线中。在代码中改装锁等等是一项困难的任务；因此，这段代码 + 才能将其合并到主线中。在代码中修改锁等等是一项困难的任务；因此，这段代码 （现在称为mac80211）的合并被推迟了一年多。 - Reiser4文件系统包含许多功能，核心内核开发人员认为这些功能应该在虚拟文件 系统层中实现。它还包括一些特性，这些特性在不将系统暴露于用户引起的死锁的 - 情况下是不容易实现的。这些问题的最新发现——以及对其中一些问题的拒绝——已经 - 导致Reiser4远离了主线内核。 + 情况下是不容易实现的。这些问题过迟发现——以及拒绝处理其中一些问题——已经 + 导致Reiser4置身主线内核之外。 - Apparmor安全模块以被认为不安全和不可靠的方式使用内部虚拟文件系统数据结构。 - 这种担心（包括其他）使Apparmor多年不在主线上。 + 这种担心（包括其他）使Apparmor多年来无法进入主线。 -在每一种情况下，通过与内核开发人员的早期讨论，可以避免大量的痛苦和额外的工作。 +在这些情况下，与内核开发人员的早期讨论，可以避免大量的痛苦和额外的工作。 -找谁交流 --------- +找谁交流？ +---------- 当开发人员决定公开他们的计划时，下一个问题是：我们从哪里开始？答案是找到正确 的邮件列表和正确的维护者。对于邮件列表，最好的方法是在维护者(MAINTAINERS)文件 -中查找要发布的相关位置。如果有一个合适的子系统列表，那么发布它通常比在Linux -内核上发布更可取；您更有可能接触到在相关子系统中具有专业知识的开发人员，并且 -环境可能具支持性。 +中查找要发布的相关位置。如果有一个合适的子系统列表，那么其上发布通常比在 +linux-kernel上发布更可取；您更有可能接触到在相关子系统中具有专业知识的开发 +人员，并且环境可能具支持性。 -找到维护人员可能会有点困难。同样，维护者文件是开始的地方。但是，该文件往往不总 -是最新的，并且并非所有子系统都在那里表示。实际上，维护者文件中列出的人员可能 +找到维护人员可能会有点困难。同样，维护者文件是开始的地方。但是，该文件往往不 +是最新的，并且并非所有子系统都在那里显示。实际上，维护者文件中列出的人员可能 不是当前实际担任该角色的人员。因此，当对联系谁有疑问时，一个有用的技巧是使用 -git（尤其是“git-log”）查看感兴趣的子系统中当前活动的用户。看看谁在写补丁， -如果有人的话，谁会在这些补丁上加上用线签名的。这些人将是帮助新开发项目的最佳 -人选。 +git（尤其是“git-log”）查看感兴趣的子系统中当前活动的用户。看看谁在写补丁、 +谁会在这些补丁上加上Signed-off-by行签名（如有）。这些人将是帮助新开发项目的 +最佳人选。 -找到合适的维护者的任务有时是非常具有挑战性的，以至于内核开发人员添加了一个 -脚本来简化过程： +找到合适的维护者有时是非常具有挑战性的，以至于内核开发人员添加了一个脚本来 +简化这个过程： :: .../scripts/get_maintainer.pl -当给定“-f”选项时，此脚本将返回给定文件或目录的当前维护者。如果在命令行上传递 -了一个补丁，它将列出可能接收补丁副本的维护人员。有许多选项可以调节 -get_maintainer.pl搜索维护者的难易程度；请小心使用更具攻击性的选项，因为最终 +当给定“-f”选项时，此脚本将返回指定文件或目录的当前维护者。如果在命令行上 +给出了一个补丁，它将列出可能接收补丁副本的维护人员。有许多选项可以调节 +get_maintainer.pl搜索维护者的严格程度；请小心使用更激进的选项，因为最终结果 可能会包括对您正在修改的代码没有真正兴趣的开发人员。 -如果所有其他方法都失败了，那么与Andrew Morton交谈可以成为一种有效的方法来跟踪 -特定代码段的维护人员。 +如果所有其他方法都失败了，那么与Andrew Morton交流是跟踪特定代码段维护人员 +的一种有效方法。 何时邮寄？ ---------- -如果可能的话，在早期阶段发布你的计划只会有帮助。描述正在解决的问题以及已经 +如果可能的话，在早期阶段发布你的计划只会更有帮助。描述正在解决的问题以及已经 制定的关于如何实施的任何计划。您可以提供的任何信息都可以帮助开发社区为项目 提供有用的输入。 -在这个阶段可能发生的一件令人沮丧的事情不是敌对的反应，而是很少或根本没有 -反应。可悲的事实是：（1）内核开发人员往往很忙；（2）不缺少有宏伟计划和很少 -代码（甚至代码前景）支持他们的人；（3）没有人有义务审查或评论别人发表的 -想法。除此之外，高级设计常常隐藏一些问题，这些问题只有在有人真正尝试实现 -这些设计时才会被发现；因此，内核开发人员宁愿看到代码。 +在这个阶段可能发生的一件令人沮丧的事情不是得到反对意见，而是很少或根本没有 +反馈。令人伤心的事实是：（1）内核开发人员往往很忙；（2）不缺少有宏伟计划但 +代码（甚至代码设想）很少的人去支持他们；（3）没有人有义务审查或评论别人发表 +的想法。除此之外，高层级的设计常常隐藏着一些问题，这些问题只有在有人真正尝试 +实现这些设计时才会被发现；因此，内核开发人员宁愿看到代码。 -如果发表评论的请求在评论的方式上没有什么效果，不要假设这意味着对项目没有 -兴趣。不幸的是，你也不能假设你的想法没有问题。在这种情况下，最好的做法是 -继续进行，把你的进展随时通知社区。 +如果发布请求评论（RFC）并没得到什么有用的评论，不要以为这意味着无人对此项目 +有兴趣，同时你也不能假设你的想法没有问题。在这种情况下，最好的做法是继续进 +行，把你的进展随时通知社区。 获得官方认可 ----------------------- -如果您的工作是在公司环境中完成的，就像大多数Linux内核工作一样，显然，在您将 -公司的计划或代码发布到公共邮件列表之前，必须获得适当授权的经理的许可。发布 -不确定是否兼容GPL的代码可能是有特别问题的；公司的管理层和法律人员越早能够就 -发布内核开发项目达成一致，对参与的每个人都越好。 +如果您的工作是在公司环境中完成的，就像大多数Linux内核工作一样；显然，在您将 +公司的计划或代码发布到公共邮件列表之前，必须获得有适当权利经理的许可。发布 +不确定是否兼容GPL的代码尤其会带来问题；公司的管理层和法律人员越早能够就发布 +内核开发项目达成一致，对参与的每个人都越好。 一些读者可能会认为他们的核心工作是为了支持还没有正式承认存在的产品。将雇主 的计划公布在公共邮件列表上可能不是一个可行的选择。在这种情况下，有必要考虑 保密是否真的是必要的；通常不需要把开发计划关在门内。 -也就是说，有些情况下，一家公司在开发过程的早期就不能合法地披露其计划。拥有 -经验丰富的内核开发人员的公司可以选择以开环的方式进行，前提是他们以后能够避免 +的确，有些情况下一家公司在开发过程的早期无法合法地披露其计划。拥有经验丰富 +的内核开发人员的公司可能选择以开环的方式进行开发，前提是他们以后能够避免 严重的集成问题。对于没有这种内部专业知识的公司，最好的选择往往是聘请外部 -开发商根据保密协议审查计划。Linux基金会运行了一个NDA程序，旨在帮助解决这种 -情况； +开发者根据保密协议审查计划。Linux基金会运行了一个NDA程序，旨在帮助解决这种 +情况；更多信息参见： - http://www.linuxfoundation.org/en/NDA_program + http://www.linuxfoundation.org/nda/ 这种审查通常足以避免以后出现严重问题，而无需公开披露项目。 diff --git a/Documentation/translations/zh_CN/process/4.Coding.rst b/Documentation/translations/zh_CN/process/4.Coding.rst index 66cd8ee07606..94f7f866f103 100644 --- a/Documentation/translations/zh_CN/process/4.Coding.rst +++ b/Documentation/translations/zh_CN/process/4.Coding.rst @@ -1,155 +1,160 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/4.Coding.rst <development_coding>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> .. _cn_development_coding: 使代码正确 ====================== -虽然对于一个坚实的、面向社区的设计过程有很多话要说，但是任何内核开发项目的 -证明都在生成的代码中。它是将由其他开发人员检查并合并（或不合并）到主线树中 +虽然一个坚实的、面向社区的设计过程有很多值得说道的，但是任何内核开发项目工作 +的证明都反映在代码中。它是将由其他开发人员检查并合并（或不合并）到主线树中 的代码。所以这段代码的质量决定了项目的最终成功。 -本节将检查编码过程。我们将从内核开发人员出错的几种方式开始。然后重点将转移 -到正确的事情和可以帮助这个任务的工具上。 +本节将检查编码过程。我们将从内核开发人员常犯的几种错误开始。然后重点将转移 +到正确的做法和相关有用的工具上。 陷阱 ---- -编码风格 +代码风格 ******** -内核长期以来都有一种标准的编码风格，如 +内核长期以来都有其标准的代码风格，如 :ref:`Documentation/translations/zh_CN/process/coding-style.rst <cn_codingstyle>` -中所述。在大部分时间里，该文件中描述的政策被认为至多是建议性的。因此，内核 -中存在大量不符合编码风格准则的代码。代码的存在会给内核开发人员带来两个独立 -的危害。 - -首先，要相信内核编码标准并不重要，也不强制执行。事实上，如果没有按照标准对代 -码进行编码，那么向内核添加新代码是非常困难的；许多开发人员甚至会在审查代码之 -前要求对代码进行重新格式化。一个与内核一样大的代码库需要一些统一的代码，以使 -开发人员能够快速理解其中的任何部分。所以已经没有空间来存放奇怪的格式化代码了。 - -偶尔，内核的编码风格会与雇主的强制风格发生冲突。在这种情况下，内核的风格必须 -在代码合并之前获胜。将代码放入内核意味着以多种方式放弃一定程度的控制权——包括 -控制代码的格式化方式。 - -另一个陷阱是假定已经在内核中的代码迫切需要编码样式的修复。开发人员可能会开始 -生成重新格式化补丁，作为熟悉过程的一种方式，或者作为将其名称写入内核变更日志 -的一种方式，或者两者兼而有之。但是纯编码风格的修复被开发社区视为噪音；它们往 -往受到冷遇。因此，最好避免使用这种类型的补丁。由于其他原因，在处理一段代码的 -同时修复它的样式是很自然的，但是编码样式的更改不应该仅为了更改而进行。 - -编码风格的文档也不应该被视为绝对的法律，这是永远不会被违反的。如果有一个很好 -的理由反对这种样式（例如，如果拆分为适合80列限制的行，那么它的可读性就会大大 -降低），那么就这样做。 - -请注意，您还可以使用 ``clang-format`` 工具来帮助您处理这些规则，自动重新格式 -化部分代码，并查看完整的文件，以发现编码样式错误、拼写错误和可能的改进。它还 -可以方便地进行排序，包括对齐变量/宏、回流文本和其他类似任务。有关详细信息，请 -参阅文件 :ref:`Documentation/process/clang-format.rst <clangformat>` +中所述。在多数时候，该文档中描述的准则至多被认为是建议性的。因此，内核中存在 +大量不符合代码风格准则的代码。这种代码的存在会给内核开发人员带来两方面的危害。 + +首先，相信内核代码标准并不重要，也不强制执行。但事实上，如果没有按照标准 +编写代码，那么新代码将很难加入到内核中；许多开发人员甚至会在审查代码之前要求 +对代码进行重新格式化。一个像内核这么大的代码库需要一些统一格式的代码，以使 +开发人员能够快速理解其中的任何部分。所以再也经不起奇怪格式的代码的折腾了。 + +内核的代码风格偶尔会与雇主的强制风格发生冲突。在这种情况下，必须在代码合并 +之前遵从内核代码风格。将代码放入内核意味着以多种方式放弃一定程度的控制权—— +包括控制代码样式。 + +另一个危害是认为已经在内核中的代码迫切需要修复代码样式。开发者可能会开始编写 +重新格式化补丁，作为熟悉开发过程的一种方式，或者作为将其名字写入内核变更日志 +的一种方式，或者两者兼而有之。但是纯代码风格的修复被开发社区视为噪音，它们往 +往受到冷遇。因此，最好避免编写这种类型的补丁。在由于其他原因处理一段代码的 +同时顺带修复其样式是很自然的，但是不应该仅为了更改代码样式而更改之。 + +代码风格文档也不应该被视为绝对不可违反的规则。如果有一个足够的理由反对这种 +样式（例如为了80列限制拆分行会导致可读性大大降低），那么就这样做吧。 + +注意您还可以使用 ``clang-format`` 工具来帮助您处理这些规则，快速自动重新格式 +化部分代码，和审阅完整的文件以发现代码样式错误、拼写错误和可能的改进。它还 +可以方便地排序 ``#includes`` 、对齐变量/宏、重排文本和其他类似任务。有关详细 +信息，请参阅文档 :ref:`Documentation/process/clang-format.rst <clangformat>` 抽象层 ****** 计算机科学教授教学生以灵活性和信息隐藏的名义广泛使用抽象层。当然，内核广泛 -地使用了抽象；任何涉及数百万行代码的项目都不能做到这一点并存活下来。但经验 -表明，过度或过早的抽象可能和过早的优化一样有害。抽象应用于所需的级别， +地使用了抽象；任何涉及数百万行代码的项目都必须做到这一点以存续下来。但经验 +表明，过度或过早的抽象可能和过早的优化一样有害。抽象应用在适当层级， 不要过度。 -在一个简单的级别上，考虑一个函数的参数，该参数总是由所有调用方作为零传递。 -我们可以保留这个论点: 以防有人最终需要使用它提供的额外灵活性。不过，到那时， -实现这个额外参数的代码很有可能以某种从未被注意到的微妙方式被破坏——因为它从 -未被使用过。或者，当需要额外的灵活性时，它不会以符合程序员早期期望的方式来 -这样做。内核开发人员通常会提交补丁来删除未使用的参数；一般来说，首先不应该 -添加这些参数。 +简单点，先考虑一个调用时始终只有一个参数且总为零的函数。我们可以保留这个参数， +以在需要使用它时提供的额外灵活性。不过，在那时实现了这个额外参数的代码很有 +可能以某种从未被注意到的微妙方式被破坏——因为它从未被使用过。或者当需要额外 +的灵活性时，它并未以符合程序员当初期望的方式来实现。内核开发人员通常会提交 +补丁来删除未使用的参数；一般来说，一开始就不应该添加这些参数。 -隐藏硬件访问的抽象层——通常允许大量的驱动程序在多个操作系统中使用——尤其不受 +隐藏硬件访问的抽象层——通常为了允许大量的驱动程序兼容多个操作系统——尤其不受 欢迎。这样的层使代码变得模糊，可能会造成性能损失；它们不属于Linux内核。 -另一方面，如果您发现自己从另一个内核子系统复制了大量的代码，那么现在是时候 -问一下，事实上，将这些代码中的一些提取到单独的库中，或者在更高的层次上实现 -这些功能是否有意义。在整个内核中复制相同的代码没有价值。 +另一方面，如果您发现自己从另一个内核子系统复制了大量的代码，那么是时候 +了解一下：是否需要将这些代码中的部分提取到单独的库中，或者在更高的层次上 +实现这些功能。在整个内核中复制相同的代码没有价值。 #ifdef 和预处理 *************** -C预处理器似乎给一些C程序员带来了强大的诱惑，他们认为它是一种有效地将大量灵 -活性编码到源文件中的方法。但是预处理器不是C，大量使用它会导致代码对其他人来 -说更难读取，对编译器来说更难检查正确性。大量的预处理器几乎总是代码需要一些 +C预处理器似乎给一些C程序员带来了强大的诱惑，他们认为它是一种将大量灵活性加入 +源代码中的方法。但是预处理器不是C，大量使用它会导致代码对其他人来说更难阅读， +对编译器来说更难检查正确性。使用了大量预处理器几乎总是代码需要一些 清理工作的标志。 -使用ifdef的条件编译实际上是一个强大的功能，它在内核中使用。但是很少有人希望 -看到代码被大量地撒上ifdef块。作为一般规则，ifdef的使用应尽可能限制在头文件 -中。有条件编译的代码可以限制函数，如果代码不存在，这些函数就会变成空的。然后 -编译器将悄悄地优化对空函数的调用。结果是代码更加清晰，更容易理解。 +使用#ifdef的条件编译实际上是一个强大的功能，它在内核中使用。但是很少有人希望 +看到代码被铺满#ifdef块。一般规定，ifdef的使用应尽可能限制在头文件中。条件 +编译代码可以限制函数，如果代码不存在，这些函数就直接变成空的。然后编译器将 +悄悄地优化对空函数的调用。使得代码更加清晰，更容易理解。 -C预处理器宏存在许多危险，包括可能对具有副作用且没有类型安全性的表达式进行多 -重评估。如果您试图定义宏，请考虑创建一个内联函数。结果相同的代码，但是内联 -函数更容易读取，不会多次计算其参数，并且允许编译器对参数和返回值执行类型检查。 +C预处理器宏存在许多危险性，包括可能对具有副作用且没有类型安全的表达式进行多 +重评估。如果您试图定义宏，请考虑创建一个内联函数替代。结果相同的代码，内联 +函数更容易阅读，不会多次计算其参数，并且允许编译器对参数和返回值执行类型检查。 内联函数 ******** 不过，内联函数本身也存在风险。程序员可以倾心于避免函数调用和用内联函数填充源 文件所固有的效率。然而，这些功能实际上会降低性能。因为它们的代码在每个调用站 -点都被复制，所以它们最终会增加编译内核的大小。反过来，这会对处理器的内存缓存 -造成压力，从而大大降低执行速度。通常，内联函数应该非常小，而且相对较少。毕竟， -函数调用的成本并不高；大量内联函数的创建是过早优化的典型例子。 +点都被复制一遍，所以最终会增加编译内核的大小。此外，这也对处理器的内存缓存 +造成压力，从而大大降低执行速度。通常内联函数应该非常小，而且相对较少。毕竟 +函数调用的成本并不高；大量创建内联函数是过早优化的典型例子。 -一般来说，内核程序员会忽略缓存效果，这会带来危险。在开始的数据结构课程中，经 -典的时间/空间权衡通常不适用于当代硬件。空间就是时间，因为一个大的程序比一个 +一般来说，内核程序员会自冒风险忽略缓存效果。在数据结构课程开头中的经典 +时间/空间权衡通常不适用于当代硬件。空间 *就是* 时间，因为一个大的程序比一个 更紧凑的程序运行得慢。 -最近的编译器在决定一个给定函数是否应该被内联方面扮演着越来越积极的角色。 -因此，“inline”关键字的自由放置可能不仅仅是过度的，它也可能是无关的。 +较新的编译器越来越激进地决定一个给定函数是否应该内联。因此，随意放置使用 +“inline”关键字可能不仅仅是过度的，也可能是无用的。 锁 ** -2006年5月，“deviceescape”网络堆栈在GPL下发布，并被纳入主线内核。这是一个受 -欢迎的消息；对Linux中无线网络的支持充其量被认为是不合格的，而deviceescape -堆栈提供了修复这种情况的承诺。然而，直到2007年6月（2.6.22），这段代码才真 +2006年5月，“deviceescape”网络堆栈在前呼后拥下以GPL发布，并被纳入主线内核。 +这是一个受欢迎的消息；Linux中对无线网络的支持充其量被认为是不合格的，而 +Deviceescape堆栈承诺修复这种情况。然而直到2007年6月（2.6.22），这段代码才真 正进入主线。发生了什么？ -这段代码显示了许多闭门造车的迹象。但一个特别大的问题是，它并不是设计用于多 -处理器系统。在合并这个网络堆栈（现在称为mac80211）之前，需要对其进行一个锁 -方案的改造。 +这段代码出现了许多闭门造车的迹象。但一个大麻烦是，它并不是为多处理器系统而 +设计。在合并这个网络堆栈（现在称为mac80211）之前，需要对其进行一个锁方案的 +改造。 曾经，Linux内核代码可以在不考虑多处理器系统所带来的并发性问题的情况下进行 -开发。然而，现在，这个文件是写在双核笔记本电脑上的。即使在单处理器系统上， +开发。然而现在，这个文档就是在双核笔记本电脑上写的。即使在单处理器系统上， 为提高响应能力所做的工作也会提高内核内的并发性水平。编写内核代码而不考虑锁 -的日子已经过去很长了。 +的日子早已远去。 可以由多个线程并发访问的任何资源（数据结构、硬件寄存器等）必须由锁保护。新 -的代码应该记住这一要求；事后改装锁是一项相当困难的任务。内核开发人员应该花 -时间充分了解可用的锁原语，以便为作业选择正确的工具。显示对并发性缺乏关注的 -代码进入主线将很困难。 +的代码应该谨记这一要求；事后修改锁是一项相当困难的任务。内核开发人员应该花 +时间充分了解可用的锁原语，以便为工作选择正确的工具。对并发性缺乏关注的代码 +很难进入主线。 回归 **** -最后一个值得一提的危险是：它可能会引起改变（这可能会带来很大的改进），从而 -导致现有用户的某些东西中断。这种变化被称为“回归”，回归已经成为主线内核最不 -受欢迎的。除少数例外情况外，如果回归不能及时修正，会导致回归的变化将被取消。 -最好首先避免回归。 +最后一个值得一提的危险是回归：它可能会引起导致现有用户的某些东西中断的改变 +（这也可能会带来很大的改进）。这种变化被称为“回归”，回归已经成为主线内核 +最不受欢迎的问题。除了少数例外情况，如果回归不能及时修正，会导致回归的修改 +将被取消。最好首先避免回归发生。 -人们常常争论，如果回归让更多人可以工作，远超过产生问题，那么回归是合理的。 -如果它破坏的一个系统却为十个系统带来新的功能，为什么不进行更改呢？2007年7月， +人们常常争论，如果回归带来的功能远超过产生的问题，那么回归是否为可接受的。 +如果它破坏了一个系统却为十个系统带来新的功能，为何不改改态度呢？2007年7月， Linus对这个问题给出了最佳答案: :: - 所以我们不会通过引入新问题来修复错误。那样的谎言很疯狂，没有人知道 - 你是否真的有进展。是前进两步，后退一步，还是向前一步，向后两步？ + + 所以我们不会通过引入新问题来修复错误。这种方式是靠不住的，没人知道 + 是否真的有进展。是前进两步、后退一步，还是前进一步、后退两步？ （http://lwn.net/articles/243460/） -一种特别不受欢迎的回归类型是用户空间ABI的任何变化。一旦接口被导出到用户空间， +特别不受欢迎的一种回归类型是用户空间ABI的任何变化。一旦接口被导出到用户空间， 就必须无限期地支持它。这一事实使得用户空间接口的创建特别具有挑战性：因为它们 -不能以不兼容的方式进行更改，所以必须第一次正确地进行更改。因此，用户空间界面 -总是需要大量的思考、清晰的文档和广泛的审查。 +不能以不兼容的方式进行更改，所以必须一次就对。因此，用户空间接口总是需要大量 +的思考、清晰的文档和广泛的审查。 代码检查工具 @@ -157,13 +162,13 @@ Linus对这个问题给出了最佳答案: 至少目前，编写无错误代码仍然是我们中很少人能达到的理想状态。不过，我们希望做 的是，在代码进入主线内核之前，尽可能多地捕获并修复这些错误。为此，内核开发人 -员已经组装了一系列令人印象深刻的工具，可以自动捕获各种各样的模糊问题。计算机 +员已经提供了一系列令人印象深刻的工具，可以自动捕获各种各样的隐藏问题。计算机 发现的任何问题都是一个以后不会困扰用户的问题，因此，只要有可能，就应该使用 自动化工具。 -第一步只是注意编译器产生的警告。当代版本的GCC可以检测（并警告）大量潜在错误。 -通常，这些警告都指向真正的问题。提交以供审阅的代码通常不会产生任何编译器警告。 -在消除警告时，注意了解真正的原因，并尽量避免“修复”，使警告消失而不解决其原因。 +第一步是注意编译器产生的警告。当前版本的GCC可以检测（并警告）大量潜在错误。 +通常，这些警告都指向真正的问题。提交以供审阅的代码一般不会产生任何编译器警告。 +在消除警告时，注意了解真正的原因，并尽量避免仅“修复”使警告消失而不解决其原因。 请注意，并非所有编译器警告都默认启用。使用“make KCFLAGS=-W”构建内核以 获得完整集合。 @@ -172,45 +177,43 @@ Linus对这个问题给出了最佳答案: 子菜单中。对于任何用于开发或测试目的的内核，都应该启用其中几个选项。特别是， 您应该打开： - - 启用 ENABLE_MUST_CHECK and FRAME_WARN 以获得一组额外的警告，以解决使用不 - 推荐使用的接口或忽略函数的重要返回值等问题。这些警告生成的输出可能是冗长 - 的，但您不必担心来自内核其他部分的警告。 + - FRAME_WARN 获取大于给定数量的堆栈帧的警告。 + 这些警告生成的输出可能比较冗长，但您不必担心来自内核其他部分的警告。 - - DEBUG_OBJECTS 将添加代码，以跟踪内核创建的各种对象的生存期，并在出现问题时 - 发出警告。如果要添加创建（和导出）自己的复杂对象的子系统，请考虑添加对对象 - 调试基础结构的支持。 + - DEBUG_OBJECTS 将添加代码以跟踪内核创建的各种对象的生命周期，并在出现问题 + 时发出警告。如果你要添加创建（和导出）关于其自己的复杂对象的子系统，请 + 考虑打开对象调试基础结构的支持。 - DEBUG_SLAB 可以发现各种内存分配和使用错误；它应该用于大多数开发内核。 - - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP and DEBUG_MUTEXES 会发现许多常见的 - 锁定错误. + - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP 和 DEBUG_MUTEXES 会发现许多常见的 + 锁错误。 -还有很多其他调试选项，其中一些将在下面讨论。其中一些具有显著的性能影响，不应 -一直使用。但是，在学习可用选项上花费的一些时间可能会在短期内得到多次回报。 +还有很多其他调试选项，其中一些将在下面讨论。其中一些有显著的性能影响，不应 +一直使用。在学习可用选项上花费一些时间，可能会在短期内得到许多回报。 -其中一个较重的调试工具是锁定检查器或“lockdep”。该工具将跟踪系统中每个锁 +其中一个较重的调试工具是锁检查器或“lockdep”。该工具将跟踪系统中每个锁 （spinlock或mutex）的获取和释放、获取锁的相对顺序、当前中断环境等等。然后， -它可以确保总是以相同的顺序获取锁，相同的中断假设适用于所有情况，等等。换句话 -说，lockdep可以找到许多场景，在这些场景中，系统很少会死锁。在部署的系统中， -这种问题可能会很痛苦（对于开发人员和用户而言）；LockDep允许提前以自动方式 -发现问题。具有任何类型的非普通锁定的代码在提交包含前应在启用lockdep的情况 -下运行。 +它可以确保总是以相同的顺序获取锁，相同的中断假设适用于所有情况等等。换句话 +说，lockdep可以找到许多导致系统死锁的场景。在部署的系统中，这种问题可能会 +很痛苦（对于开发人员和用户而言）；LockDep允许提前以自动方式发现问题。具有 +任何类型的非普通锁的代码在提交合并前应在启用lockdep的情况下运行测试。 作为一个勤奋的内核程序员，毫无疑问，您将检查任何可能失败的操作（如内存分配） -的返回状态。然而，事实上，最终的故障恢复路径可能完全没有经过测试。未测试的 -代码往往会被破坏；如果所有这些错误处理路径都被执行了几次，那么您可能对代码 +的返回状态。然而，事实上，最终的故障复现路径可能完全没有经过测试。未测试的 +代码往往会出问题；如果所有这些错误处理路径都被执行了几次，那么您可能对代码 更有信心。 内核提供了一个可以做到这一点的错误注入框架，特别是在涉及内存分配的情况下。 -启用故障注入后，内存分配的可配置百分比将失败；这些失败可以限制在特定的代码 +启用故障注入后，内存分配的可配置失败的百分比；这些失败可以限定在特定的代码 范围内。在启用了故障注入的情况下运行，程序员可以看到当情况恶化时代码如何响 应。有关如何使用此工具的详细信息，请参阅 Documentation/fault-injection/fault-injection.rst。 -使用“sparse”静态分析工具可以发现其他类型的错误。对于sparse，可以警告程序员 -用户空间和内核空间地址之间的混淆、big endian和small endian数量的混合、在需 -要一组位标志的地方传递整数值等等。sparse必须单独安装(如果您的分发服务器没 -有将其打包，可以在 https://sparse.wiki.kernel.org/index.php/Main_page)找到, +“sparse”静态分析工具可以发现其他类型的错误。sparse可以警告程序员用户空间 +和内核空间地址之间的混淆、大端序与小端序的混淆、在需要一组位标志的地方传递 +整数值等等。sparse必须单独安装(如果您的分发服务器没有将其打包， +可以在 https://sparse.wiki.kernel.org/index.php/Main_page 找到）, 然后可以通过在make命令中添加“C=1”在代码上运行它。 “Coccinelle”工具 :ref:`http://coccinelle.lip6.fr/ <devtools_coccinelle>` @@ -221,8 +224,8 @@ scripts/coccinelle目录下已经打包了相当多的内核“语义补丁” 其他类型的可移植性错误最好通过为其他体系结构编译代码来发现。如果没有S/390系统 -或Blackfin开发板，您仍然可以执行编译步骤。可以在以下位置找到一组用于x86系统的 -大型交叉编译器： +或Blackfin开发板，您仍然可以执行编译步骤。可以在以下位置找到一大堆用于x86系统的 +交叉编译器： https://www.kernel.org/pub/tools/crosstool/ @@ -233,22 +236,22 @@ scripts/coccinelle目录下已经打包了相当多的内核“语义补丁” 文档通常比内核开发规则更为例外。即便如此，足够的文档将有助于简化将新代码合并 到内核中的过程，使其他开发人员的生活更轻松，并对您的用户有所帮助。在许多情况 -下，文件的添加已基本上成为强制性的。 +下，添加文档已基本上是强制性的。 任何补丁的第一个文档是其关联的变更日志。日志条目应该描述正在解决的问题、解决 方案的形式、处理补丁的人员、对性能的任何相关影响，以及理解补丁可能需要的任何 -其他内容。确保changelog说明了为什么补丁值得应用；大量开发人员未能提供这些信息。 +其他内容。确保变更日志说明了*为什么*补丁值得应用；大量开发者未能提供这些信息。 -任何添加新用户空间界面的代码（包括新的sysfs或/proc文件）都应该包含该界面的 -文档，该文档使用户空间开发人员能够知道他们在使用什么。请参阅 -Documentation/ABI/README，了解如何格式化此文档以及需要提供哪些信息。 +任何添加新用户空间接口的代码——包括新的sysfs或/proc文件——都应该包含该接口 +的文档，该文档使用户空间开发人员能够知道他们在使用什么。请参阅 +Documentation/ABI/README，了解如何此文档格式以及需要提供哪些信息。 -文件 :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>` -描述了内核的所有引导时间参数。任何添加新参数的补丁都应该向该文件添加适当的 +文档 :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>` +描述了内核的所有引导时间参数。任何添加新参数的补丁都应该向该文档添加适当的 条目。 -任何新的配置选项都必须附有帮助文本，帮助文本清楚地解释了这些选项以及用户可能 -希望何时选择它们。 +任何新的配置选项都必须附有帮助文本，帮助文本需清楚地解释这些选项以及用户可能 +希望何时使用它们。 许多子系统的内部API信息通过专门格式化的注释进行记录；这些注释可以通过 “kernel-doc”脚本以多种方式提取和格式化。如果您在具有kerneldoc注释的子系统中 @@ -257,31 +260,31 @@ Documentation/ABI/README，了解如何格式化此文档以及需要提供哪 来说是一个有用的活动。这些注释的格式以及如何创建kerneldoc模板的一些信息可以在 :ref:`Documentation/doc-guide/ <doc_guide>` 上找到。 -任何阅读大量现有内核代码的人都会注意到，注释的缺失往往是最值得注意的。再一次， -对新代码的期望比过去更高；合并未注释的代码将更加困难。这就是说，人们几乎不希望 -用语言注释代码。代码本身应该是可读的，注释解释了更微妙的方面。 +任何阅读大量现有内核代码的人都会注意到，注释的缺失往往是最值得注意的。同时， +对新代码的要求比过去更高；合并未注释的代码将更加困难。这就是说，人们并不期望 +详细注释的代码。代码本身应该是自解释的，注释阐释了更微妙的方面。 某些事情应该总是被注释。使用内存屏障时，应附上一行文字，解释为什么需要设置内存 -屏障。数据结构的锁定规则通常需要在某个地方解释。一般来说，主要数据结构需要全面 -的文档。应该指出单独代码位之间不明显的依赖性。任何可能诱使代码看门人进行错误的 -“清理”的事情都需要一个注释来说明为什么要这样做。等等。 +屏障。数据结构的锁规则通常需要在某个地方解释。一般来说，主要数据结构需要全面 +的文档。应该指出代码中分立的位之间不明显的依赖性。任何可能诱使代码管理人进行 +错误的“清理”的事情都需要一个注释来说明为什么要这样做。等等。 内部API更改 ----------- -内核提供给用户空间的二进制接口不能被破坏，除非在最严重的情况下。相反，内核的 -内部编程接口是高度流动的，当需要时可以更改。如果你发现自己不得不处理一个内核 -API，或者仅仅因为它不满足你的需求而不使用特定的功能，这可能是API需要改变的一 -个标志。作为内核开发人员，您有权进行此类更改。 +内核提供给用户空间的二进制接口不能被破坏，除非逼不得已。而内核的内部编程接口 +是高度流动的，当需要时可以更改。如果你发现自己不得不处理一个内核API，或者仅 +仅因为它不满足你的需求导致无法使用特定的功能，这可能是API需要改变的一个标志。 +作为内核开发人员，您有权进行此类更改。 -当然, 可以进行API更改，但它们必须是合理的。因此，任何进行内部API更改的补丁都 -应该附带一个关于更改内容和必要原因的描述。这种变化也应该分解成一个单独的补丁， -而不是埋在一个更大的补丁中。 +的确可以进行API更改，但更改必须是合理的。因此任何进行内部API更改的补丁都应该 +附带关于更改内容和必要原因的描述。这种变化也应该拆分成一个单独的补丁，而不是 +埋在一个更大的补丁中。 另一个要点是，更改内部API的开发人员通常要负责修复内核树中被更改破坏的任何代码。 -对于一个广泛使用的函数，这个职责可以导致成百上千的变化，其中许多变化可能与其他 -开发人员正在做的工作相冲突。不用说，这可能是一项大工作，所以最好确保理由是 +对于一个广泛使用的函数，这个责任可以导致成百上千的变化，其中许多变化可能与其他 +开发人员正在做的工作相冲突。不用说，这可能是一项大工程，所以最好确保理由是 可靠的。请注意，coccinelle工具可以帮助进行广泛的API更改。 在进行不兼容的API更改时，应尽可能确保编译器捕获未更新的代码。这将帮助您确保找 diff --git a/Documentation/translations/zh_CN/process/5.Posting.rst b/Documentation/translations/zh_CN/process/5.Posting.rst index 9ff9945f918c..b0c65614844d 100644 --- a/Documentation/translations/zh_CN/process/5.Posting.rst +++ b/Documentation/translations/zh_CN/process/5.Posting.rst @@ -1,150 +1,157 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/5.Posting.rst <development_posting>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> .. _cn_development_posting: 发布补丁 ======== -迟早，当您的工作准备好提交给社区进行审查，并最终包含到主线内核中时。不出所料， +您的工作迟早会准备好提交给社区进行审查，并最终包含到主线内核中。毫不稀奇， 内核开发社区已经发展出一套用于发布补丁的约定和过程；遵循这些约定和过程将使 -参与其中的每个人的生活更加轻松。本文件将试图合理详细地涵盖这些期望；更多信息 -也可在以下文件中找到 -:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`, -:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` -和 :ref:`Documentation/translations/zh_CN/process/submit-checklist.rst <cn_submitchecklist>`. +参与其中的每个人的生活更加轻松。本文档试图描述这些约定的部分细节；更多信息 +也可在以下文档中找到 +:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`， +:ref:`Documentation/translations/zh_CN/process/submitting-drivers.rst <cn_submittingdrivers>` +和 :ref:`Documentation/translations/zh_CN/process/submit-checklist.rst <cn_submitchecklist>`。 何时邮寄 -------- -在补丁完全“准备好”之前，有一个不断的诱惑来避免发布补丁。对于简单的补丁， -这不是问题。但是，如果正在完成的工作很复杂，那么在工作完成之前从社区获得 -反馈就可以获得很多好处。因此，您应该考虑发布正在进行的工作，甚至使Git树 -可用，以便感兴趣的开发人员可以随时赶上您的工作。 +在补丁完全“准备好”之前，避免发布补丁是一种持续的诱惑。对于简单的补丁，这 +不是问题。但是如果正在完成的工作很复杂，那么在工作完成之前从社区获得反馈就 +可以获得很多好处。因此，您应该考虑发布正在进行的工作，甚至维护一个可用的Git +树，以便感兴趣的开发人员可以随时赶上您的工作。 -当发布还没有准备好包含的代码时，最好在发布本身中这样说。还应提及任何有待完成 -的主要工作和任何已知问题。很少有人会看到那些被认为是半生不熟的补丁，但是那些 -人会想到他们可以帮助你把工作推向正确的方向。 +当发布中有尚未准备好被包含的代码，最好在发布中说明。还应提及任何有待完成的 +主要工作和任何已知问题。很少有人会愿意看那些被认为是半生不熟的补丁，但是 +那些愿意的人会带着他们的点子来一起帮助你把工作推向正确的方向。 创建补丁之前 ------------ -在考虑将补丁发送到开发社区之前，有许多事情应该做。这些包括： +在考虑将补丁发送到开发社区之前，有许多事情应该做。包括： - - 尽可能地测试代码。利用内核的调试工具，确保内核使用所有合理的配置选项组合 - 进行构建，使用跨编译器为不同的体系结构进行构建等。 + - 尽可能地测试代码。利用内核的调试工具，确保内核使用了所有可能的配置选项组合 + 进行构建，使用交叉编译器为不同的体系结构进行构建等。 - - 确保您的代码符合内核编码风格指南。 + - 确保您的代码符合内核代码风格指南。 - 您的更改是否具有性能影响？如果是这样，您应该运行基准测试来显示您的变更的 影响（或好处）；结果的摘要应该包含在补丁中。 - 确保您有权发布代码。如果这项工作是为雇主完成的，雇主对这项工作具有所有权， - 并且必须同意根据GPL对其进行放行。 + 并且必须同意根据GPL对其进行发布。 一般来说，在发布代码之前进行一些额外的思考，几乎总是能在短时间内得到回报。 补丁准备 -------- -准备发布补丁可能是一个惊人的工作量，但再次尝试节省时间在这里通常是不明智的， -即使在短期内。 +准备补丁发布的工作量可能很惊人，但在此尝试节省时间通常是不明智的，即使在短期 +内亦然。 -必须针对内核的特定版本准备补丁。作为一般规则，补丁程序应该基于Linus的Git树中 -的当前主线。当以主线为基础时，从一个众所周知的发布点开始——一个稳定的或RC的 -发布——而不是在一个主线分支任意点。 +必须针对内核的特定版本准备补丁。一般来说，补丁应该基于Linus的Git树中的当前 +主线。当以主线为基础时，请从一个众所周知的发布点开始——如稳定版本或 -rc +版本发布点——而不是在一个任意的主线分支点。 -但是，可能需要针对-mm、linux-next或子系统树生成版本，以便于更广泛的测试和审查。 -根据补丁的区域以及其他地方的情况，针对这些其他树建立补丁可能需要大量的工作来 +也可能需要针对-mm、linux-next或子系统树生成版本，以便于更广泛的测试和审查。 +根据补丁的区域以及其他地方的情况，针对其他树建立的补丁可能需要大量的工作来 解决冲突和处理API更改。 只有最简单的更改才应格式化为单个补丁；其他所有更改都应作为一系列逻辑更改进行。 分割补丁是一门艺术；一些开发人员花了很长时间来弄清楚如何按照社区期望的方式来 -做。然而，有一些经验法则可以大大帮助： +分割。不过，这些经验法则也许有帮助： - - 您发布的补丁程序系列几乎肯定不会是工作系统中的一系列更改。相反，您所做的 - 更改需要在最终形式中加以考虑，然后以有意义的方式进行拆分。开发人员对离散的、 - 自包含的更改感兴趣，而不是您获取这些更改的路径。 + - 您发布的补丁系列几乎肯定不会是开发过程中版本控制系统中的一系列更改。相反， + 需要对您所做更改的最终形式加以考虑，然后以有意义的方式进行拆分。开发人员对 + 离散的、自包含的更改感兴趣，而不是您创造这些更改的原始路径。 - - 每个逻辑上独立的变更都应该格式化为单独的补丁。这些更改可以是小的（“向此 - 结构添加字段”）或大的（例如，添加一个重要的新驱动程序），但它们在概念上 - 应该是小的，并且可以接受一行描述。每个补丁都应该做一个特定的更改，可以单独 - 检查并验证它所做的事情。 + - 每个逻辑上独立的变更都应该格式化为单独的补丁。这些更改可以是小的（如“向 + 此结构体添加字段”）或大的（如添加一个重要的新驱动程序），但它们在概念上 + 应该是小的，并且可以在一行内简述。每个补丁都应该做一个特定的、可以单独 + 检查并验证它所做的事情的更改。 - - 作为重申上述准则的一种方法：不要在同一补丁中混合不同类型的更改。如果一个 - 补丁修复了一个关键的安全漏洞，重新排列了一些结构，并重新格式化了代码，那么 - 很有可能它会被忽略，而重要的修复将丢失。 + - 换种方式重申上述准则，也就是说：不要在同一补丁中混合不同类型的更改。如果 + 一个补丁修复了一个关键的安全漏洞，又重新排列了一些结构，还重新格式化了代 + 码，那么它很有可能会被忽略，从而导致重要的修复丢失。 - - 每个补丁都应该产生一个内核，它可以正确地构建和运行；如果补丁系列在中间被 - 中断，那么结果应该仍然是一个工作的内核。补丁系列的部分应用是使用 - “git bisct”工具查找回归的一个常见场景；如果结果是一个损坏的内核，那么对于 - 那些从事追踪问题的高尚工作的开发人员和用户来说，将使他们的生活更加艰难。 + - 每个补丁都应该能创建一个可以正确地构建和运行的内核；如果补丁系列在中间被 + 断开，那么结果仍应是一个正常工作的内核。部分应用一系列补丁是使用 + “git bisct”工具查找回归的一个常见场景；如果结果是一个损坏的内核，那么将使 + 那些从事追踪问题的高尚工作的开发人员和用户的生活更加艰难。 - - 不过，不要过分。一位开发人员曾经将一组编辑内容作为500个单独的补丁发布到一个 - 文件中，这并没有使他成为内核邮件列表中最受欢迎的人。一个补丁可以相当大， - 只要它仍然包含一个单一的逻辑变更。 + - 不要过分分割。一位开发人员曾经将一组针对单个文件的编辑分成500个单独的补丁 + 发布，这并没有使他成为内核邮件列表中最受欢迎的人。一个补丁可以相当大， + 只要它仍然包含一个单一的 *逻辑* 变更。 - - 用一系列补丁添加一个全新的基础设施是很有诱惑力的，但是在系列中的最后一个 - 补丁启用整个补丁之前，该基础设施是不使用的。如果可能的话，应该避免这种 - 诱惑；如果这个系列增加了回归，那么二分法将指出最后一个补丁是导致问题的 - 补丁，即使真正的bug在其他地方。只要有可能，添加新代码的补丁程序应该立即 - 激活该代码。 + - 用一系列补丁添加一个全新的基础设施，但是该设施在系列中的最后一个补丁启用 + 整个变更之前不能使用，这看起来很诱人。如果可能的话，应该避免这种诱惑； + 如果这个系列增加了回归，那么二分法将指出最后一个补丁是导致问题的补丁， + 即使真正的bug在其他地方。只要有可能，添加新代码的补丁程序应该立即激活该 + 代码。 -创建完美补丁系列的工作可能是一个令人沮丧的过程，在完成“真正的工作”之后需要花费 -大量的时间和思考。但是，如果做得好，这是一段很好的时间。 +创建完美补丁系列的工作可能是一个令人沮丧的过程，在完成“真正的工作”之后需要 +花费大量的时间和思考。但是如果做得好，花费的时间就是值得的。 补丁格式和更改日志 ------------------ 所以现在你有了一系列完美的补丁可以发布，但是这项工作还没有完成。每个补丁都 -需要被格式化成一条消息，它可以快速而清晰地将其目的传达给世界其他地方。为此， +需要被格式化成一条消息，以快速而清晰地将其目的传达到世界其他地方。为此， 每个补丁将由以下部分组成： - - 命名补丁作者的可选“from”行。只有当你通过电子邮件传递别人的补丁时，这一行 - 才是必要的，但是如果有疑问，添加它不会有任何伤害。 + - 可选的“From”行，表明补丁作者。只有当你通过电子邮件发送别人的补丁时，这一行 + 才是必须的，但是为防止疑问加上它也不会有什么坏处。 - - 一行描述补丁的作用。对于没有其他上下文的读者来说，此消息应该足够了解补丁 - 的范围；这是将在“短格式”变更日志中显示的行。此消息通常首先用相关的子系统 - 名称格式化，然后是补丁的目的。例如： + - 一行描述，说明补丁的作用。对于在没有其他上下文的情况下看到该消息的读者来说， + 该消息应足以确定修补程序的范围；此行将显示在“short form（简短格式）”变更 + 日志中。此消息通常需要先加上子系统名称前缀，然后是补丁的目的。例如： - :: + :: - gpio: fix build on CONFIG_GPIO_SYSFS=n + gpio: fix build on CONFIG_GPIO_SYSFS=n - - 一个空白行，后面是补丁内容的详细描述。这个描述可以是必需的；它应该说明补丁 + - 一行空白，后接补丁内容的详细描述。此描述可以是任意需要的长度；它应该说明补丁 的作用以及为什么它应该应用于内核。 - - 一个或多个标记行，至少有一个由补丁作者的：signed-off-by 签名。签名将在下面 - 更详细地描述。 + - 一个或多个标记行，至少有一个由补丁作者的 Signed-off-by 签名。标记将在下面 + 详细描述。 -上面的项目一起构成补丁的变更日志。写一篇好的变更日志是一门至关重要但常常被 -忽视的艺术；值得花一点时间来讨论这个问题。当你写一个变更日志时，你应该记住 -有很多不同的人会读你的话。其中包括子系统维护人员和审查人员，他们需要决定是否 -应该包括补丁，分销商和其他维护人员试图决定是否应该将补丁反向移植到其他内核， -bug搜寻人员想知道补丁是否负责他们正在追查的问题，想知道内核如何变化的用户。 -等等。一个好的变更日志以最直接和最简洁的方式向所有这些人传达所需的信息。 +上面的项目一起构成补丁的变更日志。写一则好的变更日志是一门至关重要但常常被 +忽视的艺术；值得花一点时间来讨论这个问题。当你编写变更日志时，你应该记住有 +很多不同的人会读你的话。其中包括子系统维护人员和审查人员，他们需要决定是否 +应该合并补丁，分销商和其他维护人员试图决定是否应该将补丁反向移植到其他内核， +缺陷搜寻人员想知道补丁是否导致他们正在追查的问题，以及想知道内核如何变化的 +用户等等。一个好的变更日志以最直接和最简洁的方式向所有这些人传达所需的信息。 -为此，总结行应该描述变更的影响和动机，以及在一行约束条件下可能发生的变化。 +在结尾，总结行应该描述变更的影响和动机，以及在一行约束条件下可能发生的变化。 然后，详细的描述可以详述这些主题，并提供任何需要的附加信息。如果补丁修复了 -一个bug，请引用引入该bug的commit（如果可能，请在引用commits时同时提供commit id -和标题）。如果某个问题与特定的日志或编译器输出相关联，请包含该输出以帮助其他 -人搜索同一问题的解决方案。如果更改是为了支持以后补丁中的其他更改，那么就这么 -说。如果更改了内部API，请详细说明这些更改以及其他开发人员应该如何响应。一般 -来说，你越能把自己放在每个阅读你的changelog的人的位置上，changelog（和内核 +一个缺陷，请引用引入该缺陷的提交（如果可能，请在引用提交时同时提供其 id 和 +标题）。如果某个问题与特定的日志或编译器输出相关联，请包含该输出以帮助其他 +人搜索同一问题的解决方案。如果更改是为了支持以后补丁中的其他更改，那么应当 +说明。如果更改了内部API，请详细说明这些更改以及其他开发人员应该如何响应。 +一般来说，你越把自己放在每个阅读你变更日志的人的位置上，变更日志（和内核 作为一个整体）就越好。 -不用说，变更日志应该是将变更提交到修订控制系统时使用的文本。接下来是： +不消说，变更日志是将变更提交到版本控制系统时使用的文本。接下来将是： - - 补丁本身，采用统一的（“-u”）补丁格式。将“-p”选项用于diff将使函数名与更改 - 相关联，从而使结果补丁更容易被其他人读取。 + - 补丁本身，采用统一的（“-u”）补丁格式。使用“-p”选项来diff将使函数名与 + 更改相关联，从而使结果补丁更容易被其他人读取。 -您应该避免在补丁中包括对不相关文件（例如，由构建过程生成的文件或编辑器 -备份文件）的更改。文档目录中的文件“dontdiff”在这方面有帮助；使用“-X”选项将 +您应该避免在补丁中包括与更改不相关文件（例如，构建过程生成的文件或编辑器 +备份文件）。文档目录中的“dontdiff”文件在这方面有帮助；使用“-X”选项将 其传递给diff。 -上面提到的标签用于描述各种开发人员如何与这个补丁的开发相关联。 +上面提到的标签（tag）用于描述各种开发人员如何与这个补丁的开发相关联。 :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` 文档中对它们进行了详细描述；下面是一个简短的总结。每一行的格式如下： @@ -154,87 +161,87 @@ bug搜寻人员想知道补丁是否负责他们正在追查的问题，想知 常用的标签有： - - Signed-off-by: 这是一个开发人员的证明，他或她有权提交补丁以包含到内核中。 - 这是开发来源认证协议，其全文可在 + - Signed-off-by: 这是一个开发人员的证明，证明他或她有权提交补丁以包含到内核 + 中。这表明同意开发者来源认证协议，其全文见 :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` - 中找到，如果没有适当的签字，则不能合并到主线中。 + 如果没有合适的签字，则不能合并到主线中。 - Co-developed-by: 声明补丁是由多个开发人员共同创建的；当几个人在一个补丁上 - 工作时，它用于将属性赋予共同作者（除了 From: 所赋予的作者之外）。因为 - Co-developed-by: 表示作者身份，所以每个共同开发人, 必须紧跟在相关合作作者 - 的签名之后。具体内容和示例可以在以下文件中找到 + 工作时，它用于给出共同作者（除了 From: 所给出的作者之外）。由于 + Co-developed-by: 表示作者身份，所以每个共同开发人，必须紧跟在相关合作作者 + 的Signed-off-by之后。具体内容和示例见以下文件 :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` - Acked-by: 表示另一个开发人员（通常是相关代码的维护人员）同意补丁适合包含 在内核中。 - - Tested-by: 声明指定的人已经测试了补丁并发现它可以工作。 + - Tested-by: 声明某人已经测试了补丁并确认它可以工作。 - - Reviewed-by: 指定的开发人员已经审查了补丁的正确性；有关详细信息，请参阅 + - Reviewed-by: 表示某开发人员已经审查了补丁的正确性；有关详细信息，请参阅 :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` - - Reported-by: 指定报告此补丁修复的问题的用户；此标记用于提供感谢。 + - Reported-by: 指定报告此补丁修复的问题的用户；此标记用于表示感谢。 - - Cc：指定的人收到了补丁的副本，并有机会对此发表评论。 + - Cc：指定某人收到了补丁的副本，并有机会对此发表评论。 -在补丁中添加标签时要小心：只有cc:才适合在没有指定人员明确许可的情况下添加。 +在补丁中添加标签时要小心：只有Cc:才适合在没有指定人员明确许可的情况下添加。 发送补丁 -------- -在邮寄补丁之前，您还需要注意以下几点： +在寄出补丁之前，您还需要注意以下几点： - - 您确定您的邮件发送程序不会损坏补丁吗？有免费的空白更改或由邮件客户端 - 执行的行包装的补丁不会在另一端复原，并且通常不会进行任何详细检查。如果有 - 任何疑问，把补丁寄给你自己，让你自己相信它是完好无损的。 + - 您确定您的邮件发送程序不会损坏补丁吗？被邮件客户端更改空白或修饰了行的补丁 + 无法被另一端接受，并且通常不会进行任何详细检查。如果有任何疑问，先把补丁寄 + 给你自己，让你自己确定它是完好无损的。 :ref:`Documentation/translations/zh_CN/process/email-clients.rst <cn_email_clients>` - 提供了一些有用的提示，可以让特定的邮件客户机工作以发送补丁。 + 提供了一些有用的提示，可以让特定的邮件客户端正常发送补丁。 - - 你确定你的补丁没有愚蠢的错误吗？您应该始终通过scripts/checkpatch.pl运行 - 补丁程序，并解决它提出的投诉。请记住，checkpatch.pl虽然是大量思考内核 - 补丁应该是什么样子的体现，但它并不比您聪明。如果修复checkpatch.pl投诉会 + - 你确定你的补丁没有荒唐的错误吗？您应该始终通过scripts/checkpatch.pl检查 + 补丁程序，并解决它提出的问题。请记住，checkpatch.pl，虽然体现了对内核补丁 + 应该是什么样的大量思考，但它并不比您聪明。如果修复checkpatch.pl给的问题会 使代码变得更糟，请不要这样做。 补丁应始终以纯文本形式发送。请不要将它们作为附件发送；这使得审阅者在答复中更难 引用补丁的部分。相反，只需将补丁直接放到您的消息中。 -邮寄补丁时，重要的是将副本发送给任何可能感兴趣的人。与其他一些项目不同，内核 -鼓励人们错误地发送过多的副本；不要假定相关人员会看到您在邮件列表中的发布。 +寄出补丁时，重要的是将副本发送给任何可能感兴趣的人。与其他一些项目不同，内核 +鼓励人们甚至错误地发送过多的副本；不要假定相关人员会看到您在邮件列表中的发布。 尤其是，副本应发送至： - - 受影响子系统的维护人员。如前所述，维护人员文件是查找这些人员的第一个地方。 + - 受影响子系统的维护人员。如前所述，维护人员文件是查找这些人员的首选地方。 - 其他在同一领域工作的开发人员，尤其是那些现在可能在那里工作的开发人员。使用 git查看还有谁修改了您正在处理的文件，这很有帮助。 - - 如果您对错误报告或功能请求做出响应，也可以抄送原始发送人。 + - 如果您对某错误报告或功能请求做出响应，也可以抄送原始发送人。 - - 将副本发送到相关邮件列表，或者，如果没有其他应用，则发送到Linux内核列表。 + - 将副本发送到相关邮件列表，或者若无相关列表，则发送到linux-kernel列表。 - - 如果您正在修复一个bug，请考虑该修复是否应进入下一个稳定更新。如果是这样， - stable@vger.kernel.org 应该得到补丁的副本。另外，在补丁本身的标签中添加 - 一个“cc:stable@vger.kernel.org”；这将使稳定团队在修复进入主线时收到通知。 + - 如果您正在修复一个缺陷，请考虑该修复是否应进入下一个稳定更新。如果是这样， + 补丁副本也应发到stable@vger.kernel.org 。另外，在补丁本身的标签中添加一个 + “Cc: stable@vger.kernel.org”；这将使稳定版团队在修复进入主线时收到通知。 -当为一个补丁选择接收者时，最好知道你认为谁最终会接受这个补丁并将其合并。虽然 -可以将补丁直接发送给LinusTorvalds并让他合并，但通常情况下不会这样做。Linus -很忙，并且有子系统维护人员负责监视内核的特定部分。通常您会希望维护人员合并您 -的补丁。如果没有明显的维护人员，Andrew Morton通常是最后的补丁目标。 +当为一个补丁选择接收者时，最好清楚你认为谁最终会接受这个补丁并将其合并。虽然 +可以将补丁直接发给Linus Torvalds并让他合并，但通常情况下不会这样做。Linus很 +忙，并且有子系统维护人员负责监视内核的特定部分。通常您会希望维护人员合并您的 +补丁。如果没有明显的维护人员，Andrew Morton通常是最后的补丁接收者。 -补丁需要好的主题行。补丁程序行的规范格式如下： +补丁需要好的主题行。补丁主题行的规范格式如下： :: [PATCH nn/mm] subsys: one-line description of the patch -其中“nn”是补丁的序号，“mm”是系列中补丁的总数，“subsys”是受影响子系统的名称。 -显然，一个单独的补丁可以省略nn/mm。 +其中“nn”是补丁的序号，“mm”是系列中补丁的总数，“subsys”是受影响子系统的 +名称。当然，一个单独的补丁可以省略nn/mm。 -如果您有一系列重要的补丁，那么通常将介绍性描述作为零部分发送。不过，这种约定 -并没有得到普遍遵循；如果您使用它，请记住简介中的信息不会使它进入内核变更日志。 +如果您有一系列重要的补丁，那么通常发送一个简介作为第〇部分。不过，这个约定 +并没有得到普遍遵循；如果您使用它，请记住简介中的信息不会进入内核变更日志。 因此，请确保补丁本身具有完整的变更日志信息。 一般来说，多部分补丁的第二部分和后续部分应作为对第一部分的回复发送，以便它们 在接收端都连接在一起。像git和coilt这样的工具有命令，可以通过适当的线程发送 -一组补丁。但是，如果您有一个长系列，并且正在使用git，请远离–chain reply-to -选项，以避免创建异常深的嵌套。 +一组补丁。但是，如果您有一长串补丁，并正使用git，请不要使用–-chain-reply-to +选项，以避免创建过深的嵌套。 diff --git a/Documentation/translations/zh_CN/process/6.Followthrough.rst b/Documentation/translations/zh_CN/process/6.Followthrough.rst index f509e077e1cb..2a127e737b6a 100644 --- a/Documentation/translations/zh_CN/process/6.Followthrough.rst +++ b/Documentation/translations/zh_CN/process/6.Followthrough.rst @@ -1,145 +1,152 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/6.Followthrough.rst <development_followthrough>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> .. _cn_development_followthrough: 跟进 ==== -在这一点上，您已经遵循了到目前为止给出的指导方针，并且，随着您自己的工程技能 -的增加，已经发布了一系列完美的补丁。即使是经验丰富的内核开发人员也能犯的最大 -错误之一是，认为他们的工作现在已经完成了。事实上，发布补丁意味着进入流程的下 -一个阶段，可能还需要做很多工作。 +此时，您已经遵循了到目前为止给出的指导方针，并且，随着您自己的工程技能的增加， +已经发布了一系列完美的补丁。即使是经验丰富的内核开发人员也能犯的最大错误之一 +是，认为他们的工作现在已经完成了。事实上，发布补丁意味着进入流程的下一个阶段， +可能还需要做很多工作。 -一个补丁在第一次发布时就非常出色，没有改进的余地,这是很罕见的。内核开发流程 -认识到这一事实，因此，它非常注重对已发布代码的改进。作为代码的作者，您应该与 +一个补丁在首次发布时就非常出色、没有改进的余地，这是很罕见的。内核开发流程已 +认识到这一事实，因此它非常注重对已发布代码的改进。作为代码的作者，您应该与 内核社区合作，以确保您的代码符合内核的质量标准。如果不参与这个过程，很可能会 -阻止将补丁包含到主线中。 +无法将补丁合并到主线中。 与审阅者合作 ------------ 任何意义上的补丁都会导致其他开发人员在审查代码时发表大量评论。对于许多开发 -人员来说，与审查人员合作可能是内核开发过程中最令人生畏的部分。但是，如果你 +人员来说，与审阅人员合作可能是内核开发过程中最令人生畏的部分。但是如果你 记住一些事情，生活会变得容易得多： - - 如果你已经很好地解释了你的补丁，评论人员会理解它的价值，以及为什么你会 - 费尽心思去写它。但是这个并不能阻止他们提出一个基本的问题：五年或十年后 - 用这个代码维护一个内核会是什么感觉？你可能被要求做出的许多改变——从编码风格 - 的调整到大量的重写——都来自于对Linux的理解，即从现在起十年后，Linux仍将在 - 开发中。 + - 如果你已经很好地解释了你的补丁，审阅人员会理解它的价值，以及为什么你会 + 费尽心思去写它。但是这个并不能阻止他们提出一个基本的问题：在五年或十年后 + 维护含有此代码的内核会怎么样？你可能被要求做出的许多改变——从编码风格的 + 调整到大量的重写——都来自于对Linux的理解，即从现在起十年后，Linux仍将 + 在开发中。 - 代码审查是一项艰苦的工作，这是一项相对吃力不讨好的工作；人们记得谁编写了 - 内核代码，但对于那些审查它的人来说，几乎没有什么持久的名声。因此，评论 + 内核代码，但对于那些审查它的人来说，几乎没有什么长久的名声。因此，审阅 人员可能会变得暴躁，尤其是当他们看到同样的错误被一遍又一遍地犯下时。如果 - 你得到了一个看起来愤怒、侮辱或完全冒犯你的评论，抵制以同样方式回应的冲动。 - 代码审查是关于代码的，而不是关于人的，代码审查人员不会亲自攻击您。 + 你得到了一个看起来愤怒、侮辱或完全冒犯你的评论，请抑制以同样方式回应的冲动。 + 代码审查是关于代码的，而不是关于人的，代码审阅人员不会亲自攻击您。 - - 同样，代码审查人员也不想以牺牲你雇主的利益为代价来宣传他们雇主的议程。 + - 同样，代码审阅人员也不想以牺牲你雇主的利益为代价来宣传他们雇主的议程。 内核开发人员通常希望今后几年能在内核上工作，但他们明白他们的雇主可能会改 变。他们真的，几乎毫无例外地，致力于创造他们所能做到的最好的内核；他们并 没有试图给雇主的竞争对手造成不适。 -所有这些归根结底都是，当审阅者向您发送评论时，您需要注意他们正在进行的技术 -观察。不要让他们的表达方式或你自己的骄傲阻止这种事情的发生。当你在一个补丁 -上得到评论时，花点时间去理解评论人想说什么。如果可能的话，请修复审阅者要求 -您修复的内容。然后回复审稿人：谢谢他们，并描述你将如何回答他们的问题。 +所有这些归根结底就是，当审阅者向您发送评论时，您需要注意他们正在进行的技术 +评论。不要让他们的表达方式或你自己的骄傲阻止此事。当你在一个补丁上得到评论 +时，花点时间去理解评论人想说什么。如果可能的话，请修复审阅者要求您修复的内 +容。然后回复审阅者：谢谢他们，并描述你将如何回答他们的问题。 请注意，您不必同意审阅者建议的每个更改。如果您认为审阅者误解了您的代码，请 解释到底发生了什么。如果您对建议的更改有技术上的异议，请描述它并证明您对该 -问题的解决方案是正确的。如果你的解释有道理，审稿人会接受的。不过，如果你的 -解释不能证明是有说服力的，尤其是当其他人开始同意审稿人的观点时，请花些时间 -重新考虑一下。你很容易对自己解决问题的方法视而不见，以至于你没有意识到某个 -问题根本是错误的，或者你甚至没有解决正确的问题。 +问题的解决方案是正确的。如果你的解释有道理，审阅者会接受的。不过，如果你的 +解释证明缺乏说服力，尤其是当其他人开始同意审稿人的观点时，请花些时间重新考虑 +一下。你很容易对自己解决问题的方法视而不见，以至于你没有意识到某些东西完全 +是错误的，或者你甚至没有解决正确的问题。 -Andrew Morton建议，每一条不会导致代码更改的评论都应该导致额外的代码注释； -这可以帮助未来的评论人员避免出现第一次出现的问题。 +Andrew Morton建议，每一个不会导致代码更改的审阅评论都应该产生一个额外的代码 +注释；这可以帮助未来的审阅人员避免第一次出现的问题。 -一个致命的错误是忽视评论，希望它们会消失。他们不会走的。如果您在没有对之前 -收到的注释做出响应的情况下重新发布代码，那么很可能会发现补丁毫无用处。 +一个致命的错误是忽视评论，希望它们会消失。它们不会走的。如果您在没有对之前 +收到的评论做出响应的情况下重新发布代码，那么很可能会发现补丁毫无用处。 说到重新发布代码：请记住，审阅者不会记住您上次发布的代码的所有细节。因此， -提醒审查人员以前提出的问题以及您如何处理这些问题总是一个好主意；补丁变更 +提醒审阅人员以前提出的问题以及您如何处理这些问题总是一个好主意；补丁变更 日志是提供此类信息的好地方。审阅者不必搜索列表档案来熟悉上次所说的内容； -如果您帮助他们开始运行，当他们重新访问您的代码时，他们的心情会更好。 +如果您帮助他们直接开始，当他们重新查看您的代码时，心情会更好。 如果你已经试着做正确的事情，但事情仍然没有进展呢？大多数技术上的分歧都可以 -通过讨论来解决，但有时人们只需要做出决定。如果你真的认为这个决定对你不利， -你可以试着向更高的权力上诉。在这篇文章中，更高的权力倾向于Andrew Morton。 -Andrew在内核开发社区中受i很大的尊重；他经常为似乎被绝望地阻塞事情清障。 -尽管如此，对Andrew的呼吁不应轻而易举，也不应在所有其他替代方案都被探索之前 -使用。当然，记住，他也可能不同意你的意见。 +通过讨论来解决，但有时人们仍需要做出决定。如果你真的认为这个决定对你不利， +你可以试着向有更高权力的人上诉。对于本文，更高权力的人是 Andrew Morton 。 +Andrew 在内核开发社区中非常受尊敬；他经常为似乎被绝望阻塞的事情清障。尽管 +如此，不应轻易就直接找 Andrew ，也不应在所有其他替代方案都被尝试之前找他。 +当然，记住，他也可能不同意你的意见。 接下来会发生什么 ---------------- -如果一个补丁被认为是添加到内核中的一件好事，并且一旦大多数审查问题得到解决， -下一步通常是进入子系统维护人员的树中。工作方式因子系统而异；每个维护人员都 -有自己的工作方式。特别是，可能有不止一棵树——一棵树，也许，专门用于计划下一 -个合并窗口的补丁，另一棵树用于长期工作。 +如果一个补丁被认为适合添加到内核中，并且大多数审查问题得到解决，下一步通常 +是进入子系统维护人员的树中。工作方式因子系统而异；每个维护人员都有自己的 +工作方式。特别是可能有不止一棵树——也许一棵树专门用于计划下一个合并窗口的 +补丁，另一棵树用于长期工作。 -对于应用于没有明显子系统树（例如内存管理修补程序）的区域的修补程序，默认树 -通常以-mm结尾。影响多个子系统的补丁也可以最终通过-mm树。 +对于应用到不属于明显子系统树（例如内存管理修补程序）的区域的修补程序，默认树 +通常上溯到-mm。影响多个子系统的补丁也可以最终进入-mm树。 包含在子系统树中可以提高补丁的可见性。现在，使用该树的其他开发人员将默认获 得补丁。子系统树通常也为Linux提供支持，使其内容对整个开发社区可见。在这一点 上，您很可能会从一组新的审阅者那里得到更多的评论；这些评论需要像上一轮那样 -得到回答。 +得到回应。 -在这一点上也会发生什么，这取决于你的补丁的性质，是与其他人正在做的工作发生 +在这时也会发生点什么，这取决于你的补丁的性质，是否与其他人正在做的工作发生 冲突。在最坏的情况下，严重的补丁冲突可能会导致一些工作被搁置，以便剩余的补丁 可以成形并合并。另一些时候，冲突解决将涉及到与其他开发人员合作，可能还会 在树之间移动一些补丁，以确保所有的应用都是干净的。这项工作可能是一件痛苦的 -事情，但要计算您的福祉：在Linux下一棵树出现之前，这些冲突通常只在合并窗口 -中出现，必须迅速解决。现在可以在合并窗口打开之前，在空闲时解决这些问题。 +事情，但也需庆幸现在的幸福：在linux-next树出现之前，这些冲突通常只在合并窗口 +中出现，必须迅速解决。现在可以在合并窗口打开之前的空闲时间解决这些问题。 有朝一日，如果一切顺利，您将登录并看到您的补丁已经合并到主线内核中。祝贺你！ -然而，一旦庆祝活动完成（并且您已经将自己添加到维护人员文件中），就值得记住 -一个重要的小事实：工作仍然没有完成。并入主线带来了自身的挑战。 +然而，一旦庆祝完了（并且您已经将自己添加到维护人员文件中），就一定要记住 +一个重要的小事实：工作仍然没有完成。并入主线也带来了它的挑战。 -首先，补丁的可见性再次提高。可能会有新一轮的开发者评论，他们以前不知道这 -个补丁。忽略它们可能很有诱惑力，因为您的代码不再存在任何被合并的问题。但是， -要抵制这种诱惑，您仍然需要对有问题或建议的开发人员作出响应。 +首先，补丁的可见性再次提高。可能会有以前不知道这个补丁的开发者的新一轮评论。 +忽略它们可能很有诱惑力，因为您的代码不再存在任何被合并的问题。但是，要抵制 +这种诱惑，您仍然需要对有问题或建议的开发人员作出响应。 -不过，更重要的是：将代码包含在主线中会将代码交给更大的一组测试人员。即使您 -为尚未提供的硬件提供了驱动程序，您也会惊讶于有多少人会将您的代码构建到内核 -中。当然，如果有测试人员，也会有错误报告。 +不过，更重要的是：将代码包含在主线中会将代码交给更多的一些测试人员。即使您 +为尚未可用的硬件提供了驱动程序，您也会惊讶于有多少人会将您的代码构建到内核 +中。当然，如果有测试人员，也可能会有错误报告。 -最糟糕的错误报告是回归。如果你的补丁导致回归，你会发现很多不舒服的眼睛盯着 -你；回归需要尽快修复。如果您不愿意或无法修复回归（其他人都不会为您修复）， +最糟糕的错误报告是回归。如果你的补丁导致回归，你会发现多到让你不舒服的眼睛盯 +着你；回归需要尽快修复。如果您不愿意或无法修复回归（其他人都不会为您修复）， 那么在稳定期内，您的补丁几乎肯定会被移除。除了否定您为使补丁进入主线所做的 -所有工作之外，如果由于未能修复回归而取消补丁，很可能会使将来的工作更难合并。 +所有工作之外，如果由于未能修复回归而取消补丁，很可能会使将来的工作更难被合并。 -在处理完任何回归之后，可能还有其他普通的bug需要处理。稳定期是修复这些错误并 -确保代码在主线内核版本中的首次发布尽可能可靠的最好机会。所以，请回答错误 +在处理完任何回归之后，可能还有其他普通缺陷需要处理。稳定期是修复这些错误并 +确保代码在主线内核版本中的首次发布尽可能可靠的最好机会。所以，请回应错误 报告，并尽可能解决问题。这就是稳定期的目的；一旦解决了旧补丁的任何问题，就 -可以开始创建酷的新补丁。 +可以开始尽情创建新补丁。 -别忘了，还有其他里程碑也可能会创建bug报告：下一个主线稳定版本，当著名的发行 -商选择包含补丁的内核版本时，等等。继续响应这些报告是您工作的基本骄傲。但是， -如果这不是足够的动机，那么也值得考虑的是，开发社区会记住那些在合并后对代码 -失去兴趣的开发人员。下一次你发布补丁时，他们会以你以后不会在身边维护它为假 -设来评估它。 +别忘了，还有其他节点也可能会创建缺陷报告：下一个主线稳定版本，当著名的发行 +商选择包含您补丁的内核版本时等等。继续响应这些报告是您工作的基本素养。但是 +如果这不能提供足够的动机，那么也需要考虑：开发社区会记住那些在合并后对代码 +失去兴趣的开发人员。下一次你发布补丁时，他们会以你以后不会持续维护它为前提 +来评估它。 其他可能发生的事情 ------------------ -有一天，你可以打开你的邮件客户端，看到有人给你寄了一个代码补丁。毕竟，这是 +某天，当你打开你的邮件客户端时，看到有人给你寄了一个代码补丁。毕竟，这是 让您的代码公开存在的好处之一。如果您同意这个补丁，您可以将它转发给子系统 -维护人员（确保包含一个正确的From:行，这样属性是正确的，并添加一个您自己 -的签准），或者回复一个Acked-by，让原始发送者向上发送它。 +维护人员（确保包含一个正确的From:行，这样属性是正确的，并添加一个您自己的 +signoff ），或者回复一个 Acked-by: 让原始发送者向上发送它。 -如果您不同意补丁，请发送一个礼貌的回复，解释原因。如果可能的话，告诉作者需要 -做哪些更改才能让您接受补丁。对于代码的编写者和维护者所反对的合并补丁，存在着 -一定的阻力，但仅此而已。如果你被认为不必要的阻碍了好的工作，那么这些补丁最 -终会经过你身边并进入主线。在Linux内核中，没有人对任何代码拥有绝对的否决权。 -除了Linus。 +如果您不同意补丁，请礼貌地回复，解释原因。如果可能的话，告诉作者需要做哪些 +更改才能让您接受补丁。合并代码的编写者和维护者所反对的补丁的确存在着一定的 +阻力，但仅此而已。如果你被认为不必要的阻碍了好的工作，那么这些补丁最终会 +绕过你并进入主线。在Linux内核中，没有人对任何代码拥有绝对的否决权。可能除 +了Linus。 在非常罕见的情况下，您可能会看到完全不同的东西：另一个开发人员发布了针对您 -的问题的不同解决方案。在这一点上，两个补丁中的一个可能不会合并，“我的在这里 -是第一个”不被认为是一个令人信服的技术论据。如果有人的补丁取代了你的补丁而进 -入了主线，那么只有一种方法可以回应你：高兴你的问题得到解决，继续你的工作。 -以这种方式把一个人的工作推到一边可能会伤害和气馁，但是在他们忘记了谁的补丁 -真正被合并很久之后，社区会记住你的反应。 +的问题的不同解决方案。在这时，两个补丁之一可能不会被合并，“我的补丁首先 +发布”不被认为是一个令人信服的技术论据。如果有别人的补丁取代了你的补丁而进 +入了主线，那么只有一种方法可以回应你：很高兴你的问题解决了，请继续工作吧。 +以这种方式把某人的工作推到一边可能导致伤心和气馁，但是社区会记住你的反应， +即使很久以后他们已经忘记了谁的补丁真正被合并。 diff --git a/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst b/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst index 2f0ef750746f..6d0dadae13b1 100644 --- a/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst +++ b/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst @@ -1,7 +1,14 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/7.AdvancedTopics.rst <development_advancedtopics>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> .. _cn_development_advancedtopics: @@ -15,110 +22,112 @@ --------------- 内核使用分布式版本控制始于2002年初，当时Linus首次开始使用专有的Bitkeeper应用 -程序。虽然bitkeeper存在争议，但它所体现的软件版本管理方法却肯定不是。分布式 -版本控制可以立即加速内核开发项目。在当前的时代，有几种免费的比特保持器替代品。 -无论好坏，内核项目都将Git作为其选择的工具。 +程序。虽然BitKeeper存在争议，但它所体现的软件版本管理方法却肯定不是。分布式 +版本控制可以立即加速内核开发项目。现在有好几种免费的BitKeeper替代品。 +但无论好坏，内核项目都已经选择了Git作为其工具。 -使用Git管理补丁可以使开发人员的生活更加轻松，尤其是随着补丁数量的增加。Git -也有其粗糙的边缘和一定的危险，它是一个年轻和强大的工具，仍然在其开发人员完善 +使用Git管理补丁可以使开发人员的生活更加轻松，尤其是随着补丁数量的增长。Git也 +有其粗糙的边角和一定的危险性，它是一个年轻和强大的工具，仍然在其开发人员完善 中。本文档不会试图教会读者如何使用git；这会是个巨长的文档。相反，这里的重点 -将是Git如何特别适合内核开发过程。想要加快Git的开发人员可以在以下网站上找到 -更多信息： +将是Git如何特别适合内核开发过程。想要加快用Git速度的开发人员可以在以下网站上 +找到更多信息： https://git-scm.com/ https://www.kernel.org/pub/software/scm/git/docs/user-manual.html -在尝试使用它使补丁可供其他人使用之前，第一要务是阅读上述站点，对Git的工作 -方式有一个扎实的了解。使用Git的开发人员应该能够获得主线存储库的副本，探索 -修订历史，提交对树的更改，使用分支等。了解Git用于重写历史的工具（如Rebase） -也很有用。Git有自己的术语和概念；Git的新用户应该了解refs、远程分支、索引、 -快进合并、推拉、分离头等。一开始可能有点吓人，但这些概念不难通过一点学习来 +同时网上也能找到各种各样的教程。 + +在尝试使用它生成补丁供他人使用之前，第一要务是阅读上述网页，对Git的工作方式 +有一个扎实的了解。使用Git的开发人员应能进行拉取主线存储库的副本，查询修订 +历史，提交对树的更改，使用分支等操作。了解Git用于重写历史的工具（如rebase） +也很有用。Git有自己的术语和概念；Git的新用户应该了解引用、远程分支、索引、 +快进合并、推拉、游离头等。一开始可能有点吓人，但这些概念不难通过一点学习来 理解。 使用git生成通过电子邮件提交的补丁是提高速度的一个很好的练习。 -当您准备好开始安装Git树供其他人查看时，您当然需要一个可以从中提取的服务器。 -如果您有一个可以访问Internet的系统，那么使用git守护进程设置这样的服务器相 -对简单。否则，免费的公共托管网站（例如github）开始出现在网络上。成熟的开发 -人员可以在kernel.org上获得一个帐户，但这些帐户并不容易找到；有关更多信息， -请参阅 https://kernel.org/faq/ +当您准备好开始建立Git树供其他人查看时，无疑需要一个可以从中拉取的服务器。 +如果您有一个可以访问因特网的系统，那么使用git-daemon设置这样的服务器相对 +简单。同时，免费的公共托管网站（例如github）也开始出现在网络上。成熟的开发 +人员可以在kernel.org上获得一个帐户，但这些帐户并不容易得到；更多有关信息， +请参阅 https://kernel.org/faq/ 。 正常的Git工作流程涉及到许多分支的使用。每一条开发线都可以分为单独的“主题 -分支”，并独立维护。Git的分支机构很便宜，没有理由不免费使用它们。而且，在 -任何情况下，您都不应该在任何您打算让其他人从中受益的分支中进行开发。应该 -小心地创建公开可用的分支；当它们处于完整的形式并准备好运行时(而不是之前）， -合并开发分支的补丁。 +分支”，并独立维护。Git的分支很容易使用，没有理由不使用它们。而且，在任何 +情况下，您都不应该在任何您打算让其他人从中拉取的分支中进行开发。应该小心地 +创建公开可用的分支；当开发分支处于完整状态并已准备好时(而不是之前）才合并 +开发分支的补丁。 Git提供了一些强大的工具，可以让您重写开发历史。一个不方便的补丁（比如说， 一个打破二分法的补丁，或者有其他一些明显的缺陷）可以在适当的位置修复，或者 -完全从历史中消失。一个补丁系列可以被重写，就好像它是在今天的主线之上写的 -一样，即使你已经花了几个月的时间在写它。可以透明地将更改从一个分支转移到另 -一个分支。等等。明智地使用git修改历史的能力可以帮助创建问题更少的干净补丁集。 +完全从历史中消失。一个补丁系列可以被重写，就好像它是在今天的主线上写的一样， +即使你已经花了几个月的时间在写它。可以透明地将更改从一个分支转移到另一个 +分支。等等。明智地使用git修改历史的能力可以帮助创建问题更少的干净补丁集。 -然而，过度使用这种能力可能会导致其他问题，而不仅仅是对创建完美项目历史的 -简单痴迷。重写历史将重写该历史中包含的更改，将经过测试（希望）的内核树变 -为未经测试的内核树。但是，除此之外，如果开发人员没有对项目历史的共享视图， -他们就无法轻松地协作；如果您重写了其他开发人员拉入他们存储库的历史，您将 -使这些开发人员的生活更加困难。因此，这里有一个简单的经验法则：被导出到其他 -人的历史在此后通常被认为是不可变的。 +然而，过度使用这种功能可能会导致其他问题，而不仅仅是对创建完美项目历史的 +简单痴迷。重写历史将重写该历史中包含的更改，将经过测试（希望如此）的内核树 +变为未经测试的内核树。除此之外，如果开发人员没有共享项目历史，他们就无法 +轻松地协作；如果您重写了其他开发人员拉入他们存储库的历史，您将使这些开发 +人员的生活更加困难。因此，这里有一个简单的经验法则：被导出到其他地方的历史 +在此后通常被认为是不可变的。 因此，一旦将一组更改推送到公开可用的服务器上，就不应该重写这些更改。如果您 -尝试强制进行不会导致快进合并（即不共享同一历史记录的更改）的更改，Git将尝 -试强制执行此规则。可以重写此检查，有时可能需要重写导出的树。在树之间移动变 -更集以避免Linux-next中的冲突就是一个例子。但这种行为应该是罕见的。这就是为 -什么开发应该在私有分支中进行（必要时可以重写）并且只有在公共分支处于合理的 -高级状态时才转移到公共分支中的原因之一。 +尝试强制进行无法快进合并的更改（即不共享同一历史记录的更改），Git将尝试强制 +执行此规则。这可能覆盖检查，有时甚至需要重写导出的树。在树之间移动变更集以 +避免linux-next中的冲突就是一个例子。但这种行为应该是罕见的。这就是为什么 +开发应该在私有分支中进行（必要时可以重写）并且只有在公共分支处于合理的较新 +状态时才转移到公共分支中的原因之一。 当主线（或其他一组变更所基于的树）前进时，很容易与该树合并以保持领先地位。 对于一个私有的分支，rebasing 可能是一个很容易跟上另一棵树的方法，但是一旦 -一棵树被导出到全世界，rebasing就不是一个选项。一旦发生这种情况，就必须进行 -完全合并（merge）。合并有时是很有意义的，但是过于频繁的合并会不必要地扰乱 -历史。在这种情况下，建议的技术是不经常合并，通常只在特定的发布点（如主线-rc -发布）合并。如果您对特定的更改感到紧张，则可以始终在私有分支中执行测试合并。 -在这种情况下，git rerere 工具很有用；它记住合并冲突是如何解决的，这样您就 -不必重复相同的工作。 +一棵树被导出到外界，rebasing就不可取了。一旦发生这种情况，就必须进行完全 +合并（merge）。合并有时是很有意义的，但是过于频繁的合并会不必要地扰乱历史。 +在这种情况下建议的做法是不要频繁合并，通常只在特定的发布点（如主线-rc发布） +合并。如果您对特定的更改感到紧张，则可以始终在私有分支中执行测试合并。在 +这种情况下，git“rerere”工具很有用；它能记住合并冲突是如何解决的，这样您 +就不必重复相同的工作。 关于Git这样的工具的一个最大的反复抱怨是：补丁从一个存储库到另一个存储库的 大量移动使得很容易陷入错误建议的变更中，这些变更避开审查雷达进入主线。当内 -核开发人员看到这种情况发生时，他们往往会感到不高兴；在Git树上放置未查看或 -主题外的补丁可能会影响您将来获取树的能力。引用Linus: +核开发人员看到这种情况发生时，他们往往会感到不高兴；在Git树上放置未审阅或 +主题外的补丁可能会影响您将来让树被拉取的能力。引用Linus的话: :: - 你可以给我发补丁，但要我从你哪里取一个Git补丁，我需要知道你知道 - 你在做什么，我需要能够相信事情而不去检查每个个人改变。 + 你可以给我发补丁，但当我从你那里拉取一个Git补丁时，我需要知道你清楚 + 自己在做什么，我需要能够相信事情而 *无需* 手动检查每个单独的更改。 （http://lwn.net/articles/224135/）。 为了避免这种情况，请确保给定分支中的所有补丁都与相关主题紧密相关；“驱动程序 修复”分支不应更改核心内存管理代码。而且，最重要的是，不要使用Git树来绕过 -审查过程。不时的将树的摘要发布到相关的列表中，当时间合适时，请求 -Linux-next 中包含该树。 +审查过程。不时的将树的摘要发布到相关的列表中，在合适时候请求linux-next中 +包含该树。 -如果其他人开始发送补丁以包含到您的树中，不要忘记查看它们。还要确保您维护正确 -的作者信息； ``git am`` 工具在这方面做得最好，但是如果它通过第三方转发给您， -您可能需要在补丁中添加“From：”行。 +如果其他人开始发送补丁以包含到您的树中，不要忘记审阅它们。还要确保您维护正确 +的作者信息； git “am”工具在这方面做得最好，但是如果补丁通过第三方转发给您， +您可能需要在补丁中添加“From:”行。 -请求pull操作时，请务必提供所有相关信息：树的位置、要拉的分支以及拉操作将导致 -的更改。在这方面，git request pull 命令非常有用；它将按照其他开发人员的预期 -格式化请求，并检查以确保您记住了将这些更改推送到公共服务器。 +请求拉取时，请务必提供所有相关信息：树的位置、要拉取的分支以及拉取将导致的 +更改。在这方面 git request-pull 命令非常有用；它将按照其他开发人员所期望的 +格式化请求，并检查以确保您已记得将这些更改推送到公共服务器。 -审查补丁 +审阅补丁 -------- -一些读者当然会反对将本节与“高级主题”放在一起，因为即使是刚开始的内核开发人员 -也应该检查补丁。当然，学习如何在内核环境中编程没有比查看其他人发布的代码更好 -的方法了。此外，审阅者永远供不应求；通过查看代码，您可以对整个流程做出重大贡献。 +一些读者显然会反对将本节与“高级主题”放在一起，因为即使是刚开始的内核开发人员 +也应该审阅补丁。当然，没有比查看其他人发布的代码更好的方法来学习如何在内核环境 +中编程了。此外，审阅者永远供不应求；通过审阅代码，您可以对整个流程做出重大贡献。 -审查代码可能是一个令人生畏的前景，特别是对于一个新的内核开发人员来说，他们 +审查代码可能是一副令人生畏的图景，特别是对一个新的内核开发人员来说，他们 可能会对公开询问代码感到紧张，而这些代码是由那些有更多经验的人发布的。不过， -即使是最有经验的开发人员编写的代码也可以得到改进。也许对评审员（所有评审员） -最好的建议是：把评审评论当成问题而不是批评。询问“在这条路径中如何释放锁？” +即使是最有经验的开发人员编写的代码也可以得到改进。也许对（所有）审阅者最好 +的建议是：把审阅评论当成问题而不是批评。询问“在这条路径中如何释放锁？” 总是比说“这里的锁是错误的”更好。 -不同的开发人员将从不同的角度审查代码。一些主要关注的是编码样式以及代码行是 -否有尾随空格。其他人将主要关注补丁作为一个整体实现的变更是否对内核有好处。 -然而，其他人会检查是否存在锁定问题、堆栈使用过度、可能的安全问题、在其他 -地方发现的代码重复、足够的文档、对性能的不利影响、用户空间ABI更改等。所有 -类型的检查，如果它们导致更好的代码进入内核，都是受欢迎和值得的。 +不同的开发人员将从不同的角度审查代码。部分人会主要关注代码风格以及代码行是 +否有尾随空格。其他人会主要关注补丁作为一个整体实现的变更是否对内核有好处。 +同时也有人会检查是否存在锁问题、堆栈使用过度、可能的安全问题、在其他地方 +发现的代码重复、足够的文档、对性能的不利影响、用户空间ABI更改等。所有类型 +的检查，只要它们能引导更好的代码进入内核，都是受欢迎和值得的。 diff --git a/Documentation/translations/zh_CN/process/8.Conclusion.rst b/Documentation/translations/zh_CN/process/8.Conclusion.rst index 90cec3de6106..71c3e30efc6f 100644 --- a/Documentation/translations/zh_CN/process/8.Conclusion.rst +++ b/Documentation/translations/zh_CN/process/8.Conclusion.rst @@ -1,7 +1,13 @@ .. include:: ../disclaimer-zh_CN.rst :Original: :ref:`Documentation/process/8.Conclusion.rst <development_conclusion>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> +:Translator: + + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> + +:校译: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> .. _cn_development_conclusion: @@ -9,56 +15,56 @@ ======== 关于Linux内核开发和相关主题的信息来源很多。首先是在内核源代码分发中找到的 -文档目录。顶级 :ref:`Documentation/translations/zh_CN/process/howto.rst <cn_process_howto>` -文件是一个重要的起点 +文档目录。顶级 +:ref:`Documentation/translations/zh_CN/process/howto.rst <cn_process_howto>` +文件是一个重要的起点； :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` -和 :ref:`process/submitting-drivers.rst <submittingdrivers>` +和 :ref:`Documentation/transaltions/zh_CN/process/submitting-drivers.rst <cn_submittingdrivers>` 也是所有内核开发人员都应该阅读的内容。许多内部内核API都是使用kerneldoc机制 -记录的；“make htmldocs”或“make pdfdocs”可用于以HTML或PDF格式生成这些文档（ -尽管某些发行版提供的tex版本会遇到内部限制，无法正确处理文档）。 +记录的；“make htmldocs”或“make pdfdocs”可用于以HTML或PDF格式生成这些文档 +（尽管某些发行版提供的tex版本会遇到内部限制，无法正确处理文档）。 -不同的网站在各个细节层次上讨论内核开发。您的作者想谦虚地建议用 https://lwn.net/ -作为来源；有关许多特定内核主题的信息可以通过以下网址的lwn内核索引找到： +不同的网站在各个细节层次上讨论内核开发。本文作者想谦虚地建议用 https://lwn.net/ +作为来源；有关许多特定内核主题的信息可以通过以下网址的 LWN 内核索引找到： - http://lwn.net/kernel/index/ + http://lwn.net/kernel/index/ 除此之外，内核开发人员的一个宝贵资源是： - https://kernelnewbies.org/ + https://kernelnewbies.org/ -当然，我们不应该忘记 https://kernel.org/ 这是内核发布信息的最终位置。 +当然，也不应该忘记 https://kernel.org/ ，这是内核发布信息的最终位置。 关于内核开发有很多书： - Linux设备驱动程序，第三版（Jonathan Corbet、Alessandro Rubini和Greg Kroah Hartman）。 - 在线：http://lwn.net/kernel/ldd3/ + 《Linux设备驱动程序》第三版（Jonathan Corbet、Alessandro Rubini和Greg Kroah Hartman） + 线上版本在 http://lwn.net/kernel/ldd3/ - Linux内核开发（Robert Love）。 + 《Linux内核设计与实现》（Robert Love） - 了解Linux内核（Daniel Bovet和Marco Cesati）。 + 《深入理解Linux内核》(Daniel Bovet和Marco Cesati） -然而，所有这些书都有一个共同的缺点：当它们上架时，它们往往有些过时，而且它们 -已经上架一段时间了。不过，在那里还可以找到相当多的好信息。 +然而，所有这些书都有一个共同的缺点：它们上架时就往往有些过时，而且已经上架 +一段时间了。不过，在那里还是可以找到相当多的好信息。 有关git的文档，请访问： - https://www.kernel.org/pub/software/scm/git/docs/ + https://www.kernel.org/pub/software/scm/git/docs/ - https://www.kernel.org/pub/software/scm/git/docs/user-manual.html + https://www.kernel.org/pub/software/scm/git/docs/user-manual.html 结论 ==== -祝贺所有通过这篇冗长的文件的人。希望它能够帮助您理解Linux内核是如何开发的， +祝贺所有通过这篇冗长的文档的人。希望它能够帮助您理解Linux内核是如何开发的， 以及您如何参与这个过程。 -最后，重要的是参与。任何开源软件项目都不超过其贡献者投入其中的总和。Linux内核 -的发展速度和以前一样快，因为它得到了大量开发人员的帮助，他们都在努力使它变得 -更好。内核是一个主要的例子，说明当成千上万的人为了一个共同的目标一起工作时， -可以做些什么。 +最后，重要的是参与。任何开源软件项目都不会超过其贡献者投入其中的总和。Linux +内核的发展速度和以前一样快，因为它得到了大量开发人员的帮助，他们都在努力使它 +变得更好。内核是一个最成功的例子，说明了当成千上万的人为了一个共同的目标一起 +工作时，可以做出什么。 -不过，内核总是可以从更大的开发人员基础中获益。总有更多的工作要做。但是，同样 +不过，内核总是可以从更大的开发人员基础中获益。总有更多的工作要做。但是同样 重要的是，Linux生态系统中的大多数其他参与者可以通过为内核做出贡献而受益。使 代码进入主线是提高代码质量、降低维护和分发成本、提高对内核开发方向的影响程度 -等的关键。这是一种人人都赢的局面。踢开你的编辑，来加入我们吧，你会非常受 -欢迎的。 +等的关键。这是一种共赢的局面。启动你的编辑器，来加入我们吧；你会非常受欢迎的。 diff --git a/Documentation/translations/zh_CN/process/index.rst b/Documentation/translations/zh_CN/process/index.rst index 8051a7b322c5..39e9c88fbaa6 100644 --- a/Documentation/translations/zh_CN/process/index.rst +++ b/Documentation/translations/zh_CN/process/index.rst @@ -13,11 +13,11 @@ 与Linux 内核社区一起工作 ======================== -那么你想成为Linux内核开发人员？ 欢迎！ 不但从技术意义上讲有很多关于内核的知识 -需要学，而且了解我们社区的工作方式也很重要。 阅读这些文章可以让您以更轻松地, -麻烦最少的方式将更改合并到内核。 +你想成为Linux内核开发人员吗？欢迎之至！在学习许多关于内核的技术知识的同时， +了解我们社区的工作方式也很重要。阅读这些文档可以让您以更轻松的、麻烦更少的 +方式将更改合并到内核。 -以下是每位开发人员应阅读的基本指南。 +以下是每位开发人员都应阅读的基本指南： .. toctree:: :maxdepth: 1 @@ -47,7 +47,7 @@ management-style embargoed-hardware-issues -这些是一些总体技术指南，由于缺乏更好的地方，现在已经放在这里 +这些是一些总体性技术指南，由于不大好分类而放在这里： .. toctree:: :maxdepth: 1 diff --git a/Documentation/translations/zh_CN/process/submit-checklist.rst b/Documentation/translations/zh_CN/process/submit-checklist.rst index 50386e0e42e7..a64858d321fc 100644 --- a/Documentation/translations/zh_CN/process/submit-checklist.rst +++ b/Documentation/translations/zh_CN/process/submit-checklist.rst @@ -82,24 +82,22 @@ Linux内核补丁提交清单 请参阅 ``Documentation/ABI/README`` 。更改用户空间接口的补丁应该抄送 linux-api@vger.kernel.org。 -20) 检查是否全部通过 ``make headers_check`` 。 - -21) 已通过至少注入slab和page分配失败进行检查。请参阅 ``Documentation/fault-injection/`` +20) 已通过至少注入slab和page分配失败进行检查。请参阅 ``Documentation/fault-injection/`` 如果新代码是实质性的，那么添加子系统特定的故障注入可能是合适的。 -22) 新添加的代码已经用 ``gcc -W`` 编译（使用 ``make EXTRA-CFLAGS=-W`` ）。这 +21) 新添加的代码已经用 ``gcc -W`` 编译（使用 ``make EXTRA-CFLAGS=-W`` ）。这 将产生大量噪声，但对于查找诸如“警告：有符号和无符号之间的比较”之类的错误 很有用。 -23) 在它被合并到-mm补丁集中之后进行测试，以确保它仍然与所有其他排队的补丁以 +22) 在它被合并到-mm补丁集中之后进行测试，以确保它仍然与所有其他排队的补丁以 及VM、VFS和其他子系统中的各种更改一起工作。 -24) 所有内存屏障例如 ``barrier()``, ``rmb()``, ``wmb()`` 都需要源代码中的注 +23) 所有内存屏障例如 ``barrier()``, ``rmb()``, ``wmb()`` 都需要源代码中的注 释来解释它们正在执行的操作及其原因的逻辑。 -25) 如果补丁添加了任何ioctl，那么也要更新 ``Documentation/userspace-api/ioctl/ioctl-number.rst`` +24) 如果补丁添加了任何ioctl，那么也要更新 ``Documentation/userspace-api/ioctl/ioctl-number.rst`` -26) 如果修改后的源代码依赖或使用与以下 ``Kconfig`` 符号相关的任何内核API或 +25) 如果修改后的源代码依赖或使用与以下 ``Kconfig`` 符号相关的任何内核API或 功能，则在禁用相关 ``Kconfig`` 符号和/或 ``=m`` （如果该选项可用）的情况 下测试以下多个构建[并非所有这些都同时存在，只是它们的各种/随机组合]： diff --git a/Documentation/translations/zh_CN/riscv/boot-image-header.rst b/Documentation/translations/zh_CN/riscv/boot-image-header.rst new file mode 100644 index 000000000000..241bf9c1bcbe --- /dev/null +++ b/Documentation/translations/zh_CN/riscv/boot-image-header.rst @@ -0,0 +1,67 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../riscv/boot-image-header` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_boot-image-header.rst: + + +========================== +RISC-V Linux启动镜像文件头 +========================== + +:Author: Atish Patra <atish.patra@wdc.com> +:Date: 20 May 2019 + +此文档仅描述RISC-V Linux 启动文件头的详情。 + +TODO: + 写一个完整的启动指南。 + +在解压后的Linux内核镜像中存在以下64字节的文件头:: + + u32 code0; /* Executable code */ + u32 code1; /* Executable code */ + u64 text_offset; /* Image load offset, little endian */ + u64 image_size; /* Effective Image size, little endian */ + u64 flags; /* kernel flags, little endian */ + u32 version; /* Version of this header */ + u32 res1 = 0; /* Reserved */ + u64 res2 = 0; /* Reserved */ + u64 magic = 0x5643534952; /* Magic number, little endian, "RISCV" */ + u32 magic2 = 0x05435352; /* Magic number 2, little endian, "RSC\x05" */ + u32 res3; /* Reserved for PE COFF offset */ + +这种头格式与PE/COFF文件头兼容，并在很大程度上受到ARM64文件头的启发。因此，ARM64 +和RISC-V文件头可以在未来合并为一个共同的头。 + +注意 +==== + +- 将来也可以复用这个文件头，用来对RISC-V的EFI桩提供支持。为了使内核镜像如同一个 + EFI应用程序一样加载，EFI规范中规定在内核镜像的开始需要PE/COFF镜像文件头。为了 + 支持EFI桩，应该用“MZ”魔术字符替换掉code0，并且res3（偏移量未0x3c）应指向PE/COFF + 文件头的其余部分. + +- 表示文件头版本号的Drop-bit位域 + + ========== ========== + Bits 0:15 次要 版本 + Bits 16:31 主要 版本 + ========== ========== + + 这保持了新旧版本之间的兼容性。 + 当前版本被定义为0.2。 + +- 从版本0.2开始，结构体成员“magic”就已经被弃用，在之后的版本中，可能会移除掉它。 + 最初，该成员应该与ARM64头的“magic”成员匹配，但遗憾的是并没有。 + “magic2”成员代替“magic”成员与ARM64头相匹配。 + +- 在当前的文件头，标志位域只剩下了一个位。 + + ===== ============================== + Bit 0 内核字节序。1 if BE, 0 if LE. + ===== ============================== + +- 对于引导加载程序加载内核映像来说，image_size成员对引导加载程序而言是必须的，否 + 则将引导失败。 diff --git a/Documentation/translations/zh_CN/riscv/index.rst b/Documentation/translations/zh_CN/riscv/index.rst new file mode 100644 index 000000000000..db13b1101490 --- /dev/null +++ b/Documentation/translations/zh_CN/riscv/index.rst @@ -0,0 +1,28 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../riscv/index` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_riscv_index: + + +=============== +RISC-V 体系结构 +=============== + +.. toctree:: + :maxdepth: 1 + + boot-image-header + pmu + patch-acceptance + + +.. only:: subproject and html + + 目录 + ==== + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/riscv/patch-acceptance.rst b/Documentation/translations/zh_CN/riscv/patch-acceptance.rst new file mode 100644 index 000000000000..9fd1c8216763 --- /dev/null +++ b/Documentation/translations/zh_CN/riscv/patch-acceptance.rst @@ -0,0 +1,31 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../riscv/patch-acceptance` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_riscv_patch-acceptance: + + +arch/riscv 开发者维护指南 +========================= + +概述 +---- +RISC-V指令集体系结构是公开开发的： +正在进行的草案可供所有人查看和测试实现。新模块或者扩展草案可能会在开发过程中发 +生更改---有时以不兼容的方式对以前的草案进行更改。这种灵活性可能会给RISC-V Linux +维护者带来挑战。Linux开发过程更喜欢经过良好检查和测试的代码，而不是试验代码。我 +们希望推广同样的规则到即将被内核合并的RISC-V相关代码。 + +附加的提交检查单 +---------------- +我们仅接受相关标准已经被RISC-V基金会标准为“已批准”或“已冻结”的扩展或模块的补丁。 +（开发者当然可以维护自己的Linux内核树，其中包含所需代码扩展草案的代码。） + +此外，RISC-V规范允许爱好者创建自己的自定义扩展。这些自定义拓展不需要通过RISC-V +基金会的任何审核或批准。为了避免将爱好者一些特别的RISC-V拓展添加进内核代码带来 +的维护复杂性和对性能的潜在影响，我们将只接受RISC-V基金会正式冻结或批准的的扩展 +补丁。（开发者当然可以维护自己的Linux内核树，其中包含他们想要的任何自定义扩展 +的代码。） diff --git a/Documentation/translations/zh_CN/riscv/pmu.rst b/Documentation/translations/zh_CN/riscv/pmu.rst new file mode 100644 index 000000000000..22dcf3a9ca6e --- /dev/null +++ b/Documentation/translations/zh_CN/riscv/pmu.rst @@ -0,0 +1,233 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../riscv/pmu` +:Translator: Yanteng Si <siyanteng@loongson.cn> + +.. _cn_riscv_pmu: + + +======================== +RISC-V平台上对PMUs的支持 +======================== + +Alan Kao <alankao@andestech.com>, Mar 2018 + +简介 +------------ + +截止本文撰写时，在The RISC-V ISA Privileged Version 1.10中提到的 perf_event +相关特性如下: +（详情请查阅手册） + +* [m|s]counteren +* mcycle[h], cycle[h] +* minstret[h], instret[h] +* mhpeventx, mhpcounterx[h] + +仅有以上这些功能，移植perf需要做很多工作，究其原因是缺少以下通用架构的性能 +监测特性: + +* 启用/停用计数器 + 在我们这里，计数器一直在自由运行。 +* 计数器溢出引起的中断 + 规范中没有这种功能。 +* 中断指示器 + 不可能所有的计数器都有很多的中断端口，所以需要一个中断指示器让软件来判断 + 哪个计数器刚好溢出。 +* 写入计数器 + 由于内核不能修改计数器，所以会有一个SBI来支持这个功能[1]。 另外，一些厂商 + 考虑实现M-S-U型号机器的硬件扩展来直接写入计数器。 + +这篇文档旨在为开发者提供一个在内核中支持PMU的简要指南。下面的章节简要解释了 +perf' 机制和待办事项。 + +你可以在这里查看以前的讨论[1][2]。 另外，查看附录中的相关内核结构体可能会有 +帮助。 + + +1. 初始化 +--------- + +*riscv_pmu* 是一个类型为 *struct riscv_pmu* 的全局指针，它包含了根据perf内部 +约定的各种方法和PMU-specific参数。人们应该声明这样的实例来代表PMU。 默认情况 +下， *riscv_pmu* 指向一个常量结构体 *riscv_base_pmu* ，它对基准QEMU模型有非常 +基础的支持。 + + +然后他/她可以将实例的指针分配给 *riscv_pmu* ，这样就可以利用已经实现的最小逻 +辑，或者创建他/她自己的 *riscv_init_platform_pmu* 实现。 + +换句话说，现有的 *riscv_base_pmu* 源只是提供了一个参考实现。 开发者可以灵活地 +决定多少部分可用，在最极端的情况下，他们可以根据自己的需要定制每一个函数。 + + +2. Event Initialization +----------------------- + +当用户启动perf命令来监控一些事件时，首先会被用户空间的perf工具解释为多个 +*perf_event_open* 系统调用，然后进一步调用上一步分配的 *event_init* 成员函数 +的主体。 在 *riscv_base_pmu* 的情况下，就是 *riscv_event_init* 。 + +该功能的主要目的是将用户提供的事件翻译成映射图，从而可以直接对HW-related的控 +制寄存器或计数器进行操作。该翻译基于 *riscv_pmu* 中提供的映射和方法。 + +注意，有些功能也可以在这个阶段完成: + +(1) 中断设置，这个在下一节说； +(2) 特限级设置(仅用户空间、仅内核空间、两者都有)； +(3) 析构函数设置。 通常应用 *riscv_destroy_event* 即可； +(4) 对非采样事件的调整，这将被函数应用，如 *perf_adjust_period* ，通常如下:: + + if (!is_sampling_event(event)) { + hwc->sample_period = x86_pmu.max_period; + hwc->last_period = hwc->sample_period; + local64_set(&hwc->period_left, hwc->sample_period); + } + + +在 *riscv_base_pmu* 的情况下，目前只提供了（3）。 + + +3. 中断 +------- + +3.1. 中断初始化 + +这种情况经常出现在 *event_init* 方案的开头。通常情况下，这应该是一个代码段，如:: + + int x86_reserve_hardware(void) + { + int err = 0; + + if (!atomic_inc_not_zero(&pmc_refcount)) { + mutex_lock(&pmc_reserve_mutex); + if (atomic_read(&pmc_refcount) == 0) { + if (!reserve_pmc_hardware()) + err = -EBUSY; + else + reserve_ds_buffers(); + } + if (!err) + atomic_inc(&pmc_refcount); + mutex_unlock(&pmc_reserve_mutex); + } + + return err; + } + +而神奇的是 *reserve_pmc_hardware* ，它通常做原子操作，使实现的IRQ可以从某个全局函 +数指针访问。 而 *release_pmc_hardware* 的作用正好相反，它用在上一节提到的事件分配 +器中。 + + (注：从所有架构的实现来看，*reserve/release* 对总是IRQ设置，所以 *pmc_hardware* + 似乎有些误导。 它并不处理事件和物理计数器之间的绑定，这一点将在下一节介绍。) + +3.2. IRQ结构体 + +基本上，一个IRQ运行以下伪代码:: + + for each hardware counter that triggered this overflow + + get the event of this counter + + // following two steps are defined as *read()*, + // check the section Reading/Writing Counters for details. + count the delta value since previous interrupt + update the event->count (# event occurs) by adding delta, and + event->hw.period_left by subtracting delta + + if the event overflows + sample data + set the counter appropriately for the next overflow + + if the event overflows again + too frequently, throttle this event + fi + fi + + end for + + 然而截至目前，没有一个RISC-V的实现为perf设计了中断，所以具体的实现要在未来完成。 + +4. Reading/Writing 计数 +----------------------- + +它们看似差不多，但perf对待它们的态度却截然不同。 对于读，在 *struct pmu* 中有一个 +*read* 接口，但它的作用不仅仅是读。 根据上下文，*read* 函数不仅要读取计数器的内容 +（event->count），还要更新左周期到下一个中断（event->hw.period_left）。 + + 但 perf 的核心不需要直接写计数器。 写计数器隐藏在以下两点的抽象化之后， + 1） *pmu->start* ，从字面上看就是开始计数，所以必须把计数器设置成一个合适的值，以 + 便下一次中断； + 2）在IRQ里面，应该把计数器设置成同样的合理值。 + +在RISC-V中，读操作不是问题，但写操作就需要费些力气了，因为S模式不允许写计数器。 + + +5. add()/del()/start()/stop() +----------------------------- + +基本思想: add()/del() 向PMU添加/删除事件，start()/stop() 启动/停止PMU中某个事件 +的计数器。 所有这些函数都使用相同的参数: *struct perf_event *event* 和 *int flag* 。 + +把 perf 看作一个状态机，那么你会发现这些函数作为这些状态之间的状态转换过程。 +定义了三种状态（event->hw.state）: + +* PERF_HES_STOPPED: 计数停止 +* PERF_HES_UPTODATE: event->count是最新的 +* PERF_HES_ARCH: 依赖于体系结构的用法，。。。我们现在并不需要它。 + +这些状态转换的正常流程如下: + +* 用户启动一个 perf 事件，导致调用 *event_init* 。 +* 当被上下文切换进来的时候，*add* 会被 perf core 调用，并带有一个标志 PERF_EF_START， + 也就是说事件被添加后应该被启动。 在这个阶段，如果有的话，一般事件会被绑定到一个物 + 理计数器上。当状态变为PERF_HES_STOPPED和PERF_HES_UPTODATE，因为现在已经停止了, + （软件）事件计数不需要更新。 + + - 然后调用 *start* ，并启用计数器。 + 通过PERF_EF_RELOAD标志，它向计数器写入一个适当的值（详细情况请参考上一节）。 + 如果标志不包含PERF_EF_RELOAD，则不会写入任何内容。 + 现在状态被重置为none，因为它既没有停止也没有更新（计数已经开始）。 + +*当被上下文切换出来时被调用。 然后，它检查出PMU中的所有事件，并调用 *stop* 来更新它们 + 的计数。 + + - *stop* 被 *del* 和perf核心调用，标志为PERF_EF_UPDATE，它经常以相同的逻辑和 *read* + 共用同一个子程序。 + 状态又一次变为PERF_HES_STOPPED和PERF_HES_UPTODATE。 + + - 这两对程序的生命周期: *add* 和 *del* 在任务切换时被反复调用；*start* 和 *stop* 在 + perf核心需要快速停止和启动时也会被调用，比如在调整中断周期时。 + +目前的实现已经足够了，将来可以很容易地扩展到功能。 + +A. 相关结构体 +------------- + +* struct pmu: include/linux/perf_event.h +* struct riscv_pmu: arch/riscv/include/asm/perf_event.h + + 两个结构体都被设计为只读。 + + *struct pmu* 定义了一些函数指针接口，它们大多以 *struct perf_event* 作为主参数，根据 + perf的内部状态机处理perf事件（详情请查看kernel/events/core.c）。 + + *struct riscv_pmu* 定义了PMU的具体参数。 命名遵循所有其它架构的惯例。 + +* struct perf_event: include/linux/perf_event.h +* struct hw_perf_event + + 表示 perf 事件的通用结构体，以及硬件相关的细节。 + +* struct riscv_hw_events: arch/riscv/include/asm/perf_event.h + + 保存事件状态的结构有两个固定成员。 + 事件的数量和事件的数组。 + +参考文献 +-------- + +[1] https://github.com/riscv/riscv-linux/pull/124 + +[2] https://groups.google.com/a/groups.riscv.org/forum/#!topic/sw-dev/f19TmCNP6yA diff --git a/Documentation/translations/zh_CN/sound/hd-audio/controls.rst b/Documentation/translations/zh_CN/sound/hd-audio/controls.rst new file mode 100644 index 000000000000..54c028ab9a40 --- /dev/null +++ b/Documentation/translations/zh_CN/sound/hd-audio/controls.rst @@ -0,0 +1,102 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Chinese translator: Huang Jianghui <huangjianghui@uniontech.com> +--------------------------------------------------------------------- +.. include:: ../../disclaimer-zh_CN.rst +以下为正文 +--------------------------------------------------------------------- +====================================== +高清音频编解码器特定混音器控件 +====================================== + + +此文件解释特定于编解码器的混音器控件. + +瑞昱编解码器 +------------ + +声道模式 + 这是一个用于更改环绕声道设置的枚举控件,仅在环绕声道打开时显示出现。 + 它给出要使用的通道数:"2ch","4ch","6ch"，和"8ch"。根据配置，这还控 + 制多I/O插孔的插孔重分配。 + +自动静音模式 + 这是一个枚举控件，用于更改耳机和线路输出插孔的自动静音行为。如果内 + 置扬声器、耳机和/或线路输出插孔在机器上可用，则显示该控件。当只有 + 耳机或者线路输出的时候，它给出”禁用“和”启用“状态。当启用后，插孔插 + 入后扬声器会自动静音。 + + 当耳机和线路输出插孔都存在时，它给出”禁用“、”仅扬声器“和”线路输出+扬 + 声器“。当”仅扬声器“被选择，插入耳机或者线路输出插孔可使扬声器静音， + 但不会使线路输出静音。当线路输出+扬声器被选择，插入耳机插孔会同时使扬 + 声器和线路输出静音。 + + +矽玛特编解码器 +-------------- + +模拟环回 + 此控件启用/禁用模拟环回电路。只有在编解码器提示中将”lookback“设置为真 + 时才会出现(见HD-Audio.txt)。请注意，在某些编解码器上，模拟环回和正常 + PCM播放是独占的,即当此选项打开时，您将听不到任何PCM流。 + +交换中置/低频 + 交换中置和低频通道顺序，通常情况下，左侧对应中置，右侧对应低频,启动此 + 项后，左边低频，右边中置。 + +耳机作为线路输出 + 当此控制开启时，将耳机视为线路输出插孔。也就是说，耳机不会自动静音其他 + 线路输出，没有耳机放大器被设置到引脚上。 + +麦克风插口模式、线路插孔模式等 + 这些枚举控制输入插孔引脚的方向和偏置。根据插孔类型，它可以设置为”麦克风 + 输入“和”线路输入“以确定输入偏置,或者当引脚是环绕声道的多I/O插孔时，它 + 可以设置为”线路输出“。 + + +威盛编解码器 +------------ + +智能5.1 + 一个枚举控件，用于为环绕输出重新分配多个I/O插孔的任务。当它打开时，相应 + 的输入插孔（通常是线路输入和麦克风输入）被切换为环绕和中央低频输出插孔。 + +独立耳机 + 启用此枚举控制时，耳机输出从单个流（第三个PCM，如hw:0,2）而不是主流路由。 + 如果耳机DAC与侧边或中央低频通道DAC共享，则DAC将自动切换到耳机。 + +环回混合 + 一个用于确定是否启动了模拟环回路由的枚举控件。当它启用后，模拟环回路由到 + 前置通道。同样，耳机与扬声器输出也采用相同的路径。作为一个副作用，当设置 + 此模式后，单个音量控制将不再适用于耳机和扬声器，因为只有一个DAC连接到混 + 音器小部件。 + +动态电源控制 + 此控件决定是否启动每个插孔的动态电源控制检测。启用时，根据插孔的插入情况 + 动态更改组件的电源状态（D0/D3）以节省电量消耗。但是，如果您的系统没有提 + 供正确的插孔检测，这将无法工作;在这种情况下，请关闭此控件。 + +插孔检测 + 此控件仅为VT1708编解码器提供，它不会为每个插孔插拔提供适当的未请求事件。 + 当此控件打开，驱动将轮询插孔检测，以便耳机自动静音可以工作，而关闭此控 + 件将降低功耗。 + + +科胜讯编解码器 +-------------- + +自动静音模式 + 见瑞昱解码器 + + + +模拟编解码器 +------------ + +通道模式 + 这是一个用于更改环绕声道设置的枚举控件,仅在环绕声道可用时显示。它提供了能 + 被使用的通道数:”2ch“、”4ch“和”6ch“。根据配置，这还控制多I/O插孔的插孔重 + 分配。 + +独立耳机 + 启动此枚举控制后，耳机输出从单个流（第三个PCM，如hw:0,2）而不是主流路由。 diff --git a/Documentation/translations/zh_CN/sound/hd-audio/index.rst b/Documentation/translations/zh_CN/sound/hd-audio/index.rst new file mode 100644 index 000000000000..d9885d53b069 --- /dev/null +++ b/Documentation/translations/zh_CN/sound/hd-audio/index.rst @@ -0,0 +1,14 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../disclaimer-zh_CN.rst + +:Original: :doc:`../../../../sound/hd-audio/index` +:Translator: Huang Jianghui <huangjianghui@uniontech.com> + + +高清音频 +======== + +.. toctree:: + :maxdepth: 2 + + controls diff --git a/Documentation/translations/zh_CN/sound/index.rst b/Documentation/translations/zh_CN/sound/index.rst new file mode 100644 index 000000000000..28d5dca34a63 --- /dev/null +++ b/Documentation/translations/zh_CN/sound/index.rst @@ -0,0 +1,22 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../sound/index` +:Translator: Huang Jianghui <huangjianghui@uniontech.com> + + +==================== +Linux 声音子系统文档 +==================== + +.. toctree:: + :maxdepth: 2 + + hd-audio/index + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst index 181211beb01d..9bfc2b510c64 100644 --- a/Documentation/userspace-api/ioctl/ioctl-number.rst +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst @@ -349,6 +349,7 @@ Code Seq# Include File Comments 0xB5 00-0F uapi/linux/rpmsg.h <mailto:linux-remoteproc@vger.kernel.org> 0xB6 all linux/fpga-dfl.h 0xB7 all uapi/linux/remoteproc_cdev.h <mailto:linux-remoteproc@vger.kernel.org> +0xB7 all uapi/linux/nsfs.h <mailto:Andrei Vagin <avagin@openvz.org>> 0xC0 00-0F linux/usb/iowarrior.h 0xCA 00-0F uapi/misc/cxl.h 0xCA 10-2F uapi/misc/ocxl.h diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 307f2fcf1b02..245d80581f15 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -55,7 +55,7 @@ not cause harm to the host, their actual behavior is not guaranteed by the API. See "General description" for details on the ioctl usage model that is supported by KVM. -It is important to note that althought VM ioctls may only be issued from +It is important to note that although VM ioctls may only be issued from the process that created the VM, a VM's lifecycle is associated with its file descriptor, not its creator (process). In other words, the VM and its resources, *including the associated address space*, are not freed diff --git a/Documentation/watchdog/pcwd-watchdog.rst b/Documentation/watchdog/pcwd-watchdog.rst index 405e2a370082..151505c856f6 100644 --- a/Documentation/watchdog/pcwd-watchdog.rst +++ b/Documentation/watchdog/pcwd-watchdog.rst @@ -47,7 +47,7 @@ Documentation and Driver by Ken Hollis <kenji@bitgate.com> WDIOC_GETSTATUS This returns the status of the card, with the bits of WDIOF_* bitwise-anded into the value. (The comments - are in linux/pcwd.h) + are in include/uapi/linux/watchdog.h) WDIOC_GETBOOTSTATUS This returns the status of the card that was reported diff --git a/MAINTAINERS b/MAINTAINERS index 1162b0917630..ac0ff5feef1d 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -4235,13 +4235,20 @@ X: drivers/char/tpm/ CHECKPATCH M: Andy Whitcroft <apw@canonical.com> M: Joe Perches <joe@perches.com> +R: Dwaipayan Ray <dwaipayanray1@gmail.com> +R: Lukas Bulwahn <lukas.bulwahn@gmail.com> S: Maintained F: scripts/checkpatch.pl +CHECKPATCH DOCUMENTATION +M: Dwaipayan Ray <dwaipayanray1@gmail.com> +M: Lukas Bulwahn <lukas.bulwahn@gmail.com> +R: Joe Perches <joe@perches.com> +S: Maintained +F: Documentation/dev-tools/checkpatch.rst + CHINESE DOCUMENTATION -M: Harry Wei <harryxiyou@gmail.com> -M: Alex Shi <alex.shi@linux.alibaba.com> -L: xiyoulinuxkernelgroup@googlegroups.com (subscribers-only) +M: Alex Shi <alexs@kernel.org> S: Maintained F: Documentation/translations/zh_CN/ @@ -5469,6 +5476,12 @@ X: Documentation/power/ X: Documentation/spi/ X: Documentation/userspace-api/media/ +DOCUMENTATION REPORTING ISSUES +M: Thorsten Leemhuis <linux@leemhuis.info> +L: linux-doc@vger.kernel.org +S: Maintained +F: Documentation/admin-guide/reporting-issues.rst + DOCUMENTATION SCRIPTS M: Mauro Carvalho Chehab <mchehab@kernel.org> L: linux-doc@vger.kernel.org @@ -9800,6 +9813,11 @@ F: include/uapi/linux/sunrpc/ F: net/sunrpc/ F: Documentation/filesystems/nfs/ +KERNEL REGRESSIONS +M: Thorsten Leemhuis <linux@leemhuis.info> +L: regressions@lists.linux.dev +S: Supported + KERNEL SELFTEST FRAMEWORK M: Shuah Khan <shuah@kernel.org> M: Shuah Khan <skhan@linuxfoundation.org> diff --git a/fs/eventpoll.c b/fs/eventpoll.c index 3196474cbe24..73138ea68342 100644 --- a/fs/eventpoll.c +++ b/fs/eventpoll.c @@ -366,8 +366,8 @@ static inline struct epitem *ep_item_from_wait(wait_queue_entry_t *p) * * @ep: Pointer to the eventpoll context. * - * Returns: Returns a value different than zero if ready events are available, - * or zero otherwise. + * Return: a value different than %zero if ready events are available, + * or %zero otherwise. */ static inline int ep_events_available(struct eventpoll *ep) { @@ -1023,7 +1023,7 @@ struct file *get_epoll_tfile_raw_ptr(struct file *file, int tfd, } #endif /* CONFIG_KCMP */ -/** +/* * Adds a new entry to the tail of the list in a lockless way, i.e. * multiple CPUs are allowed to call this function concurrently. * @@ -1035,10 +1035,10 @@ struct file *get_epoll_tfile_raw_ptr(struct file *file, int tfd, * completed. * * Also an element can be locklessly added to the list only in one - * direction i.e. either to the tail either to the head, otherwise + * direction i.e. either to the tail or to the head, otherwise * concurrent access will corrupt the list. * - * Returns %false if element has been already added to the list, %true + * Return: %false if element has been already added to the list, %true * otherwise. */ static inline bool list_add_tail_lockless(struct list_head *new, @@ -1076,11 +1076,11 @@ static inline bool list_add_tail_lockless(struct list_head *new, return true; } -/** +/* * Chains a new epi entry to the tail of the ep->ovflist in a lockless way, * i.e. multiple CPUs are allowed to call this function concurrently. * - * Returns %false if epi element has been already chained, %true otherwise. + * Return: %false if epi element has been already chained, %true otherwise. */ static inline bool chain_epi_lockless(struct epitem *epi) { @@ -1105,8 +1105,8 @@ static inline bool chain_epi_lockless(struct epitem *epi) * mechanism. It is called by the stored file descriptors when they * have events to report. * - * This callback takes a read lock in order not to content with concurrent - * events from another file descriptors, thus all modifications to ->rdllist + * This callback takes a read lock in order not to contend with concurrent + * events from another file descriptor, thus all modifications to ->rdllist * or ->ovflist are lockless. Read lock is paired with the write lock from * ep_scan_ready_list(), which stops all list modifications and guarantees * that lists state is seen correctly. @@ -1335,8 +1335,8 @@ static int reverse_path_check_proc(struct hlist_head *refs, int depth) * paths such that we will spend all our time waking up * eventpoll objects. * - * Returns: Returns zero if the proposed links don't create too many paths, - * -1 otherwise. + * Return: %zero if the proposed links don't create too many paths, + * %-1 otherwise. */ static int reverse_path_check(void) { @@ -1734,7 +1734,7 @@ static struct timespec64 *ep_timeout_to_timespec(struct timespec64 *to, long ms) } /** - * ep_poll - Retrieves ready events, and delivers them to the caller supplied + * ep_poll - Retrieves ready events, and delivers them to the caller-supplied * event buffer. * * @ep: Pointer to the eventpoll context. @@ -1747,7 +1747,7 @@ static struct timespec64 *ep_timeout_to_timespec(struct timespec64 *to, long ms) * until at least one event has been retrieved (or an error * occurred). * - * Returns: Returns the number of ready events which have been fetched, or an + * Return: the number of ready events which have been fetched, or an * error code, in case of error. */ static int ep_poll(struct eventpoll *ep, struct epoll_event __user *events, @@ -1774,9 +1774,9 @@ static int ep_poll(struct eventpoll *ep, struct epoll_event __user *events, /* * This call is racy: We may or may not see events that are being added - * to the ready list under the lock (e.g., in IRQ callbacks). For, cases + * to the ready list under the lock (e.g., in IRQ callbacks). For cases * with a non-zero timeout, this thread will check the ready list under - * lock and will added to the wait queue. For, cases with a zero + * lock and will add to the wait queue. For cases with a zero * timeout, the user by definition should not care and will have to * recheck again. */ @@ -1869,15 +1869,15 @@ static int ep_poll(struct eventpoll *ep, struct epoll_event __user *events, /** * ep_loop_check_proc - verify that adding an epoll file inside another - * epoll structure, does not violate the constraints, in + * epoll structure does not violate the constraints, in * terms of closed loops, or too deep chains (which can * result in excessive stack usage). * - * @priv: Pointer to the epoll file to be currently checked. + * @ep: the &struct eventpoll to be currently checked. * @depth: Current depth of the path being checked. * - * Returns: Returns zero if adding the epoll @file inside current epoll - * structure @ep does not violate the constraints, or -1 otherwise. + * Return: %zero if adding the epoll @file inside current epoll + * structure @ep does not violate the constraints, or %-1 otherwise. */ static int ep_loop_check_proc(struct eventpoll *ep, int depth) { @@ -1919,14 +1919,14 @@ static int ep_loop_check_proc(struct eventpoll *ep, int depth) /** * ep_loop_check - Performs a check to verify that adding an epoll file (@to) - * into another epoll file (represented by @from) does not create + * into another epoll file (represented by @ep) does not create * closed loops or too deep chains. * - * @from: Pointer to the epoll we are inserting into. + * @ep: Pointer to the epoll we are inserting into. * @to: Pointer to the epoll to be inserted. * - * Returns: Returns zero if adding the epoll @to inside the epoll @from - * does not violate the constraints, or -1 otherwise. + * Return: %zero if adding the epoll @to inside the epoll @from + * does not violate the constraints, or %-1 otherwise. */ static int ep_loop_check(struct eventpoll *ep, struct eventpoll *to) { @@ -2074,8 +2074,8 @@ int do_epoll_ctl(int epfd, int op, int fd, struct epoll_event *epds, ep = f.file->private_data; /* - * When we insert an epoll file descriptor, inside another epoll file - * descriptor, there is the change of creating closed loops, which are + * When we insert an epoll file descriptor inside another epoll file + * descriptor, there is the chance of creating closed loops, which are * better be handled here, than in more critical paths. While we are * checking for loops we also determine the list of files reachable * and hang them on the tfile_check_list, so we can check that we @@ -2113,7 +2113,7 @@ int do_epoll_ctl(int epfd, int op, int fd, struct epoll_event *epds, } /* - * Try to lookup the file inside our RB tree, Since we grabbed "mtx" + * Try to lookup the file inside our RB tree. Since we grabbed "mtx" * above, we can be sure to be able to use the item looked up by * ep_find() till we release the mutex. */ diff --git a/fs/namespace.c b/fs/namespace.c index 56bb5a5fdc0d..f63337828e1c 100644 --- a/fs/namespace.c +++ b/fs/namespace.c @@ -1242,8 +1242,9 @@ struct vfsmount *mntget(struct vfsmount *mnt) } EXPORT_SYMBOL(mntget); -/* path_is_mountpoint() - Check if path is a mount in the current - * namespace. +/** + * path_is_mountpoint() - Check if path is a mount in the current namespace. + * @path: path to check * * d_mountpoint() can only be used reliably to establish if a dentry is * not mounted in any namespace and that common case is handled inline. @@ -1369,7 +1370,7 @@ void mnt_cursor_del(struct mnt_namespace *ns, struct mount *cursor) /** * may_umount_tree - check if a mount tree is busy - * @mnt: root of mount tree + * @m: root of mount tree * * This is called to check if a tree of mounts has any * open files, pwds, chroots or sub mounts that are @@ -1939,10 +1940,11 @@ void drop_collected_mounts(struct vfsmount *mnt) /** * clone_private_mount - create a private clone of a path + * @path: path to clone * - * This creates a new vfsmount, which will be the clone of @path. The new will - * not be attached anywhere in the namespace and will be private (i.e. changes - * to the originating mount won't be propagated into this). + * This creates a new vfsmount, which will be the clone of @path. The new mount + * will not be attached anywhere in the namespace and will be private (i.e. + * changes to the originating mount won't be propagated into this). * * Release with mntput(). */ diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl index df8b23dc1eb0..f42e5ba16d9b 100755 --- a/scripts/checkpatch.pl +++ b/scripts/checkpatch.pl @@ -23,6 +23,9 @@ my $V = '0.32'; use Getopt::Long qw(:config no_auto_abbrev); my $quiet = 0; +my $verbose = 0; +my %verbose_messages = (); +my %verbose_emitted = (); my $tree = 1; my $chk_signoff = 1; my $chk_patch = 1; @@ -61,6 +64,7 @@ my $spelling_file = "$D/spelling.txt"; my $codespell = 0; my $codespellfile = "/usr/share/codespell/dictionary.txt"; my $conststructsfile = "$D/const_structs.checkpatch"; +my $docsfile = "$D/../Documentation/dev-tools/checkpatch.rst"; my $typedefsfile; my $color = "auto"; my $allow_c99_comments = 1; # Can be overridden by --ignore C99_COMMENT_TOLERANCE @@ -78,6 +82,7 @@ Version: $V Options: -q, --quiet quiet + -v, --verbose verbose mode --no-tree run without a kernel tree --no-signoff do not check for 'Signed-off-by' line --patch treat FILE as patchfile (default) @@ -158,15 +163,51 @@ sub list_types { my $text = <$script>; close($script); - my @types = (); + my %types = (); # Also catch when type or level is passed through a variable - for ($text =~ /(?:(?:\bCHK|\bWARN|\bERROR|&\{\$msg_level})\s*\(|\$msg_type\s*=)\s*"([^"]+)"/g) { - push (@types, $_); + while ($text =~ /(?:(\bCHK|\bWARN|\bERROR|&\{\$msg_level})\s*\(|\$msg_type\s*=)\s*"([^"]+)"/g) { + if (defined($1)) { + if (exists($types{$2})) { + $types{$2} .= ",$1" if ($types{$2} ne $1); + } else { + $types{$2} = $1; + } + } else { + $types{$2} = "UNDETERMINED"; + } } - @types = sort(uniq(@types)); + print("#\tMessage type\n\n"); - foreach my $type (@types) { + if ($color) { + print(" ( Color coding: "); + print(RED . "ERROR" . RESET); + print(" | "); + print(YELLOW . "WARNING" . RESET); + print(" | "); + print(GREEN . "CHECK" . RESET); + print(" | "); + print("Multiple levels / Undetermined"); + print(" )\n\n"); + } + + foreach my $type (sort keys %types) { + my $orig_type = $type; + if ($color) { + my $level = $types{$type}; + if ($level eq "ERROR") { + $type = RED . $type . RESET; + } elsif ($level eq "WARN") { + $type = YELLOW . $type . RESET; + } elsif ($level eq "CHK") { + $type = GREEN . $type . RESET; + } + } print(++$count . "\t" . $type . "\n"); + if ($verbose && exists($verbose_messages{$orig_type})) { + my $message = $verbose_messages{$orig_type}; + $message =~ s/\n/\n\t/g; + print("\t" . $message . "\n\n"); + } } exit($exitcode); @@ -198,6 +239,46 @@ if (-f $conf) { unshift(@ARGV, @conf_args) if @conf_args; } +sub load_docs { + open(my $docs, '<', "$docsfile") + or warn "$P: Can't read the documentation file $docsfile $!\n"; + + my $type = ''; + my $desc = ''; + my $in_desc = 0; + + while (<$docs>) { + chomp; + my $line = $_; + $line =~ s/\s+$//; + + if ($line =~ /^\s*\*\*(.+)\*\*$/) { + if ($desc ne '') { + $verbose_messages{$type} = trim($desc); + } + $type = $1; + $desc = ''; + $in_desc = 1; + } elsif ($in_desc) { + if ($line =~ /^(?:\s{4,}|$)/) { + $line =~ s/^\s{4}//; + $desc .= $line; + $desc .= "\n"; + } else { + $verbose_messages{$type} = trim($desc); + $type = ''; + $desc = ''; + $in_desc = 0; + } + } + } + + if ($desc ne '') { + $verbose_messages{$type} = trim($desc); + } + close($docs); +} + # Perl's Getopt::Long allows options to take optional arguments after a space. # Prevent --color by itself from consuming other arguments foreach (@ARGV) { @@ -208,6 +289,7 @@ foreach (@ARGV) { GetOptions( 'q|quiet+' => \$quiet, + 'v|verbose!' => \$verbose, 'tree!' => \$tree, 'signoff!' => \$chk_signoff, 'patch!' => \$chk_patch, @@ -247,13 +329,27 @@ GetOptions( help(0) if ($help); +die "$P: --git cannot be used with --file or --fix\n" if ($git && ($file || $fix)); +die "$P: --verbose cannot be used with --terse\n" if ($verbose && $terse); + +if ($color =~ /^[01]$/) { + $color = !$color; +} elsif ($color =~ /^always$/i) { + $color = 1; +} elsif ($color =~ /^never$/i) { + $color = 0; +} elsif ($color =~ /^auto$/i) { + $color = (-t STDOUT); +} else { + die "$P: Invalid color mode: $color\n"; +} + +load_docs() if ($verbose); list_types(0) if ($list_types); $fix = 1 if ($fix_inplace); $check_orig = $check; -die "$P: --git cannot be used with --file or --fix\n" if ($git && ($file || $fix)); - my $exit = 0; my $perl_version_ok = 1; @@ -268,18 +364,6 @@ if ($#ARGV < 0) { push(@ARGV, '-'); } -if ($color =~ /^[01]$/) { - $color = !$color; -} elsif ($color =~ /^always$/i) { - $color = 1; -} elsif ($color =~ /^never$/i) { - $color = 0; -} elsif ($color =~ /^auto$/i) { - $color = (-t STDOUT); -} else { - die "$P: Invalid color mode: $color\n"; -} - # skip TAB size 1 to avoid additional checks on $tabsize - 1 die "$P: Invalid TAB size: $tabsize\n" if ($tabsize < 2); @@ -2209,7 +2293,16 @@ sub report { splice(@lines, 1, 1); $output = join("\n", @lines); } - $output = (split('\n', $output))[0] . "\n" if ($terse); + + if ($terse) { + $output = (split('\n', $output))[0] . "\n"; + } + + if ($verbose && exists($verbose_messages{$type}) && + !exists($verbose_emitted{$type})) { + $output .= $verbose_messages{$type} . "\n\n"; + $verbose_emitted{$type} = 1; + } push(our @report, $output); diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 92d9aa6cc4f5..d7aa82094296 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -281,8 +281,12 @@ sub create_labels { # Outputs the book on ReST format # -# \b doesn't work well with paths. So, we need to define something else -my $bondary = qr { (?<![\w\/\`\{])(?=[\w\/\`\{])|(?<=[\w\/\`\{])(?![\w\/\`\{]) }x; +# \b doesn't work well with paths. So, we need to define something else: +# Boundaries are punct characters, spaces and end-of-line +my $start = qr {(^|\s|\() }x; +my $bondary = qr { ([,.:;\)\s]|\z) }x; +my $xref_match = qr { $start(\/(sys|config|proc|dev|kvd)\/[^,.:;\)\s]+)$bondary }x; +my $symbols = qr { ([\x01-\x08\x0e-\x1f\x21-\x2f\x3a-\x40\x7b-\xff]) }x; sub output_rest { create_labels(); @@ -305,7 +309,6 @@ sub output_rest { } my $w = $what; - $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g; if ($type ne "File") { my $cur_part = $what; @@ -329,6 +332,7 @@ sub output_rest { my $len = 0; foreach my $name (@names) { + $name =~ s/$symbols/\\$1/g; $name = "**$name**"; $len = length($name) if (length($name) > $len); } @@ -377,32 +381,60 @@ sub output_rest { # Enrich text by creating cross-references - $desc =~ s,Documentation/(?!devicetree)(\S+)\.rst,:doc:`/$1`,g; + my $new_desc = ""; + my $init_indent = -1; + my $literal_indent = -1; + + open(my $fh, "+<", \$desc); + while (my $d = <$fh>) { + my $indent = $d =~ m/^(\s+)/; + my $spaces = length($indent); + $init_indent = $indent if ($init_indent < 0); + if ($literal_indent >= 0) { + if ($spaces > $literal_indent) { + $new_desc .= $d; + next; + } else { + $literal_indent = -1; + } + } else { + if ($d =~ /()::$/ && !($d =~ /^\s*\.\./)) { + $literal_indent = $spaces; + } + } - my @matches = $desc =~ m,Documentation/ABI/([\w\/\-]+),; - foreach my $f (@matches) { - my $xref = $f; - my $path = $f; - $path =~ s,.*/(.*/.*),$1,;; - $path =~ s,[/\-],_,g;; - $xref .= " <abi_file_" . $path . ">"; - $desc =~ s,\bDocumentation/ABI/$f\b,:ref:`$xref`,g; - } + $d =~ s,Documentation/(?!devicetree)(\S+)\.rst,:doc:`/$1`,g; - @matches = $desc =~ m,$bondary(/sys/[^\s\.\,\;\:\*\s\`\'\(\)]+)$bondary,; + my @matches = $d =~ m,Documentation/ABI/([\w\/\-]+),g; + foreach my $f (@matches) { + my $xref = $f; + my $path = $f; + $path =~ s,.*/(.*/.*),$1,;; + $path =~ s,[/\-],_,g;; + $xref .= " <abi_file_" . $path . ">"; + $d =~ s,\bDocumentation/ABI/$f\b,:ref:`$xref`,g; + } + + # Seek for cross reference symbols like /sys/... + @matches = $d =~ m/$xref_match/g; - foreach my $s (@matches) { - if (defined($data{$s}) && defined($data{$s}->{label})) { - my $xref = $s; + foreach my $s (@matches) { + next if (!($s =~ m,/,)); + if (defined($data{$s}) && defined($data{$s}->{label})) { + my $xref = $s; - $xref =~ s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g; - $xref = ":ref:`$xref <" . $data{$s}->{label} . ">`"; + $xref =~ s/$symbols/\\$1/g; + $xref = ":ref:`$xref <" . $data{$s}->{label} . ">`"; - $desc =~ s,$bondary$s$bondary,$xref,g; + $d =~ s,$start$s$bondary,$1$xref$2,g; + } } + $new_desc .= $d; } + close $fh; + - print "$desc\n\n"; + print "$new_desc\n\n"; } else { $desc =~ s/^\s+//; diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 8b5bc7bf4bb8..2a85d34fdcd0 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -391,8 +391,14 @@ my $doc_com = '\s*\*\s*'; my $doc_com_body = '\s*\* ?'; my $doc_decl = $doc_com . '(\w+)'; # @params and a strictly limited set of supported section names +# Specifically: +# Match @word: +# @...: +# @{section-name}: +# while trying to not match literal block starts like "example::" +# my $doc_sect = $doc_com . - '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)'; + '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:].*)?$'; my $doc_content = $doc_com_body . '(.*)'; my $doc_block = $doc_com . 'DOC:\s*(.*)?'; my $doc_inline_start = '^\s*/\*\*\s*$'; @@ -1201,12 +1207,23 @@ sub dump_union($$) { sub dump_struct($$) { my $x = shift; my $file = shift; + my $decl_type; + my $members; + my $type = qr{struct|union}; + # For capturing struct/union definition body, i.e. "{members*}qualifiers*" + my $definition_body = qr{\{(.*)\}(?:\s*(?:__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*}; - if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) { - my $decl_type = $1; + if ($x =~ /($type)\s+(\w+)\s*$definition_body/) { + $decl_type = $1; $declaration_name = $2; - my $members = $3; + $members = $3; + } elsif ($x =~ /typedef\s+($type)\s*$definition_body\s*(\w+)\s*;/) { + $decl_type = $1; + $declaration_name = $3; + $members = $2; + } + if ($members) { if ($identifier ne $declaration_name) { print STDERR "${file}:$.: warning: expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n"; return; @@ -1401,9 +1418,14 @@ sub dump_enum($$) { if ($members) { if ($identifier ne $declaration_name) { - print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n"; + if ($identifier eq "") { + print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n"; + } else { + print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n"; + } return; } + $declaration_name = "(anonymous)" if ($declaration_name eq ""); my %_members; @@ -1755,12 +1777,14 @@ sub dump_function($$) { $prototype =~ s/^noinline +//; $prototype =~ s/__init +//; $prototype =~ s/__init_or_module +//; + $prototype =~ s/__flatten +//; $prototype =~ s/__meminit +//; $prototype =~ s/__must_check +//; $prototype =~ s/__weak +//; $prototype =~ s/__sched +//; $prototype =~ s/__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +//; my $define = $prototype =~ s/^#\s*define\s+//; #ak added + $prototype =~ s/__attribute_const__ +//; $prototype =~ s/__attribute__\s*\(\( (?: [\w\s]++ # attribute name @@ -2085,15 +2109,28 @@ sub process_name($$) { } } elsif (/$doc_decl/o) { $identifier = $1; - if (/\s*([\w\s]+?)(\(\))?\s*([-:].*)?$/) { + my $is_kernel_comment = 0; + my $decl_start = qr{\s*\*}; + # test for pointer declaration type, foo * bar() - desc + my $fn_type = qr{\w+\s*\*\s*}; + my $parenthesis = qr{\(\w*\)}; + my $decl_end = qr{[-:].*}; + if (/^$decl_start\s*([\w\s]+?)$parenthesis?\s*$decl_end?$/) { $identifier = $1; } if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) { $decl_type = $1; $identifier = $2; - } else { + $is_kernel_comment = 1; + } + # Look for foo() or static void foo() - description; or misspelt + # identifier + elsif (/^$decl_start\s*$fn_type?(\w+)\s*$parenthesis?\s*$decl_end?$/ || + /^$decl_start\s*$fn_type?(\w+.*)$parenthesis?\s*$decl_end$/) { + $identifier = $1; $decl_type = 'function'; $identifier =~ s/^define\s+//; + $is_kernel_comment = 1; } $identifier =~ s/\s+$//; @@ -2115,13 +2152,20 @@ sub process_name($$) { $declaration_purpose = ""; } + if (!$is_kernel_comment) { + print STDERR "${file}:$.: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n"; + print STDERR $_; + ++$warnings; + $state = STATE_NORMAL; + } + if (($declaration_purpose eq "") && $verbose) { print STDERR "${file}:$.: warning: missing initial short description on line:\n"; print STDERR $_; ++$warnings; } - if ($identifier eq "") { + if ($identifier eq "" && $decl_type ne "enum") { print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n"; print STDERR $_; ++$warnings; diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index b5f9fd5b2880..fe92020d67e3 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -259,7 +259,7 @@ sub get_sphinx_version($) open IN, "$cmd --version 2>&1 |"; while (<IN>) { - if (m/^\s*sphinx-build\s+([\d\.]+)(\+\/[\da-f]+)?$/) { + if (m/^\s*sphinx-build\s+([\d\.]+)((\+\/[\da-f]+)|(b\d+))?$/) { $ver=$1; last; } diff --git a/tools/debugging/kernel-chktaint b/tools/debugging/kernel-chktaint index 607b2b280945..719f18b1edf0 100755 --- a/tools/debugging/kernel-chktaint +++ b/tools/debugging/kernel-chktaint @@ -25,7 +25,7 @@ if [ "$1"x != "x" ]; then elif [ $1 -ge 0 ] 2>/dev/null ; then taint=$1 else - echo "Error: Parameter '$1' not a positive interger. Aborting." >&2 + echo "Error: Parameter '$1' not a positive integer. Aborting." >&2 exit 1 fi else diff --git a/tools/scripts/Makefile.include b/tools/scripts/Makefile.include index a402f32a145c..84dbf61a7eca 100644 --- a/tools/scripts/Makefile.include +++ b/tools/scripts/Makefile.include @@ -86,7 +86,8 @@ endif # in newer systems. # Needed for the __raw_cmpxchg in tools/arch/x86/include/asm/cmpxchg.h # -# See https://lkml.org/lkml/2006/11/28/253 and https://gcc.gnu.org/gcc-4.8/changes.html, +# See https://lore.kernel.org/lkml/9a8748490611281710g78402fbeh8ff7fcc162dbcbca@mail.gmail.com/ +# and https://gcc.gnu.org/gcc-4.8/changes.html, # that takes into account Linus's comments (search for Wshadow) for the reasoning about # -Wshadow not being interesting before gcc 4.8. |