Address several documentation build warnings
Subsystems (18)
cover Address several documentation build warnings
This patch series is against next-20200317. It addresses several warnings on random places.
It is worth noticing patch 07/17: It changes kernel-doc parser to accept a very common pattern on kernel-doc markups. This reduces a lot of warnings all over the tree.
The remaining patches are just random fixes with the hope to address most warnings that are shown in red when building the documentation.
Mauro Carvalho Chehab (17):
docs: amu: supress some Sphinx warnings
docs: arm64: booting.rst: get rid of some warnings
docs: pci: boot-interrupts.rst: improve html output
kernel: futex.c: get rid of a docs build warning
devfreq: devfreq.h: get rid of some doc warnings
firewire: firewire-cdev.hL get rid of a docs warning
scripts: kernel-doc: proper handle @foo->bar()
lib: bitmap.c: get rid of some doc warnings
rcu: update.c: get rid of some doc warnings
net: phy: sfp-bus.c: get rid of docs warnings
net: core: dev.c: fix a documentation warning
gpio: gpiolib.c: fix a doc warning
i2c: include/linux/i2c.h: fix a doc warning
infiniband: pa_vnic_encap.h: get rid of a warning
ata: libata-core: fix a doc warning
fs: inode.c: get rid of docs warnings
regulator: driver.h: fix regulator_map_* function names
Documentation/PCI/boot-interrupts.rst | 34 ++++++++++-------- Documentation/arm64/amu.rst | 5 +++ Documentation/arm64/booting.rst | 36 +++++++++++-------- drivers/ata/libata-core.c | 2 +- drivers/gpio/gpiolib.c | 2 +- .../infiniband/ulp/opa_vnic/opa_vnic_encap.h | 2 +- drivers/net/phy/sfp-bus.c | 32 +++++++++-------- fs/inode.c | 6 ++-- include/linux/devfreq.h | 6 ++-- include/linux/i2c.h | 4 +-- include/linux/regulator/driver.h | 4 +-- include/uapi/linux/firewire-cdev.h | 2 +- kernel/futex.c | 3 +- kernel/rcu/update.c | 8 ++--- lib/bitmap.c | 27 +++++++------- net/core/dev.c | 2 +- scripts/kernel-doc | 2 ++ 17 files changed, 101 insertions(+), 76 deletions(-)
Signature · 1 line
2.24.1
PATCH 13/17 i2c: include/linux/i2c.h: fix a doc warning
Don't let non-letters inside a literal block without escaping it, as the toolchain would mis-interpret it:
./include/linux/i2c.h:518: WARNING: Inline strong start-string without end-string.
--- include/linux/i2c.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
include/linux/i2c.h +2 -2
@@ -506,7 +506,7 @@ i2c_register_board_info(int busnum, struct i2c_board_info const *info,* @smbus_xfer_atomic: same as @smbus_xfer. Yet, only using atomic context * so e.g. PMICs can be accessed very late before shutdown. Optional. * @functionality: Return the flags that this algorithm/adapter pair supports -* from the I2C_FUNC_* flags. +* from the ``I2C_FUNC_*`` flags. * @reg_slave: Register given client to I2C slave mode of this adapter * @unreg_slave: Unregister given client from I2C slave mode of this adapter *
@@ -515,7 +515,7 @@ i2c_register_board_info(int busnum, struct i2c_board_info const *info,* be addressed using the same bus algorithms - i.e. bit-banging or the PCF8584 * to name two of the most common. * -* The return codes from the @master_xfer{_atomic} fields should indicate the +* The return codes from the ``master_xfer{_atomic}`` fields should indicate the * type of error code that occurred during the transfer, as documented in the * Kernel Documentation file Documentation/i2c/fault-codes.rst. */
Signature · 1 line
2.24.1
PATCH 1/17 docs: amu: supress some Sphinx warnings
In reply to Mauro Carvalho ChehabAdd extra blank lines on some places, in order to avoid those warnings when building the docs:
Documentation/arm64/amu.rst:26: WARNING: Unexpected indentation. Documentation/arm64/amu.rst:60: WARNING: Unexpected indentation. Documentation/arm64/amu.rst:81: WARNING: Unexpected indentation. Documentation/arm64/amu.rst:108: WARNING: Unexpected indentation.
--- Documentation/arm64/amu.rst | 5 +++++ 1 file changed, 5 insertions(+)
Documentation/arm64/amu.rst +5 -0
@@ -23,6 +23,7 @@ optional external memory-mapped interface. Version 1 of the Activity Monitors architecture implements a counter group of four fixed and architecturally defined 64-bit event counters. + - CPU cycle counter: increments at the frequency of the CPU. - Constant counter: increments at the fixed frequency of the system clock.
@@ -57,6 +58,7 @@ counters, only the presence of the extension. Firmware (code running at higher exception levels, e.g. arm-tf) support is needed to: + - Enable access for lower exception levels (EL2 and EL1) to the AMU registers. - Enable the counters. If not enabled these will read as 0.
@@ -78,6 +80,7 @@ are not trapped in EL2/EL3. The fixed counters of AMUv1 are accessible though the following system register definitions: + - SYS_AMEVCNTR0_CORE_EL0 - SYS_AMEVCNTR0_CONST_EL0 - SYS_AMEVCNTR0_INST_RET_EL0
@@ -93,6 +96,7 @@ Userspace access ---------------- Currently, access from userspace to the AMU registers is disabled due to: + - Security reasons: they might expose information about code executed in secure mode. - Purpose: AMU counters are intended for system management use.
@@ -105,6 +109,7 @@ Virtualization Currently, access from userspace (EL0) and kernelspace (EL1) on the KVM guest side is disabled due to: + - Security reasons: they might expose information about code executed by other guests or the host.
Signature · 1 line
2.24.1
PATCH 2/17 docs: arm64: booting.rst: get rid of some warnings
In reply to Mauro Carvalho ChehabGet rid of those warnings:
Documentation/arm64/booting.rst:253: WARNING: Unexpected indentation. Documentation/arm64/booting.rst:259: WARNING: Block quote ends without a blank line; unexpected unindent.
By adding an extra blank lines where needed.
While here, use list markups on some places, as otherwise Sphinx will consider the next lines as continuation of the privious ones.
--- Documentation/arm64/booting.rst | 36 ++++++++++++++++++++------------- 1 file changed, 22 insertions(+), 14 deletions(-)
Documentation/arm64/booting.rst +22 -14
@@ -173,7 +173,9 @@ Before jumping into the kernel, the following conditions must be met: - Caches, MMUs The MMU must be off. + Instruction cache may be on or off. + The address range corresponding to the loaded kernel image must be cleaned to the PoC. In the presence of a system cache or other coherent masters with caches enabled, this will typically require
@@ -238,6 +240,7 @@ Before jumping into the kernel, the following conditions must be met: - The DT or ACPI tables must describe a GICv2 interrupt controller. For CPUs with pointer authentication functionality: + - If EL3 is present: - SCR_EL3.APK (bit 16) must be initialised to 0b1
@@ -249,18 +252,22 @@ Before jumping into the kernel, the following conditions must be met: - HCR_EL2.API (bit 41) must be initialised to 0b1 For CPUs with Activity Monitors Unit v1 (AMUv1) extension present: + - If EL3 is present: - CPTR_EL3.TAM (bit 30) must be initialised to 0b0 - CPTR_EL2.TAM (bit 30) must be initialised to 0b0 - AMCNTENSET0_EL0 must be initialised to 0b1111 - AMCNTENSET1_EL0 must be initialised to a platform specific value - having 0b1 set for the corresponding bit for each of the auxiliary - counters present. + + - CPTR_EL3.TAM (bit 30) must be initialised to 0b0 + - CPTR_EL2.TAM (bit 30) must be initialised to 0b0 + - AMCNTENSET0_EL0 must be initialised to 0b1111 + - AMCNTENSET1_EL0 must be initialised to a platform specific value + having 0b1 set for the corresponding bit for each of the auxiliary + counters present. + - If the kernel is entered at EL1: - AMCNTENSET0_EL0 must be initialised to 0b1111 - AMCNTENSET1_EL0 must be initialised to a platform specific value - having 0b1 set for the corresponding bit for each of the auxiliary - counters present. + + - AMCNTENSET0_EL0 must be initialised to 0b1111 + - AMCNTENSET1_EL0 must be initialised to a platform specific value + having 0b1 set for the corresponding bit for each of the auxiliary + counters present. The requirements described above for CPU mode, caches, MMUs, architected timers, coherency and system registers apply to all CPUs. All CPUs must
@@ -304,7 +311,8 @@ following manner: Documentation/devicetree/bindings/arm/psci.yaml. - Secondary CPU general-purpose register settings - x0 = 0 (reserved for future use) - x1 = 0 (reserved for future use) - x2 = 0 (reserved for future use) - x3 = 0 (reserved for future use) + + - x0 = 0 (reserved for future use) + - x1 = 0 (reserved for future use) + - x2 = 0 (reserved for future use) + - x3 = 0 (reserved for future use)
Signature · 1 line
2.24.1
PATCH 6/17 firewire: firewire-cdev.hL get rid of a docs warning
In reply to Mauro Carvalho ChehabThis warning:
./include/uapi/linux/firewire-cdev.h:312: WARNING: Inline literal start-string without end-string.
is because %FOO doesn't work if there's a parenthesis at the string (as a parenthesis may indicate a function). So, mark the literal block using the alternate ``FOO`` syntax.
--- include/uapi/linux/firewire-cdev.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
include/uapi/linux/firewire-cdev.h +1 -1
@@ -308,7 +308,7 @@ struct fw_cdev_event_iso_interrupt_mc {/** * struct fw_cdev_event_iso_resource - Iso resources were allocated or freed * @closure: See &fw_cdev_event_common; -* set by %FW_CDEV_IOC_(DE)ALLOCATE_ISO_RESOURCE(_ONCE) ioctl +* set by``FW_CDEV_IOC_(DE)ALLOCATE_ISO_RESOURCE(_ONCE)`` ioctl * @type: %FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED or * %FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED * @handle: Reference by which an allocated resource can be deallocated
Signature · 1 line
2.24.1
PATCH 14/17 infiniband: pa_vnic_encap.h: get rid of a warning
In reply to Mauro Carvalho ChehabThe right markup for a variable is @foo, and not @foo[].
Using a wrong markup caused this warning:
./drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h:243: WARNING: Inline strong start-string without end-string.
--- drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h +1 -1
@@ -239,7 +239,7 @@ struct opa_veswport_mactable_entry {* @offset: mac table starting offset * @num_entries: Number of entries to get or set * @mac_tbl_digest: mac table digest -* @tbl_entries[]: Array of table entries +* @tbl_entries: Array of table entries * * The EM sends down this structure in a MAD indicating * the starting offset in the forwarding table that this
Signature · 1 line
2.24.1
PATCH 8/17 lib: bitmap.c: get rid of some doc warnings
In reply to Mauro Carvalho ChehabThere are two ascii art drawings there. Use a block markup tag there in order to get rid of those warnings:
./lib/bitmap.c:189: WARNING: Unexpected indentation.
./lib/bitmap.c:190: WARNING: Block quote ends without a blank line; unexpected unindent. ./lib/bitmap.c:190: WARNING: Unexpected indentation.
./lib/bitmap.c:191: WARNING: Line block ends without a blank line.
It should be noticed that there's actually a syntax violation right now, as something like:
/** ... @src:
will be handled as a definition for @src parameter, and not as part of a diagram. So, we need to add something before it, in order for this to be processed the way it should.
--- lib/bitmap.c | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-)
lib/bitmap.c +14 -13
@@ -182,21 +182,22 @@ EXPORT_SYMBOL(__bitmap_shift_left);* * In pictures, example for a big-endian 32-bit architecture: * -* @src: -* 31 63 -* | | -* 10000000 11000001 11110010 00010101 10000000 11000001 01110010 00010101 -* | | | | -* 16 14 0 32 +* The @src bitmap is:: * -* if @cut is 3, and @first is 14, bits 14-16 in @src are cut and @dst is: +* 31 63 +* | | +* 10000000 11000001 11110010 00010101 10000000 11000001 01110010 00010101 +* | | | | +* 16 14 0 32 * -* 31 63 -* | | -* 10110000 00011000 00110010 00010101 00010000 00011000 00101110 01000010 -* | | | -* 14 (bit 17 0 32 -* from @src) +* if @cut is 3, and @first is 14, bits 14-16 in @src are cut and @dst is:: +* +* 31 63 +* | | +* 10110000 00011000 00110010 00010101 00010000 00011000 00101110 01000010 +* | | | +* 14 (bit 17 0 32 +* from @src) * * Note that @dst and @src might overlap partially or entirely. *
Signature · 1 line
2.24.1
PATCH 7/17 scripts: kernel-doc: proper handle @foo->bar()
In reply to Mauro Carvalho ChehabThe pattern @foo->bar() is valid, as it can be used by a function pointer inside a struct passed as a parameter.
Right now, it causes a warning:
./drivers/firewire/core-transaction.c:606: WARNING: Inline strong start-string without end-string.
In this specific case, the kernel-doc markup is:
/**
* fw_core_remove_address_handler() - unregister an address handler
* @handler: callback
*
* To be called in process context.
*
* When fw_core_remove_address_handler() returns, @handler->callback() is
* guaranteed to not run on any CPU anymore.
*/
With seems valid on my eyes. So, instead of trying to hack the kernel-doc markup, let's teach it about how to handle such things. This should likely remove lots of other similar warnings as well.
--- scripts/kernel-doc | 2 ++ 1 file changed, 2 insertions(+)
scripts/kernel-doc +2 -0
@@ -214,6 +214,7 @@ my $type_constant2 = '\%([-_\w]+)'; my $type_func = '(\w+)\(\)'; my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)'; my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params +my $type_fp_param2 = '\@(\w+->\S+)\(\)'; # Special RST handling for structs with func ptr params my $type_env = '(\$\w+)'; my $type_enum = '\&(enum\s*([_\w]+))'; my $type_struct = '\&(struct\s*([_\w]+))';
@@ -249,6 +250,7 @@ my @highlights_rst = ( [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"], [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"], [$type_fp_param, "**\$1\\\\(\\\\)**"], + [$type_fp_param2, "**\$1\\\\(\\\\)**"], [$type_func, "\$1()"], [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"], [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
Signature · 1 line
2.24.1
PATCH 9/17 rcu: update.c: get rid of some doc warnings
In reply to Mauro Carvalho ChehabWe need to escape *ret, as otherwise the documentation system thinks that this is an incomplete emphasis block:
./kernel/rcu/update.c:65: WARNING: Inline emphasis start-string without end-string. ./kernel/rcu/update.c:65: WARNING: Inline emphasis start-string without end-string. ./kernel/rcu/update.c:70: WARNING: Inline emphasis start-string without end-string. ./kernel/rcu/update.c:82: WARNING: Inline emphasis start-string without end-string.
--- kernel/rcu/update.c | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
kernel/rcu/update.c +4 -4
@@ -63,12 +63,12 @@ module_param(rcu_normal_after_boot, int, 0);* rcu_read_lock_held_common() - might we be in RCU-sched read-side critical section? * @ret: Best guess answer if lockdep cannot be relied on * -* Returns true if lockdep must be ignored, in which case *ret contains +* Returns true if lockdep must be ignored, in which case ``*ret`` contains * the best guess described below. Otherwise returns false, in which -* case *ret tells the caller nothing and the caller should instead +* case ``*ret`` tells the caller nothing and the caller should instead * consult lockdep. * -* If CONFIG_DEBUG_LOCK_ALLOC is selected, set *ret to nonzero iff in an +* If CONFIG_DEBUG_LOCK_ALLOC is selected, set ``*ret`` to nonzero iff in an * RCU-sched read-side critical section. In absence of * CONFIG_DEBUG_LOCK_ALLOC, this assumes we are in an RCU-sched read-side * critical section unless it can prove otherwise. Note that disabling
@@ -82,7 +82,7 @@ module_param(rcu_normal_after_boot, int, 0);* * Note that if the CPU is in the idle loop from an RCU point of view (ie: * that we are in the section between rcu_idle_enter() and rcu_idle_exit()) -* then rcu_read_lock_held() sets *ret to false even if the CPU did an +* then rcu_read_lock_held() sets ``*ret`` to false even if the CPU did an * rcu_read_lock(). The reason for this is that RCU ignores CPUs that are * in such a section, considering these as in extended quiescent state, * so such a CPU is effectively never in an RCU read-side critical section
Signature · 1 line
2.24.1
PATCH 15/17 ata: libata-core: fix a doc warning
In reply to Mauro Carvalho ChehabThe docs toolchain doesn't recognise this pattern:
@link->[hw_]sata_spd_limit
As it can't really process it. So, instead, let's mark it with a literal block markup:
``link->[hw_]sata_spd_limit``
in order to get rid of the following warning:
./drivers/ata/libata-core.c:5974: WARNING: Unknown target name: "hw".
--- drivers/ata/libata-core.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/ata/libata-core.c +1 -1
@@ -5975,7 +5975,7 @@ void ata_link_init(struct ata_port *ap, struct ata_link *link, int pmp)* sata_link_init_spd - Initialize link->sata_spd_limit * @link: Link to configure sata_spd_limit for * -* Initialize @link->[hw_]sata_spd_limit to the currently +* Initialize ``link->[hw_]sata_spd_limit`` to the currently * configured value. * * LOCKING:
Signature · 1 line
2.24.1
PATCH 16/17 fs: inode.c: get rid of docs warnings
In reply to Mauro Carvalho ChehabUse *foo makes the toolchain to think that this is an emphasis, causing those warnings:
./fs/inode.c:1609: WARNING: Inline emphasis start-string without end-string. ./fs/inode.c:1609: WARNING: Inline emphasis start-string without end-string. ./fs/inode.c:1615: WARNING: Inline emphasis start-string without end-string.
So, use, instead, ``*foo``, in order to mark it as a literal block.
--- fs/inode.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
fs/inode.c +3 -3
@@ -1606,14 +1606,14 @@ EXPORT_SYMBOL(iput);* @inode: inode owning the block number being requested * @block: pointer containing the block to find * -* Replaces the value in *block with the block number on the device holding +* Replaces the value in ``*block`` with the block number on the device holding * corresponding to the requested block number in the file. * That is, asked for block 4 of inode 1 the function will replace the -* 4 in *block, with disk block relative to the disk start that holds that +* 4 in ``*block``, with disk block relative to the disk start that holds that * block of the file. * * Returns -EINVAL in case of error, 0 otherwise. If mapping falls into a -* hole, returns 0 and *block is also set to 0. +* hole, returns 0 and ``*block`` is also set to 0. */ int bmap (struct inode *inode,sector_t *block) {
Signature · 1 line
2.24.1
PATCH 17/17 regulator: driver.h: fix regulator_map_* function names
In reply to Mauro Carvalho ChehabThe toolchain produces a warning on this driver when building the docs:
./include/linux/regulator/driver.h:284: WARNING: Unknown target name: "regulator_regmap_x_voltage".
While fixing it, we notices that there's no function names with the above pattern. It seems that some previous patch renamed it to regulator_map_* instead.
So, change the function name, replacing "x" by "*", with is a more used way to add a wildcard, and escape those with ``literal`` markup, in order to avoid the toolchain to think that this is a link to some existing document chapter.
--- include/linux/regulator/driver.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
include/linux/regulator/driver.h +2 -2
@@ -277,9 +277,9 @@ enum regulator_type {* @curr_table: Current limit mapping table (if table based mapping) * * @vsel_range_reg: Register for range selector when using pickable ranges -* and regulator_regmap_X_voltage_X_pickable functions. +* and ``regulator_map_*_voltage_*_pickable`` functions. * @vsel_range_mask: Mask for register bitfield used for range selector -* @vsel_reg: Register for selector when using regulator_regmap_X_voltage_ +* @vsel_reg: Register for selector when using ``regulator_map_*_voltage_*`` * @vsel_mask: Mask for register bitfield used for selector * @vsel_step: Specify the resolution of selector stepping when setting * voltage. If 0, then no stepping is done (requested selector is
Signature · 1 line
2.24.1
PATCH 5/17 devfreq: devfreq.h: get rid of some doc warnings
In reply to Mauro Carvalho ChehabMark "void *data" as literal, in order to avoid those doc warnings:
./include/linux/devfreq.h:156: WARNING: Inline emphasis start-string without end-string. ./include/linux/devfreq.h:259: WARNING: Inline emphasis start-string without end-string. ./include/linux/devfreq.h:279: WARNING: Inline emphasis start-string without end-string.
--- include/linux/devfreq.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
include/linux/devfreq.h +3 -3
@@ -158,7 +158,7 @@ struct devfreq_stats {* functions except for the context of callbacks defined in struct * devfreq_governor, the governor should protect its access with the * struct mutex lock in struct devfreq. A governor may use this mutex -* to protect its own private data in void *data as well. +* to protect its own private data in ``void *data`` as well. */ struct devfreq {struct list_head node;
@@ -256,7 +256,7 @@ struct devfreq *devfreq_get_devfreq_by_phandle(struct device *dev, int index);#if IS_ENABLED (CONFIG_DEVFREQ_GOV_SIMPLE_ONDEMAND )/** -* struct devfreq_simple_ondemand_data - void *data fed to struct devfreq +* struct devfreq_simple_ondemand_data - ``void *data`` fed to struct devfreq * and devfreq_add_device * @upthreshold: If the load is over this value, the frequency jumps. * Specify 0 to use the default. Valid value = 0 to 100.
@@ -276,7 +276,7 @@ struct devfreq_simple_ondemand_data {#if IS_ENABLED (CONFIG_DEVFREQ_GOV_PASSIVE )/** -* struct devfreq_passive_data - void *data fed to struct devfreq +* struct devfreq_passive_data - ``void *data`` fed to struct devfreq * and devfreq_add_device * @parent: the devfreq instance of parent device. * @get_target_freq: Optional callback, Returns desired operating frequency
Signature · 1 line
2.24.1
PATCH 3/17 docs: pci: boot-interrupts.rst: improve html output
In reply to Mauro Carvalho ChehabThere are some warnings with this file:
/Documentation/PCI/boot-interrupts.rst:42: WARNING: Unexpected indentation. /Documentation/PCI/boot-interrupts.rst:52: WARNING: Block quote ends without a blank line; unexpected unindent. /Documentation/PCI/boot-interrupts.rst:92: WARNING: Unexpected indentation. /Documentation/PCI/boot-interrupts.rst:98: WARNING: Unexpected indentation. /Documentation/PCI/boot-interrupts.rst:136: WARNING: Unexpected indentation.
It turns that this file conversion to ReST could be improved, in order to remove the warnings and provide a better output.
So, fix the warnings by adjusting blank lines, add a table and some list markups. Also, mark endnodes as such.
--- Documentation/PCI/boot-interrupts.rst | 34 +++++++++++++++------------ 1 file changed, 19 insertions(+), 15 deletions(-)
Documentation/PCI/boot-interrupts.rst +19 -15
@@ -32,12 +32,13 @@ interrupt goes unhandled over time, they are tracked by the Linux kernel as Spurious Interrupts. The IRQ will be disabled by the Linux kernel after it reaches a specific count with the error "nobody cared". This disabled IRQ now prevents valid usage by an existing interrupt which may happen to share -the IRQ line. +the IRQ line:: irq 19: nobody cared (try booting with the "irqpoll" option) CPU: 0 PID: 2988 Comm: irq/34-nipalk Tainted: 4.14.87-rt49-02410-g4a640ec-dirty #1 Hardware name: National Instruments NI PXIe-8880/NI PXIe-8880, BIOS 2.1.5f1 01/09/2020 Call Trace: + <IRQ> ? dump_stack+0x46/0x5e ? __report_bad_irq+0x2e/0xb0
@@ -85,15 +86,18 @@ Mitigations The mitigations take the form of PCI quirks. The preference has been to first identify and make use of a means to disable the routing to the PCH. In such a case a quirk to disable boot interrupt generation can be -added.[1] +added. [1]_ - Intel® 6300ESB I/O Controller Hub +Intel® 6300ESB I/O Controller Hub Alternate Base Address Register: BIE: Boot Interrupt Enable - 0 = Boot interrupt is enabled. - 1 = Boot interrupt is disabled. - Intel® Sandy Bridge through Sky Lake based Xeon servers: + == =========================== + 0 Boot interrupt is enabled. + 1 Boot interrupt is disabled. + == =========================== + +Intel® Sandy Bridge through Sky Lake based Xeon servers: Coherent Interface Protocol Interrupt Control dis_intx_route2pch/dis_intx_route2ich/dis_intx_route2dmi2: When this bit is set. Local INTx messages received from the
@@ -109,12 +113,12 @@ line by default. Therefore, on chipsets where this INTx routing cannot be disabled, the Linux kernel will reroute the valid interrupt to its legacy interrupt. This redirection of the handler will prevent the occurrence of the spurious interrupt detection which would ordinarily disable the IRQ -line due to excessive unhandled counts.[2] +line due to excessive unhandled counts. [2]_ The config option X86_REROUTE_FOR_BROKEN_BOOT_IRQS exists to enable (or disable) the redirection of the interrupt handler to the PCH interrupt line. The option can be overridden by either pci=ioapicreroute or -pci=noioapicreroute.[3] +pci=noioapicreroute. [3]_ More Documentation
@@ -127,19 +131,19 @@ into the evolution of its handling with chipsets. Example of disabling of the boot interrupt ------------------------------------------ -Intel® 6300ESB I/O Controller Hub (Document # 300641-004US) + - Intel® 6300ESB I/O Controller Hub (Document # 300641-004US) 5.7.3 Boot Interrupt https://www.intel.com/content/dam/doc/datasheet/6300esb-io-controller-hub-datasheet.pdf -Intel® Xeon® Processor E5-1600/2400/2600/4600 v3 Product Families -Datasheet - Volume 2: Registers (Document # 330784-003) + - Intel® Xeon® Processor E5-1600/2400/2600/4600 v3 Product Families + Datasheet - Volume 2: Registers (Document # 330784-003) 6.6.41 cipintrc Coherent Interface Protocol Interrupt Control https://www.intel.com/content/dam/www/public/us/en/documents/datasheets/xeon-e5-v3-datasheet-vol-2.pdf Example of handler rerouting ---------------------------- -Intel® 6700PXH 64-bit PCI Hub (Document # 302628) + - Intel® 6700PXH 64-bit PCI Hub (Document # 302628) 2.15.2 PCI Express Legacy INTx Support and Boot Interrupt https://www.intel.com/content/dam/doc/datasheet/6700pxh-64-bit-pci-hub-datasheet.pdf
@@ -150,6 +154,6 @@ Cheers, Sean V Kelley [email protected] -[1] https://lore.kernel.org/r/[email protected]/ -[2] https://lore.kernel.org/r/[email protected]/ -[3] https://lore.kernel.org/r/[email protected]/ +.. [1] https://lore.kernel.org/r/[email protected]/ +.. [2] https://lore.kernel.org/r/[email protected]/ +.. [3] https://lore.kernel.org/r/[email protected]/
Signature · 1 line
2.24.1
PATCH 10/17 net: phy: sfp-bus.c: get rid of docs warnings
In reply to Mauro Carvalho ChehabThe indentation for the returned values are weird, causing those warnings:
./drivers/net/phy/sfp-bus.c:579: WARNING: Unexpected indentation. ./drivers/net/phy/sfp-bus.c:619: WARNING: Unexpected indentation.
Use a list and change the identation for it to be properly parsed by the documentation toolchain.
--- drivers/net/phy/sfp-bus.c | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-)
drivers/net/phy/sfp-bus.c +18 -14
@@ -572,13 +572,15 @@ static void sfp_upstream_clear(struct sfp_bus *bus)* the sfp_bus structure, incrementing its reference count. This must * be put via sfp_bus_put() when done. * -* Returns: on success, a pointer to the sfp_bus structure, -* %NULL if no SFP is specified, -* on failure, an error pointer value: -* corresponding to the errors detailed for -* fwnode_property_get_reference_args(). -* %-ENOMEM if we failed to allocate the bus. -* an error from the upstream's connect_phy() method. +* Returns: +* - on success, a pointer to the sfp_bus structure, +* - %NULL if no SFP is specified, +* - on failure, an error pointer value: +* +* - corresponding to the errors detailed for +* fwnode_property_get_reference_args(). +* - %-ENOMEM if we failed to allocate the bus. +* - an error from the upstream's connect_phy() method. */ struct sfp_bus *sfp_bus_find_fwnode (struct fwnode_handle *fwnode) {
@@ -612,13 +614,15 @@ EXPORT_SYMBOL_GPL(sfp_bus_find_fwnode);* the SFP bus using sfp_register_upstream(). This takes a reference on the * bus, so it is safe to put the bus after this call. * -* Returns: on success, a pointer to the sfp_bus structure, -* %NULL if no SFP is specified, -* on failure, an error pointer value: -* corresponding to the errors detailed for -* fwnode_property_get_reference_args(). -* %-ENOMEM if we failed to allocate the bus. -* an error from the upstream's connect_phy() method. +* Returns: +* - on success, a pointer to the sfp_bus structure, +* - %NULL if no SFP is specified, +* - on failure, an error pointer value: +* +* - corresponding to the errors detailed for +* fwnode_property_get_reference_args(). +* - %-ENOMEM if we failed to allocate the bus. +* - an error from the upstream's connect_phy() method. */ int sfp_bus_add_upstream (struct sfp_bus *bus,void *upstream,const struct sfp_upstream_ops *ops)
Signature · 1 line
2.24.1
PATCH 12/17 gpio: gpiolib.c: fix a doc warning
In reply to Mauro Carvalho ChehabUse a different markup for the ERR_PTR, as %FOO doesn't work if there are parenthesis. So, use, instead:
``ERR_PTR(-EINVAL)``
This fixes the following warning:
./drivers/gpio/gpiolib.c:139: WARNING: Inline literal start-string without end-string.
--- drivers/gpio/gpiolib.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/gpio/gpiolib.c +1 -1
@@ -136,7 +136,7 @@ EXPORT_SYMBOL_GPL(gpio_to_desc);* @hwnum: hardware number of the GPIO for this chip * * Returns: -* A pointer to the GPIO descriptor or %ERR_PTR(-EINVAL) if no GPIO exists +* A pointer to the GPIO descriptor or ``ERR_PTR(-EINVAL)`` if no GPIO exists * in the given chip for the specified hardware number. */ struct gpio_desc *gpiochip_get_desc(struct gpio_chip *chip,
Signature · 1 line
2.24.1
PATCH 11/17 net: core: dev.c: fix a documentation warning
In reply to Mauro Carvalho ChehabThere's a markup for link with is "foo_". On this kernel-doc comment, we don't want this, but instead, place a literal reference. So, escape the literal with ``foo``, in order to avoid this warning:
./net/core/dev.c:5195: WARNING: Unknown target name: "page_is".
--- net/core/dev.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
net/core/dev.c +1 -1
@@ -5195,7 +5195,7 @@ static int __netif_receive_skb_one_core(struct sk_buff *skb, bool pfmemalloc)* * More direct receive version of netif_receive_skb(). It should * only be used by callers that have a need to skip RPS and Generic XDP. -* Caller must also take care of handling if (page_is_)pfmemalloc. +* Caller must also take care of handling if ``(page_is_)pfmemalloc``. * * This function may only be called from softirq context and interrupts * should be enabled.
Signature · 1 line
2.24.1
PATCH 4/17 kernel: futex.c: get rid of a docs build warning
In reply to Mauro Carvalho ChehabAdjust whitespaces and blank lines in order to get rid of this:
./kernel/futex.c:491: WARNING: Definition list ends without a blank line; unexpected unindent.
--- kernel/futex.c | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
kernel/futex.c +2 -1
@@ -486,7 +486,8 @@ static u64 get_inode_sequence_number(struct inode *inode)* The key words are stored in @key on success. * * For shared mappings (when @fshared), the key is: -* ( inode->i_sequence, page->index, offset_within_page ) +* ( inode->i_sequence, page->index, offset_within_page ) +* * [ also see get_inode_sequence_number() ] * * For private mappings (or when !@fshared), the key is:
Signature · 1 line
2.24.1
Re: [PATCH 13/17] i2c: include/linux/i2c.h: fix a doc warning
In reply to Mauro Carvalho ChehabQuoted 6 lines · Mauro Carvalho Chehab
Don't let non-letters inside a literal block without escaping it, as the toolchain would mis-interpret it:
./include/linux/i2c.h:518: WARNING: Inline strong start-string without end-string.Signed-off-by Mauro Carvalho Chehab <[email protected]>
Shall I take this via I2C?
If not:
Re: [PATCH 13/17] i2c: include/linux/i2c.h: fix a doc warning
Em Tue, 17 Mar 2020 16:03:22 +0100
Wolfram Sang <[email protected]> escreveu:
Quoted 9 lines · Mauro Carvalho Chehab
Quoted 6 lines
Don't let non-letters inside a literal block without escaping it, as the toolchain would mis-interpret it:
./include/linux/i2c.h:518: WARNING: Inline strong start-string without end-string.Signed-off-by Mauro Carvalho Chehab <[email protected]>Shall I take this via I2C?
Yeah, feel free to pick it. The patches on this series are pretty much independent from the others.
Thanks,
Mauro
Re: [PATCH 09/17] rcu: update.c: get rid of some doc warnings
In reply to Mauro Carvalho ChehabQuoted 9 lines · Mauro Carvalho Chehab
We need to escape *ret, as otherwise the documentation system thinks that this is an incomplete emphasis block:
./kernel/rcu/update.c:65: WARNING: Inline emphasis start-string without end-string../kernel/rcu/update.c:65: WARNING: Inline emphasis start-string without end-string../kernel/rcu/update.c:70: WARNING: Inline emphasis start-string without end-string../kernel/rcu/update.c:82: WARNING: Inline emphasis start-string without end-string.Signed-off-by Mauro Carvalho Chehab <[email protected]>
Applied, thank you!
Thanx, Paul
Quoted 36 lines
--- kernel/rcu/update.c | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)kernel/rcu/update.c +4
-4@@ -63,12 +63,12 @@ module_param(rcu_normal_after_boot, int, 0);* rcu_read_lock_held_common() - might we be in RCU-sched read-side critical section? * @ret: Best guess answer if lockdep cannot be relied on * -* Returns true if lockdep must be ignored, in which case *ret contains +* Returns true if lockdep must be ignored, in which case ``*ret`` contains * the best guess described below. Otherwise returns false, in which -* case *ret tells the caller nothing and the caller should instead +* case ``*ret`` tells the caller nothing and the caller should instead * consult lockdep. * -* If CONFIG_DEBUG_LOCK_ALLOC is selected, set *ret to nonzero iff in an +* If CONFIG_DEBUG_LOCK_ALLOC is selected, set ``*ret`` to nonzero iff in an * RCU-sched read-side critical section. In absence of * CONFIG_DEBUG_LOCK_ALLOC, this assumes we are in an RCU-sched read-side * critical section unless it can prove otherwise. Note that disabling @@ -82,7 +82,7 @@ module_param(rcu_normal_after_boot, int, 0);* * Note that if the CPU is in the idle loop from an RCU point of view (ie: * that we are in the section between rcu_idle_enter() and rcu_idle_exit()) -* then rcu_read_lock_held() sets *ret to false even if the CPU did an +* then rcu_read_lock_held() sets ``*ret`` to false even if the CPU did an * rcu_read_lock(). The reason for this is that RCU ignores CPUs that are * in such a section, considering these as in extended quiescent state, * so such a CPU is effectively never in an RCU read-side critical section Signature · 1 line
2.24.1
Re: [PATCH 04/17] kernel: futex.c: get rid of a docs build warning
In reply to Mauro Carvalho ChehabQuoted 14 lines · Mauro Carvalho Chehab
Adjust whitespaces and blank lines in order to get rid of this:
./kernel/futex.c:491: WARNING: Definition list ends without a blank line; unexpected unindent.Signed-off-by Mauro Carvalho Chehab <[email protected]>--- kernel/futex.c | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)kernel/futex.c +0
-0
kernel/futex.c static u64 get_inode_sequence_number(struct inode *inode) · line 490
Quoted 6 lines
kernel/futex.c +2
-1@@ -486,7 +486,8 @@ static u64 get_inode_sequence_number(struct inode *inode)* The key words are stored in @key on success. * * For shared mappings (when @fshared), the key is: -* ( inode->i_sequence, page->index, offset_within_page ) +* ( inode->i_sequence, page->index, offset_within_page ) +*
WTH, that's less readable.
Quoted 6 lines
kernel/futex.c +0
-0* [ also see get_inode_sequence_number() ] * * For private mappings (or when !@fshared), the key is: Signature · 1 line
2.24.1
Re: [PATCH 06/17] firewire: firewire-cdev.hL get rid of a docs warning
In reply to Mauro Carvalho ChehabQuoted 9 lines · On Mar 17 Mauro Carvalho Chehab wrote:
This warning:
./include/uapi/linux/firewire-cdev.h:312: WARNING: Inline literal start-string without end-string.is because %FOO doesn't work if there's a parenthesis at the string (as a parenthesis may indicate a function). So, mark the literal block using the alternate ``FOO`` syntax.
Signed-off-by Mauro Carvalho Chehab <[email protected]>
I figure this is meant to go through the Documentation tree, hence
But if I am to apply it, give me a note.
Quoted 17 lines
--- include/uapi/linux/firewire-cdev.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)include/uapi/linux/firewire-cdev.h +1
-1@@ -308,7 +308,7 @@ struct fw_cdev_event_iso_interrupt_mc {/** * struct fw_cdev_event_iso_resource - Iso resources were allocated or freed * @closure: See &fw_cdev_event_common; -* set by %FW_CDEV_IOC_(DE)ALLOCATE_ISO_RESOURCE(_ONCE) ioctl +* set by``FW_CDEV_IOC_(DE)ALLOCATE_ISO_RESOURCE(_ONCE)`` ioctl * @type: %FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED or * %FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED * @handle: Reference by which an allocated resource can be deallocated
Signature · 3 lines
Stefan Richter -======--=-- --== =---= http://arcgraph.de/sr/
Jonathan Corbet
maintainerRe: [PATCH 04/17] kernel: futex.c: get rid of a docs build warning
In reply to Peter ZijlstraQuoted 10 lines · On Tue, 17 Mar 2020 17:58:05 +0100 Peter Zijlstra <[email protected]> wrote:
Quoted 9 lines · Mauro Carvalho Chehab
Adjust whitespaces and blank lines in order to get rid of this:
./kernel/futex.c:491: WARNING: Definition list ends without a blank line; unexpected unindent.Signed-off-by Mauro Carvalho Chehab <[email protected]>--- kernel/futex.c | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
Quoted 13 lines
kernel/futex.c static u64 get_inode_sequence_number(struct inode *inode) · line 490
Quoted 11 lines
kernel/futex.c +2
-1@@ -486,7 +486,8 @@ static u64 get_inode_sequence_number(struct inode *inode)* The key words are stored in @key on success. * * For shared mappings (when @fshared), the key is: -* ( inode->i_sequence, page->index, offset_within_page ) +* ( inode->i_sequence, page->index, offset_within_page ) +* WTH, that's less readable.
It won't render well in the build either; that should be a literal block.
jon
Re: [PATCH 04/17] kernel: futex.c: get rid of a docs build warning
Quoted 27 lines · Jonathan Corbet
Quoted 10 lines · On Tue, 17 Mar 2020 17:58:05 +0100 Peter Zijlstra <[email protected]> wrote:
Quoted 9 lines · Mauro Carvalho Chehab
Adjust whitespaces and blank lines in order to get rid of this:
./kernel/futex.c:491: WARNING: Definition list ends without a blank line; unexpected unindent.Signed-off-by Mauro Carvalho Chehab <[email protected]>--- kernel/futex.c | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)Quoted 13 lines
kernel/futex.c static u64 get_inode_sequence_number(struct inode *inode) · line 490
Quoted 11 lines
kernel/futex.c +2
-1@@ -486,7 +486,8 @@ static u64 get_inode_sequence_number(struct inode *inode)* The key words are stored in @key on success. * * For shared mappings (when @fshared), the key is: -* ( inode->i_sequence, page->index, offset_within_page ) +* ( inode->i_sequence, page->index, offset_within_page ) +* WTH, that's less readable.
Quoted 1 line
It won't render well in the build either; that should be a literal block.
it renders perfectly in an ASCII text editor, which is by far the most important interface for all this.
Re: [PATCH 03/17] docs: pci: boot-interrupts.rst: improve html output
In reply to Mauro Carvalho ChehabQuoted 8 lines · Mauro Carvalho Chehab
There are some warnings with this file:
/Documentation/PCI/boot-interrupts.rst:42: WARNING: Unexpected indentation. /Documentation/PCI/boot-interrupts.rst:52: WARNING: Block quote ends without a blank line; unexpected unindent. /Documentation/PCI/boot-interrupts.rst:92: WARNING: Unexpected indentation. /Documentation/PCI/boot-interrupts.rst:98: WARNING: Unexpected indentation. /Documentation/PCI/boot-interrupts.rst:136: WARNING: Unexpected indentation.
Quoted 7 lines
It turns that this file conversion to ReST could be improved, in order to remove the warnings and provide a better output.
So, fix the warnings by adjusting blank lines, add a table and some list markups. Also, mark endnodes as such.
Signed-off-by Mauro Carvalho Chehab <[email protected]>
Quoted 99 lines
--- Documentation/PCI/boot-interrupts.rst | 34 +++++++++++++++------------ 1 file changed, 19 insertions(+), 15 deletions(-)Documentation/PCI/boot-interrupts.rst +19
-15@@ -32,12 +32,13 @@ interrupt goes unhandled over time, they are tracked by the Linux kernel as Spurious Interrupts. The IRQ will be disabled by the Linux kernel after it reaches a specific count with the error "nobody cared". This disabled IRQ now prevents valid usage by an existing interrupt which may happen to share -the IRQ line. +the IRQ line:: irq 19: nobody cared (try booting with the "irqpoll" option) CPU: 0 PID: 2988 Comm: irq/34-nipalk Tainted: 4.14.87-rt49-02410-g4a640ec-dirty #1 Hardware name: National Instruments NI PXIe-8880/NI PXIe-8880, BIOS 2.1.5f1 01/09/2020 Call Trace: + <IRQ> ? dump_stack+0x46/0x5e ? __report_bad_irq+0x2e/0xb0@@ -85,15 +86,18 @@ Mitigations The mitigations take the form of PCI quirks. The preference has been to first identify and make use of a means to disable the routing to the PCH. In such a case a quirk to disable boot interrupt generation can be -added.[1] +added. [1]_ - Intel® 6300ESB I/O Controller Hub +Intel® 6300ESB I/O Controller Hub Alternate Base Address Register: BIE: Boot Interrupt Enable - 0 = Boot interrupt is enabled. - 1 = Boot interrupt is disabled. - Intel® Sandy Bridge through Sky Lake based Xeon servers: + == =========================== + 0 Boot interrupt is enabled. + 1 Boot interrupt is disabled. + == =========================== + +Intel® Sandy Bridge through Sky Lake based Xeon servers: Coherent Interface Protocol Interrupt Control dis_intx_route2pch/dis_intx_route2ich/dis_intx_route2dmi2: When this bit is set. Local INTx messages received from the@@ -109,12 +113,12 @@ line by default. Therefore, on chipsets where this INTx routing cannot be disabled, the Linux kernel will reroute the valid interrupt to its legacy interrupt. This redirection of the handler will prevent the occurrence of the spurious interrupt detection which would ordinarily disable the IRQ -line due to excessive unhandled counts.[2] +line due to excessive unhandled counts. [2]_ The config option X86_REROUTE_FOR_BROKEN_BOOT_IRQS exists to enable (or disable) the redirection of the interrupt handler to the PCH interrupt line. The option can be overridden by either pci=ioapicreroute or -pci=noioapicreroute.[3] +pci=noioapicreroute. [3]_ More Documentation@@ -127,19 +131,19 @@ into the evolution of its handling with chipsets. Example of disabling of the boot interrupt ------------------------------------------ -Intel® 6300ESB I/O Controller Hub (Document # 300641-004US) + - Intel® 6300ESB I/O Controller Hub (Document # 300641-004US) 5.7.3 Boot Interrupt https://www.intel.com/content/dam/doc/datasheet/6300esb-io-controller-hub-datasheet.pdf -Intel® Xeon® Processor E5-1600/2400/2600/4600 v3 Product Families -Datasheet - Volume 2: Registers (Document # 330784-003) + - Intel® Xeon® Processor E5-1600/2400/2600/4600 v3 Product Families + Datasheet - Volume 2: Registers (Document # 330784-003) 6.6.41 cipintrc Coherent Interface Protocol Interrupt Control https://www.intel.com/content/dam/www/public/us/en/documents/datasheets/xeon-e5-v3-datasheet-vol-2.pdf Example of handler rerouting ---------------------------- -Intel® 6700PXH 64-bit PCI Hub (Document # 302628) + - Intel® 6700PXH 64-bit PCI Hub (Document # 302628) 2.15.2 PCI Express Legacy INTx Support and Boot Interrupt https://www.intel.com/content/dam/doc/datasheet/6700pxh-64-bit-pci-hub-datasheet.pdf@@ -150,6 +154,6 @@ Cheers, Sean V Kelley [email protected] -[1] https://lore.kernel.org/r/[email protected]/ -[2] https://lore.kernel.org/r/[email protected]/ -[3] https://lore.kernel.org/r/[email protected]/ +.. [1] https://lore.kernel.org/r/[email protected]/ +.. [2] https://lore.kernel.org/r/[email protected]/ +.. [3] https://lore.kernel.org/r/[email protected]/Signature · 1 line
2.24.1
Re: [PATCH 05/17] devfreq: devfreq.h: get rid of some doc warnings
In reply to Mauro Carvalho ChehabQuoted 35 lines · Mauro Carvalho Chehab
Mark "void *data" as literal, in order to avoid those doc warnings:
./include/linux/devfreq.h:156: WARNING: Inline emphasis start-string without end-string../include/linux/devfreq.h:259: WARNING: Inline emphasis start-string without end-string../include/linux/devfreq.h:279: WARNING: Inline emphasis start-string without end-string.Signed-off-by Mauro Carvalho Chehab <[email protected]>--- include/linux/devfreq.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)include/linux/devfreq.h +2
-2@@ -158,7 +158,7 @@ struct devfreq_stats {* functions except for the context of callbacks defined in struct * devfreq_governor, the governor should protect its access with the * struct mutex lock in struct devfreq. A governor may use this mutex -* to protect its own private data in void *data as well. +* to protect its own private data in ``void *data`` as well. */ struct devfreq {struct list_head node;@@ -256,7 +256,7 @@ struct devfreq *devfreq_get_devfreq_by_phandle(struct device *dev, int index);#if IS_ENABLED (CONFIG_DEVFREQ_GOV_SIMPLE_ONDEMAND )/** -* struct devfreq_simple_ondemand_data - void *data fed to struct devfreq +* struct devfreq_simple_ondemand_data - ``void *data`` fed to struct devfreq * and devfreq_add_device * @upthreshold: If the load is over this value, the frequency jumps. * Specify 0 to use the default. Valid value = 0 to 100.
include/linux/devfreq.h struct devfreq_simple_ondemand_data { · line 282
Quoted 8 lines
include/linux/devfreq.h +1
-1@@ -276,7 +276,7 @@ struct devfreq_simple_ondemand_data {#if IS_ENABLED (CONFIG_DEVFREQ_GOV_PASSIVE )/** -* struct devfreq_passive_data - void *data fed to struct devfreq +* struct devfreq_passive_data - ``void *data`` fed to struct devfreq * and devfreq_add_device * @parent: the devfreq instance of parent device. * @get_target_freq: Optional callback, Returns desired operating frequency
Applied it. Thanks.
Signature · 3 lines
Best Regards, Chanwoo Choi Samsung Electronics
Re: [PATCH 10/17] net: phy: sfp-bus.c: get rid of docs warnings
In reply to Mauro Carvalho ChehabFrom: Mauro Carvalho Chehab <[email protected]>
Date: Tue, 17 Mar 2020 15:54:19 +0100
Quoted 10 lines
The indentation for the returned values are weird, causing those warnings:
./drivers/net/phy/sfp-bus.c:579: WARNING: Unexpected indentation../drivers/net/phy/sfp-bus.c:619: WARNING: Unexpected indentation.Use a list and change the identation for it to be properly parsed by the documentation toolchain.
Signed-off-by Mauro Carvalho Chehab <[email protected]>
Applied.
Re: [PATCH 11/17] net: core: dev.c: fix a documentation warning
In reply to Mauro Carvalho ChehabFrom: Mauro Carvalho Chehab <[email protected]>
Date: Tue, 17 Mar 2020 15:54:20 +0100
Quoted 8 lines
There's a markup for link with is "
foo_". On this kernel-doc comment, we don't want this, but instead, place a literal reference. So, escape the literal with ``foo``, in order to avoid this warning:./net/core/dev.c:5195: WARNING: Unknown target name: "page_is".Signed-off-by Mauro Carvalho Chehab <[email protected]>
Applied.
Re: [PATCH 12/17] gpio: gpiolib.c: fix a doc warning
In reply to Mauro Carvalho Chehabwt., 17 mar 2020 o 15:54 Mauro Carvalho Chehab
<[email protected]> napisał(a):
Quoted 29 lines
Use a different markup for the
ERR_PTR, as %FOO doesn't work if there are parenthesis. So, use, instead:``ERR_PTR(-EINVAL)``This fixes the following warning:
./drivers/gpio/gpiolib.c:139: WARNING: Inline literal start-string without end-string.Signed-off-by Mauro Carvalho Chehab <[email protected]>--- drivers/gpio/gpiolib.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)drivers/gpio/gpiolib.c +1
-2@@ -136,7 +136,7 @@ EXPORT_SYMBOL_GPL(gpio_to_desc);* @hwnum: hardware number of the GPIO for this chip * * Returns: -* A pointer to the GPIO descriptor or %ERR_PTR(-EINVAL) if no GPIO exists +* A pointer to the GPIO descriptor or ``ERR_PTR(-EINVAL)`` if no GPIO exists * in the given chip for the specified hardware number. */ struct gpio_desc *gpiochip_get_desc(struct gpio_chip *chip, --
Quoted 2 lines
2.24.1
Mark Brown
maintainerApplied "regulator: driver.h: fix regulator_map_* function names" to the regulator tree
In reply to Mauro Carvalho ChehabThe patch
regulator: driver.h: fix regulator_map_* function names
has been applied to the regulator tree at
https://git.kernel.org/pub/scm/linux/kernel/git/broonie/regulator.git
All being well this means that it will be integrated into the linux-next tree (usually sometime in the next 24 hours) and sent to Linus during the next merge window (or sooner if it is a bug fix), however if problems are discovered then the patch may be dropped or reverted.
You may get further e-mails resulting from automated or manual testing and review of the tree, please engage with people reporting problems and send followup patches addressing any issues that are reported if needed.
If any updates are required or you are submitting further changes they should be sent as incremental updates against current git, existing patches will not be replaced.
Please add any relevant lists and maintainers to the CCs when replying to this mail.
Thanks,
Mark
From bd3ebed9304acd2ccddde44675fedf963dbfdc71 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab <[email protected]>
Date: Tue, 17 Mar 2020 15:54:26 +0100
Subject: [PATCH] regulator: driver.h: fix regulator_map_* function names
The toolchain produces a warning on this driver when building the docs:
./include/linux/regulator/driver.h:284: WARNING: Unknown target name: "regulator_regmap_x_voltage".
While fixing it, we notices that there's no function names with the above pattern. It seems that some previous patch renamed it to regulator_map_* instead.
So, change the function name, replacing "x" by "*", with is a more used way to add a wildcard, and escape those with ``literal`` markup, in order to avoid the toolchain to think that this is a link to some existing document chapter.
--- include/linux/regulator/driver.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
include/linux/regulator/driver.h +2 -2
@@ -277,9 +277,9 @@ enum regulator_type {* @curr_table: Current limit mapping table (if table based mapping) * * @vsel_range_reg: Register for range selector when using pickable ranges -* and regulator_regmap_X_voltage_X_pickable functions. +* and ``regulator_map_*_voltage_*_pickable`` functions. * @vsel_range_mask: Mask for register bitfield used for range selector -* @vsel_reg: Register for selector when using regulator_regmap_X_voltage_ +* @vsel_reg: Register for selector when using ``regulator_map_*_voltage_*`` * @vsel_mask: Mask for register bitfield used for selector * @vsel_step: Specify the resolution of selector stepping when setting * voltage. If 0, then no stepping is done (requested selector is
Signature · 1 line
2.20.1
Re: [PATCH 14/17] infiniband: pa_vnic_encap.h: get rid of a warning
In reply to Mauro Carvalho ChehabQuoted 10 lines · Mauro Carvalho Chehab
The right markup for a variable is @foo, and not @foo[].
Using a wrong markup caused this warning:
./drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h:243: WARNING: Inline strong start-string without end-string.Signed-off-by Mauro Carvalho Chehab <[email protected]>--- drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Do you want this to go to the RDMA tree? I wasn't cc'd on the cover letter
Otherwise
Thanks,
Jason
Re: [PATCH 04/17] kernel: futex.c: get rid of a docs build warning
In reply to Mauro Carvalho ChehabMauro Carvalho Chehab <[email protected]> writes:
The subject prefix for this is: 'futex:'
Quoted 14 lines
Adjust whitespaces and blank lines in order to get rid of this:
./kernel/futex.c:491: WARNING: Definition list ends without a blank line; unexpected unindent.Signed-off-by Mauro Carvalho Chehab <[email protected]>--- kernel/futex.c | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)kernel/futex.c +0
-0
kernel/futex.c static u64 get_inode_sequence_number(struct inode *inode) · line 489
Quoted 5 lines
kernel/futex.c +1
-1@@ -486,7 +486,8 @@ static u64 get_inode_sequence_number(struct inode *inode)* The key words are stored in @key on success. * * For shared mappings (when @fshared), the key is: -* ( inode->i_sequence, page->index, offset_within_page ) +* ( inode->i_sequence, page->index, offset_within_page )
Sigh. Is there no better way to make this look sane both in the file and in the docs?
Thanks,
tglx
Jonathan Corbet
maintainerRe: [PATCH 04/17] kernel: futex.c: get rid of a docs build warning
Quoted 6 lines · On Fri, 20 Mar 2020 16:28:23 +0100 Thomas Gleixner <[email protected]> wrote:
Quoted 3 lines
* For shared mappings (when @fshared), the key is:
- * (inode->i_sequence,page->index,offset_within_page)
+ * (inode->i_sequence,page->index,offset_within_page)Sigh. Is there no better way to make this look sane both in the file and in the docs?
I'd do:
* For shared mappings (when @fshared), the key is::
*
* ( inode->i_sequence, page->index, offset_within_page )
*
jon
Re: [PATCH 04/17] kernel: futex.c: get rid of a docs build warning
In reply to Thomas GleixnerEm Fri, 20 Mar 2020 16:28:23 +0100
Thomas Gleixner <[email protected]> escreveu:
Quoted 3 lines
Mauro Carvalho Chehab <[email protected]> writes:
The subject prefix for this is: 'futex:'
Ok!
Quoted 10 lines
Quoted 10 lines
Adjust whitespaces and blank lines in order to get rid of this:
./kernel/futex.c:491: WARNING: Definition list ends without a blank line; unexpected unindent.Signed-off-by Mauro Carvalho Chehab <[email protected]>--- kernel/futex.c | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
Quoted 13 lines
kernel/futex.c static u64 get_inode_sequence_number(struct inode *inode) · line 489
Quoted 10 lines
kernel/futex.c +1
-1@@ -486,7 +486,8 @@ static u64 get_inode_sequence_number(struct inode *inode)* The key words are stored in @key on success. * * For shared mappings (when @fshared), the key is: -* ( inode->i_sequence, page->index, offset_within_page ) +* ( inode->i_sequence, page->index, offset_within_page ) Sigh. Is there no better way to make this look sane both in the file and in the docs?
The enclosed patch would do the trick.
I noticed another problem on it, however: "!@fshared" is not properly parsed by kernel-docs. It basically converts it to "!**fshared**", with is not what we want.
IMHO, this specific case should be handled by kernel-doc script. I'll write a patch addressing this issue.
Regards,
Mauro
---
[PATCH 04/17 v2] kernel: futex: get rid of a docs build warning
Adjust whitespaces and blank lines in order to get rid of this:
./kernel/futex.c:491: WARNING: Definition list ends without a blank line; unexpected unindent.
kernel/futex.c +3 -0
@@ -486,10 +486,13 @@ static u64 get_inode_sequence_number(struct inode *inode)* The key words are stored in @key on success. * * For shared mappings (when @fshared), the key is: +* * ( inode->i_sequence, page->index, offset_within_page ) +* * [ also see get_inode_sequence_number() ] * * For private mappings (or when !@fshared), the key is: +* * ( current->mm, address, 0 ) * * This allows (cross process, where applicable) identification of the futex
Wolfram Sang
AppliedRe: [PATCH 13/17] i2c: include/linux/i2c.h: fix a doc warning
In reply to Mauro Carvalho ChehabQuoted 6 lines · Mauro Carvalho Chehab
Don't let non-letters inside a literal block without escaping it, as the toolchain would mis-interpret it:
./include/linux/i2c.h:518: WARNING: Inline strong start-string without end-string.Signed-off-by Mauro Carvalho Chehab <[email protected]>
Applied to for-current, thanks!
Re: [PATCH 04/17] kernel: futex.c: get rid of a docs build warning
In reply to Mauro Carvalho ChehabQuoted 13 lines · Mauro Carvalho Chehab
Em Fri, 20 Mar 2020 16:28:23 +0100
Thomas Gleixner <[email protected]> escreveu:Quoted 3 lines
Mauro Carvalho Chehab <[email protected]> writes:
The subject prefix for this is: 'futex:'
Ok!
Quoted 4 lines
Quoted 3 lines
* For shared mappings (when @fshared), the key is:
- * (inode->i_sequence,page->index,offset_within_page)
+ * (inode->i_sequence,page->index,offset_within_page)
Quoted 7 lines
Quoted 2 lines
Sigh. Is there no better way to make this look sane both in the file and in the docs?
The enclosed patch would do the trick.
[PATCH 04/17 v2] kernel: futex: get rid of a docs build warning
The prefix is still wrong. See above.
git log --oneline $FILE usually gives you a pretty good hint.
Thanks,
tglx
Re: [PATCH 12/17] gpio: gpiolib.c: fix a doc warning
In reply to Mauro Carvalho ChehabQuoted 10 lines · Mauro Carvalho Chehab
Use a different markup for the
ERR_PTR, as %FOO doesn't work if there are parenthesis. So, use, instead:``ERR_PTR(-EINVAL)``This fixes the following warning:
./drivers/gpio/gpiolib.c:139: WARNING: Inline literal start-string without end-string.Signed-off-by Mauro Carvalho Chehab <[email protected]>
Mauro are you merging this or do you want me to merge it?
Yours,
Linus Walleij
Re: [PATCH 12/17] gpio: gpiolib.c: fix a doc warning
Em Fri, 27 Mar 2020 11:22:52 +0100
Linus Walleij <[email protected]> escreveu:
Quoted 10 lines
Quoted 7 lines · Mauro Carvalho Chehab
Use a different markup for the
ERR_PTR, as %FOO doesn't work if there are parenthesis. So, use, instead:``ERR_PTR(-EINVAL)``This fixes the following warning:
Quoted 7 lines
Quoted 3 lines
./drivers/gpio/gpiolib.c:139: WARNING: Inline literal start-string without end-string.Signed-off-by Mauro Carvalho Chehab <[email protected]>Reviewed-by Linus Walleij <[email protected]>Mauro are you merging this or do you want me to merge it?
Feel free to merge it.
My plan is to rebase my trees after the merge window, re-sending anything that got missed for them to be either applied directly or via the docs tree.
Thanks,
Mauro
Re: [PATCH 14/17] infiniband: pa_vnic_encap.h: get rid of a warning
In reply to Jason GunthorpeEm Wed, 18 Mar 2020 21:36:45 -0300
Jason Gunthorpe <[email protected]> escreveu:
Quoted 7 lines · Mauro Carvalho Chehab
Quoted 6 lines
The right markup for a variable is @foo, and not @foo[].
Using a wrong markup caused this warning:
./drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h:243: WARNING: Inline strong start-string without end-string.
Quoted 7 lines
Quoted 4 lines
Signed-off-by Mauro Carvalho Chehab <[email protected]>--- drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Do you want this to go to the RDMA tree? I wasn't cc'd on the cover letter
Sorry for not answering earlier. Got sidetracked with other things.
Yeah, if there are still time, feel free to pick it. Otherwise, I'll likely send again after the merge window, to be applied either by you or via the docs tree.
Quoted 7 lines
Otherwise
Acked-by Jason Gunthorpe <[email protected]>Thanks,
Jason
Thanks,
Mauro
Re: [PATCH 14/17] infiniband: pa_vnic_encap.h: get rid of a warning
Quoted 14 lines · Mauro Carvalho Chehab
Em Wed, 18 Mar 2020 21:36:45 -0300
Jason Gunthorpe <[email protected]> escreveu:Quoted 11 lines · Mauro Carvalho Chehab
Quoted 9 lines
The right markup for a variable is @foo, and not @foo[].
Using a wrong markup caused this warning:
./drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h:243: WARNING: Inline strong start-string without end-string.Signed-off-by Mauro Carvalho Chehab <[email protected]>drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Quoted 8 lines
Quoted 2 lines
Do you want this to go to the RDMA tree? I wasn't cc'd on the cover letter
Sorry for not answering earlier. Got sidetracked with other things.
Yeah, if there are still time, feel free to pick it. Otherwise, I'll likely send again after the merge window, to be applied either by you or via the docs tree.
Sure, done
Thanks,
Jason
Re: [PATCH 12/17] gpio: gpiolib.c: fix a doc warning
In reply to Mauro Carvalho ChehabQuoted 10 lines · Mauro Carvalho Chehab
Use a different markup for the
ERR_PTR, as %FOO doesn't work if there are parenthesis. So, use, instead:``ERR_PTR(-EINVAL)``This fixes the following warning:
./drivers/gpio/gpiolib.c:139: WARNING: Inline literal start-string without end-string.Signed-off-by Mauro Carvalho Chehab <[email protected]>
Patch applied.
Yours,
Linus Walleij