diff options
Diffstat (limited to 'Documentation')
44 files changed, 1159 insertions, 354 deletions
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 6cfa6e3996cf..80b14760314c 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -378,18 +378,16 @@ autoconf= [IPV6] See Documentation/networking/ipv6.rst. - show_lapic= [APIC,X86] Advanced Programmable Interrupt Controller - Limit apic dumping. The parameter defines the maximal - number of local apics being dumped. Also it is possible - to set it to "all" by meaning -- no limit here. - Format: { 1 (default) | 2 | ... | all }. - The parameter valid if only apic=debug or - apic=verbose is specified. - Example: apic=debug show_lapic=all - apm= [APM] Advanced Power Management See header of arch/x86/kernel/apm_32.c. + apparmor= [APPARMOR] Disable or enable AppArmor at boot time + Format: { "0" | "1" } + See security/apparmor/Kconfig help text + 0 -- disable. + 1 -- enable. + Default value is set via kernel config option. + arcrimi= [HW,NET] ARCnet - "RIM I" (entirely mem-mapped) cards Format: <io>,<irq>,<nodeID> @@ -1045,26 +1043,12 @@ can be useful when debugging issues that require an SLB miss to occur. - stress_slb [PPC] - Limits the number of kernel SLB entries, and flushes - them frequently to increase the rate of SLB faults - on kernel addresses. - - stress_hpt [PPC] - Limits the number of kernel HPT entries in the hash - page table to increase the rate of hash page table - faults on kernel addresses. - disable= [IPV6] See Documentation/networking/ipv6.rst. disable_radix [PPC] Disable RADIX MMU mode on POWER9 - radix_hcall_invalidate=on [PPC/PSERIES] - Disable RADIX GTSE feature and use hcall for TLB - invalidate. - disable_tlbie [PPC] Disable TLBIE instruction. Currently does not work with KVM, with HASH MMU, or with coherent accelerators. @@ -1166,16 +1150,6 @@ Documentation/admin-guide/dynamic-debug-howto.rst for details. - nopku [X86] Disable Memory Protection Keys CPU feature found - in some Intel CPUs. - - <module>.async_probe[=<bool>] [KNL] - If no <bool> value is specified or if the value - specified is not a valid <bool>, enable asynchronous - probe on this module. Otherwise, enable/disable - asynchronous probe on this module as indicated by the - <bool> value. See also: module.async_probe - early_ioremap_debug [KNL] Enable debug messages in early_ioremap support. This is useful for tracking down temporary early mappings @@ -1791,12 +1765,6 @@ which allow the hypervisor to 'idle' the guest on lock contention. - keep_bootcon [KNL] - Do not unregister boot console at start. This is only - useful for debugging when something happens in the window - between unregistering the boot console and initializing - the real console. - i2c_bus= [HW] Override the default board specific I2C bus speed or register an additional I2C bus that is not registered from board initialization code. @@ -2366,17 +2334,18 @@ js= [HW,JOY] Analog joystick See Documentation/input/joydev/joystick.rst. - nokaslr [KNL] - When CONFIG_RANDOMIZE_BASE is set, this disables - kernel and module base offset ASLR (Address Space - Layout Randomization). - kasan_multi_shot [KNL] Enforce KASAN (Kernel Address Sanitizer) to print report on every invalid memory access. Without this parameter KASAN will print report only for the first invalid access. + keep_bootcon [KNL] + Do not unregister boot console at start. This is only + useful for debugging when something happens in the window + between unregistering the boot console and initializing + the real console. + keepinitrd [HW,ARM] kernelcore= [KNL,X86,IA-64,PPC] @@ -3325,6 +3294,13 @@ For details see: Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst + <module>.async_probe[=<bool>] [KNL] + If no <bool> value is specified or if the value + specified is not a valid <bool>, enable asynchronous + probe on this module. Otherwise, enable/disable + asynchronous probe on this module as indicated by the + <bool> value. See also: module.async_probe + module.async_probe=<bool> [KNL] When set to true, modules will use async probing by default. To enable/disable async probing for a @@ -3779,6 +3755,11 @@ nojitter [IA-64] Disables jitter checking for ITC timers. + nokaslr [KNL] + When CONFIG_RANDOMIZE_BASE is set, this disables + kernel and module base offset ASLR (Address Space + Layout Randomization). + no-kvmclock [X86,KVM] Disable paravirtualized KVM clock driver no-kvmapf [X86,KVM] Disable paravirtualized asynchronous page @@ -3824,6 +3805,19 @@ nopcid [X86-64] Disable the PCID cpu feature. + nopku [X86] Disable Memory Protection Keys CPU feature found + in some Intel CPUs. + + nopv= [X86,XEN,KVM,HYPER_V,VMWARE] + Disables the PV optimizations forcing the guest to run + as generic guest with no PV drivers. Currently support + XEN HVM, KVM, HYPER_V and VMWARE guest. + + nopvspin [X86,XEN,KVM] + Disables the qspinlock slow path using PV optimizations + which allow the hypervisor to 'idle' the guest on lock + contention. + norandmaps Don't use address space randomization. Equivalent to echo 0 > /proc/sys/kernel/randomize_va_space @@ -4591,6 +4585,10 @@ r128= [HW,DRM] + radix_hcall_invalidate=on [PPC/PSERIES] + Disable RADIX GTSE feature and use hcall for TLB + invalidate. + raid= [HW,RAID] See Documentation/admin-guide/md.rst. @@ -5572,13 +5570,6 @@ 1 -- enable. Default value is 1. - apparmor= [APPARMOR] Disable or enable AppArmor at boot time - Format: { "0" | "1" } - See security/apparmor/Kconfig help text - 0 -- disable. - 1 -- enable. - Default value is set via kernel config option. - serialnumber [BUGS=X86-32] sev=option[,option...] [X86-64] See Documentation/x86/x86_64/boot-options.rst @@ -5586,6 +5577,15 @@ shapers= [NET] Maximal number of shapers. + show_lapic= [APIC,X86] Advanced Programmable Interrupt Controller + Limit apic dumping. The parameter defines the maximal + number of local apics being dumped. Also it is possible + to set it to "all" by meaning -- no limit here. + Format: { 1 (default) | 2 | ... | all }. + The parameter valid if only apic=debug or + apic=verbose is specified. + Example: apic=debug show_lapic=all + simeth= [IA-64] simscsi= @@ -6025,6 +6025,16 @@ be used to filter out binaries which have not yet been made aware of AT_MINSIGSTKSZ. + stress_hpt [PPC] + Limits the number of kernel HPT entries in the hash + page table to increase the rate of hash page table + faults on kernel addresses. + + stress_slb [PPC] + Limits the number of kernel SLB entries, and flushes + them frequently to increase the rate of SLB faults + on kernel addresses. + sunrpc.min_resvport= sunrpc.max_resvport= [NFS,SUNRPC] @@ -6957,16 +6967,6 @@ fairer and the number of possible event channels is much higher. Default is on (use fifo events). - nopv= [X86,XEN,KVM,HYPER_V,VMWARE] - Disables the PV optimizations forcing the guest to run - as generic guest with no PV drivers. Currently support - XEN HVM, KVM, HYPER_V and VMWARE guest. - - nopvspin [X86,XEN,KVM] - Disables the qspinlock slow path using PV optimizations - which allow the hypervisor to 'idle' the guest on lock - contention. - xirc2ps_cs= [NET,PCMCIA] Format: <irq>,<irq_mask>,<io>,<full_duplex>,<do_sound>,<lockup_hack>[,<irq2>[,<irq3>[,<irq4>]]] diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index e224b6d5b642..9d5fd9424e8b 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -1284,6 +1284,7 @@ support this. Table 1-9 lists the files and their meaning. rt_cache Routing cache snmp SNMP data sockstat Socket statistics + softnet_stat Per-CPU incoming packets queues statistics of online CPUs tcp TCP sockets udp UDP sockets unix UNIX domain sockets diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst index 93b2ae6c34a9..cfd37f31077f 100644 --- a/Documentation/maintainer/maintainer-entry-profile.rst +++ b/Documentation/maintainer/maintainer-entry-profile.rst @@ -104,3 +104,4 @@ to do something different in the near future. ../riscv/patch-acceptance ../driver-api/media/maintainer-entry-profile ../driver-api/vfio-pci-device-specific-driver-acceptance + ../nvme/feature-and-quirk-policy diff --git a/Documentation/mm/page_owner.rst b/Documentation/mm/page_owner.rst index 127514955a5e..0f4cb59bcaf4 100644 --- a/Documentation/mm/page_owner.rst +++ b/Documentation/mm/page_owner.rst @@ -52,7 +52,7 @@ pages are investigated and marked as allocated in initialization phase. Although it doesn't mean that they have the right owner information, at least, we can tell whether the page is allocated or not, more accurately. On 2GB memory x86-64 VM box, 13343 early allocated pages -are catched and marked, although they are mostly allocated from struct +are caught and marked, although they are mostly allocated from struct page extension feature. Anyway, after that, no page is left in un-tracking state. @@ -178,7 +178,7 @@ STANDARD FORMAT SPECIFIERS at alloc_ts timestamp of the page when it was allocated ator allocator memory allocator for pages - For --curl option: + For --cull option: KEY LONG DESCRIPTION p pid process ID diff --git a/Documentation/nvme/feature-and-quirk-policy.rst b/Documentation/nvme/feature-and-quirk-policy.rst new file mode 100644 index 000000000000..c01d836d8e41 --- /dev/null +++ b/Documentation/nvme/feature-and-quirk-policy.rst @@ -0,0 +1,77 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================= +Linux NVMe feature and and quirk policy +======================================= + +This file explains the policy used to decide what is supported by the +Linux NVMe driver and what is not. + + +Introduction +============ + +NVM Express is an open collection of standards and information. + +The Linux NVMe host driver in drivers/nvme/host/ supports devices +implementing the NVM Express (NVMe) family of specifications, which +currently consists of a number of documents: + + - the NVMe Base specification + - various Command Set specifications (e.g. NVM Command Set) + - various Transport specifications (e.g. PCIe, Fibre Channel, RDMA, TCP) + - the NVMe Management Interface specification + +See https://nvmexpress.org/developers/ for the NVMe specifications. + + +Supported features +================== + +NVMe is a large suite of specifications, and contains features that are only +useful or suitable for specific use-cases. It is important to note that Linux +does not aim to implement every feature in the specification. Every additional +feature implemented introduces more code, more maintenance and potentially more +bugs. Hence there is an inherent tradeoff between functionality and +maintainability of the NVMe host driver. + +Any feature implemented in the Linux NVMe host driver must support the +following requirements: + + 1. The feature is specified in a release version of an official NVMe + specification, or in a ratified Technical Proposal (TP) that is + available on NVMe website. Or if it is not directly related to the + on-wire protocol, does not contradict any of the NVMe specifications. + 2. Does not conflict with the Linux architecture, nor the design of the + NVMe host driver. + 3. Has a clear, indisputable value-proposition and a wide consensus across + the community. + +Vendor specific extensions are generally not supported in the NVMe host +driver. + +It is strongly recommended to work with the Linux NVMe and block layer +maintainers and get feedback on specification changes that are intended +to be used by the Linux NVMe host driver in order to avoid conflict at a +later stage. + + +Quirks +====== + +Sometimes implementations of open standards fail to correctly implement parts +of the standards. Linux uses identifier-based quirks to work around such +implementation bugs. The intent of quirks is to deal with widely available +hardware, usually consumer, which Linux users can't use without these quirks. +Typically these implementations are not or only superficially tested with Linux +by the hardware manufacturer. + +The Linux NVMe maintainers decide ad hoc whether to quirk implementations +based on the impact of the problem to Linux users and how it impacts +maintainability of the driver. In general quirks are a last resort, if no +firmware updates or other workarounds are available from the vendor. + +Quirks will not be added to the Linux kernel for hardware that isn't available +on the mass market. Hardware that fails qualification for enterprise Linux +distributions, ChromeOS, Android or other consumers of the Linux kernel +should be fixed before it is shipped instead of relying on Linux quirks. diff --git a/Documentation/process/botching-up-ioctls.rst b/Documentation/process/botching-up-ioctls.rst index ba4667ab396b..9739b88463a5 100644 --- a/Documentation/process/botching-up-ioctls.rst +++ b/Documentation/process/botching-up-ioctls.rst @@ -41,7 +41,7 @@ will need to add a 32-bit compat layer: structures to the kernel, or if the kernel checks the structure size, which e.g. the drm core does. - * Pointers are __u64, cast from/to a uintprt_t on the userspace side and + * Pointers are __u64, cast from/to a uintptr_t on the userspace side and from/to a void __user * in the kernel. Try really hard not to delay this conversion or worse, fiddle the raw __u64 through your code since that diminishes the checking tools like sparse can provide. The macro diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst index c8fd53a11a20..f91b8441f2ef 100644 --- a/Documentation/process/deprecated.rst +++ b/Documentation/process/deprecated.rst @@ -346,3 +346,29 @@ struct_size() and flex_array_size() helpers:: instance->count = count; memcpy(instance->items, source, flex_array_size(instance, items, instance->count)); + +There are two special cases of replacement where the DECLARE_FLEX_ARRAY() +helper needs to be used. (Note that it is named __DECLARE_FLEX_ARRAY() for +use in UAPI headers.) Those cases are when the flexible array is either +alone in a struct or is part of a union. These are disallowed by the C99 +specification, but for no technical reason (as can be seen by both the +existing use of such arrays in those places and the work-around that +DECLARE_FLEX_ARRAY() uses). For example, to convert this:: + + struct something { + ... + union { + struct type1 one[0]; + struct type2 two[0]; + }; + }; + +The helper must be used:: + + struct something { + ... + union { + DECLARE_FLEX_ARRAY(struct type1, one); + DECLARE_FLEX_ARRAY(struct type2, two); + }; + }; diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst index fc2c46f3f82d..471e1f93fa09 100644 --- a/Documentation/process/email-clients.rst +++ b/Documentation/process/email-clients.rst @@ -350,3 +350,23 @@ although tab2space problem can be solved with external editor. Another problem is that Gmail will base64-encode any message that has a non-ASCII character. That includes things like European names. + +Proton Mail +*********** + +Proton Mail has a "feature" where it looks up keys using Web Key Directory +(WKD) and encrypts mail to any recipients for which it finds a key. +Kernel.org publishes the WKD for all developers who have kernel.org accounts. +As a result, emails sent using Proton Mail to kernel.org addresses will be +encrypted. +Unfortunately, Proton Mail does not provide a mechanism to disable the +automatic encryption, viewing it as a privacy feature. +The automatic encryption feature is also enabled for mail sent via the Proton +Mail Bridge, so this affects all outgoing messages, including patches sent with +``git send-email``. +Encrypted mail adds unnecessary friction, as other developers may not have mail +clients, or tooling, configured for use with encrypted mail and some mail +clients may encrypt responses to encrypted mail for all recipients, including +the mailing lists. +Unless a way to disable this "feature" is introduced, Proton Mail is unsuited +to kernel development. diff --git a/Documentation/process/maintainer-pgp-guide.rst b/Documentation/process/maintainer-pgp-guide.rst index 40bfbd3b7648..f5277993b195 100644 --- a/Documentation/process/maintainer-pgp-guide.rst +++ b/Documentation/process/maintainer-pgp-guide.rst @@ -60,36 +60,18 @@ establish the integrity of the Linux kernel itself. PGP tools ========= -Use GnuPG v2 ------------- +Use GnuPG 2.2 or later +---------------------- Your distro should already have GnuPG installed by default, you just -need to verify that you are using version 2.x and not the legacy 1.4 -release -- many distributions still package both, with the default -``gpg`` command invoking GnuPG v.1. To check, run:: +need to verify that you are using a reasonably recent version of it. +To check, run:: $ gpg --version | head -n1 -If you see ``gpg (GnuPG) 1.4.x``, then you are using GnuPG v.1. Try the -``gpg2`` command (if you don't have it, you may need to install the -gnupg2 package):: - - $ gpg2 --version | head -n1 - -If you see ``gpg (GnuPG) 2.x.x``, then you are good to go. This guide -will assume you have the version 2.2 of GnuPG (or later). If you are -using version 2.0 of GnuPG, then some of the commands in this guide will -not work, and you should consider installing the latest 2.2 version of -GnuPG. Versions of gnupg-2.1.11 and later should be compatible for the -purposes of this guide as well. - -If you have both ``gpg`` and ``gpg2`` commands, you should make sure you -are always using GnuPG v2, not the legacy version. You can enforce this -by setting the appropriate alias:: - - $ alias gpg=gpg2 - -You can put that in your ``.bashrc`` to make sure it's always the case. +If you have version 2.2 or above, then you are good to go. If you have a +version that is prior than 2.2, then some commands from this guide may +not work. Configure gpg-agent options ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -150,9 +132,9 @@ PGP defines four capabilities that a key can have: The key with the **[C]** capability is often called the "master" key, but this terminology is misleading because it implies that the Certify key can be used in place of any of other subkey on the same chain (like -a physical "master key" can be used to open the locks made for other -keys). Since this is not the case, this guide will refer to it as "the -Certify key" to avoid any ambiguity. +a physical "master key" can be used to open locks made for other keys). +Since this is not the case, this guide will refer to it as "the Certify +key" to avoid any ambiguity. It is critical to fully understand the following: @@ -186,10 +168,10 @@ If you used the default parameters when generating your key, then that is what you will have. You can verify by running ``gpg --list-secret-keys``, for example:: - sec rsa2048 2018-01-23 [SC] [expires: 2020-01-23] + sec ed25519 2022-12-20 [SC] [expires: 2024-12-19] 000000000000000000000000AAAABBBBCCCCDDDD uid [ultimate] Alice Dev <adev@kernel.org> - ssb rsa2048 2018-01-23 [E] [expires: 2020-01-23] + ssb cv25519 2022-12-20 [E] [expires: 2024-12-19] The long line under the ``sec`` entry is your key fingerprint -- whenever you see ``[fpr]`` in the examples below, that 40-character @@ -219,18 +201,9 @@ separate signing subkey:: .. note:: ECC support in GnuPG - GnuPG 2.1 and later has full support for Elliptic Curve - Cryptography, with ability to combine ECC subkeys with traditional - RSA keys. The main upside of ECC cryptography is that it is much - faster computationally and creates much smaller signatures when - compared byte for byte with 2048+ bit RSA keys. Unless you plan on - using a smartcard device that does not support ECC operations, we - recommend that you create an ECC signing subkey for your kernel - work. - - Note, that if you plan to use a hardware device that does not + Note, that if you intend to use a hardware token that does not support ED25519 ECC keys, you should choose "nistp256" instead or - "ed25519." + "ed25519." See the section below on recommended hardware devices. Back up your Certify key for disaster recovery @@ -336,13 +309,13 @@ First, identify the keygrip of your Certify key:: The output will be something like this:: - pub rsa2048 2018-01-24 [SC] [expires: 2020-01-24] + pub ed25519 2022-12-20 [SC] [expires: 2022-12-19] 000000000000000000000000AAAABBBBCCCCDDDD Keygrip = 1111000000000000000000000000000000000000 uid [ultimate] Alice Dev <adev@kernel.org> - sub rsa2048 2018-01-24 [E] [expires: 2020-01-24] + sub cv25519 2022-12-20 [E] [expires: 2022-12-19] Keygrip = 2222000000000000000000000000000000000000 - sub ed25519 2018-01-24 [S] + sub ed25519 2022-12-20 [S] Keygrip = 3333000000000000000000000000000000000000 Find the keygrip entry that is beneath the ``pub`` line (right under the @@ -365,14 +338,14 @@ Now, if you issue the ``--list-secret-keys`` command, it will show that the Certify key is missing (the ``#`` indicates it is not available):: $ gpg --list-secret-keys - sec# rsa2048 2018-01-24 [SC] [expires: 2020-01-24] + sec# ed25519 2022-12-20 [SC] [expires: 2024-12-19] 000000000000000000000000AAAABBBBCCCCDDDD uid [ultimate] Alice Dev <adev@kernel.org> - ssb rsa2048 2018-01-24 [E] [expires: 2020-01-24] - ssb ed25519 2018-01-24 [S] + ssb cv25519 2022-12-20 [E] [expires: 2024-12-19] + ssb ed25519 2022-12-20 [S] You should also remove any ``secring.gpg`` files in the ``~/.gnupg`` -directory, which are left over from earlier versions of GnuPG. +directory, which may be left over from previous versions of GnuPG. If you don't have the "private-keys-v1.d" directory ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -437,8 +410,7 @@ functionality. There are several options available: U2F, among others, and now finally supports NISTP and ED25519 ECC keys. -`LWN has a good review`_ of some of the above models, as well as several -others. Your choice will depend on cost, shipping availability in your +Your choice will depend on cost, shipping availability in your geographical region, and open/proprietary hardware considerations. .. note:: @@ -451,7 +423,6 @@ geographical region, and open/proprietary hardware considerations. .. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nkpr2-nitrokey-pro-2-3 .. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/ .. _Gnuk: https://www.fsij.org/doc-gnuk/ -.. _`LWN has a good review`: https://lwn.net/Articles/736231/ .. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html Configure your smartcard device @@ -509,11 +480,11 @@ passphrase and the admin PIN of the card for most operations:: Secret subkeys are available. - pub rsa2048/AAAABBBBCCCCDDDD - created: 2018-01-23 expires: 2020-01-23 usage: SC + pub ed25519/AAAABBBBCCCCDDDD + created: 2022-12-20 expires: 2024-12-19 usage: SC trust: ultimate validity: ultimate - ssb rsa2048/1111222233334444 - created: 2018-01-23 expires: never usage: E + ssb cv25519/1111222233334444 + created: 2022-12-20 expires: never usage: E ssb ed25519/5555666677778888 created: 2017-12-07 expires: never usage: S [ultimate] (1). Alice Dev <adev@kernel.org> @@ -577,11 +548,11 @@ If you perform ``--list-secret-keys`` now, you will see a subtle difference in the output:: $ gpg --list-secret-keys - sec# rsa2048 2018-01-24 [SC] [expires: 2020-01-24] + sec# ed25519 2022-12-20 [SC] [expires: 2024-12-19] 000000000000000000000000AAAABBBBCCCCDDDD uid [ultimate] Alice Dev <adev@kernel.org> - ssb> rsa2048 2018-01-24 [E] [expires: 2020-01-24] - ssb> ed25519 2018-01-24 [S] + ssb> cv25519 2022-12-20 [E] [expires: 2024-12-19] + ssb> ed25519 2022-12-20 [S] The ``>`` in the ``ssb>`` output indicates that the subkey is only available on the smartcard. If you go back into your secret keys @@ -644,7 +615,7 @@ run:: You can also use a specific date if that is easier to remember (e.g. your birthday, January 1st, or Canada Day):: - $ gpg --quick-set-expire [fpr] 2020-07-01 + $ gpg --quick-set-expire [fpr] 2025-07-01 Remember to send the updated key back to keyservers:: @@ -707,12 +678,6 @@ should be used (``[fpr]`` is the fingerprint of your key):: $ git config --global user.signingKey [fpr] -**IMPORTANT**: If you have a distinct ``gpg2`` command, then you should -tell git to always use it instead of the legacy ``gpg`` from version 1:: - - $ git config --global gpg.program gpg2 - $ git config --global gpgv.program gpgv2 - How to work with signed tags ---------------------------- @@ -751,13 +716,6 @@ If you are verifying someone else's git tag, then you will need to import their PGP key. Please refer to the ":ref:`verify_identities`" section below. -.. note:: - - If you get "``gpg: Can't check signature: unknown pubkey - algorithm``" error, you need to tell git to use gpgv2 for - verification, so it properly processes signatures made by ECC keys. - See instructions at the start of this section. - Configure git to always sign annotated tags ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/trace/events.rst b/Documentation/trace/events.rst index c47f381d0c00..8f86eef1bada 100644 --- a/Documentation/trace/events.rst +++ b/Documentation/trace/events.rst @@ -258,7 +258,7 @@ file. To clear the filters for all events in a subsystem, write a '0' to the subsystem's filter file. -5.3 Subsystem filters +5.4 Subsystem filters --------------------- For convenience, filters for every event in a subsystem can be set or @@ -305,7 +305,7 @@ their old filters):: # cat sched_wakeup/filter common_pid == 0 -5.4 PID filtering +5.5 PID filtering ----------------- The set_event_pid file in the same directory as the top events directory diff --git a/Documentation/translations/it_IT/admin-guide/README.rst b/Documentation/translations/it_IT/admin-guide/README.rst index b37166817842..c874586a9af9 100644 --- a/Documentation/translations/it_IT/admin-guide/README.rst +++ b/Documentation/translations/it_IT/admin-guide/README.rst @@ -4,7 +4,7 @@ .. _it_readme: -Rilascio del kernel Linux 5.x <http://kernel.org/> +Rilascio del kernel Linux 6.x <http://kernel.org/> =================================================== .. warning:: diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst index 78082281acf9..5cece223b46b 100644 --- a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst +++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst @@ -3,6 +3,8 @@ .. note:: Per leggere la documentazione originale in inglese: :ref:`Documentation/doc-guide/index.rst <doc_guide>` +.. title:: Commenti in kernel-doc + .. _it_kernel_doc: ================================= diff --git a/Documentation/translations/it_IT/doc-guide/sphinx.rst b/Documentation/translations/it_IT/doc-guide/sphinx.rst index 64528790dc34..1f513bc33618 100644 --- a/Documentation/translations/it_IT/doc-guide/sphinx.rst +++ b/Documentation/translations/it_IT/doc-guide/sphinx.rst @@ -151,7 +151,8 @@ Ovviamente, per generare la documentazione, Sphinx (``sphinx-build``) dev'essere installato. Se disponibile, il tema *Read the Docs* per Sphinx verrà utilizzato per ottenere una documentazione HTML più gradevole. Per la documentazione in formato PDF, invece, avrete bisogno di ``XeLaTeX` -e di ``convert(1)`` disponibile in ImageMagick (https://www.imagemagick.org). +e di ``convert(1)`` disponibile in ImageMagick +(https://www.imagemagick.org). \ [#ink]_ Tipicamente, tutti questi pacchetti sono disponibili e pacchettizzati nelle distribuzioni Linux. @@ -162,9 +163,20 @@ la generazione potete usare il seguente comando ``make SPHINXOPTS=-v htmldocs``. Potete anche personalizzare l'ouptut html passando un livello aggiuntivo DOCS_CSS usando la rispettiva variabile d'ambiente ``DOCS_CSS``. +La variable make ``SPHINXDIRS`` è utile quando si vuole generare solo una parte +della documentazione. Per esempio, si possono generare solo di documenti in +``Documentation/doc-guide`` eseguendo ``make SPHINXDIRS=doc-guide htmldocs``. La +sezione dedicata alla documentazione di ``make help`` vi mostrerà quali sotto +cartelle potete specificare. + Potete eliminare la documentazione generata tramite il comando ``make cleandocs``. +.. [#ink] Avere installato anche ``inkscape(1)`` dal progetto Inkscape () + potrebbe aumentare la qualità delle immagini che verranno integrate + nel documento PDF, specialmente per quando si usando rilasci del + kernel uguali o superiori a 5.18 + Scrivere la documentazione ========================== diff --git a/Documentation/translations/it_IT/index.rst b/Documentation/translations/it_IT/index.rst index e80a3097aa57..fc5f39814e83 100644 --- a/Documentation/translations/it_IT/index.rst +++ b/Documentation/translations/it_IT/index.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. _it_linux_doc: =================== @@ -67,75 +69,68 @@ I miglioramenti alla documentazione sono sempre i benvenuti; per cui, se vuoi aiutare, iscriviti alla lista di discussione linux-doc presso vger.kernel.org. -Documentazione sulla licenza dei sorgenti ------------------------------------------ - -I seguenti documenti descrivono la licenza usata nei sorgenti del kernel Linux -(GPLv2), come licenziare i singoli file; inoltre troverete i riferimenti al -testo integrale della licenza. +Lavorare con la comunità di sviluppo +------------------------------------ -* :ref:`it_kernel_licensing` +Le guide fondamentali per l'interazione con la comunità di sviluppo del kernel e +su come vedere il proprio lavoro integrato. -Documentazione per gli utenti ------------------------------ - -I seguenti manuali sono scritti per gli *utenti* del kernel - ovvero, -coloro che cercano di farlo funzionare in modo ottimale su un dato sistema - -.. warning:: +.. toctree:: + :maxdepth: 1 - TODO ancora da tradurre + process/development-process + process/submitting-patches + Code of conduct <process/code-of-conduct> + All development-process docs <process/index> -Documentazione per gli sviluppatori di applicazioni ---------------------------------------------------- -Il manuale delle API verso lo spazio utente è una collezione di documenti -che descrivono le interfacce del kernel viste dagli sviluppatori -di applicazioni. +Manuali sull'API interna +------------------------ -.. warning:: +Di seguito una serie di manuali per gli sviluppatori che hanno bisogno di +interfacciarsi con il resto del kernel. - TODO ancora da tradurre +.. toctree:: + :maxdepth: 1 + core-api/index -Introduzione allo sviluppo del kernel -------------------------------------- +Strumenti e processi per lo sviluppo +------------------------------------ -Questi manuali contengono informazioni su come contribuire allo sviluppo -del kernel. -Attorno al kernel Linux gira una comunità molto grande con migliaia di -sviluppatori che contribuiscono ogni anno. Come in ogni grande comunità, -sapere come le cose vengono fatte renderà il processo di integrazione delle -vostre modifiche molto più semplice +Di seguito una serie di manuali contenenti informazioni utili a tutti gli +sviluppatori del kernel. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - process/index + process/license-rules doc-guide/index kernel-hacking/index -Documentazione della API del kernel ------------------------------------ +Documentazione per gli utenti +----------------------------- -Questi manuali forniscono dettagli su come funzionano i sottosistemi del -kernel dal punto di vista degli sviluppatori del kernel. Molte delle -informazioni contenute in questi manuali sono prese direttamente dai -file sorgenti, informazioni aggiuntive vengono aggiunte solo se necessarie -(o almeno ci proviamo — probabilmente *non* tutto quello che è davvero -necessario). +Di seguito una serie di manuali per gli *utenti* del kernel - ovvero coloro che +stanno cercando di farlo funzionare al meglio per un dato sistema, ma anche +coloro che stanno sviluppando applicazioni che sfruttano l'API verso lo +spazio-utente. -.. toctree:: - :maxdepth: 2 +Consultate anche `Linux man pages <https://www.kernel.org/doc/man-pages/>`_, che +vengono mantenuti separatamente dalla documentazione del kernel Linux + +Documentazione relativa ai firmware +----------------------------------- +Di seguito informazioni sulle aspettative del kernel circa i firmware. - core-api/index Documentazione specifica per architettura ----------------------------------------- -Questi manuali forniscono dettagli di programmazione per le diverse -implementazioni d'architettura. -.. warning:: +Documentazione varia +-------------------- - TODO ancora da tradurre +Ci sono documenti che sono difficili da inserire nell'attuale organizzazione +della documentazione; altri hanno bisogno di essere migliorati e/o convertiti +nel formato *ReStructured Text*; altri sono semplicamente troppo vecchi. diff --git a/Documentation/translations/it_IT/kernel-hacking/hacking.rst b/Documentation/translations/it_IT/kernel-hacking/hacking.rst index 560f1d0482d2..dd06bfc1a050 100644 --- a/Documentation/translations/it_IT/kernel-hacking/hacking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/hacking.rst @@ -137,7 +137,7 @@ macro :c:func:`in_softirq()` (``include/linux/preempt.h``). .. warning:: State attenti che questa macro ritornerà un falso positivo - se :ref:`botton half lock <it_local_bh_disable>` è bloccato. + se :ref:`bottom half lock <it_local_bh_disable>` è bloccato. Alcune regole basilari ====================== diff --git a/Documentation/translations/it_IT/process/2.Process.rst b/Documentation/translations/it_IT/process/2.Process.rst index 62826034e0b2..25cd00351c03 100644 --- a/Documentation/translations/it_IT/process/2.Process.rst +++ b/Documentation/translations/it_IT/process/2.Process.rst @@ -136,18 +136,11 @@ Quindi, per esempio, la storia del kernel 5.2 appare così (anno 2019): La 5.2.21 fu l'aggiornamento finale per la versione 5.2. Alcuni kernel sono destinati ad essere kernel a "lungo termine"; questi -riceveranno assistenza per un lungo periodo di tempo. Al momento in cui -scriviamo, i manutentori dei kernel stabili a lungo termine sono: - - ====== ================================ ========================================== - 3.16 Ben Hutchings (kernel stabile molto più a lungo termine) - 4.4 Greg Kroah-Hartman e Sasha Levin (kernel stabile molto più a lungo termine) - 4.9 Greg Kroah-Hartman e Sasha Levin - 4.14 Greg Kroah-Hartman e Sasha Levin - 4.19 Greg Kroah-Hartman e Sasha Levin - 5.4i Greg Kroah-Hartman e Sasha Levin - ====== ================================ ========================================== +riceveranno assistenza per un lungo periodo di tempo. Consultate il seguente +collegamento per avere la lista delle versioni attualmente supportate e i +relativi manutentori: + https://www.kernel.org/category/releases.html Questa selezione di kernel di lungo periodo sono puramente dovuti ai loro manutentori, alla loro necessità e al tempo per tenere aggiornate proprio diff --git a/Documentation/translations/it_IT/process/7.AdvancedTopics.rst b/Documentation/translations/it_IT/process/7.AdvancedTopics.rst index cc1cff5d23ae..dffd813a0910 100644 --- a/Documentation/translations/it_IT/process/7.AdvancedTopics.rst +++ b/Documentation/translations/it_IT/process/7.AdvancedTopics.rst @@ -35,9 +35,9 @@ git è parte del processo di sviluppo del kernel. Gli sviluppatori che desiderassero diventare agili con git troveranno più informazioni ai seguenti indirizzi: - http://git-scm.com/ + https://git-scm.com/ - http://www.kernel.org/pub/software/scm/git/docs/user-manual.html + https://www.kernel.org/pub/software/scm/git/docs/user-manual.html e su varie guide che potrete trovare su internet. @@ -63,7 +63,7 @@ eseguire git-daemon è relativamente semplice . Altrimenti, iniziano a svilupparsi piattaforme che offrono spazi pubblici, e gratuiti (Github, per esempio). Gli sviluppatori permanenti possono ottenere un account su kernel.org, ma non è proprio facile da ottenere; per maggiori informazioni -consultate la pagina web http://kernel.org/faq/. +consultate la pagina web https://kernel.org/faq/. In git è normale avere a che fare con tanti rami. Ogni linea di sviluppo può essere separata in "rami per argomenti" e gestiti indipendentemente. @@ -137,7 +137,7 @@ vostri rami. Citando Linus facendo, e ho bisogno di fidarmi *senza* dover passare tutte le modifiche manualmente una per una. -(http://lwn.net/Articles/224135/). +(https://lwn.net/Articles/224135/). Per evitare queste situazioni, assicuratevi che tutte le patch in un ramo siano strettamente correlate al tema delle modifiche; un ramo "driver fixes" diff --git a/Documentation/translations/it_IT/process/botching-up-ioctls.rst b/Documentation/translations/it_IT/process/botching-up-ioctls.rst new file mode 100644 index 000000000000..91732cdf808a --- /dev/null +++ b/Documentation/translations/it_IT/process/botching-up-ioctls.rst @@ -0,0 +1,249 @@ +.. include:: ../disclaimer-ita.rst + +:Original: Documentation/process/botching-up-ioctls.rst + +========================================== +(Come evitare di) Raffazzonare delle ioctl +========================================== + +Preso da: https://blog.ffwll.ch/2013/11/botching-up-ioctls.html + +Scritto da : Daniel Vetter, Copyright © 2013 Intel Corporation + +Una cosa che gli sviluppatori del sottosistema grafico del kernel Linux hanno +imparato negli ultimi anni è l'inutilità di cercare di creare un'interfaccia +unificata per gestire la memoria e le unità esecutive di diverse GPU. Dunque, +oggigiorno ogni driver ha il suo insieme di ioctl per allocare memoria ed +inviare dei programmi alla GPU. Il che è va bene dato che non c'è più un insano +sistema che finge di essere generico, ma al suo posto ci sono interfacce +dedicate. Ma al tempo stesso è più facile incasinare le cose. + +Per evitare di ripetere gli stessi errori ho preso nota delle lezioni imparate +mentre raffazzonavo il driver drm/i915. La maggior parte di queste lezioni si +focalizzano sui tecnicismi e non sulla visione d'insieme, come le discussioni +riguardo al modo migliore per implementare una ioctl per inviare compiti alla +GPU. Probabilmente, ogni sviluppatore di driver per GPU dovrebbe imparare queste +lezioni in autonomia. + + +Prerequisiti +------------ + +Prima i prerequisiti. Seguite i seguenti suggerimenti se non volete fallire in +partenza e ritrovarvi ad aggiungere un livello di compatibilità a 32-bit. + +* Usate solamente interi a lunghezza fissa. Per evitare i conflitti coi tipi + definiti nello spazio utente, il kernel definisce alcuni tipi speciali, come: + ``__u32``, ``__s64``. Usateli. + +* Allineate tutto alla lunghezza naturale delle piattaforma in uso e riempite + esplicitamente i vuoti. Non necessariamente le piattaforme a 32-bit allineano + i valori a 64-bit rispettandone l'allineamento, ma le piattaforme a 64-bit lo + fanno. Dunque, per farlo correttamente in entrambe i casi dobbiamo sempre + riempire i vuoti. + +* Se una struttura dati contiene valori a 64-bit, allora fate si che la sua + dimensione sia allineata a 64-bit, altrimenti la sua dimensione varierà su + sistemi a 32-bit e 64-bit. Avere una dimensione differente causa problemi + quando si passano vettori di strutture dati al kernel, o quando il kernel + effettua verifiche sulla dimensione (per esempio il sistema drm lo fa). + +* I puntatori sono di tipo ``__u64``, con un *cast* da/a ``uintptr_t`` da lato + spazio utente e da/a ``void __user *`` nello spazio kernel. Sforzatevi il più + possibile per non ritardare la conversione, o peggio maneggiare ``__u64`` nel + vostro codice perché questo riduce le verifiche che strumenti come sparse + possono effettuare. La macro u64_to_user_ptr() può essere usata nel kernel + per evitare avvisi riguardo interi e puntatori di dimensioni differenti. + + +Le Basi +------- + +Con la gioia d'aver evitato un livello di compatibilità, possiamo ora dare uno +sguardo alle basi. Trascurare questi punti renderà difficile la gestione della +compatibilità all'indietro ed in avanti. E dato che sbagliare al primo colpo è +garantito, dovrete rivisitare il codice o estenderlo per ogni interfaccia. + +* Abbiate un modo chiaro per capire dallo spazio utente se una nuova ioctl, o + l'estensione di una esistente, sia supportata dal kernel in esecuzione. Se non + potete fidarvi del fatto che un vecchio kernel possa rifiutare correttamente + un nuovo *flag*, modalità, o ioctl, (probabilmente perché avevate raffazzonato + qualcosa nel passato) allora dovrete implementare nel driver un meccanismo per + notificare quali funzionalità sono supportate, o in alternativa un numero di + versione. + +* Abbiate un piano per estendere le ioctl con nuovi *flag* o campi alla fine di + una struttura dati. Il sistema drm verifica la dimensione di ogni ioctl in + arrivo, ed estende con zeri ogni incongruenza fra kernel e spazio utente. + Questo aiuta, ma non è una soluzione completa dato che uno spazio utente nuovo + su un kernel vecchio non noterebbe che i campi nuovi alla fine della struttura + vengono ignorati. Dunque, anche questo avrà bisogno di essere notificato dal + driver allo spazio utente. + +* Verificate tutti i campi e *flag* inutilizzati ed i riempimenti siano a 0, + altrimenti rifiutare la ioctl. Se non lo fate il vostro bel piano per + estendere le ioctl andrà a rotoli dato che qualcuno userà delle ioctl con + strutture dati con valori casuali dallo stack nei campi inutilizzati. Il che + si traduce nell'avere questi campi nell'ABI, e la cui unica utilità sarà + quella di contenere spazzatura. Per questo dovrete esplicitamente riempire i + vuoti di tutte le vostre strutture dati, anche se non le userete in un + vettore. Il riempimento fatto dal compilatore potrebbe contenere valori + casuali. + +* Abbiate un semplice codice di test per ognuno dei casi sopracitati. + + +Divertirsi coi percorsi d'errore +-------------------------------- + +Oggigiorno non ci sono più scuse rimaste per permettere ai driver drm di essere +sfruttati per diventare root. Questo significa che dobbiamo avere una completa +validazione degli input e gestire in modo robusto i percorsi - tanto le GPU +moriranno comunque nel più strano dei casi particolari: + + * Le ioctl devono verificare l'overflow dei vettori. Inoltre, per i valori + interi si devono verificare *overflow*, *underflow*, e *clamping*. Il + classico esempio è l'inserimento direttamente nell'hardware di valori di + posizionamento di un'immagine *sprite* quando l'hardware supporta giusto 12 + bit, o qualcosa del genere. Tutto funzionerà finché qualche strano *display + server* non decide di preoccuparsi lui stesso del *clamping* e il cursore + farà il giro dello schermo. + + * Avere un test semplice per ogni possibile fallimento della vostra ioctl. + Verificate che il codice di errore rispetti le aspettative. Ed infine, + assicuratevi che verifichiate un solo percorso sbagliato per ogni sotto-test + inviando comunque dati corretti. Senza questo, verifiche precedenti + potrebbero rigettare la ioctl troppo presto, impedendo l'esecuzione del + codice che si voleva effettivamente verificare, rischiando quindi di + mascherare bachi e regressioni. + + * Fate si che tutte le vostre ioctl siano rieseguibili. Prima di tutto X adora + i segnali; secondo questo vi permetterà di verificare il 90% dei percorsi + d'errore interrompendo i vostri test con dei segnali. Grazie all'amore di X + per i segnali, otterrete gratuitamente un eccellente copertura di base per + tutti i vostri percorsi d'errore. Inoltre, siate consistenti sul modo di + gestire la riesecuzione delle ioctl - per esempio, drm ha una piccola + funzione di supporto `drmIoctl` nella sua librerie in spazio utente. Il + driver i915 l'abbozza con l'ioctl `set_tiling`, ed ora siamo inchiodati per + sempre con una semantica arcana sia nel kernel che nello spazio utente. + + + * Se non potete rendere un pezzo di codice rieseguibile, almeno rendete + possibile la sua interruzione. Le GPU moriranno e i vostri utenti non vi + apprezzeranno affatto se tenete in ostaggio il loro scatolotto (mediante un + processo X insopprimibile). Se anche recuperare lo stato è troppo complicato, + allora implementate una scadenza oppure come ultima spiaggia una rete di + sicurezza per rilevare situazioni di stallo quando l'hardware da di matto. + + * Preparate dei test riguardo ai casi particolarmente estremi nel codice di + recupero del sistema - è troppo facile create uno stallo fra il vostro codice + anti-stallo e un processo scrittore. + + +Tempi, attese e mancate scadenze +-------------------------------- + +Le GPU fanno quasi tutto in modo asincrono, dunque dobbiamo regolare le +operazioni ed attendere quelle in sospeso. Questo è davvero difficile; al +momento nessuna delle ioctl supportante dal driver drm/i915 riesce a farlo +perfettamente, il che significa che qui ci sono ancora una valanga di lezioni da +apprendere. + + * Per fare riferimento al tempo usate sempre ``CLOCK_MONOTONIC``. Oggigiorno + questo è quello che viene usato di base da alsa, drm, e v4l. Tuttavia, + lasciate allo spazio utente la possibilità di capire quali *timestamp* + derivano da domini temporali diversi come il vostro orologio di sistema + (fornito dal kernel) oppure un contatore hardware indipendente da qualche + parte. Gli orologi divergeranno, ma con questa informazione gli strumenti di + analisi delle prestazioni possono compensare il problema. Se il vostro spazio + utente può ottenere i valori grezzi degli orologi, allora considerate di + esporre anch'essi. + + * Per descrivere il tempo, usate ``__s64`` per i secondi e ``__u64`` per i + nanosecondi. Non è il modo migliore per specificare il tempo, ma è + praticamente uno standard. + + * Verificate che gli input di valori temporali siano normalizzati, e se non lo + sono scartateli. Fate attenzione perché la struttura dati ``struct ktime`` + del kernel usa interi con segni sia per i secondi che per i nanosecondi. + + * Per le scadenze (*timeout*) usate valori temporali assoluti. Se siete dei + bravi ragazzi e avete reso la vostra ioctl rieseguibile, allora i tempi + relativi tendono ad essere troppo grossolani e a causa degli arrotondamenti + potrebbero estendere in modo indefinito i tempi di attesa ad ogni + riesecuzione. Particolarmente vero se il vostro orologio di riferimento è + qualcosa di molto lento come il contatore di *frame*. Con la giacca da + avvocato delle specifiche diremmo che questo non è un baco perché tutte le + scadenze potrebbero essere estese - ma sicuramente gli utenti vi odieranno + quando le animazioni singhiozzano. + + * Considerate l'idea di eliminare tutte le ioctl sincrone con scadenze, e di + sostituirle con una versione asincrona il cui stato può essere consultato + attraverso il descrittore di file mediante ``poll``. Questo approccio si + sposa meglio in un applicazione guidata dagli eventi. + + * Sviluppate dei test per i casi estremi, specialmente verificate che i valori + di ritorno per gli eventi già completati, le attese terminate con successo, e + le attese scadute abbiano senso e servano ai vostri scopi. + + +Non perdere risorse +------------------- +Nel suo piccolo il driver drm implementa un sistema operativo specializzato per +certe GPU. Questo significa che il driver deve esporre verso lo spazio +utente tonnellate di agganci per accedere ad oggetti e altre risorse. Farlo +correttamente porterà con se alcune insidie: + + * Collegate sempre la vita di una risorsa creata dinamicamente, a quella del + descrittore di file. Considerate una mappatura 1:1 se la vostra risorsa + dev'essere condivisa fra processi - passarsi descrittori di file sul socket + unix semplifica la gestione anche per lo spazio utente. + + * Dev'esserci sempre Il supporto ``O_CLOEXEC``. + + * Assicuratevi di avere abbastanza isolamento fra utenti diversi. Di base + impostate uno spazio dei nomi riservato per ogni descrittore di file, il che + forzerà ogni condivisione ad essere esplicita. Usate uno spazio più globale + per dispositivo solo se gli oggetti sono effettivamente unici per quel + dispositivo. Un controesempio viene dall'interfaccia drm modeset, dove + oggetti specifici di dispositivo, come i connettori, condividono uno spazio + dei nomi con oggetti per il *framebuffer*, ma questi non sono per niente + condivisi. Uno spazio separato, privato di base, per i *framebuffer* sarebbe + stato meglio. + + * Pensate all'identificazione univoca degli agganci verso lo spazio utente. Per + esempio, per la maggior parte dei driver drm, si considera fallace la doppia + sottomissione di un oggetto allo stesso comando ioctl. Ma per evitarlo, se + gli oggetti sono condivisibili, lo spazio utente ha bisogno di sapere se il + driver ha importato un oggetto da un altro processo. Non l'ho ancora provato, + ma considerate l'idea di usare il numero di inode come identificatore per i + descrittori di file condivisi - che poi è come si distinguono i veri file. + Sfortunatamente, questo richiederebbe lo sviluppo di un vero e proprio + filesystem virtuale nel kernel. + + +Ultimo, ma non meno importante +------------------------------ + +Non tutti i problemi si risolvono con una nuova ioctl: + +* Pensateci su due o tre volte prima di implementare un'interfaccia privata per + un driver. Ovviamente è molto più veloce seguire questa via piuttosto che + buttarsi in lunghe discussioni alla ricerca di una soluzione più generica. Ed + a volte un'interfaccia privata è quello che serve per sviluppare un nuovo + concetto. Ma alla fine, una volta che c'è un'interfaccia generica a + disposizione finirete per mantenere due interfacce. Per sempre. + +* Considerate interfacce alternative alle ioctl. Gli attributi sysfs sono molto + meglio per impostazioni che sono specifiche di un dispositivo, o per + sotto-oggetti con una vita piuttosto statica (come le uscite dei connettori in + drm con tutti gli attributi per la sovrascrittura delle rilevazioni). O magari + solo il vostro sistema di test ha bisogno di una certa interfaccia, e allora + debugfs (che non ha un'interfaccia stabile) sarà la soluzione migliore. + +Per concludere. Questo gioco consiste nel fare le cose giuste fin da subito, +dato che se il vostro driver diventa popolare e la piattaforma hardware longeva +finirete per mantenere le vostre ioctl per sempre. Potrete tentare di deprecare +alcune orribili ioctl, ma ci vorranno anni per riuscirci effettivamente. E +ancora, altri anni prima che sparisca l'ultimo utente capace di lamentarsi per +una regressione. diff --git a/Documentation/translations/it_IT/process/changes.rst b/Documentation/translations/it_IT/process/changes.rst index 10e0ef9c34b7..473ec2cc558e 100644 --- a/Documentation/translations/it_IT/process/changes.rst +++ b/Documentation/translations/it_IT/process/changes.rst @@ -35,6 +35,7 @@ PC Card, per esempio, probabilmente non dovreste preoccuparvi di pcmciautils. GNU C 5.1 gcc --version Clang/LLVM (optional) 11.0.0 clang --version GNU make 3.81 make --version +bash 4.2 bash --version binutils 2.23 ld -v flex 2.5.35 flex --version bison 2.0 bison --version @@ -88,6 +89,11 @@ Make Per compilare il kernel vi servirà GNU make 3.81 o successivo. +Bash +---- +Per generare il kernel vengono usati alcuni script per bash. +Questo richiede bash 4.2 o successivo. + Binutils -------- @@ -370,6 +376,11 @@ Make - <ftp://ftp.gnu.org/gnu/make/> +Bash +---- + +- <ftp://ftp.gnu.org/gnu/bash/> + Binutils -------- diff --git a/Documentation/translations/it_IT/process/email-clients.rst b/Documentation/translations/it_IT/process/email-clients.rst index de7d32f78246..970671cd91af 100644 --- a/Documentation/translations/it_IT/process/email-clients.rst +++ b/Documentation/translations/it_IT/process/email-clients.rst @@ -106,7 +106,7 @@ Funziona. Alcune persone riescono ad usarlo con successo per inviare le patch. Per inserire una patch usate :menuselection:`Messaggio-->Inserisci file` (:kbd:`CTRL-I`) oppure un editor esterno. -Se la patch che avete inserito dev'essere modificata usato la finestra di +Se la patch che avete inserito dev'essere modificata usando la finestra di scrittura di Claws, allora assicuratevi che l'"auto-interruzione" sia disabilitata :menuselection:`Configurazione-->Preferenze-->Composizione-->Interruzione riga`. @@ -288,37 +288,62 @@ Thunderbird (GUI) Thunderbird è un clone di Outlook a cui piace maciullare il testo, ma esistono modi per impedirglielo. +Dopo la configurazione, inclusa l'installazione delle estenzioni, dovrete +riavviare Thunderbird. + - permettere l'uso di editor esterni: + La cosa più semplice da fare con Thunderbird e le patch è quello di usare - l'estensione "external editor" e di usare il vostro ``$EDITOR`` preferito per - leggere/includere patch nel vostro messaggio. Per farlo, scaricate ed - installate l'estensione e aggiungete un bottone per chiamarla rapidamente - usando :menuselection:`Visualizza-->Barra degli strumenti-->Personalizza...`; - una volta fatto potrete richiamarlo premendo sul bottone mentre siete nella - finestra :menuselection:`Scrivi` - - Tenete presente che "external editor" richiede che il vostro editor non - faccia alcun fork, in altre parole, l'editor non deve ritornare prima di - essere stato chiuso. Potreste dover passare dei parametri aggiuntivi al - vostro editor oppure cambiargli la configurazione. Per esempio, usando - gvim dovrete aggiungere l'opzione -f ``/usr/bin/gvim -f`` (Se il binario - si trova in ``/usr/bin``) nell'apposito campo nell'interfaccia di - configurazione di :menuselection:`external editor`. Se usate altri editor - consultate il loro manuale per sapere come configurarli. + estensioni che permettano di aprire il vostro editor preferito. + + Di seguito alcune estensioni che possono essere utili al caso. + + - "External Editor Revived" + + https://github.com/Frederick888/external-editor-revived + + https://addons.thunderbird.net/en-GB/thunderbird/addon/external-editor-revived/ + + L'estensione richiede l'installazione di "native messaging host". Date + un'occhiata alla seguente wiki: + https://github.com/Frederick888/external-editor-revived/wiki + + - "External Editor" + + https://github.com/exteditor/exteditor + + Per usarlo, scaricate ed installate l'applicazione. Poi aprite la finestra + :menuselection:`Scrivi` e a seguire aggiungete un bottone per eseguirlo + `Visualizza-->Barra degli strumenti-->Personalizza...`. Infine, premente + questo nuovo bottone tutte le volte che volete usare l'editor esterno. + + Tenete presente che "external editor" richiede che il vostro editor non + faccia alcun fork, in altre parole, l'editor non deve ritornare prima di + essere stato chiuso. Potreste dover passare dei parametri aggiuntivi al + vostro editor oppure cambiargli la configurazione. Per esempio, usando + gvim dovrete aggiungere l'opzione -f ``/usr/bin/gvim -f`` (Se il binario + si trova in ``/usr/bin``) nell'apposito campo nell'interfaccia di + configurazione di :menuselection:`external editor`. Se usate altri editor + consultate il loro manuale per sapere come configurarli.``)`` Per rendere l'editor interno un po' più sensato, fate così: -- Modificate le impostazioni di Thunderbird per far si che non usi - ``format=flowed``. Andate in :menuselection:`Modifica-->Preferenze-->Avanzate-->Editor di configurazione` +- Modificate le impostazioni di Thunderbird per far si che non usi ``format=flowed``! + Andate sulla finestra principale e cercate il bottone per il menu a tendina principale. + Poi :menuselection:`Modifica-->Preferenze-->Avanzate-->Editor di configurazione` per invocare il registro delle impostazioni. -- impostate ``mailnews.send_plaintext_flowed`` a ``false`` + - impostate ``mailnews.send_plaintext_flowed`` a ``false`` -- impostate ``mailnews.wraplength`` da ``72`` a ``0`` + - impostate ``mailnews.wraplength`` da ``72`` a ``0`` -- :menuselection:`Visualizza-->Corpo del messaggio come-->Testo semplice` +- Non scrivete messaggi HTML! Andate sulla finestra principale ed aprite la + schermata :menuselection:`Menu principale-->Impostazioni account-->nome@unserver.ovunque-->Composizioni e indirizzi`. + Qui potrete disabilitare l'opzione "Componi i messaggi in HTML" -- :menuselection:`Visualizza-->Codifica del testo-->Unicode` +- Aprite i messaggi solo in formato testo! Andate sulla finestra principale e + selezionate + :menuselection:`Menu principale-->Visualizza-->Copro del messaggio come-->Testo semplice` TkRat (GUI) diff --git a/Documentation/translations/it_IT/process/index.rst b/Documentation/translations/it_IT/process/index.rst index 8d4e36a07ff4..25602c1a97d1 100644 --- a/Documentation/translations/it_IT/process/index.rst +++ b/Documentation/translations/it_IT/process/index.rst @@ -58,6 +58,7 @@ perché non si è trovato un posto migliore. adding-syscalls magic-number volatile-considered-harmful + botching-up-ioctls clang-format ../riscv/patch-acceptance diff --git a/Documentation/translations/it_IT/process/kernel-docs.rst b/Documentation/translations/it_IT/process/kernel-docs.rst index 38e0a955121a..eadcbf50a1b5 100644 --- a/Documentation/translations/it_IT/process/kernel-docs.rst +++ b/Documentation/translations/it_IT/process/kernel-docs.rst @@ -6,8 +6,8 @@ .. _it_kernel_docs: -Indice di documenti per le persone interessate a capire e/o scrivere per il kernel Linux -======================================================================================== +Ulteriore Documentazione Del Kernel Linux +========================================= .. note:: Questo documento contiene riferimenti a documenti in lingua inglese; inoltre diff --git a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst index a1e98ec9532e..5526bcabeb0a 100644 --- a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst +++ b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst @@ -163,7 +163,7 @@ chiave principale attraverso firme certificate. È quindi importante comprendere i seguenti punti: 1. Non ci sono differenze tecniche tra la chiave principale e la sottochiave. -2. In fesa di creazione, assegniamo limitazioni funzionali ad ogni chiave +2. In fase di creazione, assegniamo limitazioni funzionali ad ogni chiave assegnando capacità specifiche. 3. Una chiave PGP può avere 4 capacità: @@ -286,9 +286,7 @@ magari in una cassetta di sicurezza in banca. Probabilmente la vostra stampante non è più quello stupido dispositivo connesso alla porta parallela, ma dato che il suo output è comunque criptato con la passphrase, eseguire la stampa in un sistema "cloud" - moderno dovrebbe essere comunque relativamente sicuro. Un'opzione potrebbe - essere quella di cambiare la passphrase della vostra chiave primaria - subito dopo aver finito con paperkey. + moderno dovrebbe essere comunque relativamente sicuro. Copia di riserva di tutta la cartella GnuPG ------------------------------------------- diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst index a3bb0008837a..c2cfa0948b2b 100644 --- a/Documentation/translations/it_IT/process/submitting-patches.rst +++ b/Documentation/translations/it_IT/process/submitting-patches.rst @@ -340,7 +340,7 @@ Assicuratevi di dire ai revisori quali cambiamenti state facendo e di ringraziarli per il loro tempo. Revisionare codice è un lavoro faticoso e che richiede molto tempo, e a volte i revisori diventano burberi. Tuttavia, anche in questo caso, rispondete con educazione e concentratevi sul problema che hanno -evidenziato. Quando inviate una version successiva ricordatevi di aggiungere un +evidenziato. Quando inviate una versione successiva ricordatevi di aggiungere un ``patch changelog`` alla email di intestazione o ad ogni singola patch spiegando le differenze rispetto a sottomissioni precedenti (vedere :ref:`it_the_canonical_patch_format`). diff --git a/Documentation/translations/sp_SP/process/code-of-conduct.rst b/Documentation/translations/sp_SP/process/code-of-conduct.rst new file mode 100644 index 000000000000..adc6c770cc37 --- /dev/null +++ b/Documentation/translations/sp_SP/process/code-of-conduct.rst @@ -0,0 +1,97 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/code-of-conduct.rst <code_of_conduct>` +:Translator: Contributor Covenant and Carlos Bilbao <carlos.bilbao@amd.com> + +.. _sp_code_of_conduct: + +Código de Conducta para Contribuyentes ++++++++++++++++++++++++++++++++++++++++ + +Nuestro Compromiso +================== + +Nosotros, como miembros, contribuyentes y administradores nos comprometemos +a hacer de la participación en nuestra comunidad una experiencia libre de +acoso para todo el mundo, independientemente de la edad, dimensión corporal, +minusvalía visible o invisible, etnicidad, características sexuales, +identidad y expresión de género, nivel de experiencia, educación, nivel +socio-económico, nacionalidad, apariencia personal, raza, religión, o +identidad u orientación sexual. Nos comprometemos a actuar e interactuar de +maneras que contribuyan a una comunidad abierta, acogedora, diversa, +inclusiva y sana. + +Nuestros Estándares +=================== + +Ejemplos de comportamiento que contribuyen a crear un ambiente positivo +para nuestra comunidad: + +* Demostrar empatía y amabilidad ante otras personas +* Respeto a diferentes opiniones, puntos de vista y experiencias +* Dar y aceptar adecuadamente retroalimentación constructiva +* Aceptar la responsabilidad y disculparse ante quienes se vean afectados + por nuestros errores, aprendiendo de la experiencia +* Centrarse en lo que sea mejor no sólo para nosotros como individuos, sino + para la comunidad en general + + +Ejemplos de comportamiento inaceptable: + +* El uso de lenguaje o imágenes sexualizadas, y aproximaciones o + atenciones sexuales de cualquier tipo +* Comentarios despectivos (trolling), insultantes o derogatorios, y ataques + personales o políticos +* El acoso en público o privado +* Publicar información privada de otras personas, tales como direcciones + físicas o de correo + electrónico, sin su permiso explícito +* Otras conductas que puedan ser razonablemente consideradas como + inapropiadas en un entorno profesional + + +Aplicación de las responsabilidades +=================================== + +Los administradores de la comunidad son responsables de aclarar y hacer +cumplir nuestros estándares de comportamiento aceptable y tomarán acciones +apropiadas y correctivas de forma justa en respuesta a cualquier +comportamiento que consideren inapropiado, amenazante, ofensivo o dañino. + +Los administradores de la comunidad tendrán el derecho y la responsabilidad +de eliminar, editar o rechazar comentarios, commits, código, ediciones de +páginas de wiki, issues y otras contribuciones que no se alineen con este +Código de Conducta, y comunicarán las razones para sus decisiones de +moderación cuando sea apropiado. + +Alcance +======= + +Este código de conducta aplica tanto a espacios del proyecto como a +espacios públicos donde un individuo esté en representación del proyecto o +comunidad. Ejemplos de esto incluyen el uso de la cuenta oficial de correo +electrónico, publicaciones a través de las redes sociales oficiales, o +presentaciones con personas designadas en eventos en línea o no. + +Aplicación +========== + +Instancias de comportamiento abusivo, acosador o inaceptable de otro modo +podrán ser reportadas contactando el Code of Conduct Commitee a través de +<conduct@kernel.org>. Todas las quejas serán evaluadas e investigadas de +una manera puntual y justa. El Code of Condut Commitee está obligados a +respetar la privacidad y la seguridad de quienes reporten incidentes. +Detalles de políticas y aplicación en particular, serán incluidos por +separado. + +Atribución +========== + +Este Código de Conducta es una adaptación del Contributor Covenant, versión +1.4, disponible en https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +Interpretación +============== + +Consulte el documento :ref:`code_of_conduct_interpretation` para ver cómo +interpretará la comunidad del kernel Linux este documento. diff --git a/Documentation/translations/sp_SP/process/index.rst b/Documentation/translations/sp_SP/process/index.rst index 49a05f6a5544..f7e1f3d814f2 100644 --- a/Documentation/translations/sp_SP/process/index.rst +++ b/Documentation/translations/sp_SP/process/index.rst @@ -13,3 +13,5 @@ submitting-patches kernel-docs coding-style + code-of-conduct + kernel-enforcement-statement diff --git a/Documentation/translations/sp_SP/process/kernel-enforcement-statement.rst b/Documentation/translations/sp_SP/process/kernel-enforcement-statement.rst new file mode 100644 index 000000000000..d66902694089 --- /dev/null +++ b/Documentation/translations/sp_SP/process/kernel-enforcement-statement.rst @@ -0,0 +1,174 @@ +.. include:: ../disclaimer-sp.rst + +:Original: :ref:`Documentation/process/kernel-enforcement-statement.rst <process_statement_kernel>` +:Translator: Carlos Bilbao <carlos.bilbao@amd.com> + +.. _sp_process_statement_kernel: + +Aplicación de la licencia en el kernel Linux +============================================ + +Como desarrolladores del kernel Linux, tenemos un gran interés en cómo se +se utiliza nuestro software y cómo se aplica la licencia de nuestro software. +El cumplimiento de las obligaciones de intercambio recíproco de GPL-2.0 son +fundamentales en el largo plazo para la sostenibilidad de nuestro software +y comunidad. + +Aunque existe el derecho de hacer valer un copyright distinto en las +contribuciones hechas a nuestra comunidad, compartimos el interés de +asegurar que las acciones individuales para proteger estos se lleven a cabo +de una manera que beneficia a nuestra comunidad y no tenga un indeseado +impacto negativo en la salud y crecimiento de nuestro ecosistema de software. +Con el fin de disuadir la aplicación inútil de acciones, estamos de acuerdo +en que es en el mejor interés de nuestro desarrollo como comunidad asumir +el siguiente compromiso con los usuarios del kernel Linux, en nombre +nuestro y de cualquier sucesor de nuestros derechos de autor (copyright): + + Sin perjuicio de las disposiciones de terminación de GPL-2.0, aceptamos + que es en el mejor interés de nuestra comunidad de desarrollo adoptar + las siguientes disposiciones de GPL-3.0 como permisos adicionales bajo + nuestra licencia, con respecto a cualquier interposición de alegación + de infringimiento (en inglés, "non-defensive assertion") de los + derechos bajo la licencia. + + Sin embargo, si deja de violar esta Licencia, entonces su licencia + de copyright como particular se restablece (a) provisionalmente, + a menos que y hasta que el titular de los derechos de autor explícita + y finalmente rescinda su licencia, y (b) de forma permanente, si el + titular de los derechos de autor no le notifica la violación por algún + medio razonable antes de 60 días después del cese. + + Además, su licencia de un titular de derechos de autor en particular es + restablecida permanentemente si el titular de los derechos de autor le + notifica de la violación por algún medio razonable, esta es la primera + vez que ha recibido notificación de violación de esta Licencia (para + cualquier trabajo) de ese titular de los derechos de autor, y subsana + la infracción antes de los 30 días posteriores de recibir el aviso. + +Nuestra intención al proporcionar estas garantías es fomentar un mayor uso +del software. Queremos que empresas y particulares utilicen, modifiquen y +distribuyan este software. Queremos trabajar con los usuarios de forma +abierta y transparente para eliminar cualquier incertidumbre sobre nuestras +expectativas con respecto al cumplimiento que podría limitar la adopción de +nuestro software. Entendemos la acción legal como último recurso, que se +iniciará solo cuando otros esfuerzos de la comunidad no hayan podido +resolver el problema. + +Finalmente, una vez que se resuelva un problema de incumplimiento, +esperamos que el usuario se sienta bienvenido a unirse a nosotros en +nuestros esfuerzos con este proyecto. Trabajando juntos, somos más fuertes. + +Excepto donde se indica a continuación, hablamos solo por nosotros mismos y +no por ninguna compañía donde puede que trabajemos hoy, o hayamos trabajado +en el pasado, o trabajaremos en el futuro. + +- Laura Abbott +- Bjorn Andersson (Linaro) +- Andrea Arcangeli +- Neil Armstrong +- Jens Axboe +- Pablo Neira Ayuso +- Khalid Aziz +- Ralf Baechle +- Felipe Balbi +- Arnd Bergmann +- Ard Biesheuvel +- Tim Bird +- Paolo Bonzini +- Christian Borntraeger +- Mark Brown (Linaro) +- Paul Burton +- Javier Martinez Canillas +- Rob Clark +- Kees Cook (Google) +- Jonathan Corbet +- Dennis Dalessandro +- Vivien Didelot (Savoir-faire Linux) +- Hans de Goede +- Mel Gorman (SUSE) +- Sven Eckelmann +- Alex Elder (Linaro) +- Fabio Estevam +- Larry Finger +- Bhumika Goyal +- Andy Gross +- Juergen Gross +- Shawn Guo +- Ulf Hansson +- Stephen Hemminger (Microsoft) +- Tejun Heo +- Rob Herring +- Masami Hiramatsu +- Michal Hocko +- Simon Horman +- Johan Hovold (Hovold Consulting AB) +- Christophe JAILLET +- Olof Johansson +- Lee Jones (Linaro) +- Heiner Kallweit +- Srinivas Kandagatla +- Jan Kara +- Shuah Khan (Samsung) +- David Kershner +- Jaegeuk Kim +- Namhyung Kim +- Colin Ian King +- Jeff Kirsher +- Greg Kroah-Hartman (Linux Foundation) +- Christian König +- Vinod Koul +- Krzysztof Kozlowski +- Viresh Kumar +- Aneesh Kumar K.V +- Julia Lawall +- Doug Ledford +- Chuck Lever (Oracle) +- Daniel Lezcano +- Shaohua Li +- Xin Long +- Tony Luck +- Catalin Marinas (Arm Ltd) +- Mike Marshall +- Chris Mason +- Paul E. McKenney +- Arnaldo Carvalho de Melo +- David S. Miller +- Ingo Molnar +- Kuninori Morimoto +- Trond Myklebust +- Martin K. Petersen (Oracle) +- Borislav Petkov +- Jiri Pirko +- Josh Poimboeuf +- Sebastian Reichel (Collabora) +- Guenter Roeck +- Joerg Roedel +- Leon Romanovsky +- Steven Rostedt (VMware) +- Frank Rowand +- Ivan Safonov +- Anna Schumaker +- Jes Sorensen +- K.Y. Srinivasan +- David Sterba (SUSE) +- Heiko Stuebner +- Jiri Kosina (SUSE) +- Willy Tarreau +- Dmitry Torokhov +- Linus Torvalds +- Thierry Reding +- Rik van Riel +- Luis R. Rodriguez +- Geert Uytterhoeven (Glider bvba) +- Eduardo Valentin (Amazon.com) +- Daniel Vetter +- Linus Walleij +- Richard Weinberger +- Dan Williams +- Rafael J. Wysocki +- Arvind Yadav +- Masahiro Yamada +- Wei Yongjun +- Lv Zheng +- Marc Zyngier (Arm Ltd) + diff --git a/Documentation/translations/zh_CN/PCI/msi-howto.rst b/Documentation/translations/zh_CN/PCI/msi-howto.rst index 7ea4d50cdad2..1b9b5ea790d8 100644 --- a/Documentation/translations/zh_CN/PCI/msi-howto.rst +++ b/Documentation/translations/zh_CN/PCI/msi-howto.rst @@ -231,3 +231,14 @@ ACPI FADT表中指明了它。在这种情况下，Linux会自动禁用MSI。有 也需要检查设备驱动程序，看它是否支持MSI。例如，它可能包含对带有PCI_IRQ_MSI或 PCI_IRQ_MSIX标志的pci_alloc_irq_vectors（）的调用。 + + +MSI(-X) APIs设备驱动程序列表 +============================ + +PCI/MSI子系统有一个专门的C文件，用于其导出的设备驱动程序APIs - `drivers/pci/msi/api.c` 。 +以下是导出的函数: + +该API在以下内核代码中: + +drivers/pci/msi/api.c diff --git a/Documentation/translations/zh_CN/accounting/delay-accounting.rst b/Documentation/translations/zh_CN/accounting/delay-accounting.rst index f1849411018e..a01dc3d5b0db 100644 --- a/Documentation/translations/zh_CN/accounting/delay-accounting.rst +++ b/Documentation/translations/zh_CN/accounting/delay-accounting.rst @@ -17,8 +17,9 @@ a) 等待一个CPU（任务为可运行） b) 完成由该任务发起的块I/O同步请求 c) 页面交换 d) 内存回收 -e) 页缓存抖动 +e) 抖动 f) 直接规整 +g) 写保护复制 并将这些统计信息通过taskstats接口提供给用户空间。 @@ -42,7 +43,7 @@ f) 直接规整 include/uapi/linux/taskstats.h 其描述了延时计数相关字段。系统通常以计数器形式返回 CPU、同步块 I/O、交换、内存 -回收、页缓存抖动、直接规整等的累积延时。 +回收、页缓存抖动、直接规整、写保护复制等的累积延时。 取任务某计数器两个连续读数的差值，将得到任务在该时间间隔内等待对应资源的总延时。 @@ -100,6 +101,8 @@ getdelays命令的一般格式:: 0 0 0ms COMPACT count delay total delay average 0 0 0ms + WPCOPY count delay total delay average + 0 0 0ms 获取pid为1的IO计数，它只和-p一起使用:: # ./getdelays -i -p 1 diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst index c976f3e33ffd..bb185b7a9b9c 100644 --- a/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst @@ -47,10 +47,6 @@ DAMON_RECLAIM找到在特定时间内没有被访问的内存区域并分页。 是说，你可以把 ``damon_reclaim.<parameter>=<value>`` 放在内核启动命令行上，或者把 适当的值写入 ``/sys/modules/damon_reclaim/parameters/<parameter>`` 文件。 -注意，除 ``启用`` 外的参数值只在DAMON_RECLAIM启动时应用。因此，如果你想在运行时应用新 -的参数值，而DAMON_RECLAIM已经被启用，你应该通过 ``启用`` 的参数文件禁用和重新启用它。 -在重新启用之前，应将新的参数值写入适当的参数值中。 - 下面是每个参数的描述。 enabled diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst index 67d1b49481dc..bf21ff84f396 100644 --- a/Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst @@ -34,16 +34,8 @@ https://github.com/awslabs/damo找到。下面的例子假设DAMO在你的$PATH上。当然，但 这并不是强制性的。 -因为DAMO使用的是DAMON的debugfs接口(详情请参考 :doc:`usage` 中的使用方法) 你应该 -确保debugfs被挂载。手动挂载它，如下所示:: - - # mount -t debugfs none /sys/kernel/debug/ - -或者在你的 ``/etc/fstab`` 文件中添加以下一行，这样你的系统就可以在启动时自动挂载 -debugfs了:: - - debugfs /sys/kernel/debug debugfs defaults 0 0 - +因为DAMO使用了DAMON的sysfs接口（详情请参考:doc:`usage`），你应该确保 +:doc:`sysfs </filesystems/sysfs>` 被挂载。 记录数据访问模式 ================ diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst index aeae2ab65dd8..17b9949d9b43 100644 --- a/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst @@ -46,10 +46,10 @@ DAMON的sysfs接口是在定义 ``CONFIG_DAMON_SYSFS`` 时建立的。它在其s 对于一个简短的例子，用户可以监测一个给定工作负载的虚拟地址空间，如下所示:: # cd /sys/kernel/mm/damon/admin/ - # echo 1 > kdamonds/nr && echo 1 > kdamonds/0/contexts/nr + # echo 1 > kdamonds/nr_kdamonds && echo 1 > kdamonds/0/contexts/nr_contexts # echo vaddr > kdamonds/0/contexts/0/operations - # echo 1 > kdamonds/0/contexts/0/targets/nr - # echo $(pidof <workload>) > kdamonds/0/contexts/0/targets/0/pid + # echo 1 > kdamonds/0/contexts/0/targets/nr_targets + # echo $(pidof <workload>) > kdamonds/0/contexts/0/targets/0/pid_target # echo on > kdamonds/0/state 文件层次结构 @@ -82,6 +82,9 @@ DAMON sysfs接口的文件层次结构如下图所示。在下图中，父子关 │ │ │ │ │ │ │ │ weights/sz_permil,nr_accesses_permil,age_permil │ │ │ │ │ │ │ watermarks/metric,interval_us,high,mid,low │ │ │ │ │ │ │ stats/nr_tried,sz_tried,nr_applied,sz_applied,qt_exceeds + │ │ │ │ │ │ │ tried_regions/ + │ │ │ │ │ │ │ │ 0/start,end,nr_accesses,age + │ │ │ │ │ │ │ │ ... │ │ │ │ │ │ ... │ │ │ │ ... │ │ ... @@ -111,7 +114,11 @@ kdamonds/<N>/ 读取 ``state`` 时，如果kdamond当前正在运行，则返回 ``on`` ，如果没有运行则返回 ``off`` 。 写入 ``on`` 或 ``off`` 使kdamond处于状态。向 ``state`` 文件写 ``update_schemes_stats`` ， 更新kdamond的每个基于DAMON的操作方案的统计文件的内容。关于统计信息的细节，请参考 -:ref:`stats section <sysfs_schemes_stats>`. +:ref:`stats section <sysfs_schemes_stats>`. 将 ``update_schemes_tried_regions`` 写到 +``state`` 文件，为kdamond的每个基于DAMON的操作方案，更新基于DAMON的操作方案动作的尝试区域目录。 +将`clear_schemes_tried_regions`写入`state`文件，清除kdamond的每个基于DAMON的操作方案的动作 +尝试区域目录。 关于基于DAMON的操作方案动作尝试区域目录的细节，请参考:ref:tried_regions 部分 +<sysfs_schemes_tried_regions>`。 如果状态为 ``on``，读取 ``pid`` 显示kdamond线程的pid。 @@ -186,6 +193,8 @@ regions/<N>/ 在每个区域目录中，你会发现两个文件（ ``start`` 和 ``end`` ）。你可以通过向文件写入 和从文件中读出，分别设置和获得初始监测目标区域的起始和结束地址。 +每个区域不应该与其他区域重叠。 目录“N”的“结束”应等于或小于目录“N+1”的“开始”。 + contexts/<N>/schemes/ --------------------- @@ -199,8 +208,8 @@ contexts/<N>/schemes/ schemes/<N>/ ------------ -在每个方案目录中，存在四个目录(``access_pattern``, ``quotas``,``watermarks``, -和 ``stats``)和一个文件(``action``)。 +在每个方案目录中，存在五个目录(``access_pattern``、``quotas``、``watermarks``、 +``stats`` 和 ``tried_regions``)和一个文件(``action``)。 ``action`` 文件用于设置和获取你想应用于具有特定访问模式的内存区域的动作。可以写入文件 和从文件中读取的关键词及其含义如下。 @@ -229,8 +238,8 @@ schemes/<N>/quotas/ 每个 ``动作`` 的最佳 ``目标访问模式`` 取决于工作负载，所以不容易找到。更糟糕的是，将某些动作 的方案设置得过于激进会造成严重的开销。为了避免这种开销，用户可以为每个方案限制时间和大小配额。 -具体来说，用户可以要求DAMON尽量只使用特定的时间（``时间配额``）来应用行动，并且在给定的时间间 -隔（``重置间隔``）内，只对具有目标访问模式的内存区域应用行动，而不使用特定数量（``大小配额``）。 +具体来说，用户可以要求DAMON尽量只使用特定的时间（``时间配额``）来应用动作，并且在给定的时间间 +隔（``重置间隔``）内，只对具有目标访问模式的内存区域应用动作，而不使用特定数量（``大小配额``）。 当预计超过配额限制时，DAMON会根据 ``目标访问模式`` 的大小、访问频率和年龄，对找到的内存区域 进行优先排序。为了进行个性化的优先排序，用户可以为这三个属性设置权重。 @@ -272,6 +281,24 @@ DAMON统计每个方案被尝试应用的区域的总数量和字节数，每个 你应该要求DAMON sysfs接口通过在相关的 ``kdamonds/<N>/state`` 文件中写入一个特殊的关键字 ``update_schemes_stats`` 来更新统计信息的文件内容。 +schemes/<N>/tried_regions/ +-------------------------- + +当一个特殊的关键字 ``update_schemes_tried_regions`` 被写入相关的 ``kdamonds/<N>/state`` +文件时，DAMON会在这个目录下创建从 ``0`` 开始命名的整数目录。每个目录包含的文件暴露了关于每个 +内存区域的详细信息，在下一个 :ref:`聚集区间 <sysfs_monitoring_attrs>`，相应的方案的 ``动作`` +已经尝试在这个目录下应用。这些信息包括地址范围、``nr_accesses`` 以及区域的 ``年龄`` 。 + +当另一个特殊的关键字 ``clear_schemes_tried_regions`` 被写入相关的 ``kdamonds/<N>/state`` +文件时，这些目录将被删除。 + +tried_regions/<N>/ +------------------ + +在每个区域目录中，你会发现四个文件(``start``, ``end``, ``nr_accesses``, and ``age``)。 +读取这些文件将显示相应的基于DAMON的操作方案 ``动作`` 试图应用的区域的开始和结束地址、``nr_accesses`` +和 ``年龄`` 。 + 用例 ~~~~ @@ -287,12 +314,12 @@ DAMON统计每个方案被尝试应用的区域的总数量和字节数，每个 # echo 1 > kdamonds/0/contexts/0/schemes/nr_schemes # cd kdamonds/0/contexts/0/schemes/0 # # set the basic access pattern and the action - # echo 4096 > access_patterns/sz/min - # echo 8192 > access_patterns/sz/max - # echo 0 > access_patterns/nr_accesses/min - # echo 5 > access_patterns/nr_accesses/max - # echo 10 > access_patterns/age/min - # echo 20 > access_patterns/age/max + # echo 4096 > access_pattern/sz/min + # echo 8192 > access_pattern/sz/max + # echo 0 > access_pattern/nr_accesses/min + # echo 5 > access_pattern/nr_accesses/max + # echo 10 > access_pattern/age/min + # echo 20 > access_pattern/age/max # echo pageout > action # # set quotas # echo 10 > quotas/ms @@ -311,6 +338,11 @@ DAMON统计每个方案被尝试应用的区域的总数量和字节数，每个 debugfs接口 =========== +.. note:: + + DAMON debugfs接口将在下一个LTS内核发布后被移除，所以用户应该转移到 + :ref:`sysfs接口<sysfs_interface>`。 + DAMON导出了八个文件, ``attrs``, ``target_ids``, ``init_regions``, ``schemes``, ``monitor_on``, ``kdamond_pid``, ``mk_contexts`` 和 ``rm_contexts`` under its debugfs directory, ``<debugfs>/damon/``. @@ -364,7 +396,7 @@ DAMON导出了八个文件, ``attrs``, ``target_ids``, ``init_regions``, 监测目标区域。 在这种情况下，用户可以通过在 ``init_regions`` 文件中写入适当的值，明确地设置他们想要的初 -始监测目标区域。输入的每一行应代表一个区域，形式如下:: +始监测目标区域。输入应该是一个由三个整数组成的队列，用空格隔开，代表一个区域的形式如下:: <target idx> <start address> <end address> @@ -376,9 +408,9 @@ DAMON导出了八个文件, ``attrs``, ``target_ids``, ``init_regions``, # cd <debugfs>/damon # cat target_ids 42 4242 - # echo "0 1 100 - 0 100 200 - 1 20 40 + # echo "0 1 100 \ + 0 100 200 \ + 1 20 40 \ 1 50 100" > init_regions 请注意，这只是设置了初始的监测目标区域。在虚拟内存监测的情况下，DAMON会在一个 ``更新间隔`` diff --git a/Documentation/translations/zh_CN/admin-guide/mm/ksm.rst b/Documentation/translations/zh_CN/admin-guide/mm/ksm.rst index 4829156ef1ae..0029c4fd2201 100644 --- a/Documentation/translations/zh_CN/admin-guide/mm/ksm.rst +++ b/Documentation/translations/zh_CN/admin-guide/mm/ksm.rst @@ -146,3 +146,53 @@ stable_node_dups 比值 ``pages_sharing/pages_shared`` 的最大值受限制于 ``max_page_sharing`` 的设定。要想增加该比值，则相应地要增加 ``max_page_sharing`` 的值。 + +监测KSM的收益 +============= + +KSM可以通过合并相同的页面来节省内存，但也会消耗额外的内存，因为它需要生成一些rmap_items +来保存每个扫描页面的简要rmap信息。其中有些页面可能会被合并，但有些页面在被检查几次 +后可能无法被合并，这些都是无益的内存消耗。 + +1) 如何确定KSM在全系统范围内是节省内存还是消耗内存？这里有一个简单的近似计算方法供参考:: + + general_profit =~ pages_sharing * sizeof(page) - (all_rmap_items) * + sizeof(rmap_item); + + 其中all_rmap_items可以通过对 ``pages_sharing`` 、 ``pages_shared`` 、 ``pages_unshared`` + 和 ``pages_volatile`` 的求和而轻松获得。 + +2) 单一进程中KSM的收益也可以通过以下近似的计算得到:: + + process_profit =~ ksm_merging_pages * sizeof(page) - + ksm_rmap_items * sizeof(rmap_item). + + 其中ksm_merging_pages显示在 ``/proc/<pid>/`` 目录下，而ksm_rmap_items + 显示在 ``/proc/<pid>/ksm_stat`` 。 + +从应用的角度来看， ``ksm_rmap_items`` 和 ``ksm_merging_pages`` 的高比例意 +味着不好的madvise-applied策略，所以开发者或管理员必须重新考虑如何改变madvis策 +略。举个例子供参考，一个页面的大小通常是4K，而rmap_item的大小在32位CPU架构上分 +别是32B，在64位CPU架构上是64B。所以如果 ``ksm_rmap_items/ksm_merging_pages`` +的比例在64位CPU上超过64，或者在32位CPU上超过128，那么应用程序的madvise策略应 +该被放弃，因为ksm收益大约为零或负值。 + +监控KSM事件 +=========== + +在/proc/vmstat中有一些计数器，可以用来监控KSM事件。KSM可能有助于节省内存，这是 +一种权衡，因为它可能会在KSM COW或复制中的交换上遭受延迟。这些事件可以帮助用户评估 +是否或如何使用KSM。例如，如果cow_ksm增加得太快，用户可以减少madvise(, , MADV_MERGEABLE) +的范围。 + +cow_ksm + 在每次KSM页面触发写时拷贝（COW）时都会被递增，当用户试图写入KSM页面时， + 我们必须做一个拷贝。 + +ksm_swpin_copy + 在换入时，每次KSM页被复制时都会被递增。请注意，KSM页在换入时可能会被复 + 制，因为do_swap_page()不能做所有的锁，而需要重组一个跨anon_vma的KSM页。 + +-- +Izik Eidus, +Hugh Dickins, 2009年11月17日。 diff --git a/Documentation/translations/zh_CN/core-api/kernel-api.rst b/Documentation/translations/zh_CN/core-api/kernel-api.rst index c22662679065..a4b373c48c0c 100644 --- a/Documentation/translations/zh_CN/core-api/kernel-api.rst +++ b/Documentation/translations/zh_CN/core-api/kernel-api.rst @@ -48,6 +48,8 @@ lib/string_helpers.c 该API在以下内核代码中: +include/linux/fortify-string.h + lib/string.c include/linux/string.h @@ -119,6 +121,12 @@ include/linux/textsearch.h Linux中的CRC和数学函数 ====================== +算术溢出检查 +------------ + +该API在以下内核代码中: + +include/linux/overflow.h CRC函数 ------- @@ -166,8 +174,6 @@ include/asm-generic/div64.h include/linux/math64.h -lib/math/div64.c - lib/math/gcd.c UUID/GUID diff --git a/Documentation/translations/zh_CN/core-api/mm-api.rst b/Documentation/translations/zh_CN/core-api/mm-api.rst index a732b0eebf16..113359bdb7be 100644 --- a/Documentation/translations/zh_CN/core-api/mm-api.rst +++ b/Documentation/translations/zh_CN/core-api/mm-api.rst @@ -37,7 +37,7 @@ mm/gup.c 该API在以下内核代码中: -include/linux/gfp.h +include/linux/gfp_types.h Slab缓存 ======== diff --git a/Documentation/translations/zh_CN/dev-tools/kasan.rst b/Documentation/translations/zh_CN/dev-tools/kasan.rst index fe76cbe77ad6..05ef904dbcfb 100644 --- a/Documentation/translations/zh_CN/dev-tools/kasan.rst +++ b/Documentation/translations/zh_CN/dev-tools/kasan.rst @@ -90,6 +90,47 @@ KASAN只支持SLUB。 ``CONFIG_STACKTRACE`` 。要包括受影响物理页面的分配和释放堆栈跟踪的话， 请启用 ``CONFIG_PAGE_OWNER`` 并使用 ``page_owner=on`` 进行引导。 +启动参数 +~~~~~~~~ + +KASAN受到通用 ``panic_on_warn`` 命令行参数的影响。当它被启用时，KASAN +在打印出错误报告后会使内核恐慌。 + +默认情况下，KASAN只对第一个无效的内存访问打印错误报告。使用 +``kasan_multi_shot``，KASAN对每一个无效的访问都打印一份报告。这会禁用 +了KASAN报告的 ``panic_on_warn``。 + +另外，独立于 ``panic_on_warn`` 、 ``kasan.fault=`` boot参数可以用 +来控制恐慌和报告行为。 + +- ``kasan.fault=report`` 或 ``=panic`` 控制是否只打印KASAN report或 + 同时使内核恐慌（默认： ``report`` ）。即使 ``kasan_multi_shot`` 被 + 启用，恐慌也会发生。 + +基于软件和硬件标签的KASAN模式（见下面关于各种模式的部分）支持改变堆栈跟 +踪收集行为： + +- ``kasan.stacktrace=off`` 或 ``=on`` 禁用或启用分配和释放堆栈痕 + 迹的收集（默认： ``on`` ）。 + +- ``kasan.stack_ring_size=<number of entries>`` 指定堆栈环的条 + 目数（默认： ``32768`` ）。 + +基于硬件标签的KASAN模式是为了在生产中作为一种安全缓解措施使用。因此，它 +支持额外的启动参数，允许完全禁用KASAN或控制其功能。 + +- ``kasan=off`` 或 ``=on`` 控制KASAN是否被启用（默认： ``on`` ）。 + +- ``kasan.mode=sync``, ``=async`` or ``=asymm`` 控制KASAN是否 + 被配置为同步、异步或非对称的执行模式（默认： ``同步`` ）。 + 同步模式：当标签检查异常发生时，会立即检测到不良访问。 + 异步模式：不良访问的检测是延迟的。当标签检查异常发生时，信息被存储在硬 + 件中（对于arm64来说是在TFSR_EL1寄存器中）。内核周期性地检查硬件，并\ + 且只在这些检查中报告标签异常。 + 非对称模式：读取时同步检测不良访问，写入时异步检测。 + +- ``kasan.vmalloc=off`` or ``=on`` 禁用或启用vmalloc分配的标记（默认： ``on`` ）。 + 错误报告 ~~~~~~~~ @@ -194,39 +235,6 @@ slab对象的描述以及关于访问的内存页的信息。 通用KASAN还报告两个辅助调用堆栈跟踪。这些堆栈跟踪指向代码中与对象交互但不直接 出现在错误访问堆栈跟踪中的位置。目前，这包括 call_rcu() 和排队的工作队列。 -启动参数 -~~~~~~~~ - -KASAN受通用 ``panic_on_warn`` 命令行参数的影响。启用该功能后，KASAN在打印错误 -报告后会引起内核恐慌。 - -默认情况下，KASAN只为第一次无效内存访问打印错误报告。使用 ``kasan_multi_shot`` ， -KASAN会针对每个无效访问打印报告。这有效地禁用了KASAN报告的 ``panic_on_warn`` 。 - -另外，独立于 ``panic_on_warn`` , ``kasan.fault=`` 引导参数可以用来控制恐慌和报 -告行为: - -- ``kasan.fault=report`` 或 ``=panic`` 控制是只打印KASAN报告还是同时使内核恐慌 - (默认: ``report`` )。即使启用了 ``kasan_multi_shot`` ，也会发生内核恐慌。 - -基于硬件标签的KASAN模式（请参阅下面有关各种模式的部分）旨在在生产中用作安全缓解 -措施。因此，它支持允许禁用KASAN或控制其功能的附加引导参数。 - -- ``kasan=off`` 或 ``=on`` 控制KASAN是否启用 (默认: ``on`` )。 - -- ``kasan.mode=sync`` 、 ``=async`` 或 ``=asymm`` 控制KASAN是否配置 - 为同步或异步执行模式(默认:``sync`` )。 - 同步模式：当标签检查错误发生时，立即检测到错误访问。 - 异步模式：延迟错误访问检测。当标签检查错误发生时，信息存储在硬件中（在arm64的 - TFSR_EL1寄存器中）。内核会定期检查硬件，并且仅在这些检查期间报告标签错误。 - 非对称模式：读取时同步检测不良访问，写入时异步检测。 - -- ``kasan.vmalloc=off`` 或 ``=on`` 禁用或启用vmalloc分配的标记（默认：``on`` ）。 - -- ``kasan.stacktrace=off`` 或 ``=on`` 禁用或启用alloc和free堆栈跟踪收集 - (默认: ``on`` )。 - - 实施细则 -------- diff --git a/Documentation/translations/zh_CN/dev-tools/testing-overview.rst b/Documentation/translations/zh_CN/dev-tools/testing-overview.rst index d6f2c65ed511..af65e7e93c02 100644 --- a/Documentation/translations/zh_CN/dev-tools/testing-overview.rst +++ b/Documentation/translations/zh_CN/dev-tools/testing-overview.rst @@ -132,3 +132,30 @@ Documentation/dev-tools/kcov.rst 是能够构建在内核之中，用于在每 不过要注意的是，静态分析工具存在**假阳性**的问题。在试图修复错误和警 告之前，需要仔细评估它们。 + +何时使用Sparse和Smatch +---------------------- + +Sparse做类型检查，例如验证注释的变量不会导致无符号的错误，检测 +``__user`` 指针使用不当的地方，以及分析符号初始化器的兼容性。 + +Smatch进行流程分析，如果允许建立函数数据库，它还会进行跨函数分析。 +Smatch试图回答一些问题，比如这个缓冲区是在哪里分配的？它有多大？这 +个索引可以由用户控制吗？这个变量比那个变量大吗？ + +一般来说，在Smatch中写检查比在Sparse中写检查要容易。尽管如此， +Sparse和Smatch的检查还是有一些重叠的地方。 + +Smatch和Coccinelle的强项 +------------------------ + +Coccinelle可能是最容易写检查的。它在预处理器之前工作，所以用Coccinelle +检查宏中的错误更容易。Coccinelle还能为你创建补丁，这是其他工具无法做到的。 + +例如，用Coccinelle你可以从 ``kmalloc_array(x, size, GFP_KERNEL)`` +到 ``kmalloc_array(x, size, GFP_KERNEL)`` 进行大规模转换，这真的很 +有用。如果你只是创建一个Smatch警告，并试图把转换的工作推给维护者，他们会很 +恼火。你将不得不为每个警告争论是否真的可以溢出。 + +Coccinelle不对变量值进行分析，而这正是Smatch的强项。另一方面，Coccinelle +允许你用简单的方法做简单的事情。 diff --git a/Documentation/translations/zh_CN/mm/highmem.rst b/Documentation/translations/zh_CN/mm/highmem.rst index f74800a6d9a7..2c0ee0cbf5c4 100644 --- a/Documentation/translations/zh_CN/mm/highmem.rst +++ b/Documentation/translations/zh_CN/mm/highmem.rst @@ -57,15 +57,29 @@ 在可行的情况下，这个函数应该比其他所有的函数优先使用。 - 这些映射是线程本地和CPU本地的，这意味着映射只能从这个线程中访问，并且当映射处于活动状 - 态时，该线程与CPU绑定。即使线程被抢占了（因为抢占永远不会被函数禁用），CPU也不能通过 - CPU-hotplug从系统中拔出，直到映射被处理掉。 + 这些映射是线程本地和CPU本地的，这意味着映射只能从这个线程中访问，并且当映射处于活跃状 + 态时，线程被绑定到CPU上。尽管这个函数从来没有禁用过抢占，但在映射被处理之前，CPU不能 + 通过CPU-hotplug从系统中拔出。 在本地的kmap区域中采取pagefaults是有效的，除非获取本地映射的上下文由于其他原因不允许 这样做。 + 如前所述，缺页异常和抢占从未被禁用。没有必要禁用抢占，因为当上下文切换到一个不同的任务 + 时，离开的任务的映射被保存，而进入的任务的映射被恢复。 + kmap_local_page()总是返回一个有效的虚拟地址，并且假定kunmap_local()不会失败。 + 在CONFIG_HIGHMEM=n的内核中，对于低内存页，它返回直接映射的虚拟地址。只有真正的高内 + 存页面才会被临时映射。因此，用户可以为那些已知不是来自ZONE_HIGHMEM的页面调用普通的 + page_address()。然而，使用kmap_local_page() / kunmap_local()总是安全的。 + + 虽然它比kmap()快得多，但在高内存的情况下，它对指针的有效性有限制。与kmap()映射相反， + 本地映射只在调用者的上下文中有效，不能传递给其他上下文。这意味着用户必须绝对保证返回 + 地址的使用只限于映射它的线程。 + + 大多数代码可以被设计成使用线程本地映射。因此，用户在设计他们的代码时，应该尽量避免使用 + kmap()，将页面映射到将被使用的同一线程中，并优先使用kmap_local_page()。 + 嵌套kmap_local_page()和kmap_atomic()映射在一定程度上是允许的（最多到KMAP_TYPE_NR）， 但是它们的调用必须严格排序，因为映射的实现是基于堆栈的。关于如何管理嵌套映射的细节， 请参见kmap_local_page() kdocs（包含在 "函数 "部分）。 diff --git a/Documentation/translations/zh_CN/mm/page_owner.rst b/Documentation/translations/zh_CN/mm/page_owner.rst index 21a6a0837d42..dba511fafef2 100644 --- a/Documentation/translations/zh_CN/mm/page_owner.rst +++ b/Documentation/translations/zh_CN/mm/page_owner.rst @@ -34,20 +34,9 @@ page owner在默认情况下是禁用的。所以，如果你想使用它，你 一样进行。这两个不可能的分支应该不会影响到分配的性能，特别是在静态键跳转标签修补 功能可用的情况下。以下是由于这个功能而导致的内核代码大小的变化。 -- 没有page owner:: - - text data bss dec hex filename - 48392 2333 644 51369 c8a9 mm/page_alloc.o - -- 有page owner:: - - text data bss dec hex filename - 48800 2445 644 51889 cab1 mm/page_alloc.o - 6662 108 29 6799 1a8f mm/page_owner.o - 1025 8 8 1041 411 mm/page_ext.o - -虽然总共增加了8KB的代码，但page_alloc.o增加了520字节，其中不到一半是在hotpath -中。构建带有page owner的内核，并在需要时打开它，将是调试内核内存问题的最佳选择。 +尽管启用page owner会使内核的大小增加几千字节，但这些代码大部分都在页面分配器和 +热路径之外。构建带有page owner的内核，并在需要时打开它，将是调试内核内存问题的 +最佳选择。 有一个问题是由实现细节引起的。页所有者将信息存储到struct page扩展的内存中。这 个内存的初始化时间比稀疏内存系统中的页面分配器启动的时间要晚一些，所以，在初始化 diff --git a/Documentation/translations/zh_CN/power/energy-model.rst b/Documentation/translations/zh_CN/power/energy-model.rst index c7da1b6aefee..48849919d8aa 100644 --- a/Documentation/translations/zh_CN/power/energy-model.rst +++ b/Documentation/translations/zh_CN/power/energy-model.rst @@ -23,15 +23,15 @@ 实现支持，EM框架作为一个抽象层介入，它在内核中对功率成本表的格式进行标准化， 因此能够避免多余的工作。 -功率值可以用毫瓦或“抽象刻度”表示。多个子系统可能使用EM，由系统集成商来检查 +功率值可以用微瓦或“抽象刻度”表示。多个子系统可能使用EM，由系统集成商来检查 功率值刻度类型的要求是否满足。可以在能量感知调度器的文档中找到一个例子 Documentation/scheduler/sched-energy.rst。对于一些子系统，比如热能或 powercap，用“抽象刻度”描述功率值可能会导致问题。这些子系统对过去使用的功率的 -估算值更感兴趣，因此可能需要真实的毫瓦。这些要求的一个例子可以在智能功率分配 +估算值更感兴趣，因此可能需要真实的微瓦。这些要求的一个例子可以在智能功率分配 Documentation/driver-api/thermal/power_allocator.rst文档中找到。 内核子系统可能（基于EM内部标志位）实现了对EM注册设备是否具有不一致刻度的自动 -检查。要记住的重要事情是，当功率值以“抽象刻度”表示时，从中推导以毫焦耳为单位 +检查。要记住的重要事情是，当功率值以“抽象刻度”表示时，从中推导以微焦耳为单位 的真实能量消耗是不可能的。 下图描述了一个驱动的例子（这里是针对Arm的，但该方法适用于任何体系结构），它 @@ -89,20 +89,40 @@ Documentation/driver-api/thermal/power_allocator.rst文档中找到。 驱动程序应通过以下API将性能域注册到EM框架中:: int em_dev_register_perf_domain(struct device *dev, unsigned int nr_states, - struct em_data_callback *cb, cpumask_t *cpus, bool milliwatts); + struct em_data_callback *cb, cpumask_t *cpus, bool microwatts); 驱动程序必须提供一个回调函数，为每个性能状态返回<频率,功率>元组。驱动程序 提供的回调函数可以自由地从任何相关位置（DT、固件......）以及以任何被认为是 必要的方式获取数据。只有对于CPU设备，驱动程序必须使用cpumask指定性能域的CPU。 对于CPU以外的其他设备，最后一个参数必须被设置为NULL。 -最后一个参数“milliwatts”（毫瓦）设置成正确的值是很重要的，使用EM的内核 +最后一个参数“microwatts”（微瓦）设置成正确的值是很重要的，使用EM的内核 子系统可能会依赖这个标志来检查所有的EM设备是否使用相同的刻度。如果有不同的 -刻度，这些子系统可能决定：返回警告/错误，停止工作或崩溃（panic）。 +刻度，这些子系统可能决定返回警告/错误，停止工作或崩溃（panic）。 关于实现这个回调函数的驱动程序的例子，参见第3节。或者在第2.4节阅读这个API 的更多文档。 +使用DT的EM注册 +============== + +EM也可以使用OPP框架和DT "操作点-v2 "中的信息注册。DT中的每个OPP条目都可 +以用一个包含微瓦特功率值的属性 "op-microwatt "来扩展。这个OPP DT属性允 +许平台注册反映总功率（静态+动态）的EM功率值。这些功率值可能直接来自实验和 +测量。 + +“人工”EM的注册 +============== + +有一个选项可以为缺少关于每个性能状态的功率值的详细知识的驱动程序提供一个自 +定义回调。回调.get_cost()是可选的，它提供EAS使用的“成本”值。这对那些只提 +供CPU类型之间相对效率信息的平台很有用，人们可以利用这些信息来创建一个抽象的 +功率模型。但是，考虑到输入功率值的大小限制，即使是抽象的功率模型有时也很难装 +进去。.get_cost()允许提供反映CPU效率的“成本”值。这将允许提供EAS信息，它 +与EM内部计算'成本'值的公式有不同的关系。要为这样的平台注册EM，驱动程序必须 +将标志“microwatts”设置为0，提供.get_power()回调和.get_cost()回调。EM +框架会在注册过程中正确处理这样的平台。这种平台会被设置EM_PERF_DOMAIN_ARTIFICIAL +标志。其他使用EM的框架应该特别注意测试和正确对待这个标志。 “简单”EM的注册 ~~~~~~~~~~~~~~~~ @@ -147,8 +167,8 @@ cpufreq_driver::register_em()。这个回调必须为每个特定的驱动程序 -> drivers/cpufreq/foo_cpufreq.c - 01 static int est_power(unsigned long *mW, unsigned long *KHz, - 02 struct device *dev) + 01 static int est_power(struct device *dev, unsigned long *mW, + 02 unsigned long *KHz) 03 { 04 long freq, power; 05 diff --git a/Documentation/translations/zh_CN/process/howto.rst b/Documentation/translations/zh_CN/process/howto.rst index 888978a62db3..10254751df6a 100644 --- a/Documentation/translations/zh_CN/process/howto.rst +++ b/Documentation/translations/zh_CN/process/howto.rst @@ -254,7 +254,7 @@ Linux-next 集成测试树 https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git 通过这种方式，Linux-next 对下一个合并阶段将进入主线内核的内容给出了一个概要 -展望。非常欢冒险的测试者运行测试Linux-next。 +展望。非常欢迎冒险的测试者运行测试Linux-next。 多个主要版本的稳定版内核树 ----------------------------------- diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 0dd5d8733dd5..deb494f759ed 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -5343,9 +5343,9 @@ KVM_XEN_ATTR_TYPE_SHARED_INFO 32 vCPUs in the shared_info page, KVM does not automatically do so and instead requires that KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO be used explicitly even when the vcpu_info for a given vCPU resides at the - "default" location in the shared_info page. This is because KVM is - not aware of the Xen CPU id which is used as the index into the - vcpu_info[] array, so cannot know the correct default location. + "default" location in the shared_info page. This is because KVM may + not be aware of the Xen CPU id which is used as the index into the + vcpu_info[] array, so may know the correct default location. Note that the shared info page may be constantly written to by KVM; it contains the event channel bitmap used to deliver interrupts to @@ -5356,23 +5356,29 @@ KVM_XEN_ATTR_TYPE_SHARED_INFO any vCPU has been running or any event channel interrupts can be routed to the guest. + Setting the gfn to KVM_XEN_INVALID_GFN will disable the shared info + page. + KVM_XEN_ATTR_TYPE_UPCALL_VECTOR Sets the exception vector used to deliver Xen event channel upcalls. This is the HVM-wide vector injected directly by the hypervisor (not through the local APIC), typically configured by a guest via - HVM_PARAM_CALLBACK_IRQ. + HVM_PARAM_CALLBACK_IRQ. This can be disabled again (e.g. for guest + SHUTDOWN_soft_reset) by setting it to zero. KVM_XEN_ATTR_TYPE_EVTCHN This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates support for KVM_XEN_HVM_CONFIG_EVTCHN_SEND features. It configures an outbound port number for interception of EVTCHNOP_send requests - from the guest. A given sending port number may be directed back - to a specified vCPU (by APIC ID) / port / priority on the guest, - or to trigger events on an eventfd. The vCPU and priority can be - changed by setting KVM_XEN_EVTCHN_UPDATE in a subsequent call, - but other fields cannot change for a given sending port. A port - mapping is removed by using KVM_XEN_EVTCHN_DEASSIGN in the flags - field. + from the guest. A given sending port number may be directed back to + a specified vCPU (by APIC ID) / port / priority on the guest, or to + trigger events on an eventfd. The vCPU and priority can be changed + by setting KVM_XEN_EVTCHN_UPDATE in a subsequent call, but but other + fields cannot change for a given sending port. A port mapping is + removed by using KVM_XEN_EVTCHN_DEASSIGN in the flags field. Passing + KVM_XEN_EVTCHN_RESET in the flags field removes all interception of + outbound event channels. The values of the flags field are mutually + exclusive and cannot be combined as a bitmask. KVM_XEN_ATTR_TYPE_XEN_VERSION This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates @@ -5388,7 +5394,7 @@ KVM_XEN_ATTR_TYPE_RUNSTATE_UPDATE_FLAG support for KVM_XEN_HVM_CONFIG_RUNSTATE_UPDATE_FLAG. It enables the XEN_RUNSTATE_UPDATE flag which allows guest vCPUs to safely read other vCPUs' vcpu_runstate_info. Xen guests enable this feature via - the VM_ASST_TYPE_runstate_update_flag of the HYPERVISOR_vm_assist + the VMASST_TYPE_runstate_update_flag of the HYPERVISOR_vm_assist hypercall. 4.127 KVM_XEN_HVM_GET_ATTR @@ -5446,15 +5452,18 @@ KVM_XEN_VCPU_ATTR_TYPE_VCPU_INFO As with the shared_info page for the VM, the corresponding page may be dirtied at any time if event channel interrupt delivery is enabled, so userspace should always assume that the page is dirty without relying - on dirty logging. + on dirty logging. Setting the gpa to KVM_XEN_INVALID_GPA will disable + the vcpu_info. KVM_XEN_VCPU_ATTR_TYPE_VCPU_TIME_INFO Sets the guest physical address of an additional pvclock structure for a given vCPU. This is typically used for guest vsyscall support. + Setting the gpa to KVM_XEN_INVALID_GPA will disable the structure. KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_ADDR Sets the guest physical address of the vcpu_runstate_info for a given vCPU. This is how a Xen guest tracks CPU state such as steal time. + Setting the gpa to KVM_XEN_INVALID_GPA will disable the runstate area. KVM_XEN_VCPU_ATTR_TYPE_RUNSTATE_CURRENT Sets the runstate (RUNSTATE_running/_runnable/_blocked/_offline) of @@ -5487,7 +5496,8 @@ KVM_XEN_VCPU_ATTR_TYPE_TIMER This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates support for KVM_XEN_HVM_CONFIG_EVTCHN_SEND features. It sets the event channel port/priority for the VIRQ_TIMER of the vCPU, as well - as allowing a pending timer to be saved/restored. + as allowing a pending timer to be saved/restored. Setting the timer + port to zero disables kernel handling of the singleshot timer. KVM_XEN_VCPU_ATTR_TYPE_UPCALL_VECTOR This attribute is available when the KVM_CAP_XEN_HVM ioctl indicates @@ -5495,7 +5505,8 @@ KVM_XEN_VCPU_ATTR_TYPE_UPCALL_VECTOR per-vCPU local APIC upcall vector, configured by a Xen guest with the HVMOP_set_evtchn_upcall_vector hypercall. This is typically used by Windows guests, and is distinct from the HVM-wide upcall - vector configured with HVM_PARAM_CALLBACK_IRQ. + vector configured with HVM_PARAM_CALLBACK_IRQ. It is disabled by + setting the vector to zero. 4.129 KVM_XEN_VCPU_GET_ATTR @@ -6577,11 +6588,6 @@ Please note that the kernel is allowed to use the kvm_run structure as the primary storage for certain register types. Therefore, the kernel may use the values in kvm_run even if the corresponding bit in kvm_dirty_regs is not set. -:: - - }; - - 6. Capabilities that can be enabled on vCPUs ============================================ diff --git a/Documentation/virt/kvm/locking.rst b/Documentation/virt/kvm/locking.rst index 845a561629f1..a3ca76f9be75 100644 --- a/Documentation/virt/kvm/locking.rst +++ b/Documentation/virt/kvm/locking.rst @@ -16,17 +16,26 @@ The acquisition orders for mutexes are as follows: - kvm->slots_lock is taken outside kvm->irq_lock, though acquiring them together is quite rare. -- Unlike kvm->slots_lock, kvm->slots_arch_lock is released before - synchronize_srcu(&kvm->srcu). Therefore kvm->slots_arch_lock - can be taken inside a kvm->srcu read-side critical section, - while kvm->slots_lock cannot. - - kvm->mn_active_invalidate_count ensures that pairs of invalidate_range_start() and invalidate_range_end() callbacks use the same memslots array. kvm->slots_lock and kvm->slots_arch_lock are taken on the waiting side in install_new_memslots, so MMU notifiers must not take either kvm->slots_lock or kvm->slots_arch_lock. +For SRCU: + +- ``synchronize_srcu(&kvm->srcu)`` is called _inside_ + the kvm->slots_lock critical section, therefore kvm->slots_lock + cannot be taken inside a kvm->srcu read-side critical section. + Instead, kvm->slots_arch_lock is released before the call + to ``synchronize_srcu()`` and _can_ be taken inside a + kvm->srcu read-side critical section. + +- kvm->lock is taken inside kvm->srcu, therefore + ``synchronize_srcu(&kvm->srcu)`` cannot be called inside + a kvm->lock critical section. If you cannot delay the + call until after kvm->lock is released, use ``call_srcu``. + On x86: - vcpu->mutex is taken outside kvm->arch.hyperv.hv_lock diff --git a/Documentation/x86/x86_64/mm.rst b/Documentation/x86/x86_64/mm.rst index 9798676bb0bf..35e5e18c83d0 100644 --- a/Documentation/x86/x86_64/mm.rst +++ b/Documentation/x86/x86_64/mm.rst @@ -140,7 +140,7 @@ The direct mapping covers all memory in the system up to the highest memory address (this means in some cases it can also include PCI memory holes). -We map EFI runtime services in the 'efi_pgd' PGD in a 64Gb large virtual +We map EFI runtime services in the 'efi_pgd' PGD in a 64GB large virtual memory window (this size is arbitrary, it can be raised later if needed). The mappings are not part of any other kernel PGD and are only available during EFI runtime calls. |