diff options
| author | Mark Brown <broonie@kernel.org> | 2026-05-29 18:09:44 +0100 |
|---|---|---|
| committer | Mark Brown <broonie@kernel.org> | 2026-05-29 18:09:44 +0100 |
| commit | 10009bb9d1ae89c174a2e0f2132a91822aae42fa (patch) | |
| tree | cd969b50e12639f3ef9dafcce43cca5c3a8e0a89 /Documentation | |
| parent | 75729570cb18aecca07da172d007478a95e0378e (diff) | |
| parent | d6dd61121cff3aaec3d444e2489c8cc66220c400 (diff) | |
| download | linux-next-history-10009bb9d1ae89c174a2e0f2132a91822aae42fa.tar.gz | |
Merge branch 'docs-next' of git://git.lwn.net/linux.git
Diffstat (limited to 'Documentation')
62 files changed, 1644 insertions, 367 deletions
diff --git a/Documentation/RCU/Design/Requirements/Requirements.rst b/Documentation/RCU/Design/Requirements/Requirements.rst index 4d886e7c7a956..8a216e4a46a7d 100644 --- a/Documentation/RCU/Design/Requirements/Requirements.rst +++ b/Documentation/RCU/Design/Requirements/Requirements.rst @@ -206,7 +206,7 @@ non-\ ``NULL``, locklessly accessing the ``->a`` and ``->b`` fields. 1 bool add_gp_buggy(int a, int b) 2 { - 3 p = kmalloc(sizeof(*p), GFP_KERNEL); + 3 p = kmalloc_obj(*p); 4 if (!p) 5 return -ENOMEM; 6 spin_lock(&gp_lock); @@ -228,7 +228,7 @@ their rights to reorder this code as follows: 1 bool add_gp_buggy_optimized(int a, int b) 2 { - 3 p = kmalloc(sizeof(*p), GFP_KERNEL); + 3 p = kmalloc_obj(*p); 4 if (!p) 5 return -ENOMEM; 6 spin_lock(&gp_lock); @@ -264,7 +264,7 @@ shows an example of insertion: 1 bool add_gp(int a, int b) 2 { - 3 p = kmalloc(sizeof(*p), GFP_KERNEL); + 3 p = kmalloc_obj(*p); 4 if (!p) 5 return -ENOMEM; 6 spin_lock(&gp_lock); diff --git a/Documentation/RCU/listRCU.rst b/Documentation/RCU/listRCU.rst index d8bb98623c124..48c7272a4cccb 100644 --- a/Documentation/RCU/listRCU.rst +++ b/Documentation/RCU/listRCU.rst @@ -276,7 +276,7 @@ The RCU version of audit_upd_rule() is as follows:: list_for_each_entry(e, list, list) { if (!audit_compare_rule(rule, &e->rule)) { - ne = kmalloc(sizeof(*entry), GFP_ATOMIC); + ne = kmalloc_obj(*entry, GFP_ATOMIC); if (ne == NULL) return -ENOMEM; audit_copy_rule(&ne->rule, &e->rule); diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst index a1582bd653d11..e6767baff2d34 100644 --- a/Documentation/RCU/whatisRCU.rst +++ b/Documentation/RCU/whatisRCU.rst @@ -468,7 +468,7 @@ uses of RCU may be found in listRCU.rst and NMI-RCU.rst. struct foo *new_fp; struct foo *old_fp; - new_fp = kmalloc(sizeof(*new_fp), GFP_KERNEL); + new_fp = kmalloc_obj(*new_fp); spin_lock(&foo_mutex); old_fp = rcu_dereference_protected(gbl_foo, lockdep_is_held(&foo_mutex)); *new_fp = *old_fp; @@ -570,7 +570,7 @@ The foo_update_a() function might then be written as follows:: struct foo *new_fp; struct foo *old_fp; - new_fp = kmalloc(sizeof(*new_fp), GFP_KERNEL); + new_fp = kmalloc_obj(*new_fp); spin_lock(&foo_mutex); old_fp = rcu_dereference_protected(gbl_foo, lockdep_is_held(&foo_mutex)); *new_fp = *old_fp; diff --git a/Documentation/admin-guide/binfmt-misc.rst b/Documentation/admin-guide/binfmt-misc.rst index 59cd902e35497..c0a34fbf8022b 100644 --- a/Documentation/admin-guide/binfmt-misc.rst +++ b/Documentation/admin-guide/binfmt-misc.rst @@ -68,10 +68,10 @@ Here is what the fields mean: Legacy behavior of binfmt_misc is to pass the full path of the binary to the interpreter as an argument. When this flag is included, binfmt_misc will open the file for reading and pass its - descriptor as an argument, instead of the full path, thus allowing - the interpreter to execute non-readable binaries. This feature - should be used with care - the interpreter has to be trusted not to - emit the contents of the non-readable binary. + descriptor into the auxilary vector with the key "AT_EXECFD", thus + allowing the interpreter to execute non-readable binaries. This + feature should be used with care - the interpreter has to be trusted + not to emit the contents of the non-readable binary. ``C`` - credentials Currently, the behavior of binfmt_misc is to calculate the credentials and security token of the new process according to diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index b64d571dfb6a1..bd928033d346c 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -24,7 +24,6 @@ IP_PNP IP DHCP, BOOTP, or RARP is enabled. IPV6 IPv6 support is enabled. ISAPNP ISA PnP code is enabled. - ISDN Appropriate ISDN support is enabled. ISOL CPU Isolation is enabled. JOY Appropriate joystick support is enabled. KGDB Kernel debugger support is enabled. @@ -2240,9 +2239,6 @@ Kernel parameters syscalls, essentially overriding IA32_EMULATION_DEFAULT_DISABLED at boot time. When false, unconditionally disables IA32 emulation. - icn= [HW,ISDN] - Format: <io>[,<membase>[,<icn_id>[,<icn_id2>]]] - idle= [X86,EARLY] Format: idle=poll, idle=halt, idle=nomwait @@ -2750,7 +2746,6 @@ Kernel parameters Format: <RDP>,<reset>,<pci_scan>,<verbosity> isolcpus= [KNL,SMP,ISOL] Isolate a given set of CPUs from disturbance. - [Deprecated - use cpusets instead] Format: [flag-list,]<cpu-list> Specify one or more CPUs to isolate from disturbances @@ -2775,11 +2770,10 @@ Kernel parameters Isolate from the general SMP balancing and scheduling algorithms. Note that performing domain isolation this way is irreversible: it's not possible to bring back a CPU to - the domains once isolated through isolcpus. It's strongly - advised to use cpusets instead to disable scheduler load - balancing through the "cpuset.sched_load_balance" file. - It offers a much more flexible interface where CPUs can - move in and out of an isolated set anytime. + the domains once isolated through this boot time + configuration. Use cpusets for a dynamic configuration + which can be altered at runtime. For details see + Documentation/admin-guide/cpu-isolation.rst. You can move a process onto or off an "isolated" CPU via the CPU affinity syscalls or cpuset. @@ -4639,7 +4633,7 @@ Kernel parameters nosmt [KNL,MIPS,PPC,EARLY] Disable symmetric multithreading (SMT). Equivalent to smt=1. - [KNL,LOONGARCH,X86,PPC,S390] Disable symmetric multithreading (SMT). + [KNL,LOONGARCH,X86,ARM64,PPC,S390] Disable symmetric multithreading (SMT). nosmt=force: Force disable SMT, cannot be undone via the sysfs control file. @@ -5032,8 +5026,6 @@ Kernel parameters the specified number of seconds. This is to be used if your oopses keep scrolling off the screen. - pcbit= [HW,ISDN] - pci=option[,option...] [PCI,EARLY] various PCI subsystem options. Some options herein operate on a specific device diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst index 16a66a1f1975f..87dd874fffcf2 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -129,7 +129,7 @@ After these preparations you'll now enter the main part: situations; during the merge window that actually might be even the best approach, but in that development phase it can be an even better idea to suspend your efforts for a few days anyway. Whatever version you choose, - ideally use a 'vanilla' build. Ignoring these advices will dramatically + ideally use a 'vanilla' build. Ignoring all of this advice will dramatically increase the risk your report will be rejected or ignored. * Ensure the kernel you just installed does not 'taint' itself when @@ -795,7 +795,7 @@ Install a fresh kernel for testing situations; during the merge window that actually might be even the best approach, but in that development phase it can be an even better idea to suspend your efforts for a few days anyway. Whatever version you choose, - ideally use a 'vanilla' built. Ignoring these advices will dramatically + ideally use a 'vanilla' built. Ignoring all of this advice will dramatically increase the risk your report will be rejected or ignored.* As mentioned in the detailed explanation for the first step already: Like most diff --git a/Documentation/admin-guide/sysctl/net.rst b/Documentation/admin-guide/sysctl/net.rst index 0724a793798f3..3db464e006a3d 100644 --- a/Documentation/admin-guide/sysctl/net.rst +++ b/Documentation/admin-guide/sysctl/net.rst @@ -36,12 +36,11 @@ Table : Subdirectories in /proc/sys/net ========= =================== = ========== =================== 802 E802 protocol mptcp Multipath TCP appletalk Appletalk protocol netfilter Network Filter - ax25 AX25 netrom NET/ROM - bridge Bridging rose X.25 PLP layer - core General parameter tipc TIPC - ethernet Ethernet protocol unix Unix domain sockets - ipv4 IP version 4 vsock VSOCK sockets - ipv6 IP version 6 x25 X.25 protocol + bridge Bridging tipc TIPC + core General parameter unix Unix domain sockets + ethernet Ethernet protocol vsock VSOCK sockets + ipv4 IP version 4 x25 X.25 protocol + ipv6 IP version 6 ========= =================== = ========== =================== 1. /proc/sys/net/core - Network core options diff --git a/Documentation/admin-guide/workload-tracing.rst b/Documentation/admin-guide/workload-tracing.rst index 35963491b9f19..314e5f03474e6 100644 --- a/Documentation/admin-guide/workload-tracing.rst +++ b/Documentation/admin-guide/workload-tracing.rst @@ -202,6 +202,15 @@ database. To get out of this mode press ctrl+d. -p option is used to specify the number of file path components to display. -p10 is optimal for browsing kernel sources. +Alternatively, the kernel build system can generate the cscope database:: + + make cscope + +To exclude directories from the generated database, pass IGNORE_DIRS to +the cscope target. For example, to exclude Documentation/, run:: + + make IGNORE_DIRS="Documentation" cscope + What is perf and how do we use it? ================================== @@ -243,13 +252,21 @@ which can help mitigate performance regressions. It also acts as a common benchmarking framework, enabling developers to easily create test cases, integrate transparently, and use performance-rich tooling. -"perf bench all" command runs the following benchmarks: +"perf bench all" runs all available benchmarks in the perf bench +framework. The exact set of benchmarks depends on the perf version and on +the features enabled when perf was built. + +To list the benchmark collections available on the current system, run:: + + perf bench + +To list benchmarks in a collection, run:: + + perf bench <collection> + +For example, to list the benchmarks in the mem collection, run:: - * sched/messaging - * sched/pipe - * syscall/basic - * mem/memcpy - * mem/memset + perf bench mem What is stress-ng and how do we use it? ======================================= @@ -271,17 +288,17 @@ exercised: The following command runs the stressor:: - stress-ng --netdev 1 -t 60 --metrics command. + stress-ng --netdev 1 -t 60 --metrics We can use the perf record command to record the events and information associated with a process. This command records the profiling data in the perf.data file in the same directory. Using the following commands you can record the events associated with the -netdev stressor, view the generated report perf.data and annotate the to -view the statistics of each instruction of the program:: +netdev stressor, view the generated report perf.data and annotate the output +to view the statistics of each instruction of the program:: - perf record stress-ng --netdev 1 -t 60 --metrics command. + perf record -- stress-ng --netdev 1 -t 60 --metrics perf report perf annotate @@ -349,13 +366,13 @@ times each system call is invoked, and the corresponding Linux subsystem. +-------------------+-----------+-----------------+-------------------------+ | geteuid | 1 | Process Mgmt. | sys_geteuid() | +-------------------+-----------+-----------------+-------------------------+ -| getegid | 1 | Process Mgmt. | sys_getegid | +| getegid | 1 | Process Mgmt. | sys_getegid() | +-------------------+-----------+-----------------+-------------------------+ | close | 49951 | Filesystem | sys_close() | +-------------------+-----------+-----------------+-------------------------+ | pipe | 604 | Filesystem | sys_pipe() | +-------------------+-----------+-----------------+-------------------------+ -| openat | 48560 | Filesystem | sys_opennat() | +| openat | 48560 | Filesystem | sys_openat() | +-------------------+-----------+-----------------+-------------------------+ | fstat | 8338 | Filesystem | sys_fstat() | +-------------------+-----------+-----------------+-------------------------+ diff --git a/Documentation/block/data-integrity.rst b/Documentation/block/data-integrity.rst index 99905e880a0e5..b7b10c8abbcc2 100644 --- a/Documentation/block/data-integrity.rst +++ b/Documentation/block/data-integrity.rst @@ -154,7 +154,7 @@ bio_free() will automatically free the bip. ---------------- Block devices can set up the integrity information in the integrity -sub-struture of the queue_limits structure. +sub-structure of the queue_limits structure. Layered block devices will need to pick a profile that's appropriate for all subdevices. queue_limits_stack_integrity() can help with that. DM diff --git a/Documentation/core-api/cpu_hotplug.rst b/Documentation/core-api/cpu_hotplug.rst index 9b4afca9fd09c..6de26d1c6a9ad 100644 --- a/Documentation/core-api/cpu_hotplug.rst +++ b/Documentation/core-api/cpu_hotplug.rst @@ -45,11 +45,6 @@ Command Line Switches This option is limited to the X86 and S390 architecture. -``cpu0_hotplug`` - Allow to shutdown CPU0. - - This option is limited to the X86 architecture. - CPU maps ======== diff --git a/Documentation/core-api/housekeeping.rst b/Documentation/core-api/housekeeping.rst index 92c6e53cea755..ccb0a88b9cb36 100644 --- a/Documentation/core-api/housekeeping.rst +++ b/Documentation/core-api/housekeeping.rst @@ -99,7 +99,7 @@ the same RCU read side critical section. A typical layout example would look like this on the update side (``housekeeping_update()``):: - rcu_assign_pointer(housekeeping_cpumasks[type], trial); + rcu_assign_pointer(housekeeping.cpumasks[type], trial); synchronize_rcu(); flush_workqueue(example_workqueue); diff --git a/Documentation/core-api/kref.rst b/Documentation/core-api/kref.rst index 8db9ff03d952e..233d52d2393db 100644 --- a/Documentation/core-api/kref.rst +++ b/Documentation/core-api/kref.rst @@ -40,7 +40,7 @@ kref_init as so:: struct my_data *data; - data = kmalloc(sizeof(*data), GFP_KERNEL); + data = kmalloc_obj(*data); if (!data) return -ENOMEM; kref_init(&data->refcount); @@ -100,7 +100,7 @@ thread to process:: int rv = 0; struct my_data *data; struct task_struct *task; - data = kmalloc(sizeof(*data), GFP_KERNEL); + data = kmalloc_obj(*data); if (!data) return -ENOMEM; kref_init(&data->refcount); diff --git a/Documentation/core-api/list.rst b/Documentation/core-api/list.rst index 241464ca05498..479aa91cc3958 100644 --- a/Documentation/core-api/list.rst +++ b/Documentation/core-api/list.rst @@ -112,7 +112,7 @@ list: /* State 1 */ - grock = kzalloc(sizeof(*grock), GFP_KERNEL); + grock = kzalloc_obj(*grock); if (!grock) return -ENOMEM; grock->name = "Grock"; @@ -123,7 +123,7 @@ list: /* State 2 */ - dimitri = kzalloc(sizeof(*dimitri), GFP_KERNEL); + dimitri = kzalloc_obj(*dimitri); if (!dimitri) return -ENOMEM; dimitri->name = "Dimitri"; @@ -752,7 +752,7 @@ This is because list_splice() did not reinitialize the list_head it took entries from, leaving its pointer pointing into what is now a different list. If we want to avoid this situation, list_splice_init() can be used. It does the -same thing as list_splice(), except reinitalizes the donor list_head after the +same thing as list_splice(), except reinitializes the donor list_head after the transplant. Concurrency considerations diff --git a/Documentation/driver-api/eisa.rst b/Documentation/driver-api/eisa.rst index 3563e5f7e98d6..e98b21b608657 100644 --- a/Documentation/driver-api/eisa.rst +++ b/Documentation/driver-api/eisa.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + ================ EISA bus support ================ diff --git a/Documentation/driver-api/mailbox.rst b/Documentation/driver-api/mailbox.rst index 463dd032b96cd..d46c60bd5df64 100644 --- a/Documentation/driver-api/mailbox.rst +++ b/Documentation/driver-api/mailbox.rst @@ -87,8 +87,8 @@ a message and a callback function to the API and return immediately). struct async_pkt ap; struct sync_pkt sp; - dc_sync = kzalloc(sizeof(*dc_sync), GFP_KERNEL); - dc_async = kzalloc(sizeof(*dc_async), GFP_KERNEL); + dc_sync = kzalloc_obj(*dc_sync); + dc_async = kzalloc_obj(*dc_async); /* Populate non-blocking mode client */ dc_async->cl.dev = &pdev->dev; diff --git a/Documentation/driver-api/media/v4l2-fh.rst b/Documentation/driver-api/media/v4l2-fh.rst index a934caa483a43..ff1fdd8975040 100644 --- a/Documentation/driver-api/media/v4l2-fh.rst +++ b/Documentation/driver-api/media/v4l2-fh.rst @@ -42,7 +42,7 @@ Example: ... - my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL); + my_fh = kzalloc_obj(*my_fh); ... diff --git a/Documentation/filesystems/cramfs.rst b/Documentation/filesystems/cramfs.rst index afbdbde98bd25..221c0bf91b9c8 100644 --- a/Documentation/filesystems/cramfs.rst +++ b/Documentation/filesystems/cramfs.rst @@ -28,8 +28,10 @@ Only the low 8 bits of gid are stored. The current version of mkcramfs simply truncates to 8 bits, which is a potential security issue. -Hard links are supported, but hard linked files -will still have a link count of 1 in the cramfs image. +Hard links are not preserved. mkcramfs deduplicates files with +identical content, but two names for the same on-disk inode in the +source tree become two separate (content-shared) entries in the +image, and cramfs always reports a link count of 1. Cramfs directories have no ``.`` or ``..`` entries. Directories (like every other file on cramfs) always have a link count of 1. (There's @@ -40,12 +42,16 @@ No timestamps are stored in a cramfs, so these default to the epoch the update lasts only as long as the inode is cached in memory, after which the timestamp reverts to 1970, i.e. moves backwards in time. -Currently, cramfs must be written and read with architectures of the -same endianness, and can be read only by kernels with PAGE_SIZE -== 4096. At least the latter of these is a bug, but it hasn't been -decided what the best fix is. For the moment if you have larger pages -you can just change the #define in mkcramfs.c, so long as you don't -mind the filesystem becoming unreadable to future kernels. +The on-disk layout is host-endian: the kernel does not swab, and +refuses to mount an image whose endianness does not match the CPU. +For cross-builds, mkcramfs -B / -L forces the output endianness so +that a host of one endianness can produce an image for a target of +the other. + +The on-disk block size is fixed at 4096 bytes. On systems with a +larger PAGE_SIZE you can change the #define in mkcramfs.c, with the +caveat that the resulting image will only be readable on kernels +configured for the same PAGE_SIZE. Memory Mapped cramfs image diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst index 8421ea21bd35e..277e49314d324 100644 --- a/Documentation/filesystems/locking.rst +++ b/Documentation/filesystems/locking.rst @@ -584,7 +584,7 @@ write_info: yes dqonoff_sem FS recursion means calling ->quota_read() and ->quota_write() from superblock operations. -More details about quota locking can be found in fs/dquot.c. +More details about quota locking can be found in fs/quota/dquot.c. vm_operations_struct ==================== diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index 5006644c1d198..2ccd5b2dfdd33 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -23,13 +23,13 @@ fixes/update part 1.1 Stefani Seibold <stefani@seibold.net> June 9 2009 1 Collecting System Information 1.1 Process-Specific Subdirectories 1.2 Kernel data - 1.3 IDE devices in /proc/ide - 1.4 Networking info in /proc/net - 1.5 SCSI info - 1.6 Parallel port info in /proc/parport - 1.7 TTY info in /proc/tty - 1.8 Miscellaneous kernel statistics in /proc/stat - 1.9 Ext4 file system parameters + 1.3 Networking info in /proc/net + 1.4 SCSI info + 1.5 Parallel port info in /proc/parport + 1.6 TTY info in /proc/tty + 1.7 Miscellaneous kernel statistics in /proc/stat + 1.8 Ext4 file system parameters + 1.9 /proc/consoles - Shows registered system consoles 2 Modifying System Parameters @@ -119,7 +119,7 @@ PTRACE_MODE_ATTACH permissions; CAP_PERFMON capability does not grant access to /proc/PID/mem for other processes. Note that an open file descriptor to /proc/<pid> or to any of its -contained files or subdirectories does not prevent <pid> being reused +contained files or subdirectories does not prevent <pid> from being reused for some other process in the event that <pid> exits. Operations on open /proc/<pid> file descriptors corresponding to dead processes never act on any new process that the kernel may, through chance, have @@ -2212,7 +2212,7 @@ the process is maintaining. Example output:: | lr-------- 1 root root 64 Jan 27 11:24 400000-41a000 -> /usr/bin/ls The name of a link represents the virtual memory bounds of a mapping, i.e. -vm_area_struct::vm_start-vm_area_struct::vm_end. +vm_area_struct::vm_start - vm_area_struct::vm_end. The main purpose of the map_files is to retrieve a set of memory mapped files in a fast way instead of parsing /proc/<pid>/maps or diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index 579e87cb9ff75..8717744f0fec0 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -568,7 +568,7 @@ ENOSPC: EPERM/EACCES: Returned for an operation that is valid, but needs more privileges. E.g. root-only or much more common, DRM master-only operations return - this when called by unpriviledged clients. There's no clear + this when called by unprivileged clients. There's no clear difference between EACCES and EPERM. ENODEV: diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst index dff0646a717bf..c969c76ef7cb4 100644 --- a/Documentation/kernel-hacking/locking.rst +++ b/Documentation/kernel-hacking/locking.rst @@ -442,7 +442,7 @@ to protect the cache and all the objects within it. Here's the code:: { struct object *obj; - if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL) + if ((obj = kmalloc_obj(*obj)) == NULL) return -ENOMEM; strscpy(obj->name, name, sizeof(obj->name)); @@ -517,7 +517,7 @@ which are taken away, and the ``+`` are lines which are added. struct object *obj; + unsigned long flags; - if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL) + if ((obj = kmalloc_obj(*obj)) == NULL) return -ENOMEM; @@ -63,30 +64,33 @@ obj->id = id; diff --git a/Documentation/leds/leds-lp55xx.rst b/Documentation/leds/leds-lp55xx.rst index 632e41cec0b59..f60c7ec398163 100644 --- a/Documentation/leds/leds-lp55xx.rst +++ b/Documentation/leds/leds-lp55xx.rst @@ -18,7 +18,7 @@ The LP55xx common driver provides these features using exported functions. lp55xx_init_device() / lp55xx_deinit_device() lp55xx_register_leds() / lp55xx_unregister_leds() - lp55xx_regsister_sysfs() / lp55xx_unregister_sysfs() + lp55xx_register_sysfs() / lp55xx_unregister_sysfs() ( Driver Structure Data ) diff --git a/Documentation/locking/locktypes.rst b/Documentation/locking/locktypes.rst index 37b6a5670c2fa..ac1ad722a9e7e 100644 --- a/Documentation/locking/locktypes.rst +++ b/Documentation/locking/locktypes.rst @@ -498,7 +498,7 @@ allocating memory. Thus, on a non-PREEMPT_RT kernel the following code works perfectly:: raw_spin_lock(&lock); - p = kmalloc(sizeof(*p), GFP_ATOMIC); + p = kmalloc_obj(*p, GFP_ATOMIC); But this code fails on PREEMPT_RT kernels because the memory allocator is fully preemptible and therefore cannot be invoked from truly atomic @@ -507,7 +507,7 @@ while holding normal non-raw spinlocks because they do not disable preemption on PREEMPT_RT kernels:: spin_lock(&lock); - p = kmalloc(sizeof(*p), GFP_ATOMIC); + p = kmalloc_obj(*p, GFP_ATOMIC); bit spinlocks diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst index 6020d188e13de..58e2af333692d 100644 --- a/Documentation/maintainer/maintainer-entry-profile.rst +++ b/Documentation/maintainer/maintainer-entry-profile.rst @@ -92,24 +92,8 @@ full series, or privately send a reminder email. This section might also list how review works for this code area and methods to get feedback that are not directly from the maintainer. -Existing profiles ------------------ +Maintainer Handbooks +-------------------- -For now, existing maintainer profiles are listed here; we will likely want -to do something different in the near future. - -.. toctree:: - :maxdepth: 1 - - ../doc-guide/maintainer-profile - ../nvdimm/maintainer-entry-profile - ../arch/riscv/patch-acceptance - ../process/maintainer-soc - ../process/maintainer-soc-clean-dts - ../driver-api/media/maintainer-entry-profile - ../process/maintainer-netdev - ../driver-api/vfio-pci-device-specific-driver-acceptance - ../nvme/feature-and-quirk-policy - ../filesystems/nfs/nfsd-maintainer-entry-profile - ../filesystems/xfs/xfs-maintainer-entry-profile - ../mm/damon/maintainer-profile +For examples of other subsystem handbooks see +Documentation/process/maintainer-handbooks.rst. diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 35b381230f6e4..a3bf75dc7c880 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -936,7 +936,7 @@ used. --------------------- The kernel provides the following general purpose memory allocators: -kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and +kmalloc(), kzalloc(), kmalloc_objs(), kzalloc_objs(), vmalloc(), and vzalloc(). Please refer to the API documentation for further information about them. :ref:`Documentation/core-api/memory-allocation.rst <memory_allocation>` @@ -945,7 +945,7 @@ The preferred form for passing a size of a struct is the following: .. code-block:: c - p = kmalloc(sizeof(*p), ...); + p = kmalloc_obj(*p, ...); The alternative form where struct name is spelled out hurts readability and introduces an opportunity for a bug when the pointer variable type is changed @@ -959,13 +959,13 @@ The preferred form for allocating an array is the following: .. code-block:: c - p = kmalloc_array(n, sizeof(...), ...); + p = kmalloc_objs(*ptr, n, ...); The preferred form for allocating a zeroed array is the following: .. code-block:: c - p = kcalloc(n, sizeof(...), ...); + p = kzalloc_objs(*ptr, n, ...); Both forms check for overflow on the allocation size n * sizeof(...), and return NULL if that occurred. diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst index fed56864d0363..ac75b7ecac470 100644 --- a/Documentation/process/deprecated.rst +++ b/Documentation/process/deprecated.rst @@ -392,13 +392,14 @@ allocations. For example, these open coded assignments:: become, respectively:: - ptr = kmalloc_obj(*ptr, gfp); - ptr = kzalloc_obj(*ptr, gfp); - ptr = kmalloc_objs(*ptr, count, gfp); - ptr = kzalloc_objs(*ptr, count, gfp); - ptr = kmalloc_flex(*ptr, flex_member, count, gfp); - __auto_type ptr = kmalloc_obj(struct foo, gfp); + ptr = kmalloc_obj(*ptr [, gfp] ); + ptr = kzalloc_obj(*ptr [, gfp] ); + ptr = kmalloc_objs(*ptr, count [, gfp] ); + ptr = kzalloc_objs(*ptr, count [, gfp] ); + ptr = kmalloc_flex(*ptr, flex_member, count [, gfp] ); + __auto_type ptr = kmalloc_obj(struct foo [, gfp] ); +The argument gfp is optional, the default value is GFP_KERNEL. If `ptr->flex_member` is annotated with __counted_by(), the allocation will automatically fail if `count` is larger than the maximum representable value that can be stored in the counter member associated diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst index 3d72ad25fc6ac..3821e78aefc0a 100644 --- a/Documentation/process/maintainer-handbooks.rst +++ b/Documentation/process/maintainer-handbooks.rst @@ -7,14 +7,13 @@ The purpose of this document is to provide subsystem specific information which is supplementary to the general development process handbook :ref:`Documentation/process <development_process_main>`. -Contents: +For developers, see below for all the known subsystem specific guides. +If the subsystem you are contributing to does not have a guide listed +here, it is fair to seek clarification of questions raised in +Documentation/maintainer/maintainer-entry-profile.rst. -.. toctree:: - :numbered: - :maxdepth: 2 +For maintainers, consider documenting additional requirements and +expectations if submissions routinely overlook specific submission +criteria. See Documentation/maintainer/maintainer-entry-profile.rst. - maintainer-netdev - maintainer-soc - maintainer-soc-clean-dts - maintainer-tip - maintainer-kvm-x86 +.. maintainers-profile-toc:: diff --git a/Documentation/process/maintainers.rst b/Documentation/process/maintainers.rst index 6174cfb4138ff..5d1b1464c3aea 100644 --- a/Documentation/process/maintainers.rst +++ b/Documentation/process/maintainers.rst @@ -1 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. maintainers-include:: diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index d7290e208e72d..cc6a1f73d7f20 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -581,12 +581,12 @@ By offering my Reviewed-by: tag, I state that: A Reviewed-by tag is a statement of opinion that the patch is an appropriate modification of the kernel without any remaining serious -technical issues. Any interested reviewer (who has done the work) can -offer a Reviewed-by tag for a patch. This tag serves to give credit to -reviewers and to inform maintainers of the degree of review which has been -done on the patch. Reviewed-by: tags, when supplied by reviewers known to -understand the subject area and to perform thorough reviews, will normally -increase the likelihood of your patch getting into the kernel. +technical issues. Any interested reviewer (who has done the work and is a +person with known identity) can offer a Reviewed-by tag for a patch. This tag +serves to give credit to reviewers and to inform maintainers of the degree of +review which has been done on the patch. Reviewed-by: tags, when supplied by +reviewers known to understand the subject area and to perform thorough reviews, +will normally increase the likelihood of your patch getting into the kernel. Both Tested-by and Reviewed-by tags, once received on mailing list from tester or reviewer, should be added by author to the applicable patches when sending diff --git a/Documentation/process/threat-model.rst b/Documentation/process/threat-model.rst index f177b8d3c1caf..9dd8011dde828 100644 --- a/Documentation/process/threat-model.rst +++ b/Documentation/process/threat-model.rst @@ -176,7 +176,7 @@ regular bug: * problems seen only under development simulators, emulators, or combinations that do not exist on real systems at the time of reporting (issues involving tens of millions of threads, tens of thousands of CPUs, - unrealistic CPU frequencies, RAM sizes or disk capacities, network speeds. + unrealistic CPU frequencies, RAM sizes or disk capacities, network speeds). * issues whose reproduction requires hardware modification or emulation, including fake USB devices that pretend to be another one. diff --git a/Documentation/scheduler/sched-deadline.rst b/Documentation/scheduler/sched-deadline.rst index 3ad93cd7b59ad..9019b66f6a5ba 100644 --- a/Documentation/scheduler/sched-deadline.rst +++ b/Documentation/scheduler/sched-deadline.rst @@ -685,7 +685,7 @@ Deadline Task Scheduling Deadline tasks cannot have a cpu affinity mask smaller than the root domain they are created on. So, using ``sched_setaffinity(2)`` won't work. Instead, the - the deadline task should be created in a restricted root domain. This can be + deadline task should be created in a restricted root domain. This can be done using the cpuset controller of either cgroup v1 (deprecated) or cgroup v2. See :ref:`Documentation/admin-guide/cgroup-v1/cpusets.rst <cpusets>` and :ref:`Documentation/admin-guide/cgroup-v2.rst <cgroup-v2>` for more information. diff --git a/Documentation/security/credentials.rst b/Documentation/security/credentials.rst index d0191c8b8060e..4996838491b10 100644 --- a/Documentation/security/credentials.rst +++ b/Documentation/security/credentials.rst @@ -189,9 +189,9 @@ The Linux kernel supports the following types of credentials: be searched for the desired key. Each process may subscribe to a number of keyrings: - Per-thread keying - Per-process keyring - Per-session keyring + - Per-thread keyring + - Per-process keyring + - Per-session keyring When a process accesses a key, if not already present, it will normally be cached on one of these keyrings for future accesses to find. diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst index 895752cbcedd6..86b64de031402 100644 --- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst +++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst @@ -266,7 +266,7 @@ to details explained in the following section. .... /* allocate a chip-specific data with zero filled */ - chip = kzalloc(sizeof(*chip), GFP_KERNEL); + chip = kzalloc_obj(*chip); if (chip == NULL) return -ENOMEM; @@ -628,7 +628,7 @@ After allocating a card instance via :c:func:`snd_card_new()` err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, 0, &card); ..... - chip = kzalloc(sizeof(*chip), GFP_KERNEL); + chip = kzalloc_obj(*chip); The chip record should have the field to hold the card pointer at least, @@ -747,7 +747,7 @@ destructor and PCI entries. Example code is shown first, below:: return -ENXIO; } - chip = kzalloc(sizeof(*chip), GFP_KERNEL); + chip = kzalloc_obj(*chip); if (chip == NULL) { pci_disable_device(pci); return -ENOMEM; @@ -1737,7 +1737,7 @@ callback:: { struct my_pcm_data *data; .... - data = kmalloc(sizeof(*data), GFP_KERNEL); + data = kmalloc_obj(*data); substream->runtime->private_data = data; .... } @@ -3301,7 +3301,7 @@ You can then pass any pointer value to the ``private_data``. If you assign private data, you should define a destructor, too. The destructor function is set in the ``private_free`` field:: - struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL); + struct mydata *p = kmalloc_obj(*p); hw->private_data = p; hw->private_free = mydata_free; @@ -3833,7 +3833,7 @@ chip data individually:: err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, 0, &card); .... - chip = kzalloc(sizeof(*chip), GFP_KERNEL); + chip = kzalloc_obj(*chip); .... card->private_data = chip; .... diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css index f91393426a506..5aa0a1ed9864c 100644 --- a/Documentation/sphinx-static/custom.css +++ b/Documentation/sphinx-static/custom.css @@ -30,7 +30,7 @@ img.logo { margin-bottom: 20px; } -/* The default is to use -1em, wich makes it override text */ +/* The default is to use -1em, which makes it override text */ li { text-indent: 0em; } /* diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py index 519ad18685b23..dc9f9e188ffa8 100755 --- a/Documentation/sphinx/maintainers_include.py +++ b/Documentation/sphinx/maintainers_include.py @@ -1,197 +1,415 @@ #!/usr/bin/env python # SPDX-License-Identifier: GPL-2.0 # -*- coding: utf-8; mode: python -*- -# pylint: disable=R0903, C0330, R0914, R0912, E0401 +# pylint: disable=C0209, C0301, E0401, R0022, R0902, R0903, R0912, R0914 """ - maintainers-include - ~~~~~~~~~~~~~~~~~~~ +Implementation of the ``maintainers-include`` reST-directive. - Implementation of the ``maintainers-include`` reST-directive. +:copyright: Copyright (C) 2019 Kees Cook <keescook@chromium.org> +:license: GPL Version 2, June 1991 see linux/COPYING for details. - :copyright: Copyright (C) 2019 Kees Cook <keescook@chromium.org> - :license: GPL Version 2, June 1991 see linux/COPYING for details. - - The ``maintainers-include`` reST-directive performs extensive parsing - specific to the Linux kernel's standard "MAINTAINERS" file, in an - effort to avoid needing to heavily mark up the original plain text. +The ``maintainers-include`` reST-directive performs extensive parsing +specific to the Linux kernel's standard "MAINTAINERS" file, in an +effort to avoid needing to heavily mark up the original plain text. """ -import sys -import re import os.path +import re + +from glob import glob from docutils import statemachine -from docutils.parsers.rst import Directive from docutils.parsers.rst.directives.misc import Include -def ErrorString(exc): # Shamelessly stolen from docutils - return f'{exc.__class__.__name}: {exc}' +# +# Base URL for intersphinx-like links to maintainer profiles +# +KERNELDOC_URL = "https://docs.kernel.org/" -__version__ = '1.0' +__version__ = "1.0" -def setup(app): - app.add_directive("maintainers-include", MaintainersInclude) - return dict( - version = __version__, - parallel_read_safe = True, - parallel_write_safe = True - ) +maint_parser = None # pylint: disable=C0103 -class MaintainersInclude(Include): - """MaintainersInclude (``maintainers-include``) directive""" - required_arguments = 0 +JS_FILTER = """ +(function() { + function filterTable(table) { + const filter = document.getElementById("filter-table").value.trim(); + const rows = table.querySelectorAll("tbody tr"); + for (let i = 0; i < rows.length; i++) { + const tds = rows[i].getElementsByTagName("td"); + let match = false; + for (let j = 0; j < tds.length; j++) { + const cellText = (tds[j].textContent || tds[j].innerText); + if (cellText.includes(filter)) { + match = true; + break; + } + } + rows[i].style.display = match ? "table-row" : "none"; + } + } + function addInput() { + const table = document.getElementById("maintainers-table"); + if (!table) return; + let input = document.getElementById("filter-table"); + if (!input) { + const filt_div = document.createElement('div'); + filt_div.innerHTML = ` + <p>Filter: + <input type="search" id="filter-table" placeholder="search string"/> + subsystem or property (case-sensitive) + </p> + `; + table.parentNode.insertBefore(filt_div, table); + const input = document.getElementById("filter-table") + input.addEventListener('input', () => filterTable(table)); + } + } + if (document.readyState === 'loading') { + document.addEventListener('DOMContentLoaded', addInput); + } else { + addInput(); + } +})(); +""" - def parse_maintainers(self, path): - """Parse all the MAINTAINERS lines into ReST for human-readability""" - result = list() - result.append(".. _maintainers:") - result.append("") +# Shamelessly stolen from docutils +def ErrorString(exc): # pylint: disable=C0103, C0116 + return f"{exc.__class__.__name}: {exc}" # pylint: disable=W0212 + +class MaintainersParser: + """Parse MAINTAINERS file(s) content""" + + def __init__(self, base_dir, app_dir, path): + self.path = path # Poor man's state machine. - descriptions = False - maintainers = False - subsystems = False + self.descriptions = False + self.maintainers = False + self.subsystems = False + + self.subsystem_name = None + + self.base_dir = base_dir + self.app_dir = app_dir - # Field letter to field name mapping. - field_letter = None - fields = dict() + self.re_doc = re.compile(r'(Documentation/(\S*)\.rst)') + + # + # Output variables with maintainers content to be stored + # + self.profile_toc = set() + self.profile_entries = {} + self.header = "" + self.maint_entries = {} + self.fields = {} prev = None - field_prev = "" - field_content = "" + with open(path, "r", encoding="utf-8") as fp: + for line in fp: + if self.descriptions: + self.parse_descriptions(line) + elif self.maintainers and not self.subsystems: + if re.search('^[A-Z0-9]', line): + self.subsystems = True + self.parse_subsystems(line) + else: + self.header += line + elif self.subsystems: + self.parse_subsystems(line) + else: + self.header += line + + # Update the state machine when we find heading separators. + if line.startswith("----------"): + if prev.startswith("Descriptions"): + self.descriptions = True + if prev.startswith("Maintainers"): + self.maintainers = True - for line in open(path): - # Have we reached the end of the preformatted Descriptions text? - if descriptions and line.startswith('Maintainers'): - descriptions = False - # Ensure a blank line following the last "|"-prefixed line. - result.append("") + # Retain previous line for state machine transitions. + prev = line - # Start subsystem processing? This is to skip processing the text - # between the Maintainers heading and the first subsystem name. - if maintainers and not subsystems: - if re.search('^[A-Z0-9]', line): - subsystems = True + def get_entries(self, text): + """Generate refs to ReST files in Documentation/""" - # Drop needless input whitespace. - line = line.rstrip() + if "Documentation/" not in text: + return None - # Linkify all non-wildcard refs to ReST files in Documentation/. - pat = r'(Documentation/([^\s\?\*]*)\.rst)' - m = re.search(pat, line) + if "*" in text or "?" in text: + m = self.re_doc.search(text) + if not m: + return None + + doc_list = glob(os.path.join(self.base_dir, m.group(1))) + else: + doc_list = [text] + + entries = {} + for doc in doc_list: + m = self.re_doc.search(doc) if m: - # maintainers.rst is in a subdirectory, so include "../". - line = re.sub(pat, ':doc:`%s <../%s>`' % (m.group(2), m.group(2)), line) + fname = m.group(1) + ename = m.group(2) + + entry = os.path.relpath(self.base_dir + fname, self.app_dir) + entry = entry.removesuffix(".rst") + + if entry.startswith("../"): + html = KERNELDOC_URL + ename + ".html" + entries[entry] = f'`{ename} <{html}>`_' + else: + entries[entry] = f':doc:`{ename} </{entry}>`' - # Check state machine for output rendering behavior. - output = None - if descriptions: - # Escape the escapes in preformatted text. - output = "| %s" % (line.replace("\\", "\\\\")) - # Look for and record field letter to field name mappings: - # R: Designated *reviewer*: FullName <address@domain> - m = re.search(r"\s(\S):\s", line) + return entries + + def linkify(self, text): + """Return a list of doc files converted to cross-references""" + + entries = self.get_entries(text) + if not entries: + return text + + return self.re_doc.sub(", ".join(entries.values()), text) + + def parse_descriptions(self, line): + """Handle contents of the descriptions section.""" + + # Have we reached the end of the preformatted Descriptions text? + if line.startswith("Maintainers"): + self.descriptions = False + self.header += "\n" + line + return + + # Look for and record field letter to field name mappings: + # R: Designated *reviewer*: FullName <address@domain> + m = re.match(r"\s+(\S):\s+(\S+)", line) + if m: + field = m.group(1) + details = m.group(2) + + if field not in self.fields: + m = re.search(r"\*([^\*]+)\*", line) if m: - field_letter = m.group(1) - if field_letter and not field_letter in fields: - m = re.search(r"\*([^\*]+)\*", line) - if m: - fields[field_letter] = m.group(1) - elif subsystems: - # Skip empty lines: subsystem parser adds them as needed. - if len(line) == 0: - continue - # Subsystem fields are batched into "field_content" - if line[1] != ':': - # Render a subsystem entry as: - # SUBSYSTEM NAME - # ~~~~~~~~~~~~~~ + self.fields[field] = m.group(1) + elif field in ['F', 'N', 'X', 'K']: + line = line.replace(details, f'``{details}``') - # Flush pending field content. - output = field_content + "\n\n" - field_content = "" + self.header += "| " + self.linkify(line) - # Collapse whitespace in subsystem name. - heading = re.sub(r"\s+", " ", line) - output = output + "%s\n%s" % (heading, "~" * len(heading)) - field_prev = "" - else: - # Render a subsystem field as: - # :Field: entry - # entry... - field, details = line.split(':', 1) - details = details.strip() - # Mark paths (and regexes) as literal text for improved - # readability and to escape any escapes. - if field in ['F', 'N', 'X', 'K']: - # But only if not already marked :) - if not ':doc:' in details: - details = '``%s``' % (details) + def parse_subsystems(self, line): + """Handle contents of the per-subsystem sections.""" + + # Drop needless input whitespace. + line = line.rstrip() + + # Skip empty lines: subsystem parser adds them as needed. + if not line: + return + + if line[1] != ':': + self.subsystem_name = re.sub(r"\s+", " ", self.linkify(line)) + return - # Comma separate email field continuations. - if field == field_prev and field_prev in ['M', 'R', 'L']: - field_content = field_content + "," + # Render a subsystem field as: + # :Field: entry + # entry... + field, details = line.split(":", 1) + details = details.strip() - # Do not repeat field names, so that field entries - # will be collapsed together. - if field != field_prev: - output = field_content + "\n" - field_content = ":%s:" % (fields.get(field, field)) - field_content = field_content + "\n\t%s" % (details) - field_prev = field + # + # Handle profile entries - either as files or as https refs + # + if field == "P": + entries = self.get_entries(details) + if entries: + for e, link in entries.items(): + if "html" not in link: + self.profile_toc.add(e) + + self.profile_entries[self.subsystem_name] = link + + details = ", ".join(entries.values()) else: - output = line + match = re.match(r"(https?://.*)", details) + if match: + entry = match.group(1).strip() + self.profile_entries[self.subsystem_name] = entry + else: + self.profile_entries[self.subsystem_name] = f"``{details}``" + + details = self.linkify(details) + else: + details = self.linkify(details) + + # + # Mark paths (and regexes) as literal text for improved + # readability and to escape any escapes. + # + if field in ['F', 'N', 'X', 'K']: + # But only if not already marked :) + if ':doc:' not in details and "http" not in details: + details = '``%s``' % (details) + + if self.subsystem_name not in self.maint_entries: + self.maint_entries[self.subsystem_name] = {} + + if field not in self.maint_entries[self.subsystem_name]: + self.maint_entries[self.subsystem_name][field] = [] + + self.maint_entries[self.subsystem_name][field].append(details) + + self.field_prev = field + + +class MaintainersInclude(Include): + """MaintainersInclude (``maintainers-include``) directive""" + + required_arguments = 0 + + def emit(self): + """Parse all the MAINTAINERS lines into ReST for human-readability""" + path = maint_parser.path + output = ".. _maintainers:\n\n" + output += maint_parser.header - # Re-split on any added newlines in any above parsing. - if output != None: - for separated in output.split('\n'): - result.append(separated) + output += ".. _maintainers_table:\n\n" + output += ".. flat-table::\n" + output += " :header-rows: 1\n\n" + output += " * - Subsystem\n" + output += " - Properties\n\n" - # Update the state machine when we find heading separators. - if line.startswith('----------'): - if prev.startswith('Descriptions'): - descriptions = True - if prev.startswith('Maintainers'): - maintainers = True + self.state.document['maintainers_included'] = True - # Retain previous line for state machine transitions. - prev = line + # Keep the last entry ("THE REST") in the end + entries = list(maint_parser.maint_entries.keys()) + entries = sorted(entries[:-1], key=str.casefold) + [entries[-1]] - # Flush pending field contents. - if field_content != "": - for separated in field_content.split('\n'): - result.append(separated) + for name in entries: + fields = maint_parser.maint_entries[name] + output += f" * - {name}\n" + tag = "-" + for field, lines in fields.items(): + field_name = maint_parser.fields.get(field, field) + + output += f" {tag} :{field_name}:\n " + output += ",\n ".join(lines) + "\n" + tag = " " + + output += "\n" - output = "\n".join(result) # For debugging the pre-rendered results... #print(output, file=open("/tmp/MAINTAINERS.rst", "w")) - self.state_machine.insert_input( - statemachine.string2lines(output), path) + self.state.document.settings.record_dependencies.add(path) + self.state_machine.insert_input(statemachine.string2lines(output), path) def run(self): """Include the MAINTAINERS file as part of this reST file.""" if not self.state.document.settings.file_insertion_enabled: raise self.warning('"%s" directive disabled.' % self.name) - # Walk up source path directories to find Documentation/../ - path = self.state_machine.document.attributes['source'] - path = os.path.realpath(path) - tail = path - while tail != "Documentation" and tail != "": - (path, tail) = os.path.split(path) + try: + self.emit() + except IOError as error: + raise self.severe('Problems with "%s" directive path:\n%s.' % + (self.name, ErrorString(error))) + + return [] + + +class MaintainersProfile(Include): + """Generate a list with all maintainer's profiles""" + + required_arguments = 0 + + def emit(self): + """Parse all the MAINTAINERS lines looking for profile entries""" + env = self.state.document.settings.env + docdir = os.path.dirname(os.path.join(env.srcdir, env.docname)) + path = maint_parser.path + + # + # Produce a list with all maintainer profiles, sorted by subsystem name + # + output = "" + for profile, entry in sorted(maint_parser.profile_entries.items()): + name = profile.title() + + if entry.startswith("http"): + output += f"- `{name} <{entry}>`_\n" + elif entry.startswith("`"): + output += f"- {name}: {entry}\n" + self.warning(f"{profile}: Invalid 'P' tag: {entry}\n") + else: + output += f"- {entry}\n" + + # + # Create a hidden TOC table with all profiles. That allows adding + # profiles without needing to add them on any index.rst file. + # + output += "\n.. toctree::\n" + output += " :hidden:\n\n" - # Append "MAINTAINERS" - path = os.path.join(path, "MAINTAINERS") + for f in sorted(maint_parser.profile_toc): + fname = os.path.join(maint_parser.base_dir, "Documentation", f) + fname = os.path.relpath(fname, docdir) + output += f" {fname}\n" + + output += "\n" + + # For debugging the pre-rendered results... + #print(output, file=open("/tmp/profiles.rst", "w")) + + self.state.document.settings.record_dependencies.add(path) + self.state_machine.insert_input(statemachine.string2lines(output), path) + + def run(self): + """Include the MAINTAINERS file as part of this reST file.""" + if not self.state.document.settings.file_insertion_enabled: + raise self.warning('"%s" directive disabled.' % self.name) try: - self.state.document.settings.record_dependencies.add(path) - lines = self.parse_maintainers(path) + self.emit() except IOError as error: raise self.severe('Problems with "%s" directive path:\n%s.' % (self.name, ErrorString(error))) return [] + + +# pylint: disable=W0613 +def add_filter_script(app, pagename, templatename, context, doctree): + """Add Filter javascript only to maintainers page""" + + if doctree and doctree.get('maintainers_included'): + app.add_js_file(None, body=JS_FILTER) + + +def setup(app): + """Setup Sphinx extension""" + global maint_parser # pylint: disable=W0603 + + app_dir = os.path.abspath(app.srcdir) + match = re.match(r"(.*/)Documentation", app_dir) + if not match: + raise ValueError('Documentation directory not found.') + + base_dir = match.group(1) + path = os.path.join(base_dir, "MAINTAINERS") + + maint_parser = MaintainersParser(base_dir, app_dir, path) + + app.add_directive("maintainers-include", MaintainersInclude) + app.add_directive("maintainers-profile-toc", MaintainersProfile) + + app.connect("html-page-context", add_filter_script) + + return { + "version": __version__, + "parallel_read_safe": True, + "parallel_write_safe": True, + } diff --git a/Documentation/spi/spi-summary.rst b/Documentation/spi/spi-summary.rst index 6e21e6f86912b..ee34796cfbb64 100644 --- a/Documentation/spi/spi-summary.rst +++ b/Documentation/spi/spi-summary.rst @@ -249,7 +249,7 @@ And SOC-specific utility code might look something like:: { struct mysoc_spi_data *pdata2; - pdata2 = kmalloc(sizeof *pdata2, GFP_KERNEL); + pdata2 = kmalloc_obj(*pdata2); *pdata2 = pdata; ... if (n == 2) { @@ -373,7 +373,7 @@ a bus (appearing under /sys/class/spi_master). return -ENODEV; /* get memory for driver's per-chip state */ - chip = kzalloc(sizeof *chip, GFP_KERNEL); + chip = kzalloc(*chip); if (!chip) return -ENOMEM; spi_set_drvdata(spi, chip); diff --git a/Documentation/staging/crc32.rst b/Documentation/staging/crc32.rst index 64f3dd430a6ca..fc0d9564b99c1 100644 --- a/Documentation/staging/crc32.rst +++ b/Documentation/staging/crc32.rst @@ -119,7 +119,7 @@ the byte-at-a-time table method, popularized by Dilip V. Sarwate, v.31 no.8 (August 1988) p. 1008-1013. Here, rather than just shifting one bit of the remainder to decide -in the correct multiple to subtract, we can shift a byte at a time. +on the correct multiple to subtract, we can shift a byte at a time. This produces a 40-bit (rather than a 33-bit) intermediate remainder, and the correct multiple of the polynomial to subtract is found using a 256-entry lookup table indexed by the high 8 bits. diff --git a/Documentation/staging/lzo.rst b/Documentation/staging/lzo.rst index f65b515230146..2d48b2667dd22 100644 --- a/Documentation/staging/lzo.rst +++ b/Documentation/staging/lzo.rst @@ -75,7 +75,7 @@ Description are called under the assumption that a certain number of bytes follow because it has already been guaranteed before parsing the instructions. They just have to "refill" this credit if they consume extra bytes. This - is an implementation design choice independent on the algorithm or + is an implementation design choice independent of the algorithm or encoding. Versions diff --git a/Documentation/staging/remoteproc.rst b/Documentation/staging/remoteproc.rst index 5c226fa076d6b..c117b060e76c7 100644 --- a/Documentation/staging/remoteproc.rst +++ b/Documentation/staging/remoteproc.rst @@ -24,7 +24,7 @@ handlers, and then all rpmsg drivers will then just work (for more information about the virtio-based rpmsg bus and its drivers, please read Documentation/staging/rpmsg.rst). Registration of other types of virtio devices is now also possible. Firmwares -just need to publish what kind of virtio devices do they support, and then +just need to publish what kind of virtio devices they support, and then remoteproc will add those devices. This makes it possible to reuse the existing virtio drivers with remote processor backends at a minimal development cost. diff --git a/Documentation/staging/static-keys.rst b/Documentation/staging/static-keys.rst index b0a519f456cfa..e8dc3a87c3817 100644 --- a/Documentation/staging/static-keys.rst +++ b/Documentation/staging/static-keys.rst @@ -90,7 +90,7 @@ out-of-line true branch. Thus, changing branch direction is expensive but branch selection is basically 'free'. That is the basic tradeoff of this optimization. -This lowlevel patching mechanism is called 'jump label patching', and it gives +This low-level patching mechanism is called 'jump label patching', and it gives the basis for the static keys facility. Static key label API, usage and examples diff --git a/Documentation/trace/histogram-design.rst b/Documentation/trace/histogram-design.rst index e92f56ebd0b50..41a726cd35369 100644 --- a/Documentation/trace/histogram-design.rst +++ b/Documentation/trace/histogram-design.rst @@ -247,7 +247,7 @@ field's size and offset, is used to grab that subkey's data from the current trace record. Note, the hist field function use to be a function pointer in the -hist_field stucture. Due to spectre mitigation, it was converted into +hist_field structure. Due to spectre mitigation, it was converted into a fn_num and hist_fn_call() is used to call the associated hist field function that corresponds to the fn_num of the hist_field structure. diff --git a/Documentation/trace/rv/monitor_sched.rst b/Documentation/trace/rv/monitor_sched.rst index 0b96d6e147c65..d3ba7edc202f6 100644 --- a/Documentation/trace/rv/monitor_sched.rst +++ b/Documentation/trace/rv/monitor_sched.rst @@ -36,7 +36,7 @@ Specifications -------------- The specifications included in sched are currently a work in progress, adapting the ones -defined in by Daniel Bristot in [1]. +defined by Daniel Bristot in [1]_. Currently we included the following: @@ -365,4 +365,7 @@ constraints when processing the events:: References ---------- -[1] - https://bristot.me/linux-task-model +.. [1] Daniel Bristot de Oliveira et al.: + `A thread synchronization model for the PREEMPT_RT Linux kernel + <https://www.iris.sssup.it/bitstream/11382/533630/1/Elsevier-JSA-2020.pdf>`_, + J. Syst. Archit., 2020. diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst index 4c21cf60f775a..205a232c98e23 100644 --- a/Documentation/translations/it_IT/kernel-hacking/locking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst @@ -462,7 +462,7 @@ e tutti gli oggetti che contiene. Ecco il codice:: { struct object *obj; - if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL) + if ((obj = kmalloc_obj(*obj)) == NULL) return -ENOMEM; strscpy(obj->name, name, sizeof(obj->name)); @@ -537,7 +537,7 @@ sono quelle rimosse, mentre quelle ``+`` sono quelle aggiunte. struct object *obj; + unsigned long flags; - if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL) + if ((obj = kmalloc_obj(*obj)) == NULL) return -ENOMEM; @@ -63,30 +64,33 @@ obj->id = id; diff --git a/Documentation/translations/it_IT/locking/locktypes.rst b/Documentation/translations/it_IT/locking/locktypes.rst index 1c7056283b9de..d5fa36aa05cc7 100644 --- a/Documentation/translations/it_IT/locking/locktypes.rst +++ b/Documentation/translations/it_IT/locking/locktypes.rst @@ -488,7 +488,7 @@ o rwlock_t. Per esempio, la sezione critica non deve fare allocazioni di memoria. Su un kernel non-PREEMPT_RT il seguente codice funziona perfettamente:: raw_spin_lock(&lock); - p = kmalloc(sizeof(*p), GFP_ATOMIC); + p = kmalloc_obj(*p, GFP_ATOMIC); Ma lo stesso codice non funziona su un kernel PREEMPT_RT perché l'allocatore di memoria può essere oggetto di prelazione e quindi non può essere chiamato in un @@ -497,7 +497,7 @@ trattiene un blocco *non-raw* perché non disabilitano la prelazione sui kernel PREEMPT_RT:: spin_lock(&lock); - p = kmalloc(sizeof(*p), GFP_ATOMIC); + p = kmalloc_obj(*p, GFP_ATOMIC); bit spinlocks diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst index c0dc786b84749..2a499412a2e3d 100644 --- a/Documentation/translations/it_IT/process/coding-style.rst +++ b/Documentation/translations/it_IT/process/coding-style.rst @@ -943,7 +943,7 @@ Il modo preferito per passare la dimensione di una struttura è il seguente: .. code-block:: c - p = kmalloc(sizeof(*p), ...); + p = kmalloc_obj(*p, ...); La forma alternativa, dove il nome della struttura viene scritto interamente, peggiora la leggibilità e introduce possibili bachi quando il tipo di diff --git a/Documentation/translations/ja_JP/process/submitting-patches.rst b/Documentation/translations/ja_JP/process/submitting-patches.rst index 9d63220abd15b..165cb3ed94ec0 100644 --- a/Documentation/translations/ja_JP/process/submitting-patches.rst +++ b/Documentation/translations/ja_JP/process/submitting-patches.rst @@ -83,19 +83,18 @@ Linux の多くの環境は、上流から特定のパッチだけを取り込� 詳しく説明してください。コードが意図したとおりに動作していることを レビューアが確認できるよう、変更内容を平易な言葉で書き下すことが重要です。 -パッチの説明が Linux のソースコード管理システム ``git`` の「コミットログ」 -としてそのまま取り込める形で書かれていれば、メンテナは助かります。 -詳細は原文の該当節 ("The canonical patch format") を参照してください。 +パッチ説明を Linux のソースコード管理システム ``git`` の +「コミットログ」としてそのまま取り込める形で書けば、メンテナは +助かります。詳細は原文の該当節 ("The canonical patch format") を +参照してください。 .. TODO: Convert to file-local cross-reference when the destination is translated. 1 つのパッチでは 1 つの問題だけを解決してください。記述が長くなり -始めたら、それはパッチを分割すべきサインです。 -詳細は原文の該当節 ("Separate your changes") を参照してください。 +始めたら、パッチを分割すべきサインです。詳細は `変更を分割する`_ を +参照してください。 -.. TODO: Convert to file-local cross-reference when the destination is - translated. パッチまたはパッチシリーズを投稿／再投稿する際は、その完全な 説明と、それを正当化する理由を含めてください。単に「これはパッチ @@ -179,3 +178,180 @@ URL は禁止です。 $ git log -1 --pretty=fixes 54a4f0239f2e Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") + +変更を分割する +-------------- + +各 **論理的な変更** は、��別のパッチに分けてください。 + +たとえば、単一のドライバに対する変更にバグ修正と性能改善の +両方が含まれるなら、それらは 2 つ以上のパッチに分けてください。 +変更に API の更新と、その新しい API を使う新しいドライバが +含まれるなら、それらは 2 つのパッチに分けてください。 + +一方、多数のファイルに対して単一の変更を行う場合は、それらを +1 つのパッチにまとめてください。つまり、1 つの論理的な変更は +1 つのパッチに含めるべきです。 + +覚えておくべき点は、各パッチがレビューアに理解しやすく、 +検証できる変更であるべきだということです。各パッチは、 +それ自体の妥当性で正当化できなければなりません。 + +変更を完成させるために、あるパッチが別のパッチに依存するなら、 +それでも構いません。単に、パッチの説明に +**"this patch depends on patch X"** と記してください。 + +変更を一連のパッチに分ける際は、シリーズ中の各パッチを +適用した後でも、カーネルが正しくビルドされ、正常に動作することを +特に注意して確認してください。問題の追跡に ``git bisect`` を +使う開発者は、あなたのパッチシリーズを任意の地点で分割する +ことがあります。途中でバグを持ち込めば、彼らに感謝されることは +ないでしょう。 + +パッチセットをこれ以上小さくできないなら、一度に投稿するのは +15 個程度までにして、レビューと統合を待ってください。 + + +変更のスタイルを確認する +------------------------ + +パッチに基本的なスタイル違反がないか確認してください。詳細は +Documentation/process/coding-style.rst を参照してください。 +これを怠ると、単にレビューアの時間を無駄にするだけでなく、 +パッチはおそらく読まれもせずに却下されます。 + +大きな例外が 1 つあります。コードをあるファイルから別の +ファイルへ移動する場合です。このときは、コードを移動する +その同じパッチの中で、移動したコードを一切変更してはいけません。 +そうすることで、コードの移動という行為と、あなたの変更とを +明確に区別できます。これは実際の差分のレビューを大いに助け、 +ツールがコード自体の履歴をより適切に追跡できるようにします。 + +提出前に、パッチスタイルチェッカー +(``scripts/checkpatch.pl``) でパッチを確認してください。 +ただし、スタイルチェッカーは指針として見るべきであり、 +人間の判断に取って代わるものではないことに注意してください。 +違反があっても、その方がコードの見栄えがよいなら、 +そのままにしておくのが最善でしょう。 + +チェッカーは 3 つのレベルで報告します: + + - ERROR: 間違っている可能性が非常に高いもの + - WARNING: 慎重なレビューを要するもの + - CHECK: 検討を要するもの + +パッチに残した違反については、すべて理由を説明できなければ +なりません。 + + +パッチの宛先を選択する +---------------------- + +各パッチでは、そのコードを保守する適切なサブシステムメンテナと +メーリングリストを、必ず Cc に入れてください。誰がその +メンテナかは、MAINTAINERS ファイルとソースコードの改訂履歴を +調べて確認してください。この段階では ``scripts/get_maintainer.pl`` +が非常に役立ちます（パッチへのパスを引数として +``scripts/get_maintainer.pl`` に渡してください）。作業中の +サブシステムのメンテナが見つからない場合は、Andrew Morton +(akpm@linux-foundation.org) が最後の手段となるメンテナです。 + +すべてのパッチでは、デフォルトで linux-kernel@vger.kernel.org を +使うべきですが、このリストの流量が多いため、目を通さなくなった +開発者も少なくありません。とはいえ、無関係なメーリングリストや +無関係な人々にスパムを送らないでください。 + +カーネル関連のメーリングリストの多くは kernel.org で運営されており、 +その一覧は https://subspace.kernel.org で確認できます。ただし、 +他所で運営されているカーネル関連のメーリングリストもあります。 + +Linux カーネルに採用されるすべての変更の最終的な裁定者は +Linus Torvalds です。彼のメールアドレスは +<torvalds@linux-foundation.org> です。Linus は大量のメールを +受け取っており、現時点では彼に直接届くパッチはごくわずかなので、 +通常は彼にメールを送ることを極力避けてください。 + +悪用可能なセキュリティバグを修正するパッチがあるなら、 +そのパッチを security@kernel.org に送ってください。深刻なバグに +ついては、ディストリビュータがユーザーにパッチを配布できるよう、 +短期間の embargo が検討される場合があります。そのような場合、 +そのパッチを公開メーリングリストに送るべきではありません。 +Documentation/process/security-bugs.rst も参照してください。 + +リリース済みカーネルの深刻なバグを修正するパッチは、次のような行を +パッチの sign-off 欄に入れることで、stable メンテナへ向けてください:: + + Cc: stable@vger.kernel.org + +これはメールの受信者ではないことに注意してください。また、 +この文書に加えて Documentation/process/stable-kernel-rules.rst も +読んでください。 + +変更がユーザーランドとカーネルのインターフェースに影響する場合は、 +MAINTAINERS ファイルに記載されている MAN-PAGES メンテナに +man-pages パッチ、少なくとも変更の通知を送って、情報が +マニュアルページに反映されるようにしてください。ユーザー空間 API の +変更は、linux-api@vger.kernel.org にも Cc してください。 + +MIME・リンク・圧縮・添付なし、プレーンテキストのみ +---------------------------------------------------- + +Linus や他のカーネル開発者は、あなたが投稿する変更を読み、 +コメントできる必要があります。カーネル開発者が標準的な +メールツールを使ってあなたの変更を「引用」し、コードの特定の +箇所についてコメントできることが重要です。 + +このため、すべてのパッチはメール本文中に ``inline`` で投稿すべきです�� +これを行う最も簡単な方法は ``git send-email`` を使うことであり、 +強く推奨されます。``git send-email`` の対話型チュートリアルは +https://git-send-email.io で利用できます。 + +``git send-email`` を使わないことを選ぶ場合: + +.. warning:: + + パッチをコピー＆ペーストする場合は、エディタの word-wrap によって + パッチが壊れないよう注意してください。 + +圧縮の有無にかかわらず、パッチを MIME 添付ファイルとして添付しては +いけません。多くの一般的なメールアプリケーションは、MIME 添付 +ファイルを常にプレーンテキストとして送信するとは限らず、あなたの +コードにコメントできなくなります。MIME 添付ファイルは Linus が +処理するのにも少し余分な時間がかかるため、MIME 添付された変更が +受け入れられる可能性を下げます。 + +例外: メーラがパッチを壊してしまう場合は、誰かから MIME を使って +再送するよう求められることがあります。 + +パッチを変更せずに送信するようメールクライアントを設定するための +ヒントについては、Documentation/process/email-clients.rst を参照してください。 + + +レビューコメントに返答する +-------------------------- + +あなたのパッチには、ほぼ確実に、パッチを改善する方法について +レビューアからコメントが付きます。それは、あなたのメールへの返信という +形で届きます。それらのコメントには必ず返答してください。レビューアを +無視することは、こちらも無視されるためのよい方法です。コメントに +答えるには、単にそのメールへ返信すれば構いません。コード変更に +つながらないレビューコメントや質問であっても、次のレビューアが状況を +よりよく理解できるように、ほぼ確実にコメントまたは changelog エントリに +反映すべきです。 + +どのような変更を行うのかをレビューアに必ず伝え、時間を割いてくれた +ことに感謝してください。コードレビューは疲れる、時間のかかる作業であり、 +レビューアが不機嫌になることもあります。そのような場合であっても、 +丁寧に返答し、指摘された問題に対応してください。次の版を送るときは、 +cover letter または個々のパッチに ``patch changelog`` を追加し、前回の +投稿との差分を説明してください。詳細は原文の該当節 +("The canonical patch format") を参照してください。 + +.. TODO: Convert to file-local cross-reference when the destination is + translated. + +あなたのパッチにコメントした人には、パッチの Cc リストに追加して、 +新しい版を知らせてください。 + +メールクライアントとメーリングリストでの作法についての推奨事項は、 +Documentation/process/email-clients.rst を参照してください。 diff --git a/Documentation/translations/pt_BR/index.rst b/Documentation/translations/pt_BR/index.rst index 4a094d8b794fa..76936710b06e2 100644 --- a/Documentation/translations/pt_BR/index.rst +++ b/Documentation/translations/pt_BR/index.rst @@ -67,6 +67,8 @@ kernel e sobre como ver seu trabalho integrado. :maxdepth: 1 Introdução <process/1.Intro> + Index de documentos do Kernel <process/kernel-docs> + Regras de licenciamento <process/license-rules> Como começar <process/howto> Requisitos mínimos <process/changes> Conclave (Continuidade do projeto) <process/conclave> diff --git a/Documentation/translations/pt_BR/process/changes.rst b/Documentation/translations/pt_BR/process/changes.rst index 1964c1c93b345..a105581dcf64e 100644 --- a/Documentation/translations/pt_BR/process/changes.rst +++ b/Documentation/translations/pt_BR/process/changes.rst @@ -20,7 +20,8 @@ Requisitos Mínimos Atuais Atualize para pelo menos estas revisões de software antes de pensar que encontrou um bug! Se não tiver certeza de qual versão está executando atualmente -, o comando sugerido deve lhe informar. +, o comando sugerido deve lhe informar. Para uma lista dos programas em seu +sistema, incluindo as versões, execute ./scripts/ver_linux. Novamente, tenha em mente que esta lista pressupõe que você já possui um kernel Linux em execução funcional. Além disso, nem todas as ferramentas são @@ -28,20 +29,21 @@ necessárias em todos os sistemas; obviamente, se você não possui nenhum hardw PC Card por exemplo, provavelmente não precisará se preocupar com o pcmciautils. ====================== =============== ======================================== - Programa Versão mínima Comando para verificar a versão +Programa Versão mínima Comando para verificar a versão ====================== =============== ======================================== GNU C 8.1 gcc --version Clang/LLVM (optional) 15.0.0 clang --version -Rust (optional) 1.78.0 rustc --version -bindgen (optional) 0.65.1 bindgen --version +Rust (optional) 1.85.0 rustc --version +bindgen (optional) 0.71.1 bindgen --version GNU make 4.0 make --version bash 4.2 bash --version binutils 2.30 ld -v flex 2.5.35 flex --version +gdb 7.2 gdb --version bison 2.0 bison --version -pahole 1.16 pahole --version +pahole 1.22 pahole --version util-linux 2.10o mount --version -kmod 13 depmod -V +kmod 13 kmod -V e2fsprogs 1.41.4 e2fsck -V jfsutils 1.1.3 fsck.jfs -V xfsprogs 2.6.0 xfs_db -V @@ -52,13 +54,13 @@ quota-tools 3.09 quota -V PPP 2.4.0 pppd --version nfs-utils 1.0.5 showmount --version procps 3.2.0 ps --version -udev 081 udevd --version +udev 081 udevadm --version grub 0.93 grub --version || grub-install --version mcelog 0.6 mcelog --version iptables 1.4.2 iptables -V openssl & libcrypto 1.0.0 openssl version bc 1.06.95 bc --version -Sphinx\ [#f1]_ 3.4.3 sphinx-build --version +Sphinx [#f1]_ 3.4.3 sphinx-build --version GNU tar 1.28 tar --version gtags (opcional) 6.6.5 gtags --version mkimage (opcional) 2017.01 mkimage --version @@ -81,11 +83,11 @@ Clang/LLVM (opcional) --------------------- A versão formal mais recente do clang e dos utilitários LLVM (de acordo com -releases.llvm.org <https://releases.llvm.org>_) é suportada para a compilação +`releases.llvm.org <https://releases.llvm.org>`_) é suportada para a compilação de kernels. Versões anteriores não têm funcionamento garantido, e poderemos remover do kernel soluções de contorno (workarounds) que eram utilizadas para -suportar versões mais antigas. Por favor, veja a documentação adicional em: -ref:Building Linux with Clang/LLVM <kbuild_llvm>. +suportar versões mais antigas. Por favor, veja a documentação adicional em +:ref:`Building Linux with Clang/LLVM <kbuild_llvm>`. Rust (opcional) --------------- @@ -124,7 +126,7 @@ pkg-config O sistema de compilação, a partir da versão 4.18, requer o pkg-config para verificar as ferramentas kconfig instaladas e para determinar as configurações -de flags para uso em make {g,x}config. Anteriormente, o pkg-config já era +de flags para uso em 'make {g,x}config'. Anteriormente, o pkg-config já era utilizado, mas não era verificado nem documentado. Flex @@ -145,7 +147,7 @@ pahole Desde o Linux 5.2, se CONFIG_DEBUG_INFO_BTF estiver selecionado, o sistema de compilação gera BTF (BPF Type Format) a partir do DWARF no vmlinux, e um pouco -depois para os módulos do kernel também. Isso requer o pahole v1.16 ou superior. +depois para os módulos do kernel também. Isso requer o pahole v1.22 ou superior. Ele pode ser encontrado nos pacotes ``dwarves`` ou ``pahole`` das distribuições, ou em https://fedorapeople.org/~acme/dwarves/. @@ -153,8 +155,8 @@ distribuições, ou em https://fedorapeople.org/~acme/dwarves/. Perl ---- -Você precisará do perl 5 e dos seguintes módulos: Getopt::Long, -Getopt::Std, File::Basename e File::Find para compilar o kernel. +Você precisará do perl 5 e dos seguintes módulos: ``Getopt::Long``, +``Getopt::Std``, ``File::Basename`` e ``File::Find`` para compilar o kernel. Python ------ @@ -191,14 +193,14 @@ gtags / GNU GLOBAL (optional) ----------------------------- A compilação do kernel requer o GNU GLOBAL versão 6.6.5 ou superior para gerar -arquivos de tags através de make gtags. Isso se deve ao uso da flag -C -(--directory) pelo gtags. +arquivos de tags através de make gtags. Isso se deve ao uso da flag ``-C +(--directory)`` pelo ``gtags``. mkimage ------- Esta ferramenta é utilizada ao gerar uma Flat Image Tree (FIT), comumente usada -em plataformas ARM. A ferramenta está disponível através do pacote u-boot-tools +em plataformas ARM. A ferramenta está disponível através do pacote ``u-boot-tools`` ou pode ser compilada a partir do código-fonte do U-Boot. Veja as instruções em https://docs.u-boot.org/en/latest/build/tools.html#building-tools-for-linux @@ -225,13 +227,13 @@ A documentação das funções do Linux está migrando para a documentação emb definições no código-fonte. Esses comentários podem ser combinados com arquivos ReST no diretório Documentation/ para criar uma documentação enriquecida, que pode então ser convertida para arquivos PostScript, HTML, LaTeX, ePUB e PDF. -Para converter do formato ReST para o formato de sua escolha,você precisará do +Para converter do formato ReST para o formato de sua escolha, você precisará do Sphinx. Util-linux ---------- -Novas versões do util-linux oferecem suporte no fdisk para discos maiores, +Novas versões do util-linux oferecem suporte no ``fdisk`` para discos maiores, suporte a novas opções para o mount, reconhecimento de mais tipos de partição e outras funcionalidades interessantes. Você provavelmente vai querer atualizar. @@ -240,23 +242,23 @@ Ksymoops Se o impensável acontecer e o seu kernel sofrer um oops, você pode precisar da ferramenta ksymoops para decodificá-lo, mas na maioria dos casos, não será -necessário. É geralmente preferível compilar o kernel com CONFIG_KALLSYMS para +necessário. É geralmente preferível compilar o kernel com ``CONFIG_KALLSYMS`` para que ele produza dumps legíveis que possam ser usados no estado em que se encontram (isso também gera uma saída melhor do que a do ksymoops). -Se por algum motivo o seu kernel não for compilado com CONFIG_KALLSYMS e você +Se por algum motivo o seu kernel não for compilado com ``CONFIG_KALLSYMS`` e você não tiver como recompilar e reproduzir o oops com essa opção, você ainda poderá decodificá-lo com o ksymoops. Mkinitrd -------- -Estas mudanças no layout da árvore de arquivos /lib/modules também exigem que o +Estas mudanças no layout da árvore de arquivos ``/lib/modules`` também exigem que o mkinitrd seja atualizado. E2fsprogs --------- -A versão mais recente do e2fsprogs corrige diversos bugs no fsck e no debugfs. +A versão mais recente do ``e2fsprogs`` corrige diversos bugs no fsck e no debugfs. Obviamente, é uma boa ideia atualizar. JFSutils @@ -270,8 +272,6 @@ utilitários estão disponíveis: - ``mkfs.jfs`` - cria uma partição formatada em JFS. -- Para o seu arquivo changes.rst, a tradução técnica adequada é: - Outros utilitários de sistema de arquivos também estão disponíveis neste pacote. Xfsprogs @@ -309,7 +309,7 @@ usando o udev, você poderá precisar de:: mknod /dev/cpu/microcode c 10 184 chmod 0644 /dev/cpu/microcode -Se você não estiver usando o udev, você poderá precisar executar os comandos +você poderá precisar executar os comandos acima como root antes de poder usar isso. Você provavelmente também desejará obter o utilitário de espaço de usuário ``microcode_ctl`` para utilizar em conjunto com este driver. @@ -318,7 +318,7 @@ udev ---- O udev é uma aplicação de espaço de usuário para popular o diretório /dev -dinamicamente, apenas com entradas para dispositivos de fat presentes no +dinamicamente, apenas com entradas para dispositivos de fato presentes no sistema. O udev substitui a funcionalidade básica do devfs, permitindo ao mesmo tempo a nomeação persistente de dispositivos. diff --git a/Documentation/translations/pt_BR/process/kernel-docs.rst b/Documentation/translations/pt_BR/process/kernel-docs.rst new file mode 100644 index 0000000000000..3c8d80ffa567f --- /dev/null +++ b/Documentation/translations/pt_BR/process/kernel-docs.rst @@ -0,0 +1,373 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Índice de Documentação Adicional do Kernel +========================================== + +A necessidade de um documento como este tornou-se evidente na lista de discussão +linux-kernel, uma vez que as mesmas perguntas, solicitando referências de +informações, apareciam repetidamente. + +Felizmente, à medida que cada vez mais pessoas chegam ao GNU/Linux, mais pessoas +se interessam pelo Kernel. No entanto, ler o código-fonte nem sempre é o +suficiente. É fácil entender o código, mas perder os conceitos, a filosofia +e as decisões de design por trás dele. + +Infelizmente, não há muitos documentos disponíveis para iniciantes começarem. +E, mesmo quando existem, não havia um local "bem conhecido" que os centralizasse. +Estas linhas tentam suprir essa falta. + +POR FAVOR, se você conhece algum artigo não listado aqui ou se escrever um novo +documento, inclua uma referência a ele aqui, seguindo o processo de envio de +patches do kernel. Quaisquer correções, ideias ou comentários também são +bem-vindos. + +Todos os documentos estão catalogados com os seguintes campos: o "Título" do +documento, o(s) "Autor(es)", a "URL" onde podem ser encontrados, algumas +"Palavras-chave" úteis para pesquisar tópicos específicos e uma breve +"Descrição" do documento. + +.. note:: + + Os documentos em cada seção deste documento estão ordenados por sua data de + publicação, do mais recente para o mais antigo. O(s) mantenedor(es) deve(m) + remover periodicamente recursos à medida que se tornem obsoletos ou + desatualizados; com exceção de livros fundamentais. + +Documentação na árvore do Kernel +-------------------------------- + +Os manuais Sphinx devem ser compilados com ``make {htmldocs | pdfdocs | epubdocs}``. + + * Nome: **linux/Documentation** + + :Autor: Muitos. + :Localização: Documentation/ + :Palavras-chave: arquivos de texto, Sphinx. + :Descrição: Documentação que acompanha o código-fonte do kernel, + dentro do diretório Documentation. Algumas páginas deste documento + (incluindo este próprio documento) foram movidas para lá e podem + estar mais atualizadas do que a versão web. + +Documentação on-line +-------------------- + + * Título: **Linux Kernel Mailing List Glossary** + + :Autor: diversos + :URL: https://kernelnewbies.org/KernelGlossary + :Data: versão contínua (rolling) + :Palavras-chave: glossário, termos, linux-kernel. + :Descrição: Da introdução: "Este glossário destina-se a ser uma breve + descrição de algumas das siglas e termos que você poderá ouvir durante + as discussões sobre o kernel Linux". + + * Título: **The Linux Kernel Module Programming Guide** + + :Autor: Peter Jay Salzman, Michael Burian, Ori Pomerantz, Bob Mottram, + Jim Huang. + :URL: https://sysprog21.github.io/lkmpg/ + :Data: 2021 + :Palavras-chave: módulos, livro GPL, /proc, ioctls, chamadas de sistema, + manipuladores de interrupção. + :Descrição: Um excelente livro sob licença GPL sobre o tópico de + programação de módulos. Repleto de exemplos. Atualmente, a nova versão + está sendo mantida ativamente em https://github.com/sysprog21/lkmpg. + +Livros Publicados +----------------- + + * Title: **The Linux Memory Manager** + + :Autor: Lorenzo Stoakes + :Editora: No Starch Press + :Data: Fevereiro 2025 + :Páginas: 1300 + :ISBN: 978-1718504462 + :Notas: Gerenciamento de memória. Rascunho completo disponível como acesso + antecipado para ré-venda, lançamento completo agendado para o + outono de 2025. Veja https://nostarch.com/linux-memory-manager + para mais informações. + + * Title: **Practical Linux System Administration: A Guide to Installation, Configuration, and Management, 1st Edition** + + :Autor: Kenneth Hess + :Editora: O'Reilly Media + :Data: Maio, 2023 + :Páginas: 246 + :ISBN: 978-1098109035 + :Notas: Administração de sistemas + + * Title: **Linux Kernel Debugging: Leverage proven tools and advanced techniques to effectively debug Linux kernels and kernel modules** + + :Autor: Kaiwan N Billimoria + :Editora: Packt Publishing Ltd + :Data: Agosto, 2022 + :Páginas: 638 + :ISBN: 978-1801075039 + :Notas: Livro sobre depuração (debugging) + + * Title: **Linux Kernel Programming: A Comprehensive Guide to Kernel Internals, Writing Kernel Modules, and Kernel Synchronization** + + :Autor: Kaiwan N Billimoria + :Editora: Packt Publishing Ltd + :Data: Março, 2021 (Segunda edição publicada em 2024) + :Páginas: 754 + :ISBN: 978-1789953435 (O ISBN da segunda edição é 978-1803232225) + + * Title: **Linux Kernel Programming Part 2 - Char Device Drivers and Kernel Synchronization: Create user-kernel interfaces, work with peripheral I/O, and handle hardware interrupts** + + :Autor: Kaiwan N Billimoria + :Editora: Packt Publishing Ltd + :Data: Março, 2021 + :Páginas: 452 + :ISBN: 978-1801079518 + + * Title: **Linux System Programming: Talking Directly to the Kernel and C Library** + + :Autor: Robert Love + :Editora: O'Reilly Media + :Data: Junho, 2013 + :Páginas: 456 + :ISBN: 978-1449339531 + :Notas: Livro fundamental + + * Título: **Linux Kernel Development, 3rd Edition** + + :Autor: Robert Love + :Editora: Addison-Wesley + :Data: Julho de 2010 + :Páginas: 440 + :ISBN: 978-0672329463 + :Notas: Livro fundamental + + * Título: **Linux Device Drivers, 3rd Edition** + + :Autores: Jonathan Corbet, Alessandro Rubini e Greg Kroah-Hartman + :Editora: O'Reilly & Associates + :Data: 2005 + :Páginas: 636 + :ISBN: 0-596-00590-3 + :Notas: Livro fundamental. Mais informações em + http://www.oreilly.com/catalog/linuxdrive3/ + Formato PDF, URL: https://lwn.net/Kernel/LDD3/ + + * Título: **The Design of the UNIX Operating System** + + :Autor: Maurice J. Bach + :Editora: Prentice Hall + :Data: 1986 + :Páginas: 471 + :ISBN: 0-13-201757-1 + :Notas: Livro fundamental + +Diversos +-------- + + * Nome: **Cross-Referencing Linux** + + :URL: https://elixir.bootlin.com/ + :Palavras-chave: Navegação em código-fonte. + :Descrição: Outro navegador web para o código-fonte do kernel Linux. + Possui muitas referências cruzadas para variáveis e funções. Você pode + ver onde elas são definidas e onde são utilizadas. + + * Nome: **Linux Weekly News** + + :URL: https://lwn.net + :Palavras-chave: últimas notícias do kernel. + :Descrição: O título diz tudo. Há uma seção fixa sobre o kernel que + resume o trabalho dos desenvolvedores, correções de bugs, novos recursos + e versões produzidas durante a semana. + + * Nome: **The home page of Linux-MM** + + :Autor: A equipe Linux-MM. + :URL: https://linux-mm.org/ + :Palavras-chave: gerenciamento de memória, Linux-MM, mm patches, TODO, + docs, mailing list. + :Descrição: Site dedicado ao desenvolvimento do Gerenciamento de Memória + do Linux. Patches relacionados à memória, HOWTOs, links, desenvolvedores + mm... Não perca se você estiver interessado no desenvolvimento do + gerenciamento de memória! + + * Nome: **Kernel Newbies IRC Channel and Website** + + :URL: https://www.kernelnewbies.org + :Palavras-chave: IRC, novatos, canal, tirar dúvidas. + :Descrição: #kernelnewbies em irc.oftc.net. + O canal #kernelnewbies é uma rede de IRC dedicada ao hacker de kernel + "novato" (newbie). O público consiste principalmente de pessoas que estão + aprendendo sobre o kernel, trabalhando em projetos do kernel ou hackers + profissionais que desejam ajudar pessoas menos experientes. + O #kernelnewbies está na rede de IRC OFTC. + Tente acessar irc.oftc.net como seu servidor e então digite /join #kernelnewbies. + O site kernelnewbies também hospeda artigos, documentos, FAQs... + + * Nome: **linux-kernel mailing list archives and search engines** + + :URL: https://subspace.kernel.org + :URL: https://lore.kernel.org + :Palavras-chave: linux-kernel, arquivos, busca. + :Descrição: Alguns dos arquivadores da lista de discussão linux-kernel. + Se você conhece algum outro (ou um melhor), por favor, me avise. + + * Nome: **The Linux Foundation YouTube channel** + + :URL: https://www.youtube.com/user/thelinuxfoundation + :Palavras-chave: linux, vídeos, linux-foundation, youtube. + :Descrição: A Linux Foundation faz o upload de gravações de vídeo de seus + eventos colaborativos, conferências de Linux (incluindo a LinuxCon) e + outras pesquisas originais e conteúdos relacionados ao Linux e ao + desenvolvimento de software. + +Rust +---- + + * Título: **Rust for Linux** + + :Autor: diversos + :URL: https://rust-for-linux.com/ + :Data: versão contínua (rolling) + :Palavras-chave: glossário, termos, linux-kernel, rust. + :Descrição Do site: "Rust for Linux é o projeto que adiciona suporte à + linguagem Rust ao kernel Linux. Este site pretende ser um hub de links, + documentação e recursos relacionados ao projeto". + + * Título: **Learn Rust the Dangerous Way** + + :Autor: Cliff L. Biffle + :URL: https://cliffle.com/p/dangerust/ + :Data: Acessado em 11 de setembro de 2024 + :Palavras-chave: rust, blog. + :Descrição: Do site: "LRtDW é uma série de artigos que coloca os recursos + do Rust em contexto para programadores C de baixo nível que talvez não + tenham uma formação formal em Ciência da Computação, o tipo de pessoa + que trabalha com firmware, engines de jogos, kernels de SO e afins. + Basicamente, pessoas como eu.". O site ilustra conversões de linha por + linha de C para Rust. + + * Título: **The Rust Book** + + :Autor: Steve Klabnik e Carol Nichols, com contribuições da comunidade Rust + :URL: https://doc.rust-lang.org/book/ + :Data: Acessado em 11 de setembro de 2024 + :Palavras-chave: rust, livro. + :Descrição: Do site: "Este livro abraça totalmente o potencial do Rust para + capacitar seus usuários. É um texto amigável e acessível destinado a + ajudá-lo a elevar não apenas seu conhecimento de Rust, mas também seu + alcance e confiança como programador em geral. Então mergulhe de cabeça, + prepare-se para aprender e bem-vindo à comunidade Rust!". + + * Título: **Rust for the Polyglot Programmer** + + :Autor: Ian Jackson + :URL: https://www.chiark.greenend.org.uk/~ianmdlvl/rust-polyglot/index.html + :Data: Dezembro de 2022 + :Palavras-chave: rust, blog, tooling. + :Descrição: Do site: "Existem muitos guias e introduções ao Rust. Este é + algo diferente: destina-se ao programador experiente que já conhece + muitas outras linguagens de programação. Tento ser abrangente o suficiente + para servir de ponto de partida para qualquer área do Rust, mas evito + entrar em detalhes excessivos, exceto onde as coisas não são como você + poderia esperar. Além disso, este guia não é inteiramente isento de + opiniões, incluindo recomendações de bibliotecas (crates), ferramentas, etc.". + + * Título: **Fasterthanli.me** + + :Autor: Amos Wenger + :URL: https://fasterthanli.me/ + :Data: Acessado em 11 de setembro de 2024 + :Palavras-chave: rust, blog, notícias. + :Descrição: Do site: "Eu crio artigos e vídeos sobre como os computadores + funcionam. Meu conteúdo é de formato longo, didático e exploratório + e frequentemente uma desculpa para ensinar Rust!". + + * Título: **Comprehensive Rust** + + :Autor: Equipe Android do Google + :URL: https://google.github.io/comprehensive-rust/ + :Data: Acessado em 13 de setembro de 2024 + :Palavras-chave: rust, blog. + :Descrição: Do site: "O curso cobre todo o espectro do Rust, desde a + sintaxe básica até tópicos avançados como genéricos e tratamento de erros". + + * Título: **The Embedded Rust Book** + + :Autor: Múltiplos colaboradores, principalmente Jorge Aparicio + :URL: https://docs.rust-embedded.org/book/ + :Data: Acessado em 13 de setembro de 2024 + :Palavras-chave: rust, blog. + :Descrição: Do site: "Um livro introdutório sobre o uso da linguagem de + programação Rust em sistemas embarcados 'Bare Metal', como microcontroladores". + + * Título: **Experiment: Improving the Rust Book** + + :Autor: Cognitive Engineering Lab na Brown University + :URL: https://rust-book.cs.brown.edu/ + :Data: Acessado em 22 de setembro de 2024 + :Palavras-chave: rust, blog. + :Descrição: Do site: "O objetivo deste experimento é avaliar e melhorar o + conteúdo do Rust Book para ajudar as pessoas a aprenderem Rust de forma + mais eficaz". + + * Título: **New Rustacean** (podcast) + + :Autor: Chris Krycho + :URL: https://newrustacean.com/ + :Data: Acessado em 22 de setembro de 2024 + :Palavras-chave: rust, podcast. + :Descrição: Do site: "Este é um podcast sobre aprender a linguagem de + programação Rust do zero! Além desta página inicial elegante, todo o + conteúdo do site é construído com as próprias ferramentas de documentação + do Rust". + + * Título: **Opsem-team** (repositório) + + :Autor: Equipe de semântica operacional (Operational semantics team) + :URL: https://github.com/rust-lang/opsem-team/tree/main + :Data: Acessado em 22 de setembro de 2024 + :Palavras-chave: rust, repositório. + :Descrição: Do README: "A equipe opsem é a sucessora do grupo de trabalho + unsafe-code-guidelines e é responsável por responder a muitas das perguntas + difíceis sobre a semântica do Rust inseguro (unsafe Rust)". + + * Título: **You Can't Spell Trust Without Rust** + + :Autor: Alexis Beingessner + :URL: https://repository.library.carleton.ca/downloads/1j92g820w?locale=en + :Data: 2015 + :Palavras-chave: rust, mestrado, tese. + :Descrição: Esta tese foca no sistema de propriedade (ownership) do Rust, + que garante a segurança de memória ao controlar a manipulação de dados e + o tempo de vida, enquanto também destaca suas limitações e o compara a + sistemas semelhantes no Cyclone e C++. + + * Nome: **Apresentações de Rust no Linux Plumbers (LPC) 2024** + + :Título: Rust microconference + :URL: https://lpc.events/event/18/sessions/186/#20240918 + :Título: Rust for Linux + :URL: https://lpc.events/event/18/contributions/1912/ + :Título: Journey of a C kernel engineer starting a Rust driver project + :URL: https://lpc.events/event/18/contributions/1911/ + :Título: Crafting a Linux kernel scheduler that runs in user-space using Rust + :URL: https://lpc.events/event/18/contributions/1723/ + :Título: openHCL: A Linux and Rust based paravisor + :URL: https://lpc.events/event/18/contributions/1956/ + :Palavras-chave: rust, lpc, apresentações. + :Descrição: Uma série de palestras do LPC relacionadas ao Rust. + + * Nome: **The Rustacean Station Podcast** + + :URL: https://rustacean-station.org/ + :Palavras-chave: rust, podcasts. + :Descrição: Um projeto comunitário para a criação de conteúdo em podcast + sobre a linguagem de programação Rust. + +------- + +Este documento foi originalmente baseado em: + +https://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html + +e escrito por Juan-Mariano de Goyeneche. diff --git a/Documentation/translations/pt_BR/process/license-rules.rst b/Documentation/translations/pt_BR/process/license-rules.rst new file mode 100644 index 0000000000000..1e395dfea8759 --- /dev/null +++ b/Documentation/translations/pt_BR/process/license-rules.rst @@ -0,0 +1,483 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Regras de licenciamento do kernel Linux +======================================= + +O Kernel Linux é fornecido apenas sob os termos da licença GNU General Public +License versão 2 (GPL-2.0), conforme estabelecido em LICENSES/preferred/GPL-2.0, +com uma exceção explícita para syscalls descrita em +LICENSES/exceptions/Linux-syscall-note, conforme descrito no arquivo COPYING. + +Este arquivo de documentação fornece uma descrição de como cada arquivo-fonte +deve ser anotado para tornar sua licença clara e inequívoca. Ele não substitui +a licença do Kernel. + +A licença descrita no arquivo COPYING aplica-se ao código-fonte do kernel como +um todo, embora arquivos-fonte individuais possam ter uma licença diferente, a +qual deve ser obrigatoriamente compatível com a GPL-2.0:: + + GPL-1.0+ : GNU General Public License v1.0 ou posterior + GPL-2.0+ : GNU General Public License v2.0 ou posterior + LGPL-2.0 : GNU Library General Public License v2 apenas + LGPL-2.0+ : GNU Library General Public License v2 ou posterior + LGPL-2.1 : GNU Lesser General Public License v2.1 apenas + LGPL-2.1+ : GNU Lesser General Public License v2.1 ou posterior + +Além disso, arquivos individuais podem ser fornecidos sob uma licença dupla +(dual license), por exemplo, uma das variantes GPL compatíveis e, +alternativamente, sob uma licença permissiva como BSD, MIT, etc. + +Os arquivos de cabeçalho da API do espaço do usuário (UAPI), que descrevem a +interface dos programas do espaço do usuário com o kernel, são um caso especial. +De acordo com a nota no arquivo COPYING do kernel, a interface de syscall é um +limite claro, que não estende os requisitos da GPL a qualquer software que a +utilize para se comunicar com o kernel. Como os cabeçalhos UAPI devem ser +passíveis de inclusão em quaisquer arquivos-fonte que criem um executável +executado no kernel Linux, a exceção deve ser documentada por uma expressão de +licença especial. + +A forma comum de expressar a licença de um arquivo-fonte é adicionar o texto +padrão (boilerplate) correspondente no comentário inicial do arquivo. Devido a +variações de formatação, erros de digitação, etc., esses "textos padrão" são +difíceis de validar por ferramentas usadas no contexto de conformidade de +licença. + +Uma alternativa aos textos padrão é o uso de identificadores de licença +Software Package Data Exchange (SPDX) em cada arquivo-fonte. Os identificadores +de licença SPDX são abreviações precisas e analisáveis por máquina para a +licença sob a qual o conteúdo do arquivo é contribuído. Os identificadores de +licença SPDX são gerenciados pelo Grupo de Trabalho SPDX na Linux Foundation e +foram acordados por parceiros em toda a indústria, fornecedores de ferramentas +e equipes jurídicas. Para mais informações, consulte https://spdx.org/ + +O kernel Linux exige o identificador SPDX preciso em todos os arquivos-fonte. +Os identificadores válidos usados no kernel são explicados na seção +`Identificadores de Licença`_ e foram obtidos da lista de licenças +oficial do SPDX em https://spdx.org/licenses/ junto com os textos das licenças. + +Sintaxe do identificador de licença +----------------------------------- + +1. Posicionamento: + + O identificador de licença SPDX em arquivos do kernel deve ser adicionado na + primeira linha possível do arquivo que possa conter um comentário. Para a + maioria dos arquivos, esta é a primeira linha, exceto para scripts que + requerem o '#!CAMINHO_PARA_INTERPRETADOR' na primeira linha. Para esses + scripts, o identificador de licença SPDX deve ser colocado na segunda linha. + + A linha do identificador de licença pode então ser seguida por uma ou + múltiplas linhas de SPDX-FileCopyrightText, se desejado. + +2. Estilo: + + O identificador de licença SPDX é adicionado na forma de um comentário. O + estilo do comentário depende do tipo de arquivo:: + + Fonte C: // SPDX-License-Identifier: <Expressão de Licença SPDX> + Cabeçalho C:/* SPDX-License-Identifier: <Expressão de Licença SPDX> */ + ASM: /* SPDX-License-Identifier: <Expressão de Licença SPDX> */ + scripts: # SPDX-License-Identifier: <Expressão de Licença SPDX> + .rst: .. SPDX-License-Identifier: <Expressão de Licença SPDX> + .dts{i}: // SPDX-License-Identifier: <Expressão de Licença SPDX> + + Se uma ferramenta específica não conseguir lidar com o estilo de comentário + padrão, então deve ser utilizado o mecanismo de comentário apropriado que a + ferramenta aceite. Este é o motivo para ter o comentário no estilo ``/* */`` + em arquivos de cabeçalho C. Foi observada uma quebra de build com arquivos + .lds gerados, onde o 'ld' falhou ao analisar o comentário C++. Isso já foi + corrigido, mas ainda existem ferramentas de assembler mais antigas que não + conseguem lidar com comentários no estilo C++. + +3. Sintaxe: + + Uma <Expressão de Licença SPDX> pode ser um identificador SPDX simplificado + encontrado na Lista de Licenças SPDX, ou a combinação de dois desses + identificadores separados por "WITH", caso uma exceção de licença se aplique. + Quando múltiplas licenças são aplicáveis, a expressão utiliza as palavras-chave + "AND" ou "OR" para separar as sub-expressões, que devem ser delimitadas + por parênteses "(", ")". + + Para licenças como [L]GPL, utiliza-se o sufixo "+" para indicar a opção + 'ou posterior':: + + // SPDX-License-Identifier: GPL-2.0+ + // SPDX-License-Identifier: LGPL-2.1+ + + O termo "WITH" deve ser usado sempre que houver um modificador necessário + para a licença. Por exemplo, os arquivos UAPI do kernel Linux utilizam a + expressão:: + + // SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note + // SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note + + Outros exemplos de uso da cláusula "WITH" para exceções no kernel são:: + + // SPDX-License-Identifier: GPL-2.0 WITH mif-exception + // SPDX-License-Identifier: GPL-2.0+ WITH GCC-exception-2.0 + + As exceções só podem ser aplicadas a identificadores de licença específicos. + Os identificadores válidos estão listados nas tags do arquivo de texto de + cada exceção. Para detalhes, veja o ponto `Exceções`_ no capítulo + `Identificadores de Licença`_. + + O termo "OR" deve ser usado se o arquivo possuir licenciamento duplo (dual + licensed) e apenas uma das licenças puder ser selecionada. Por exemplo, + alguns arquivos dtsi estão disponíveis sob licença dupla:: + + // SPDX-License-Identifier: GPL-2.0 OR BSD-3-Clause + + Exemplos de expressões para arquivos com licenciamento duplo no kernel:: + + // SPDX-License-Identifier: GPL-2.0 OR MIT + // SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause + // SPDX-License-Identifier: GPL-2.0 OR Apache-2.0 + // SPDX-License-Identifier: GPL-2.0 OR MPL-1.1 + // SPDX-License-Identifier: (GPL-2.0 WITH Linux-syscall-note) OR MIT + // SPDX-License-Identifier: GPL-1.0+ OR BSD-3-Clause OR OpenSSL + + O termo "AND" deve ser usado se o arquivo possuir múltiplas licenças cujos + termos devem ser aplicados simultaneamente. Por exemplo, se um código herdado + de outro projeto foi incorporado ao kernel, mas os termos da licença original + ainda precisam ser respeitados:: + + // SPDX-License-Identifier: (GPL-2.0 WITH Linux-syscall-note) AND MIT + + Outro exemplo onde ambos os conjuntos de termos devem ser cumpridos é:: + + // SPDX-License-Identifier: GPL-1.0+ AND LGPL-2.1+ + +Identificadores de Licença +-------------------------- + +As licenças atualmente em uso, bem como as licenças para código adicionado ao +kernel, podem ser divididas em: + +4. _`Licenças preferenciais`: + + Sempre que possível, estas licenças devem ser utilizadas, pois são conhecidas + por serem totalmente compatíveis e amplamente usadas. Estas licenças estão + disponíveis no diretório:: + + LICENSES/preferred/ + + na árvore de diretórios do código-fonte do kernel. + + Os arquivos neste diretório contêm o texto completo da licença e as + `Metatags`_. Os nomes dos arquivos são idênticos ao identificador de licença + SPDX que deve ser utilizado para a licença nos arquivos-fonte. + + Exemplos:: + + LICENSES/preferred/GPL-2.0 + + Contém o texto da licença GPL versão 2 e as metatags obrigatórias:: + + LICENSES/preferred/MIT + + Contém o texto da licença MIT e as metatags obrigatórias. + + _`Metatags`: + + As seguintes metatags devem estar presentes em um arquivo de licença: + + - Valid-License-Identifier: + + Uma ou mais linhas que declaram quais Identificadores de Licença são válidos + dentro do projeto para referenciar este texto de licença específico. + Geralmente, trata-se de um único identificador válido, mas, por exemplo, + para licenças com as opções 'ou posterior' (or later), dois identificadores + são válidos. + + - SPDX-URL: + + A URL da página SPDX que contém informações adicionais relacionadas à licença. + + - Usage-Guidance: + + Texto livre para conselhos de uso. O texto deve incluir exemplos corretos + para os identificadores de licença SPDX, conforme eles devem ser colocados + nos arquivos-fonte de acordo com as diretrizes de + `Sintaxe do identificador de licença`_. + + - License-Text: + + Todo o texto após esta tag é tratado como o texto original da licença. + + Exemplos de formato de arquivo:: + + Valid-License-Identifier: GPL-2.0 + Valid-License-Identifier: GPL-2.0+ + SPDX-URL: https://spdx.org/licenses/GPL-2.0.html + Usage-Guide: + Para usar esta licença no código-fonte, coloque um dos seguintes pares + SPDX tag/valor em um comentário, de acordo com as diretrizes de + posicionamento na documentação das regras de licenciamento. + Para 'GNU General Public License (GPL) version 2 only', use: + SPDX-License-Identifier: GPL-2.0 + Para 'GNU General Public License (GPL) version 2 or any later version', use: + SPDX-License-Identifier: GPL-2.0+ + License-Text: + Texto completo da licença + + :: + + Valid-License-Identifier: MIT + SPDX-URL: https://spdx.org/licenses/MIT.html + Usage-Guide: + Para usar esta licença no código-fonte, coloque o seguinte par SPDX + tag/valor em um comentário, de acordo com as diretrizes de + posicionamento na documentação das regras de licenciamento. + SPDX-License-Identifier: MIT + License-Text: + Texto completo da licença + +5. Licenças obsoletas: + + Estas licenças devem ser utilizadas apenas para código já existente ou para + a importação de código de outros projetos. Estas licenças estão disponíveis + no diretório:: + + LICENSES/deprecated/ + + na árvore de fontes do kernel. + + Os arquivos neste diretório contêm o texto completo da licença e as + `Metatags`_. Os nomes dos arquivos são idênticos ao identificador de + licença SPDX que deve ser utilizado para a licença nos arquivos fonte. + + Exemplos:: + + LICENSES/deprecated/ISC + + Contém o texto da licença *Internet Systems Consortium* e as metatags + necessárias:: + + LICENSES/deprecated/GPL-1.0 + + Contém o texto da licença GPL versão 1 e as metatags necessárias. + + Metatags: + + Os requisitos de metatags para "outras" licenças são idênticos aos + requisitos das `Licenças preferenciais`_. + + Exemplo de formato de arquivo:: + + Valid-License-Identifier: ISC + SPDX-URL: https://spdx.org/licenses/ISC.html + Usage-Guide: + O uso desta licença no kernel para novos códigos é desencorajado + e deve ser utilizada exclusivamente para importar código de um + projeto já existente. + Para usar esta licença no código-fonte, coloque o seguinte par + tag/valor SPDX em um comentário, seguindo as diretrizes de + posicionamento na documentação das regras de licenciamento. + SPDX-License-Identifier: ISC + License-Text: + Texto completo da licença + +6. Apenas Licenciamento Duplo + + Estas licenças devem ser usadas apenas para o licenciamento duplo de código + com outra licença, além de uma licença preferencial. Estas licenças estão + disponíveis no diretório:: + + LICENSES/dual/ + + No código-fonte do kernel. + + Os arquivos neste diretório contêm o texto completo da licença e as + `Metatags`_. Os nomes dos arquivos são idênticos ao identificador de licença + SPDX que deve ser usado para a licença nos arquivos fonte. + + Exemplos:: + + LICENSES/dual/MPL-1.1 + + Contém o texto da licença Mozilla Public License versão 1.1 e as metatags + necessárias:: + + LICENSES/dual/Apache-2.0 + + Contém o texto da licença Apache License versão 2.0 e as metatags + necessárias. + + Metatags: + + Os requisitos de metatags para 'outras' licenças são idênticos aos + requisitos das `Licenças preferenciais`_. + + Exemplo de formato de arquivo:: + + Valid-License-Identifier: MPL-1.1 + SPDX-URL: https://spdx.org/licenses/MPL-1.1.html + Usage-Guide: + NÃO use. A licença MPL-1.1 não é compatível com a GPL2. Ela só pode ser + usada para arquivos com licenciamento duplo onde a outra licença seja + compatível com a GPL2. + Se você acabar utilizando-a, ela DEVE ser usada em conjunto com uma + licença compatível com a GPL2 utilizando "OR". + Para usar a Mozilla Public License versão 1.1, coloque o seguinte par + tag/valor SPDX em um comentário, de acordo com as diretrizes de + posicionamento na documentação das regras de licenciamento: + SPDX-License-Identifier: MPL-1.1 + License-Text: + Texto completo da licença + +| + +7. _`Exceções`: + +Algumas licenças podem ser alteradas com exceções que concedem certos direitos + que a licença original não concede. Estas exceções estão disponíveis no + diretório:: + + LICENSES/exceptions/ + + no código-fonte do kernel. Os arquivos neste diretório contêm o texto completo + da exceção e as `Metatags de Exceção`_ necessárias. + + Exemplos:: + + LICENSES/exceptions/Linux-syscall-note + + Contém a exceção de syscall do Linux, conforme documentado no arquivo COPYING + do kernel Linux, que é usada para arquivos de cabeçalho UAPI. + ex: /\* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note \*/:: + + LICENSES/exceptions/GCC-exception-2.0 + + Contém a 'exceção de vinculação' do GCC, que permite + vincular qualquer binário, independente de sua licença, à versão compilada + de um arquivo marcado com esta exceção. Isso é necessário para criar + executáveis funcionais a partir de código-fonte que não seja compatível + com a GPL. + + _`Metatags de Exceção`: + + As seguintes meta tags devem estar disponíveis em um arquivo de exceção: + + - SPDX-Exception-Identifier: + + Um identificador de exceção que pode ser usado com identificadores de + licença SPDX. + + - SPDX-URL: + + A URL da página SPDX que contém informações adicionais relacionadas + à exceção. + + - SPDX-Licenses: + + Uma lista separada por vírgulas de identificadores de licença SPDX para os + quais a exceção pode ser usada. + + - Usage-Guidance: + + Texto de formato livre para conselhos de uso. O texto deve ser seguido por + exemplos corretos para os identificadores de licença SPDX, conforme devem + ser colocados nos arquivos fonte de acordo com as diretrizes de + `Sintaxe do identificador de licença`_. + + - Exception-Text: + + Todo o texto após esta tag é tratado como o texto original da exceção. + + Exemplos de formato de arquivo:: + + SPDX-Exception-Identifier: Linux-syscall-note + SPDX-URL: https://spdx.org/licenses/Linux-syscall-note.html + SPDX-Licenses: GPL-2.0, GPL-2.0+, GPL-1.0+, LGPL-2.0, LGPL-2.0+, LGPL-2.1, LGPL-2.1+ + Usage-Guidance: + Esta exceção é usada em conjunto com uma das SPDX-Licenses acima para + marcar arquivos de cabeçalho de API do espaço do usuário (uapi), para que + possam ser incluídos em código de aplicativo de espaço do usuário que não + esteja em conformidade com a GPL. + Para usar esta exceção, adicione-a com a palavra-chave WITH a um dos + identificadores na tag SPDX-Licenses: + SPDX-License-Identifier: <SPDX-License> WITH Linux-syscall-note + Exception-Text: + Texto completo da exceção + +Exemplos de formato de arquivo:: + + SPDX-Exception-Identifier: GCC-exception-2.0 + SPDX-URL: https://spdx.org/licenses/GCC-exception-2.0.html + SPDX-Licenses: GPL-2.0, GPL-2.0+ + Usage-Guidance: + A "GCC Runtime Library exception 2.0" é usada em conjunto com uma das + SPDX-Licenses acima para código importado da biblioteca de tempo de + execução (runtime) do GCC. + Para usar esta exceção, adicione-a com a palavra-chave WITH a um dos + identificadores na tag SPDX-Licenses: + SPDX-License-Identifier: <SPDX-License> WITH GCC-exception-2.0 + Exception-Text: + Texto completo da exceção + +Todos os identificadores de licença e exceções SPDX devem ter um arquivo +correspondente nos subdiretórios LICENSES. Isso é necessário para permitir a +verificação por ferramentas (ex: checkpatch.pl) e para que as licenças estejam +prontas para leitura e extração diretamente da fonte, o que é recomendado por +várias organizações de FOSS (Software Livre e de Código Aberto), como a +`iniciativa REUSE da FSFE <https://reuse.software/>`_. + +_`MODULE_LICENSE` +----------------- + + Módulos carregáveis do kernel também exigem uma tag MODULE_LICENSE(). Esta tag + não substitui as informações adequadas de licença do código-fonte + (SPDX-License-Identifier), nem é de forma alguma relevante para expressar ou + determinar a licença exata sob a qual o código-fonte do módulo é fornecido. + + O único propósito desta tag é fornecer informações suficientes ao carregador + de módulos do kernel e às ferramentas de espaço do usuário sobre o módulo ser + software livre ou proprietário. + + As strings de licença válidas para MODULE_LICENSE() são:: + + ============================= ============================================= + "GPL" O módulo está licenciado sob a GPL versão 2. + Isso não expressa nenhuma distinção entre + GPL-2.0-only ou GPL-2.0-or-later. A informação + exata da licença só pode ser determinada por + meio das informações de licença nos arquivos + fonte correspondentes. + + "GPL v2" O mesmo que "GPL". Existe por razões + históricas. + + "GPL and additional rights" Variante histórica para expressar que o fonte + do módulo possui licenciamento duplo sob uma + variante da GPL v2 e a licença MIT. Por favor, + não use em códigos novos. + + "Dual MIT/GPL" A maneira correta de expressar que o módulo + possui licenciamento duplo sob uma escolha de + variante GPL v2 ou licença MIT. + + "Dual BSD/GPL" O módulo possui licenciamento duplo sob uma + escolha de variante GPL v2 ou licença BSD. A + variante exata da licença BSD só pode ser + determinada por meio das informações de + licença nos arquivos fonte correspondentes. + + "Dual MPL/GPL" O módulo possui licenciamento duplo sob uma + escolha de variante GPL v2 ou Mozilla Public + License (MPL). A variante exata da licença + MPL só pode ser determinada por meio das + informações de licença nos arquivos fonte + correspondentes. + + "Proprietary" O módulo está sob uma licença proprietária. + "Proprietary" deve ser entendido apenas como + "A licença não é compatível com GPLv2". Esta + string é exclusiva para módulos de terceiros + não compatíveis com GPL2 e não pode ser usada + para módulos que tenham seu código-fonte na + árvore do kernel. Módulos marcados dessa forma + contaminam (tainting) o kernel com a flag 'P' + quando carregados, e o carregador de módulos + recusa-se a vincular tais módulos a símbolos + exportados com EXPORT_SYMBOL_GPL(). + ============================= =============================================
\ No newline at end of file diff --git a/Documentation/translations/pt_BR/process/maintainer-handbooks.rst b/Documentation/translations/pt_BR/process/maintainer-handbooks.rst index ba36df8eeaf18..bf7a381472e23 100644 --- a/Documentation/translations/pt_BR/process/maintainer-handbooks.rst +++ b/Documentation/translations/pt_BR/process/maintainer-handbooks.rst @@ -16,3 +16,4 @@ Conteúdos: maintainer-netdev maintainer-soc maintainer-soc-clean-dts + maintainer-kvm-x86 diff --git a/Documentation/translations/sp_SP/process/coding-style.rst b/Documentation/translations/sp_SP/process/coding-style.rst index 7d63aa8426e63..44c93d5f6beb3 100644 --- a/Documentation/translations/sp_SP/process/coding-style.rst +++ b/Documentation/translations/sp_SP/process/coding-style.rst @@ -955,7 +955,7 @@ La forma preferida para pasar el tamaño de una estructura es la siguiente: .. code-block:: c - p = kmalloc(sizeof(*p), ...); + p = kmalloc_obj(*p, ...); La forma alternativa donde se deletrea el nombre de la estructura perjudica la legibilidad, y presenta una oportunidad para un error cuando se cambia diff --git a/Documentation/translations/zh_CN/core-api/kref.rst b/Documentation/translations/zh_CN/core-api/kref.rst index b9902af310c55..8a0c030ec1d31 100644 --- a/Documentation/translations/zh_CN/core-api/kref.rst +++ b/Documentation/translations/zh_CN/core-api/kref.rst @@ -52,7 +52,7 @@ kref可以出现在数据结构体中的任何地方。 struct my_data *data; - data = kmalloc(sizeof(*data), GFP_KERNEL); + data = kmalloc_obj(*data); if (!data) return -ENOMEM; kref_init(&data->refcount); @@ -106,7 +106,7 @@ Kref规则 int rv = 0; struct my_data *data; struct task_struct *task; - data = kmalloc(sizeof(*data), GFP_KERNEL); + data = kmalloc_obj(*data); if (!data) return -ENOMEM; kref_init(&data->refcount); diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst index 5a342a024c01e..55d5da974d89f 100644 --- a/Documentation/translations/zh_CN/process/coding-style.rst +++ b/Documentation/translations/zh_CN/process/coding-style.rst @@ -813,7 +813,7 @@ Documentation/translations/zh_CN/core-api/memory-allocation.rst 。 .. code-block:: c - p = kmalloc(sizeof(*p), ...); + p = kmalloc_obj(*p, ...); 另外一种传递方式中，sizeof 的操作数是结构体的名字，这样会降低可读性，并且可能 会引入 bug。有可能指针变量类型被改变时，而对应的传递给内存分配函数的 sizeof diff --git a/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt index f0be21a60a0fb..05414579efaca 100644 --- a/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt +++ b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt @@ -799,7 +799,7 @@ int my_open(struct file *file) ... - my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL); + my_fh = kzalloc_obj(*my_fh); ... diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/translations/zh_TW/process/coding-style.rst index e2ba97b3d8bbf..63c78982a1afc 100644 --- a/Documentation/translations/zh_TW/process/coding-style.rst +++ b/Documentation/translations/zh_TW/process/coding-style.rst @@ -827,7 +827,7 @@ Documentation/translations/zh_CN/core-api/memory-allocation.rst 。 .. code-block:: c - p = kmalloc(sizeof(*p), ...); + p = kmalloc_obj(*p, ...); 另外一種傳遞方式中，sizeof 的操作數是結構體的名字，這樣會降低可讀性，並且可能 會引入 bug。有可能指針變量類型被改變時，而對應的傳遞給內存分配函數的 sizeof diff --git a/Documentation/virt/uml/user_mode_linux_howto_v2.rst b/Documentation/virt/uml/user_mode_linux_howto_v2.rst index c37e8e594d122..9224bea5ee9f9 100644 --- a/Documentation/virt/uml/user_mode_linux_howto_v2.rst +++ b/Documentation/virt/uml/user_mode_linux_howto_v2.rst @@ -234,7 +234,7 @@ an ioctl to setup the tun interface and/or use raw sockets where needed. This can be achieved by granting the user a particular capability instead of running UML as root. In case of vector transport, a user can add the capability ``CAP_NET_ADMIN`` or ``CAP_NET_RAW`` to the uml binary. -Thenceforth, UML can be run with normal user privilges, along with +Thenceforth, UML can be run with normal user privileges, along with full networking. For example:: diff --git a/Documentation/watchdog/mlx-wdt.rst b/Documentation/watchdog/mlx-wdt.rst index 35e690dea9db6..2da36c7628900 100644 --- a/Documentation/watchdog/mlx-wdt.rst +++ b/Documentation/watchdog/mlx-wdt.rst @@ -28,7 +28,7 @@ Type 3: Same as Type 2 with extended maximum timeout period. Maximum timeout is 65535 sec. -Type 1 HW watchdog implementation exist in old systems and +Type 1 HW watchdog implementation exists in old systems and all new systems have type 2 HW watchdog. Two types of HW implementation have also different register map. @@ -48,7 +48,7 @@ which is optional. Watchdog can be started during a probe, in this case it will be pinged by watchdog core before watchdog device will be opened by user space application. -Watchdog can be initialised in nowayout way, i.e. oncse started +Watchdog can be initialised in nowayout mode, i.e. once started it can't be stopped. This mlx-wdt driver supports both HW watchdog implementations. diff --git a/Documentation/watchdog/pcwd-watchdog.rst b/Documentation/watchdog/pcwd-watchdog.rst index 151505c856f63..5cd45abe246a6 100644 --- a/Documentation/watchdog/pcwd-watchdog.rst +++ b/Documentation/watchdog/pcwd-watchdog.rst @@ -29,7 +29,7 @@ Documentation and Driver by Ken Hollis <kenji@bitgate.com> to run the program with an "&" to run it in the background!) If you want to write a program to be compatible with the PC Watchdog - driver, simply use of modify the watchdog test program: + driver, simply use or modify the watchdog test program: tools/testing/selftests/watchdog/watchdog-test.c @@ -37,16 +37,23 @@ Documentation and Driver by Ken Hollis <kenji@bitgate.com> WDIOC_GETSUPPORT This returns the support of the card itself. This - returns in structure "PCWDS" which returns: + returns in structure watchdog_info: + + identity = "PCWD" + + options = list of supported options:: + WDIOF_OVERHEAT + WDIOF_CARDRESET + WDIOF_KEEPALIVEPING + WDIOF_SETTIMEOUT + WDIOF_MAGICCLOSE - options = WDIOS_TEMPPANIC - (This card supports temperature) firmware_version = xxxx (Firmware version of the card) WDIOC_GETSTATUS This returns the status of the card, with the bits of - WDIOF_* bitwise-anded into the value. (The comments + WDIOF_* bitwise-ored into the value. (The comments are in include/uapi/linux/watchdog.h) WDIOC_GETBOOTSTATUS @@ -55,7 +62,7 @@ Documentation and Driver by Ken Hollis <kenji@bitgate.com> WDIOC_GETTEMP This returns the temperature of the card. (You can also - read /dev/watchdog, which gives a temperature update + read /dev/temperature, which gives a temperature update every second.) WDIOC_SETOPTIONS diff --git a/Documentation/watchdog/watchdog-api.rst b/Documentation/watchdog/watchdog-api.rst index 78e228c272cf8..983d4800d2102 100644 --- a/Documentation/watchdog/watchdog-api.rst +++ b/Documentation/watchdog/watchdog-api.rst @@ -39,12 +39,12 @@ The simplest API All drivers support the basic mode of operation, where the watchdog activates as soon as /dev/watchdog is opened and will reboot unless -the watchdog is pinged within a certain time, this time is called the +the watchdog is pinged within a certain time; this time is called the timeout or margin. The simplest way to ping the watchdog is to write some data to the device. So a very simple watchdog daemon would look like this source file: see samples/watchdog/watchdog-simple.c -A more advanced driver could for example check that a HTTP server is +A more advanced driver could for example check that an HTTP server is still responding before doing the write call to ping the watchdog. When the device is closed, the watchdog is disabled, unless the "Magic @@ -87,13 +87,13 @@ replaced with:: sleep(10); } -the argument to the ioctl is ignored. +The argument to the ioctl is ignored. Setting and getting the timeout =============================== For some drivers it is possible to modify the watchdog timeout on the -fly with the SETTIMEOUT ioctl, those drivers have the WDIOF_SETTIMEOUT +fly with the SETTIMEOUT ioctl; those drivers have the WDIOF_SETTIMEOUT flag set in their option field. The argument is an integer representing the timeout in seconds. The driver returns the real timeout used in the same variable, and this timeout might differ from @@ -110,7 +110,7 @@ Starting with the Linux 2.4.18 kernel, it is possible to query the current timeout using the GETTIMEOUT ioctl:: ioctl(fd, WDIOC_GETTIMEOUT, &timeout); - printf("The timeout was is %d seconds\n", timeout); + printf("The timeout is %d seconds\n", timeout); Pretimeouts =========== @@ -133,7 +133,7 @@ seconds. Setting a pretimeout to zero disables it. There is also a get function for getting the pretimeout:: ioctl(fd, WDIOC_GETPRETIMEOUT, &timeout); - printf("The pretimeout was is %d seconds\n", timeout); + printf("The pretimeout is %d seconds\n", timeout); Not all watchdog drivers will support a pretimeout. @@ -145,13 +145,13 @@ before the system will reboot. The WDIOC_GETTIMELEFT is the ioctl that returns the number of seconds before reboot:: ioctl(fd, WDIOC_GETTIMELEFT, &timeleft); - printf("The timeout was is %d seconds\n", timeleft); + printf("The timeout is %d seconds\n", timeleft); Environmental monitoring ======================== -All watchdog drivers are required return more information about the system, -some do temperature, fan and power level monitoring, some can tell you +All watchdog drivers are required to return more information about the system. +Some do temperature, fan and power level monitoring; some can tell you the reason for the last reboot of the system. The GETSUPPORT ioctl is available to ask what the device can do:: @@ -166,7 +166,7 @@ the fields returned in the ident struct are: options a flags describing what the device supports ================ ============================================= -the options field can have the following bits set, and describes what +The options field can have the following bits set, and describes what kind of information that the GET_STATUS and GET_BOOT_STATUS ioctls can return. @@ -175,13 +175,13 @@ return. ================ ========================= The machine was last rebooted by the watchdog because the thermal limit was -exceeded: +exceeded. ============== ========== WDIOF_FANFAULT Fan failed ============== ========== -A system fan monitored by the watchdog card has failed +A system fan monitored by the watchdog card has failed. ============= ================ WDIOF_EXTERN1 External relay 1 @@ -195,26 +195,26 @@ a reset. WDIOF_EXTERN2 External relay 2 ============= ================ -External monitoring relay/source 2 was triggered +External monitoring relay/source 2 was triggered. ================ ===================== WDIOF_POWERUNDER Power bad/power fault ================ ===================== -The machine is showing an undervoltage status +The machine is showing an undervoltage status. =============== ============================= WDIOF_CARDRESET Card previously reset the CPU =============== ============================= -The last reboot was caused by the watchdog card +The last reboot was caused by the watchdog card. ================ ===================== WDIOF_POWEROVER Power over voltage ================ ===================== The machine is showing an overvoltage status. Note that if one level is -under and one over both bits will be set - this may seem odd but makes +under and one over, both bits will be set - this may seem odd but makes sense. =================== ===================== @@ -227,12 +227,14 @@ The watchdog saw a keepalive ping since it was last queried. WDIOF_SETTIMEOUT Can set/get the timeout ================ ======================= -The watchdog can do pretimeouts. +The watchdog can get/set the timeout. ================ ================================ WDIOF_PRETIMEOUT Pretimeout (in seconds), get/set ================ ================================ +The watchdog can do pretimeouts. + For those drivers that return any bits set in the option field, the GETSTATUS and GETBOOTSTATUS ioctls can be used to ask for the current @@ -255,7 +257,7 @@ returned value is the temperature in degrees Fahrenheit:: ioctl(fd, WDIOC_GETTEMP, &temperature); Finally the SETOPTIONS ioctl can be used to control some aspects of -the cards operation:: +the card's operation:: int options = 0; ioctl(fd, WDIOC_SETOPTIONS, &options); diff --git a/Documentation/watchdog/watchdog-kernel-api.rst b/Documentation/watchdog/watchdog-kernel-api.rst index 5649c54cf6fbe..350e9037a69eb 100644 --- a/Documentation/watchdog/watchdog-kernel-api.rst +++ b/Documentation/watchdog/watchdog-kernel-api.rst @@ -38,8 +38,8 @@ The watchdog_unregister_device routine deregisters a registered watchdog timer device. The parameter of this routine is the pointer to the registered watchdog_device structure. -The watchdog subsystem includes an registration deferral mechanism, -which allows you to register an watchdog as early as you wish during +The watchdog subsystem includes a registration deferral mechanism, +which allows you to register a watchdog as early as you wish during the boot process. The watchdog device structure looks like this:: @@ -60,13 +60,14 @@ The watchdog device structure looks like this:: unsigned int max_hw_heartbeat_ms; struct notifier_block reboot_nb; struct notifier_block restart_nb; + struct notifier_block pm_nb; void *driver_data; struct watchdog_core_data *wd_data; unsigned long status; struct list_head deferred; }; -It contains following fields: +It contains the following fields: * id: set by watchdog_register_device, id 0 is special. It has both a /dev/watchdog0 cdev (dynamic major, minor 0) as well as the old @@ -105,6 +106,8 @@ It contains following fields: internal use only. If a watchdog is capable of restarting the machine, it should define ops->restart. Priority can be changed through watchdog_set_restart_priority. +* pm_nb: coordinates watchdog_dev_suspend/resume to cancel a ping worker + during suspend and restore it during resume. * bootstatus: status of the device after booting (reported with watchdog WDIOF_* status bits). * driver_data: a pointer to the drivers private data of a watchdog device. @@ -204,7 +207,7 @@ they are supported. These optional routines/operations are: If the watchdog driver does not have to perform any action but setting the watchdog_device.timeout, this callback can be omitted. - If set_timeout is not provided but, WDIOF_SETTIMEOUT is set, the watchdog + If set_timeout is not provided but WDIOF_SETTIMEOUT is set, the watchdog infrastructure updates the timeout value of the watchdog_device internally to the requested value. @@ -220,7 +223,7 @@ they are supported. These optional routines/operations are: the watchdog". A value of 0 disables pretimeout notification. (Note: the WDIOF_PRETIMEOUT needs to be set in the options field of the - watchdog's info structure). + watchdog's info structure.) If the watchdog driver does not have to perform any action but setting the watchdog_device.pretimeout, this callback can be omitted. That means if @@ -239,7 +242,7 @@ they are supported. These optional routines/operations are: The status bits should (preferably) be set with the set_bit and clear_bit alike bit-operations. The status bits that are defined are: -* WDOG_ACTIVE: this status bit indicates whether or not a watchdog timer device +* WDOG_ACTIVE: this status bit indicates whether a watchdog timer device is active or not from user perspective. User space is expected to send heartbeat requests to the driver while this flag is set. * WDOG_NO_WAY_OUT: this bit stores the nowayout setting for the watchdog. @@ -254,6 +257,9 @@ bit-operations. The status bits that are defined are: then opening /dev/watchdog will skip the start operation but send a keepalive request instead. +Helper Functions +~~~~~~~~~~~~~~~~ + To set the WDOG_NO_WAY_OUT status bit (before registering your watchdog timer device) you can either: @@ -331,7 +337,7 @@ To raise a pretimeout notification, the following function should be used:: void watchdog_notify_pretimeout(struct watchdog_device *wdd) The function can be called in the interrupt context. If watchdog pretimeout -governor framework (kbuild CONFIG_WATCHDOG_PRETIMEOUT_GOV symbol) is enabled, +governor framework (kconfig CONFIG_WATCHDOG_PRETIMEOUT_GOV symbol) is enabled, an action is taken by a preconfigured pretimeout governor preassigned to the watchdog device. If watchdog pretimeout governor framework is not enabled, watchdog_notify_pretimeout() prints a notification message to diff --git a/Documentation/watchdog/watchdog-parameters.rst b/Documentation/watchdog/watchdog-parameters.rst index 773241ed99867..2359aa32e25d5 100644 --- a/Documentation/watchdog/watchdog-parameters.rst +++ b/Documentation/watchdog/watchdog-parameters.rst @@ -14,13 +14,22 @@ modules. ------------------------------------------------- watchdog core: + handle_boot_enabled: + Watchdog core auto-updates boot-enabled watchdogs before userspace + takes over. Default is set by the kconfig option + CONFIG_WATCHDOG_HANDLE_BOOT_ENABLED. + open_timeout: Maximum time, in seconds, for which the watchdog framework will take care of pinging a running hardware watchdog until userspace opens the corresponding /dev/watchdogN device. A value of 0 means an infinite timeout. Setting this to a non-zero value can be useful to ensure that either userspace comes up properly, or the board gets reset and allows - fallback logic in the bootloader to try something else. + fallback logic in the bootloader to try something else. Default is set + by the kconfig option CONFIG_WATCHDOG_OPEN_TIMEOUT. + + stop_on_reboot: + Stops watchdogs on reboot (0 = keep watching, 1 = stop). ------------------------------------------------- |