This series is based on the top of my previous series:
https://lore.kernel.org/lkml/[email protected]/
plus linux-next.
It contains the patches I sent before with documentation fixes
for Kernel 5.10, plus 3 new fixes for stuff that got merged today
at linux-next.
My plan is to do a late pull request by the end of the merge window
with the patches from this tree that weren't merged directly
via some other trees.
-
After both series applied, the only warnings with Sphinx 2.4.4
are those:
../include/kunit/test.h:282: warning: Function parameter or member '__suites' not described in 'kunit_test_suites_for_module'
../include/kunit/test.h:282: warning: Excess function parameter 'suites_list' description in 'kunit_test_suites_for_module'
../include/kunit/test.h:314: warning: Excess function parameter 'suites' description in 'kunit_test_suites'
.../Documentation/core-api/counters.rst:46: WARNING: undefined label: test counters module (if the link has no caption the label must precede a section header)
.../Documentation/core-api/counters.rst:49: WARNING: undefined label: selftest for counters (if the link has no caption the label must precede a section header)
.../Documentation/core-api/counters.rst:62: WARNING: undefined label: atomic_ops (if the link has no caption the label must precede a section header)
Those require some care from the authors in order to
properly address them.
Hopefully, this will all be sorted until the end of the merge window.
Mauro Carvalho Chehab (24):
docs: hwmon: adm1266.rst: fix a broken reference
tools: docs: memory-model: fix references for some files
docs: SafeSetID: fix a warning
docs: lockdep-design: fix some warning issues
docs: admin-guide: net.rst: add a missing blank line
blk-mq: docs: add kernel-doc description for a new struct member
drm: amdgpu: kernel-doc: update some adev parameters
drm: kernel-doc: document drm_dp_set_subconnector_property() params
docs: kasan.rst: add two missing blank lines
mm: pagemap.h: fix two kernel-doc markups
drm/dp: fix kernel-doc warnings at drm_dp_helper.c
drm/dp: fix a kernel-doc issue at drm_edid.c
docs: i2c: index.rst: add slave-testunit-backend.rst
docs: conf.py: disable automarkup for Sphinx 3.x
docs: net: statistics.rst: remove a duplicated kernel-doc
seqlock: fix two kernel-doc warnings
docs: hwmon: mp2975.rst: address some html build warnings
docs: userspace-api: add iommu.rst to the index file
net: phy: remove kernel-doc duplication
MAINTAINERS: fix broken doc refs due to yaml conversion
crypto: sun8x-ce*: update entries to its documentation
ice: docs fix a devlink info that broke a table
RDMA: add a missing kernel-doc parameter markup
counters: docs: add a missing include
Documentation/admin-guide/LSM/SafeSetID.rst | 2 +-
.../admin-guide/hw-vuln/l1d_flush.rst | 3 +-
Documentation/admin-guide/sysctl/net.rst | 1 +
Documentation/conf.py | 3 +-
Documentation/core-api/counters.rst | 1 +
Documentation/core-api/index.rst | 1 +
Documentation/dev-tools/kasan.rst | 2 +
.../bindings/clock/hi6220-clock.txt | 2 +-
Documentation/hwmon/adm1266.rst | 2 +-
Documentation/hwmon/index.rst | 1 +
Documentation/hwmon/mp2975.rst | 14 +++-
Documentation/i2c/index.rst | 1 +
Documentation/locking/lockdep-design.rst | 69 +++++++++++--------
Documentation/networking/devlink/ice.rst | 1 +
Documentation/networking/statistics.rst | 3 +-
Documentation/userspace-api/index.rst | 1 +
MAINTAINERS | 9 ++-
.../crypto/allwinner/sun8i-ce/sun8i-ce-hash.c | 2 +-
.../crypto/allwinner/sun8i-ce/sun8i-ce-prng.c | 2 +-
.../crypto/allwinner/sun8i-ce/sun8i-ce-trng.c | 2 +-
drivers/gpu/drm/amd/amdgpu/amdgpu_device.c | 2 +-
drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c | 6 +-
drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c | 5 +-
drivers/gpu/drm/drm_dp_helper.c | 12 +++-
drivers/gpu/drm/drm_edid.c | 2 +-
drivers/infiniband/core/device.c | 5 +-
.../bindings/net/wireless/silabs,wfx.yaml | 2 +-
include/linux/blk-mq.h | 2 +
include/linux/pagemap.h | 8 +--
include/linux/phy.h | 40 ++---------
include/linux/seqlock.h | 2 +-
tools/memory-model/Documentation/README | 2 +-
tools/memory-model/Documentation/ordering.txt | 2 +-
33 files changed, 113 insertions(+), 99 deletions(-)
--
2.26.2
- The sysfs.txt file was converted to ReST and renamed;
- The control-dependencies.txt is not at
Documentation/control-dependencies.txt. As it is at the
same dir as the README file, which mentions it, just
remove Documentation/.
With that, ./scripts/documentation-file-ref-check script
is now happy again for files under tools/.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
tools/memory-model/Documentation/README | 2 +-
tools/memory-model/Documentation/ordering.txt | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/tools/memory-model/Documentation/README b/tools/memory-model/Documentation/README
index 16177aaa9752..004969992bac 100644
--- a/tools/memory-model/Documentation/README
+++ b/tools/memory-model/Documentation/README
@@ -55,7 +55,7 @@ README
Documentation/cheatsheet.txt
Quick-reference guide to the Linux-kernel memory model.
-Documentation/control-dependencies.txt
+control-dependencies.txt
A guide to preventing compiler optimizations from destroying
your control dependencies.
diff --git a/tools/memory-model/Documentation/ordering.txt b/tools/memory-model/Documentation/ordering.txt
index 3d020bed8585..629b19ae64a6 100644
--- a/tools/memory-model/Documentation/ordering.txt
+++ b/tools/memory-model/Documentation/ordering.txt
@@ -346,7 +346,7 @@ o Accessing RCU-protected pointers via rcu_dereference()
If there is any significant processing of the pointer value
between the rcu_dereference() that returned it and a later
- dereference(), please read Documentation/RCU/rcu_dereference.txt.
+ dereference(), please read Documentation/RCU/rcu_dereference.rst.
It can also be quite helpful to review uses in the Linux kernel.
--
2.26.2
The class types changed after the C domain rewrite on
Sphinx 3.x. Due to that, the automarkup extension is just
generating additional noise when trying to convert structs
and other markups into cross references.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/conf.py | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 376dd0ddf39c..4f5d15abd047 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -37,7 +37,7 @@ needs_sphinx = '1.3'
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
- 'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
+ 'kfigure', 'sphinx.ext.ifconfig',
'maintainers_include', 'sphinx.ext.autosectionlabel' ]
#
@@ -111,6 +111,7 @@ if major >= 3:
else:
extensions.append('cdomain')
+ extensions.append('automarkup')
# Ensure that autosectionlabel will produce unique names
autosectionlabel_prefix_document = True
--
2.26.2
Changeset 6c8adf8446a3 ("mm: add find_lock_head") renamed the
index parameter, but forgot to update the kernel-doc markups
accordingly.
Fixes: 6c8adf8446a3 ("mm: add find_lock_head")
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
include/linux/pagemap.h | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/include/linux/pagemap.h b/include/linux/pagemap.h
index 7dd3523093db..932a260a29f2 100644
--- a/include/linux/pagemap.h
+++ b/include/linux/pagemap.h
@@ -342,9 +342,9 @@ static inline struct page *find_get_page_flags(struct address_space *mapping,
/**
* find_lock_page - locate, pin and lock a pagecache page
* @mapping: the address_space to search
- * @offset: the page index
+ * @index: the page index
*
- * Looks up the page cache entry at @mapping & @offset. If there is a
+ * Looks up the page cache entry at @mapping & @index. If there is a
* page cache page, it is returned locked and with an increased
* refcount.
*
@@ -361,9 +361,9 @@ static inline struct page *find_lock_page(struct address_space *mapping,
/**
* find_lock_head - Locate, pin and lock a pagecache page.
* @mapping: The address_space to search.
- * @offset: The page index.
+ * @index: The page index.
*
- * Looks up the page cache entry at @mapping & @offset. If there is a
+ * Looks up the page cache entry at @mapping & @index. If there is a
* page cache page, its head page is returned locked and with an increased
* refcount.
*
--
2.26.2
Changeset 54816d3e69d1 ("RDMA: Explicitly pass in the dma_device to ib_register_device")
added a new parameter to ib_register_device().
Document it.
Fixes: 54816d3e69d1 ("RDMA: Explicitly pass in the dma_device to ib_register_device")
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/infiniband/core/device.c | 5 ++++-
1 file changed, 4 insertions(+), 1 deletion(-)
diff --git a/drivers/infiniband/core/device.c b/drivers/infiniband/core/device.c
index feaec8d2f0ca..a3b1fc84cdca 100644
--- a/drivers/infiniband/core/device.c
+++ b/drivers/infiniband/core/device.c
@@ -1318,7 +1318,10 @@ static void prevent_dealloc_device(struct ib_device *ib_dev)
* ib_register_device - Register an IB device with IB core
* @device: Device to register
* @name: unique string device name. This may include a '%' which will
- * cause a unique index to be added to the passed device name.
+ * cause a unique index to be added to the passed device name.
+ * @dma_device: pointer to a DMA-capable device. If %NULL, then the IB
+ * device will be used. In this case the caller should fully
+ * setup the ibdev for DMA. This usually means using dma_virt_ops.
*
* Low-level drivers use ib_register_device() to register their
* devices with the IB core. All registered clients will receive a
--
2.26.2
There's a new uAPI doc for IOMMU. Add it to the index file.
Should address this warning:
.../Documentation/userspace-api/iommu.rst: WARNING: document isn't included in any toctree
Fixes: d0023e3ee28d ("docs: IOMMU user API")
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/userspace-api/index.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst
index 69fc5167e648..acd2cc2a538d 100644
--- a/Documentation/userspace-api/index.rst
+++ b/Documentation/userspace-api/index.rst
@@ -22,6 +22,7 @@ place where this information is gathered.
spec_ctrl
accelerators/ocxl
ioctl/index
+ iommu
media/index
.. only:: subproject and html
--
2.26.2
Running "make htmldocs: produce lots of warnings on those files:
./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_init'
./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'p_size' description in 'amdgpu_vram_mgr_init'
./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:211: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_fini'
./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_init'
./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'p_size' description in 'amdgpu_vram_mgr_init'
./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:211: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_fini'
./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_init'
./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'p_size' description in 'amdgpu_vram_mgr_init'
./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:211: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_fini'
./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_init'
./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'p_size' description in 'amdgpu_vram_mgr_init'
./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:211: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_fini'
./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:90: warning: Excess function parameter 'man' description in 'amdgpu_gtt_mgr_init'
./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:90: warning: Excess function parameter 'p_size' description in 'amdgpu_gtt_mgr_init'
./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:134: warning: Excess function parameter 'man' description in 'amdgpu_gtt_mgr_fini'
./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:90: warning: Excess function parameter 'man' description in 'amdgpu_gtt_mgr_init'
./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:90: warning: Excess function parameter 'p_size' description in 'amdgpu_gtt_mgr_init'
./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:134: warning: Excess function parameter 'man' description in 'amdgpu_gtt_mgr_fini'
./drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:675: warning: Excess function parameter 'dev' description in 'amdgpu_device_asic_init'
./drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:675: warning: Excess function parameter 'dev' description in 'amdgpu_device_asic_init'
./drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:675: warning: Excess function parameter 'dev' description in 'amdgpu_device_asic_init'
./drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:675: warning: Excess function parameter 'dev' description in 'amdgpu_device_asic_init'
They're related to the repacement of some parameters by adev,
and due to a few renamed parameters.
Update the kernel-doc documentation accordingly.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/gpu/drm/amd/amdgpu/amdgpu_device.c | 2 +-
drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c | 6 +++---
drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c | 5 ++---
3 files changed, 6 insertions(+), 7 deletions(-)
diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
index f8f298b34805..fb375752feb1 100644
--- a/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
+++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
@@ -817,7 +817,7 @@ static void amdgpu_block_invalid_wreg(struct amdgpu_device *adev,
/**
* amdgpu_device_asic_init - Wrapper for atom asic_init
*
- * @dev: drm_device pointer
+ * @adev: drm_device pointer
*
* Does any asic specific work and then calls atom asic init.
*/
diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c
index f203e4a6a3f2..5f3a04cd0fba 100644
--- a/drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c
+++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c
@@ -81,8 +81,8 @@ static const struct ttm_resource_manager_func amdgpu_gtt_mgr_func;
/**
* amdgpu_gtt_mgr_init - init GTT manager and DRM MM
*
- * @man: TTM memory type manager
- * @p_size: maximum size of GTT
+ * @adev: amdgpu device structure
+ * @gtt_size: maximum size of GTT
*
* Allocate and initialize the GTT manager.
*/
@@ -123,7 +123,7 @@ int amdgpu_gtt_mgr_init(struct amdgpu_device *adev, uint64_t gtt_size)
/**
* amdgpu_gtt_mgr_fini - free and destroy GTT manager
*
- * @man: TTM memory type manager
+ * @adev: amdgpu device structure
*
* Destroy and free the GTT manager, returns -EBUSY if ranges are still
* allocated inside it.
diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
index 01c1171afbe0..a0e787ddbbd7 100644
--- a/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
+++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
@@ -168,8 +168,7 @@ static const struct ttm_resource_manager_func amdgpu_vram_mgr_func;
/**
* amdgpu_vram_mgr_init - init VRAM manager and DRM MM
*
- * @man: TTM memory type manager
- * @p_size: maximum size of VRAM
+ * @adev: amdgpu device structure
*
* Allocate and initialize the VRAM manager.
*/
@@ -199,7 +198,7 @@ int amdgpu_vram_mgr_init(struct amdgpu_device *adev)
/**
* amdgpu_vram_mgr_fini - free and destroy VRAM manager
*
- * @man: TTM memory type manager
+ * @adev: amdgpu device structure
*
* Destroy and free the VRAM manager, returns -EBUSY if ranges are still
* allocated inside it.
--
2.26.2
Changeset e5b92773287c ("drm: report dp downstream port type as a subconnector property")
added a new function to the kAPI, but didn't add any documentation
for the parameters for drm_dp_set_subconnector_property().
Fixes: e5b92773287c ("drm: report dp downstream port type as a subconnector property")
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/gpu/drm/drm_dp_helper.c | 7 ++++++-
1 file changed, 6 insertions(+), 1 deletion(-)
diff --git a/drivers/gpu/drm/drm_dp_helper.c b/drivers/gpu/drm/drm_dp_helper.c
index 90807a6b415c..b1c71af88579 100644
--- a/drivers/gpu/drm/drm_dp_helper.c
+++ b/drivers/gpu/drm/drm_dp_helper.c
@@ -1028,7 +1028,8 @@ EXPORT_SYMBOL(drm_dp_downstream_debug);
/**
* drm_dp_subconnector_type() - get DP branch device type
- *
+ * @dpcd: DisplayPort configuration data
+ * @port_cap: port capabilities
*/
enum drm_mode_subconnector
drm_dp_subconnector_type(const u8 dpcd[DP_RECEIVER_CAP_SIZE],
@@ -1079,6 +1080,10 @@ EXPORT_SYMBOL(drm_dp_subconnector_type);
/**
* drm_mode_set_dp_subconnector_property - set subconnector for DP connector
+ * @connector: connector to set property on
+ * @status: connector status
+ * @dpcd: DisplayPort configuration data
+ * @port_cap: port capabilities
*
* Called by a driver on every detect event.
*/
--
2.26.2
Sphinx 3 now checks for duplicated function declarations:
.../Documentation/networking/kapi:143: ../include/linux/phy.h:163: WARNING: Duplicate C declaration, also defined in 'networking/kapi'.
Declaration is 'unsigned int phy_supported_speeds (struct phy_device *phy, unsigned int *speeds, unsigned int size)'.
.../Documentation/networking/kapi:143: ../include/linux/phy.h:1034: WARNING: Duplicate C declaration, also defined in 'networking/kapi'.
Declaration is 'int phy_read_mmd (struct phy_device *phydev, int devad, u32 regnum)'.
.../Documentation/networking/kapi:143: ../include/linux/phy.h:1076: WARNING: Duplicate C declaration, also defined in 'networking/kapi'.
Declaration is 'int __phy_read_mmd (struct phy_device *phydev, int devad, u32 regnum)'.
.../Documentation/networking/kapi:143: ../include/linux/phy.h:1088: WARNING: Duplicate C declaration, also defined in 'networking/kapi'.
Declaration is 'int phy_write_mmd (struct phy_device *phydev, int devad, u32 regnum, u16 val)'.
.../Documentation/networking/kapi:143: ../include/linux/phy.h:1100: WARNING: Duplicate C declaration, also defined in 'networking/kapi'.
Declaration is 'int __phy_write_mmd (struct phy_device *phydev, int devad, u32 regnum, u16 val)'.
It turns that both the C and the H files have the same
kernel-doc markup for the same functions. Let's drop the
at the header file, keeping the one closer to the code.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
include/linux/phy.h | 40 +++++-----------------------------------
1 file changed, 5 insertions(+), 35 deletions(-)
diff --git a/include/linux/phy.h b/include/linux/phy.h
index eb3cb1a98b45..56563e5e0dc7 100644
--- a/include/linux/phy.h
+++ b/include/linux/phy.h
@@ -147,16 +147,8 @@ typedef enum {
PHY_INTERFACE_MODE_MAX,
} phy_interface_t;
-/**
+/*
* phy_supported_speeds - return all speeds currently supported by a PHY device
- * @phy: The PHY device to return supported speeds of.
- * @speeds: buffer to store supported speeds in.
- * @size: size of speeds buffer.
- *
- * Description: Returns the number of supported speeds, and fills
- * the speeds buffer with the supported speeds. If speeds buffer is
- * too small to contain all currently supported speeds, will return as
- * many speeds as can fit.
*/
unsigned int phy_supported_speeds(struct phy_device *phy,
unsigned int *speeds,
@@ -1022,14 +1014,9 @@ static inline int __phy_modify_changed(struct phy_device *phydev, u32 regnum,
regnum, mask, set);
}
-/**
+/*
* phy_read_mmd - Convenience function for reading a register
* from an MMD on a given PHY.
- * @phydev: The phy_device struct
- * @devad: The MMD to read from
- * @regnum: The register on the MMD to read
- *
- * Same rules as for phy_read();
*/
int phy_read_mmd(struct phy_device *phydev, int devad, u32 regnum);
@@ -1064,38 +1051,21 @@ int phy_read_mmd(struct phy_device *phydev, int devad, u32 regnum);
__ret; \
})
-/**
+/*
* __phy_read_mmd - Convenience function for reading a register
* from an MMD on a given PHY.
- * @phydev: The phy_device struct
- * @devad: The MMD to read from
- * @regnum: The register on the MMD to read
- *
- * Same rules as for __phy_read();
*/
int __phy_read_mmd(struct phy_device *phydev, int devad, u32 regnum);
-/**
+/*
* phy_write_mmd - Convenience function for writing a register
* on an MMD on a given PHY.
- * @phydev: The phy_device struct
- * @devad: The MMD to write to
- * @regnum: The register on the MMD to read
- * @val: value to write to @regnum
- *
- * Same rules as for phy_write();
*/
int phy_write_mmd(struct phy_device *phydev, int devad, u32 regnum, u16 val);
-/**
+/*
* __phy_write_mmd - Convenience function for writing a register
* on an MMD on a given PHY.
- * @phydev: The phy_device struct
- * @devad: The MMD to write to
- * @regnum: The register on the MMD to read
- * @val: value to write to @regnum
- *
- * Same rules as for __phy_write();
*/
int __phy_write_mmd(struct phy_device *phydev, int devad, u32 regnum, u16 val);
--
2.26.2
As warned by kernel-doc:
./drivers/gpu/drm/drm_dp_helper.c:385: warning: Function parameter or member 'type' not described in 'drm_dp_downstream_is_type'
./drivers/gpu/drm/drm_dp_helper.c:886: warning: Function parameter or member 'dev' not described in 'drm_dp_downstream_mode'
Some function parameters weren't documented.
Fixes: 38784f6f8805 ("drm/dp: Add helpers to identify downstream facing port types")
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
drivers/gpu/drm/drm_dp_helper.c | 5 +++++
1 file changed, 5 insertions(+)
diff --git a/drivers/gpu/drm/drm_dp_helper.c b/drivers/gpu/drm/drm_dp_helper.c
index b1c71af88579..deeed73f4ed6 100644
--- a/drivers/gpu/drm/drm_dp_helper.c
+++ b/drivers/gpu/drm/drm_dp_helper.c
@@ -374,6 +374,10 @@ static bool is_edid_digital_input_dp(const struct edid *edid)
* drm_dp_downstream_is_type() - is the downstream facing port of certain type?
* @dpcd: DisplayPort configuration data
* @port_cap: port capabilities
+ * @type: port type to be checked. Can be:
+ * %DP_DS_PORT_TYPE_DP, %DP_DS_PORT_TYPE_VGA, %DP_DS_PORT_TYPE_DVI,
+ * %DP_DS_PORT_TYPE_HDMI, %DP_DS_PORT_TYPE_NON_EDID,
+ * %DP_DS_PORT_TYPE_DP_DUALMODE or %DP_DS_PORT_TYPE_WIRELESS.
*
* Caveat: Only works with DPCD 1.1+ port caps.
*
@@ -870,6 +874,7 @@ EXPORT_SYMBOL(drm_dp_downstream_444_to_420_conversion);
/**
* drm_dp_downstream_mode() - return a mode for downstream facing port
+ * @dev: DRM device
* @dpcd: DisplayPort configuration data
* @port_cap: port capabilities
*
--
2.26.2
Changeset 37a0dbf631f6 ("counters: Introduce counter_atomic* counters")
Is causing two new warnings:
.../Documentation/core-api/counters.rst:8: WARNING: Undefined substitution referenced: "copy".
.../Documentation/core-api/counters.rst:9: WARNING: Undefined substitution referenced: "copy".
Because it forgot to include isonum.txt, which defines |copy|
macro.
While here, also add it to core-api index file, in order to
solve this warning:
.../Documentation/core-api/counters.rst: WARNING: document isn't included in any toctree
Fixes: 37a0dbf631f6 ("counters: Introduce counter_atomic* counters")
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/core-api/counters.rst | 1 +
Documentation/core-api/index.rst | 1 +
2 files changed, 2 insertions(+)
diff --git a/Documentation/core-api/counters.rst b/Documentation/core-api/counters.rst
index 642d907f4d3a..2821aebf3f45 100644
--- a/Documentation/core-api/counters.rst
+++ b/Documentation/core-api/counters.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
======================
Simple atomic counters
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index 69171b1799f2..cf9cd44c1191 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -43,6 +43,7 @@ Library functionality that is used throughout the kernel.
this_cpu_ops
timekeeping
errseq
+ counters
Concurrency primitives
======================
--
2.26.2
There are several warnings caused by a recent change
224ec489d3cd ("lockdep/Documention: Recursive read lock detection reasoning")
Those are reported by htmldocs build:
Documentation/locking/lockdep-design.rst:429: WARNING: Definition list ends without a blank line; unexpected unindent.
Documentation/locking/lockdep-design.rst:452: WARNING: Block quote ends without a blank line; unexpected unindent.
Documentation/locking/lockdep-design.rst:453: WARNING: Unexpected indentation.
Documentation/locking/lockdep-design.rst:453: WARNING: Blank line required after table.
Documentation/locking/lockdep-design.rst:454: WARNING: Block quote ends without a blank line; unexpected unindent.
Documentation/locking/lockdep-design.rst:455: WARNING: Unexpected indentation.
Documentation/locking/lockdep-design.rst:455: WARNING: Blank line required after table.
Documentation/locking/lockdep-design.rst:456: WARNING: Block quote ends without a blank line; unexpected unindent.
Documentation/locking/lockdep-design.rst:457: WARNING: Unexpected indentation.
Documentation/locking/lockdep-design.rst:457: WARNING: Blank line required after table.
Besides the reported issues, there are some missing blank
lines that ended producing wrong html output, and some
literals are not properly identified.
Also, the symbols used at the irq enabled/disable table
are not displayed as expected, as they're not literals.
Also, on another table they're using a different notation.
Fixes: 224ec489d3cd ("lockdep/Documention: Recursive read lock detection reasoning")
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/locking/lockdep-design.rst | 69 ++++++++++++++----------
1 file changed, 40 insertions(+), 29 deletions(-)
diff --git a/Documentation/locking/lockdep-design.rst b/Documentation/locking/lockdep-design.rst
index cec03bd1294a..7ac0c5092c21 100644
--- a/Documentation/locking/lockdep-design.rst
+++ b/Documentation/locking/lockdep-design.rst
@@ -42,6 +42,7 @@ The validator tracks lock-class usage history and divides the usage into
(4 usages * n STATEs + 1) categories:
where the 4 usages can be:
+
- 'ever held in STATE context'
- 'ever held as readlock in STATE context'
- 'ever held with STATE enabled'
@@ -49,10 +50,12 @@ where the 4 usages can be:
where the n STATEs are coded in kernel/locking/lockdep_states.h and as of
now they include:
+
- hardirq
- softirq
where the last 1 category is:
+
- 'ever used' [ == !unused ]
When locking rules are violated, these usage bits are presented in the
@@ -71,12 +74,12 @@ of the lock and readlock (if exists), for each of the n STATEs listed
above respectively, and the character displayed at each bit position
indicates:
- === ===================================================
- '.' acquired while irqs disabled and not in irq context
- '-' acquired in irq context
- '+' acquired with irqs enabled
- '?' acquired in irq context with irqs enabled.
- === ===================================================
+ ===== ===================================================
+ ``.`` acquired while irqs disabled and not in irq context
+ ``-`` acquired in irq context
+ ``+`` acquired with irqs enabled
+ ``?`` acquired in irq context with irqs enabled.
+ ===== ===================================================
The bits are illustrated with an example::
@@ -96,14 +99,14 @@ exact case is for the lock as of the reporting time.
+--------------+-------------+--------------+
| | irq enabled | irq disabled |
+--------------+-------------+--------------+
- | ever in irq | ? | - |
+ | ever in irq | ``?`` | ``-`` |
+--------------+-------------+--------------+
- | never in irq | + | . |
+ | never in irq | ``+`` | ``.`` |
+--------------+-------------+--------------+
-The character '-' suggests irq is disabled because if otherwise the
-charactor '?' would have been shown instead. Similar deduction can be
-applied for '+' too.
+The character ``-`` suggests irq is disabled because if otherwise the
+charactor ``?`` would have been shown instead. Similar deduction can be
+applied for ``+`` too.
Unused locks (e.g., mutexes) cannot be part of the cause of an error.
@@ -216,7 +219,7 @@ looks like this::
BD_MUTEX_PARTITION
};
-mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION);
+ mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION);
In this case the locking is done on a bdev object that is known to be a
partition.
@@ -334,7 +337,7 @@ Troubleshooting:
----------------
The validator tracks a maximum of MAX_LOCKDEP_KEYS number of lock classes.
-Exceeding this number will trigger the following lockdep warning:
+Exceeding this number will trigger the following lockdep warning::
(DEBUG_LOCKS_WARN_ON(id >= MAX_LOCKDEP_KEYS))
@@ -420,7 +423,8 @@ the critical section of another reader of the same lock instance.
The difference between recursive readers and non-recursive readers is because:
recursive readers get blocked only by a write lock *holder*, while non-recursive
-readers could get blocked by a write lock *waiter*. Considering the follow example:
+readers could get blocked by a write lock *waiter*. Considering the follow
+example::
TASK A: TASK B:
@@ -448,20 +452,22 @@ There are simply four block conditions:
Block condition matrix, Y means the row blocks the column, and N means otherwise.
- | E | r | R |
+---+---+---+---+
- E | Y | Y | Y |
+ | | E | r | R |
+---+---+---+---+
- r | Y | Y | N |
+ | E | Y | Y | Y |
+ +---+---+---+---+
+ | r | Y | Y | N |
+ +---+---+---+---+
+ | R | Y | Y | N |
+---+---+---+---+
- R | Y | Y | N |
(W: writers, r: non-recursive readers, R: recursive readers)
acquired recursively. Unlike non-recursive read locks, recursive read locks
only get blocked by current write lock *holders* other than write lock
-*waiters*, for example:
+*waiters*, for example::
TASK A: TASK B:
@@ -491,7 +497,7 @@ Recursive locks don't block each other, while non-recursive locks do (this is
even true for two non-recursive read locks). A non-recursive lock can block the
corresponding recursive lock, and vice versa.
-A deadlock case with recursive locks involved is as follow:
+A deadlock case with recursive locks involved is as follow::
TASK A: TASK B:
@@ -510,7 +516,7 @@ because there are 3 types for lockers, there are, in theory, 9 types of lock
dependencies, but we can show that 4 types of lock dependencies are enough for
deadlock detection.
-For each lock dependency:
+For each lock dependency::
L1 -> L2
@@ -525,20 +531,25 @@ same types).
With the above combination for simplification, there are 4 types of dependency edges
in the lockdep graph:
-1) -(ER)->: exclusive writer to recursive reader dependency, "X -(ER)-> Y" means
+1) -(ER)->:
+ exclusive writer to recursive reader dependency, "X -(ER)-> Y" means
X -> Y and X is a writer and Y is a recursive reader.
-2) -(EN)->: exclusive writer to non-recursive locker dependency, "X -(EN)-> Y" means
+2) -(EN)->:
+ exclusive writer to non-recursive locker dependency, "X -(EN)-> Y" means
X -> Y and X is a writer and Y is either a writer or non-recursive reader.
-3) -(SR)->: shared reader to recursive reader dependency, "X -(SR)-> Y" means
+3) -(SR)->:
+ shared reader to recursive reader dependency, "X -(SR)-> Y" means
X -> Y and X is a reader (recursive or not) and Y is a recursive reader.
-4) -(SN)->: shared reader to non-recursive locker dependency, "X -(SN)-> Y" means
+4) -(SN)->:
+ shared reader to non-recursive locker dependency, "X -(SN)-> Y" means
X -> Y and X is a reader (recursive or not) and Y is either a writer or
non-recursive reader.
-Note that given two locks, they may have multiple dependencies between them, for example:
+Note that given two locks, they may have multiple dependencies between them,
+for example::
TASK A:
@@ -592,11 +603,11 @@ circles that won't cause deadlocks.
Proof for sufficiency (Lemma 1):
-Let's say we have a strong circle:
+Let's say we have a strong circle::
L1 -> L2 ... -> Ln -> L1
-, which means we have dependencies:
+, which means we have dependencies::
L1 -> L2
L2 -> L3
@@ -633,7 +644,7 @@ a lock held by P2, and P2 is waiting for a lock held by P3, ... and Pn is waitin
for a lock held by P1. Let's name the lock Px is waiting as Lx, so since P1 is waiting
for L1 and holding Ln, so we will have Ln -> L1 in the dependency graph. Similarly,
we have L1 -> L2, L2 -> L3, ..., Ln-1 -> Ln in the dependency graph, which means we
-have a circle:
+have a circle::
Ln -> L1 -> L2 -> ... -> Ln
--
2.26.2
There's a missing blank line after a literal block, which
causes this warning:
Documentation/admin-guide/sysctl/net.rst:303: WARNING: Literal block ends without a blank line; unexpected unindent.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/admin-guide/sysctl/net.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/Documentation/admin-guide/sysctl/net.rst b/Documentation/admin-guide/sysctl/net.rst
index 57fd6ce68fe0..f2ab8a5b6a4b 100644
--- a/Documentation/admin-guide/sysctl/net.rst
+++ b/Documentation/admin-guide/sysctl/net.rst
@@ -300,6 +300,7 @@ Note:
0: 0 1 2 3 4 5 6 7
RSS hash key:
84:50:f4:00:a8:15:d1:a7:e9:7f:1d:60:35:c7:47:25:42:97:74:ca:56:bb:b6:a1:d8:43:e3:c9:0c:fd:17:55:c2:3a:4d:69:ed:f1:42:89
+
netdev_tstamp_prequeue
----------------------
--
2.26.2
literal blocks should start and end with a blank line,
as otherwise the parser complains and may do the wrong
thing, as warned by Sphinx:
Documentation/dev-tools/kasan.rst:298: WARNING: Literal block ends without a blank line; unexpected unindent.
Documentation/dev-tools/kasan.rst:303: WARNING: Literal block ends without a blank line; unexpected unindent.
Reviewed-by: Andrey Konovalov <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/dev-tools/kasan.rst | 2 ++
1 file changed, 2 insertions(+)
diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst
index c09c9ca2ff1c..2b68addaadcd 100644
--- a/Documentation/dev-tools/kasan.rst
+++ b/Documentation/dev-tools/kasan.rst
@@ -295,11 +295,13 @@ print the number of the test and the status of the test:
pass::
ok 28 - kmalloc_double_kzfree
+
or, if kmalloc failed::
# kmalloc_large_oob_right: ASSERTION FAILED at lib/test_kasan.c:163
Expected ptr is not null, but is
not ok 4 - kmalloc_large_oob_right
+
or, if a KASAN report was expected, but not found::
# kmalloc_double_kzfree: EXPECTATION FAILED at lib/test_kasan.c:629
--
2.26.2
As warned by Sphinx:
.../Documentation/i2c/slave-testunit-backend.rst: WARNING: document isn't included in any toctree
This document is not included anywhere.
Fixes: a8335c64c5f0 ("i2c: add slave testunit driver")
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/admin-guide/hw-vuln/l1d_flush.rst | 3 +--
Documentation/i2c/index.rst | 1 +
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/admin-guide/hw-vuln/l1d_flush.rst b/Documentation/admin-guide/hw-vuln/l1d_flush.rst
index adc4ecc72361..f794e2b1096c 100644
--- a/Documentation/admin-guide/hw-vuln/l1d_flush.rst
+++ b/Documentation/admin-guide/hw-vuln/l1d_flush.rst
@@ -22,8 +22,7 @@ mechanism
Usage Guidelines
----------------
-Please see document: :ref:`Documentation/userspace-api/spec_ctrl.rst` for
-details.
+Please see document: :doc:`/userspace-api/spec_ctrl` for details.
**NOTE**: The feature is disabled by default, applications need to
specifically opt into the feature to enable it.
diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst
index 8b76217e370a..c8bf6f7d5286 100644
--- a/Documentation/i2c/index.rst
+++ b/Documentation/i2c/index.rst
@@ -38,6 +38,7 @@ Debugging
gpio-fault-injection
i2c-stub
+ slave-testunit-backend
Slave I2C
=========
--
2.26.2
Changeset 410d06879c01 ("ice: add the DDP Track ID to devlink info")
added description for a new devlink field, but forgot to add
one of its columns, causing it to break:
.../Documentation/networking/devlink/ice.rst:15: WARNING: Error parsing content block for the "list-table" directive: uniform two-level bullet list expected, but row 11 does not contain the same number of items as row 1 (3 vs 4).
.. list-table:: devlink info versions implemented
:widths: 5 5 5 90
...
* - ``fw.app.bundle_id``
- 0xc0000001
- Unique identifier for the DDP package loaded in the device. Also
referred to as the DDP Track ID. Can be used to uniquely identify
the specific DDP package.
Add the type field to the ``fw.app.bundle_id`` row.
Fixes: 410d06879c01 ("ice: add the DDP Track ID to devlink info")
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/networking/devlink/ice.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/Documentation/networking/devlink/ice.rst b/Documentation/networking/devlink/ice.rst
index b165181d5d4d..a432dc419fa4 100644
--- a/Documentation/networking/devlink/ice.rst
+++ b/Documentation/networking/devlink/ice.rst
@@ -70,6 +70,7 @@ The ``ice`` driver reports the following versions
that both the name (as reported by ``fw.app.name``) and version are
required to uniquely identify the package.
* - ``fw.app.bundle_id``
+ - running
- 0xc0000001
- Unique identifier for the DDP package loaded in the device. Also
referred to as the DDP Track ID. Can be used to uniquely identify
--
2.26.2
As reported by kernel-doc:
./include/linux/blk-mq.h:267: warning: Function parameter or member 'active_queues_shared_sbitmap' not described in 'blk_mq_tag_set'
There is now a new member for struct blk_mq_tag_set. Add a
description for it, based on the commit that introduced it.
Fixes: f1b49fdc1c64 ("blk-mq: Record active_queues_shared_sbitmap per tag_set for when using shared sbitmap")
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
include/linux/blk-mq.h | 2 ++
1 file changed, 2 insertions(+)
diff --git a/include/linux/blk-mq.h b/include/linux/blk-mq.h
index b23eeca4d677..794b2a33a2c3 100644
--- a/include/linux/blk-mq.h
+++ b/include/linux/blk-mq.h
@@ -235,6 +235,8 @@ enum hctx_type {
* @flags: Zero or more BLK_MQ_F_* flags.
* @driver_data: Pointer to data owned by the block driver that created this
* tag set.
+ * @active_queues_shared_sbitmap:
+ * number of active request queues per tag set.
* @__bitmap_tags: A shared tags sbitmap, used over all hctx's
* @__breserved_tags:
* A shared reserved tags sbitmap, used over all hctx's
--
2.26.2
include/linux/ethtool.h is included twice with kernel-doc,
both to document ethtool_pause_stats(). The first one is
at statistics.rst, and the second one at ethtool-netlink.rst.
Replace one of the references to use the name of the
function. The automarkup.py extension should create the
cross-references.
Solves this warning:
../Documentation/networking/ethtool-netlink.rst: WARNING: Duplicate C declaration, also defined in 'networking/statistics'.
Declaration is 'ethtool_pause_stats'.
Acked-by: David S. Miller <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/networking/statistics.rst | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/Documentation/networking/statistics.rst b/Documentation/networking/statistics.rst
index 8e15bc98830b..234abedc29b2 100644
--- a/Documentation/networking/statistics.rst
+++ b/Documentation/networking/statistics.rst
@@ -175,5 +175,4 @@ The following structures are internal to the kernel, their members are
translated to netlink attributes when dumped. Drivers must not overwrite
the statistics they don't report with 0.
-.. kernel-doc:: include/linux/ethtool.h
- :identifiers: ethtool_pause_stats
+- ethtool_pause_stats()
--
2.26.2
Am 13.10.20 um 14:14 schrieb Mauro Carvalho Chehab:
> Running "make htmldocs: produce lots of warnings on those files:
> ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_init'
> ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'p_size' description in 'amdgpu_vram_mgr_init'
> ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:211: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_fini'
> ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_init'
> ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'p_size' description in 'amdgpu_vram_mgr_init'
> ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:211: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_fini'
> ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_init'
> ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'p_size' description in 'amdgpu_vram_mgr_init'
> ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:211: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_fini'
> ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_init'
> ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:177: warning: Excess function parameter 'p_size' description in 'amdgpu_vram_mgr_init'
> ./drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c:211: warning: Excess function parameter 'man' description in 'amdgpu_vram_mgr_fini'
> ./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:90: warning: Excess function parameter 'man' description in 'amdgpu_gtt_mgr_init'
> ./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:90: warning: Excess function parameter 'p_size' description in 'amdgpu_gtt_mgr_init'
> ./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:134: warning: Excess function parameter 'man' description in 'amdgpu_gtt_mgr_fini'
> ./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:90: warning: Excess function parameter 'man' description in 'amdgpu_gtt_mgr_init'
> ./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:90: warning: Excess function parameter 'p_size' description in 'amdgpu_gtt_mgr_init'
> ./drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c:134: warning: Excess function parameter 'man' description in 'amdgpu_gtt_mgr_fini'
> ./drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:675: warning: Excess function parameter 'dev' description in 'amdgpu_device_asic_init'
> ./drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:675: warning: Excess function parameter 'dev' description in 'amdgpu_device_asic_init'
> ./drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:675: warning: Excess function parameter 'dev' description in 'amdgpu_device_asic_init'
> ./drivers/gpu/drm/amd/amdgpu/amdgpu_device.c:675: warning: Excess function parameter 'dev' description in 'amdgpu_device_asic_init'
>
> They're related to the repacement of some parameters by adev,
> and due to a few renamed parameters.
>
> Update the kernel-doc documentation accordingly.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> drivers/gpu/drm/amd/amdgpu/amdgpu_device.c | 2 +-
> drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c | 6 +++---
> drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c | 5 ++---
> 3 files changed, 6 insertions(+), 7 deletions(-)
>
> diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
> index f8f298b34805..fb375752feb1 100644
> --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
> +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_device.c
> @@ -817,7 +817,7 @@ static void amdgpu_block_invalid_wreg(struct amdgpu_device *adev,
> /**
> * amdgpu_device_asic_init - Wrapper for atom asic_init
> *
> - * @dev: drm_device pointer
> + * @adev: drm_device pointer
This should probably read amdgpu device pointer, but apart from that
looks good to me.
Christian.
> *
> * Does any asic specific work and then calls atom asic init.
> */
> diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c
> index f203e4a6a3f2..5f3a04cd0fba 100644
> --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c
> +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_gtt_mgr.c
> @@ -81,8 +81,8 @@ static const struct ttm_resource_manager_func amdgpu_gtt_mgr_func;
> /**
> * amdgpu_gtt_mgr_init - init GTT manager and DRM MM
> *
> - * @man: TTM memory type manager
> - * @p_size: maximum size of GTT
> + * @adev: amdgpu device structure
> + * @gtt_size: maximum size of GTT
> *
> * Allocate and initialize the GTT manager.
> */
> @@ -123,7 +123,7 @@ int amdgpu_gtt_mgr_init(struct amdgpu_device *adev, uint64_t gtt_size)
> /**
> * amdgpu_gtt_mgr_fini - free and destroy GTT manager
> *
> - * @man: TTM memory type manager
> + * @adev: amdgpu device structure
> *
> * Destroy and free the GTT manager, returns -EBUSY if ranges are still
> * allocated inside it.
> diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
> index 01c1171afbe0..a0e787ddbbd7 100644
> --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
> +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_vram_mgr.c
> @@ -168,8 +168,7 @@ static const struct ttm_resource_manager_func amdgpu_vram_mgr_func;
> /**
> * amdgpu_vram_mgr_init - init VRAM manager and DRM MM
> *
> - * @man: TTM memory type manager
> - * @p_size: maximum size of VRAM
> + * @adev: amdgpu device structure
> *
> * Allocate and initialize the VRAM manager.
> */
> @@ -199,7 +198,7 @@ int amdgpu_vram_mgr_init(struct amdgpu_device *adev)
> /**
> * amdgpu_vram_mgr_fini - free and destroy VRAM manager
> *
> - * @man: TTM memory type manager
> + * @adev: amdgpu device structure
> *
> * Destroy and free the VRAM manager, returns -EBUSY if ranges are still
> * allocated inside it.
On Tue, Oct 13, 2020 at 02:14:37PM +0200, Mauro Carvalho Chehab wrote:
> Changeset 6c8adf8446a3 ("mm: add find_lock_head") renamed the
> index parameter, but forgot to update the kernel-doc markups
> accordingly.
The patch is correct (thank you!), but the description here references
a git commit id that's only found in the -next tree and is unstable.
Andrew, can you fold this into the offending commit?
> Fixes: 6c8adf8446a3 ("mm: add find_lock_head")
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> include/linux/pagemap.h | 8 ++++----
> 1 file changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/include/linux/pagemap.h b/include/linux/pagemap.h
> index 7dd3523093db..932a260a29f2 100644
> --- a/include/linux/pagemap.h
> +++ b/include/linux/pagemap.h
> @@ -342,9 +342,9 @@ static inline struct page *find_get_page_flags(struct address_space *mapping,
> /**
> * find_lock_page - locate, pin and lock a pagecache page
> * @mapping: the address_space to search
> - * @offset: the page index
> + * @index: the page index
> *
> - * Looks up the page cache entry at @mapping & @offset. If there is a
> + * Looks up the page cache entry at @mapping & @index. If there is a
> * page cache page, it is returned locked and with an increased
> * refcount.
> *
> @@ -361,9 +361,9 @@ static inline struct page *find_lock_page(struct address_space *mapping,
> /**
> * find_lock_head - Locate, pin and lock a pagecache page.
> * @mapping: The address_space to search.
> - * @offset: The page index.
> + * @index: The page index.
> *
> - * Looks up the page cache entry at @mapping & @offset. If there is a
> + * Looks up the page cache entry at @mapping & @index. If there is a
> * page cache page, its head page is returned locked and with an increased
> * refcount.
> *
> --
> 2.26.2
>
On Tue, Oct 13, 2020 at 02:14:31PM +0200, Mauro Carvalho Chehab wrote:
> + ===== ===================================================
> + ``.`` acquired while irqs disabled and not in irq context
> + ``-`` acquired in irq context
> + ``+`` acquired with irqs enabled
> + ``?`` acquired in irq context with irqs enabled.
> + ===== ===================================================
>
> The bits are illustrated with an example::
>
> @@ -96,14 +99,14 @@ exact case is for the lock as of the reporting time.
> +--------------+-------------+--------------+
> | | irq enabled | irq disabled |
> +--------------+-------------+--------------+
> - | ever in irq | ? | - |
> + | ever in irq | ``?`` | ``-`` |
> +--------------+-------------+--------------+
> - | never in irq | + | . |
> + | never in irq | ``+`` | ``.`` |
> +--------------+-------------+--------------+
>
> -The character '-' suggests irq is disabled because if otherwise the
> -charactor '?' would have been shown instead. Similar deduction can be
> -applied for '+' too.
> +The character ``-`` suggests irq is disabled because if otherwise the
> +charactor ``?`` would have been shown instead. Similar deduction can be
> +applied for ``+`` too.
>
NAK!
On Tue, Oct 13, 2020 at 02:52:06PM +0200, Peter Zijlstra wrote:
> On Tue, Oct 13, 2020 at 02:14:31PM +0200, Mauro Carvalho Chehab wrote:
> > + ===== ===================================================
> > + ``.`` acquired while irqs disabled and not in irq context
> > + ``-`` acquired in irq context
> > + ``+`` acquired with irqs enabled
> > + ``?`` acquired in irq context with irqs enabled.
> > + ===== ===================================================
>
> NAK!
You're seriously suggesting that:
- === ===================================================
- '.' acquired while irqs disabled and not in irq context
- '-' acquired in irq context
- '+' acquired with irqs enabled
- '?' acquired in irq context with irqs enabled.
- === ===================================================
+ ===== ===================================================
+ ``.`` acquired while irqs disabled and not in irq context
+ ``-`` acquired in irq context
+ ``+`` acquired with irqs enabled
+ ``?`` acquired in irq context with irqs enabled.
+ ===== ===================================================
this change makes the lockdep docs less readable?
It's not the markup that makes the lockdep documentation hard to
understand.
On 13/10/2020 13:14, Mauro Carvalho Chehab wrote:
> As reported by kernel-doc:
> ./include/linux/blk-mq.h:267: warning: Function parameter or member 'active_queues_shared_sbitmap' not described in 'blk_mq_tag_set'
>
> There is now a new member for struct blk_mq_tag_set. Add a
> description for it, based on the commit that introduced it.
>
> Fixes: f1b49fdc1c64 ("blk-mq: Record active_queues_shared_sbitmap per tag_set for when using shared sbitmap")
> Signed-off-by: Mauro Carvalho Chehab<[email protected]>
Reviewed-by: John Garry <[email protected]>
On Tue, Oct 13, 2020 at 02:11:16PM +0100, Matthew Wilcox wrote:
> On Tue, Oct 13, 2020 at 02:52:06PM +0200, Peter Zijlstra wrote:
> > On Tue, Oct 13, 2020 at 02:14:31PM +0200, Mauro Carvalho Chehab wrote:
> > > + ===== ===================================================
> > > + ``.`` acquired while irqs disabled and not in irq context
> > > + ``-`` acquired in irq context
> > > + ``+`` acquired with irqs enabled
> > > + ``?`` acquired in irq context with irqs enabled.
> > > + ===== ===================================================
> >
> > NAK!
>
> You're seriously suggesting that:
>
> - === ===================================================
> - '.' acquired while irqs disabled and not in irq context
> - '-' acquired in irq context
> - '+' acquired with irqs enabled
> - '?' acquired in irq context with irqs enabled.
> - === ===================================================
> + ===== ===================================================
> + ``.`` acquired while irqs disabled and not in irq context
> + ``-`` acquired in irq context
> + ``+`` acquired with irqs enabled
> + ``?`` acquired in irq context with irqs enabled.
> + ===== ===================================================
>
> this change makes the lockdep docs less readable?
Definitely makes it harder to read for me. My C trained eyes go WTF at
seeing it, which breaks the flow. ',' is a regular single character
constant, '','' a syntax error.
> It's not the markup that makes the lockdep documentation hard to
> understand.
I'm not sure what you're alluding to, the subject just isn't easy to
begin with.
Over all I'm tempted to just convert the whole thing to .txt and avoid
all the RST shit entirely.
Several *.txt files got converted to yaml. Update their
references at MAINTAINERS file accordingly.
Acked-by: Stephen Boyd <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/devicetree/bindings/clock/hi6220-clock.txt | 2 +-
MAINTAINERS | 9 ++++-----
.../devicetree/bindings/net/wireless/silabs,wfx.yaml | 2 +-
3 files changed, 6 insertions(+), 7 deletions(-)
diff --git a/Documentation/devicetree/bindings/clock/hi6220-clock.txt b/Documentation/devicetree/bindings/clock/hi6220-clock.txt
index ef3deb7b86ea..17ac4a3dd26a 100644
--- a/Documentation/devicetree/bindings/clock/hi6220-clock.txt
+++ b/Documentation/devicetree/bindings/clock/hi6220-clock.txt
@@ -4,7 +4,7 @@ Clock control registers reside in different Hi6220 system controllers,
please refer the following document to know more about the binding rules
for these system controllers:
-Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt
+Documentation/devicetree/bindings/arm/hisilicon/hisilicon.yaml
Required Properties:
diff --git a/MAINTAINERS b/MAINTAINERS
index f1eeef654caa..891b735233d3 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -978,7 +978,7 @@ M: Michael Hennerich <[email protected]>
L: [email protected]
S: Supported
W: http://ez.analog.com/community/linux-device-drivers
-F: Documentation/devicetree/bindings/iio/adc/adi,ad7768-1.txt
+F: Documentation/devicetree/bindings/iio/adc/adi,ad7768-1.yaml
F: drivers/iio/adc/ad7768-1.c
ANALOG DEVICES INC AD7780 DRIVER
@@ -3867,7 +3867,7 @@ M: Roger Quadros <[email protected]>
L: [email protected]
S: Maintained
T: git git://git.kernel.org/pub/scm/linux/kernel/git/peter.chen/usb.git
-F: Documentation/devicetree/bindings/usb/cdns-usb3.txt
+F: Documentation/devicetree/bindings/usb/cdns,usb3.yaml
F: drivers/usb/cdns3/
CADET FM/AM RADIO RECEIVER DRIVER
@@ -7919,7 +7919,7 @@ HISILICON LPC BUS DRIVER
M: [email protected]
S: Maintained
W: http://www.hisilicon.com
-F: Documentation/devicetree/bindings/arm/hisilicon/hisilicon-low-pin-count.txt
+F: Documentation/devicetree/bindings/arm/hisilicon/low-pin-count.yaml
F: drivers/bus/hisi_lpc.c
HISILICON NETWORK SUBSYSTEM 3 DRIVER (HNS3)
@@ -14910,7 +14910,6 @@ RENESAS ETHERNET DRIVERS
R: Sergei Shtylyov <[email protected]>
L: [email protected]
L: [email protected]
-F: Documentation/devicetree/bindings/net/renesas,*.txt
F: Documentation/devicetree/bindings/net/renesas,*.yaml
F: drivers/net/ethernet/renesas/
F: include/linux/sh_eth.h
@@ -18114,7 +18113,7 @@ M: Yu Chen <[email protected]>
M: Binghui Wang <[email protected]>
L: [email protected]
S: Maintained
-F: Documentation/devicetree/bindings/phy/phy-hi3660-usb3.txt
+F: Documentation/devicetree/bindings/phy/hisilicon,hi3660-usb3.yaml
F: drivers/phy/hisilicon/phy-hi3660-usb3.c
USB ISP116X DRIVER
diff --git a/drivers/staging/wfx/Documentation/devicetree/bindings/net/wireless/silabs,wfx.yaml b/drivers/staging/wfx/Documentation/devicetree/bindings/net/wireless/silabs,wfx.yaml
index 43b5630c0407..510edd12ed19 100644
--- a/drivers/staging/wfx/Documentation/devicetree/bindings/net/wireless/silabs,wfx.yaml
+++ b/drivers/staging/wfx/Documentation/devicetree/bindings/net/wireless/silabs,wfx.yaml
@@ -24,7 +24,7 @@ description:
In addition, it is recommended to declare a mmc-pwrseq on SDIO host above
WFx. Without it, you may encounter issues with warm boot. The mmc-pwrseq
should be compatible with mmc-pwrseq-simple. Please consult
- Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.txt for more
+ Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.yaml for more
information.
For SPI':'
--
2.26.2
On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote:
> On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote:
> > - The sysfs.txt file was converted to ReST and renamed;
> > - The control-dependencies.txt is not at
> > Documentation/control-dependencies.txt. As it is at the
> > same dir as the README file, which mentions it, just
> > remove Documentation/.
> >
> > With that, ./scripts/documentation-file-ref-check script
> > is now happy again for files under tools/.
> >
> > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
>
> Queued for review and testing, likely target v5.11.
Instead of changing the path in the README reference, shouldn't
tools/memory-model/control-dependencies.txt be moved to its proper
position in .../Documentation?
Alan Stern
Reviewed-by: Lyude Paul <[email protected]>
On Tue, 2020-10-13 at 14:14 +0200, Mauro Carvalho Chehab wrote:
> As warned by kernel-doc:
>
> ./drivers/gpu/drm/drm_dp_helper.c:385: warning: Function parameter or
> member 'type' not described in 'drm_dp_downstream_is_type'
> ./drivers/gpu/drm/drm_dp_helper.c:886: warning: Function parameter or
> member 'dev' not described in 'drm_dp_downstream_mode'
>
> Some function parameters weren't documented.
>
> Fixes: 38784f6f8805 ("drm/dp: Add helpers to identify downstream facing port
> types")
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> drivers/gpu/drm/drm_dp_helper.c | 5 +++++
> 1 file changed, 5 insertions(+)
>
> diff --git a/drivers/gpu/drm/drm_dp_helper.c b/drivers/gpu/drm/drm_dp_helper.c
> index b1c71af88579..deeed73f4ed6 100644
> --- a/drivers/gpu/drm/drm_dp_helper.c
> +++ b/drivers/gpu/drm/drm_dp_helper.c
> @@ -374,6 +374,10 @@ static bool is_edid_digital_input_dp(const struct edid
> *edid)
> * drm_dp_downstream_is_type() - is the downstream facing port of certain
> type?
> * @dpcd: DisplayPort configuration data
> * @port_cap: port capabilities
> + * @type: port type to be checked. Can be:
> + * %DP_DS_PORT_TYPE_DP, %DP_DS_PORT_TYPE_VGA, %DP_DS_PORT_TYPE_DVI,
> + * %DP_DS_PORT_TYPE_HDMI, %DP_DS_PORT_TYPE_NON_EDID,
> + * %DP_DS_PORT_TYPE_DP_DUALMODE or %DP_DS_PORT_TYPE_WIRELESS.
> *
> * Caveat: Only works with DPCD 1.1+ port caps.
> *
> @@ -870,6 +874,7 @@ EXPORT_SYMBOL(drm_dp_downstream_444_to_420_conversion);
>
> /**
> * drm_dp_downstream_mode() - return a mode for downstream facing port
> + * @dev: DRM device
> * @dpcd: DisplayPort configuration data
> * @port_cap: port capabilities
> *
--
Sincerely,
Lyude Paul (she/her)
Software Engineer at Red Hat
Note: I deal with a lot of emails and have a lot of bugs on my plate. If you've
asked me a question, are waiting for a review/merge on a patch, etc. and I
haven't responded in a while, please feel free to send me another email to check
on my status. I don't bite!
On 10/13/20 6:14 AM, Mauro Carvalho Chehab wrote:
> As reported by kernel-doc:
> ./include/linux/blk-mq.h:267: warning: Function parameter or member 'active_queues_shared_sbitmap' not described in 'blk_mq_tag_set'
>
> There is now a new member for struct blk_mq_tag_set. Add a
> description for it, based on the commit that introduced it.
Reviewed-by: Jens Axboe <[email protected]>
--
Jens Axboe
On Tue, Oct 13, 2020 at 04:09:41PM +0200, Peter Zijlstra wrote:
> On Tue, Oct 13, 2020 at 02:11:16PM +0100, Matthew Wilcox wrote:
> > On Tue, Oct 13, 2020 at 02:52:06PM +0200, Peter Zijlstra wrote:
> > > On Tue, Oct 13, 2020 at 02:14:31PM +0200, Mauro Carvalho Chehab wrote:
> > > > + ===== ===================================================
> > > > + ``.`` acquired while irqs disabled and not in irq context
> > > > + ``-`` acquired in irq context
> > > > + ``+`` acquired with irqs enabled
> > > > + ``?`` acquired in irq context with irqs enabled.
> > > > + ===== ===================================================
> > >
> > > NAK!
> >
> > You're seriously suggesting that:
> >
> > - === ===================================================
> > - '.' acquired while irqs disabled and not in irq context
> > - '-' acquired in irq context
> > - '+' acquired with irqs enabled
> > - '?' acquired in irq context with irqs enabled.
> > - === ===================================================
> > + ===== ===================================================
> > + ``.`` acquired while irqs disabled and not in irq context
> > + ``-`` acquired in irq context
> > + ``+`` acquired with irqs enabled
> > + ``?`` acquired in irq context with irqs enabled.
> > + ===== ===================================================
> >
> > this change makes the lockdep docs less readable?
>
> Definitely makes it harder to read for me. My C trained eyes go WTF at
> seeing it, which breaks the flow. ',' is a regular single character
> constant, '','' a syntax error.
OK, that's fair. 'a' is definitely a character constant. Perhaps
the automarkup script can take care of this for us? We'd have to
be careful not to catch anything we shouldn't've [1], but I'm sure
there's a regex for it. Something like "\<'.'\>", perhaps?
[1] I'm quite proud of that one.
> > It's not the markup that makes the lockdep documentation hard to
> > understand.
>
> I'm not sure what you're alluding to, the subject just isn't easy to
> begin with.
Absolutely. The problem is (similar to most Linux documentation)
the document doesn't know who its audience is. It mixes internal
implementation details of lockdep with what people need to know who
are just trying to understand what a lockdep splat means. I don't
have time to restructure it right now though.
> Fixes: a8335c64c5f0 ("i2c: add slave testunit driver")
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
As discussed with v1, I already fixed it (correctly). Patch is in
linux-next:
https://git.kernel.org/pub/scm/linux/kernel/git/wsa/linux.git/commit/?h=i2c/for-next&id=40daf09a30a0c86a038bcce606604333f32e03f8
Thanks!
On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote:
> - The sysfs.txt file was converted to ReST and renamed;
> - The control-dependencies.txt is not at
> Documentation/control-dependencies.txt. As it is at the
> same dir as the README file, which mentions it, just
> remove Documentation/.
>
> With that, ./scripts/documentation-file-ref-check script
> is now happy again for files under tools/.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Queued for review and testing, likely target v5.11.
Thanx, Paul
> ---
> tools/memory-model/Documentation/README | 2 +-
> tools/memory-model/Documentation/ordering.txt | 2 +-
> 2 files changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/tools/memory-model/Documentation/README b/tools/memory-model/Documentation/README
> index 16177aaa9752..004969992bac 100644
> --- a/tools/memory-model/Documentation/README
> +++ b/tools/memory-model/Documentation/README
> @@ -55,7 +55,7 @@ README
> Documentation/cheatsheet.txt
> Quick-reference guide to the Linux-kernel memory model.
>
> -Documentation/control-dependencies.txt
> +control-dependencies.txt
> A guide to preventing compiler optimizations from destroying
> your control dependencies.
>
> diff --git a/tools/memory-model/Documentation/ordering.txt b/tools/memory-model/Documentation/ordering.txt
> index 3d020bed8585..629b19ae64a6 100644
> --- a/tools/memory-model/Documentation/ordering.txt
> +++ b/tools/memory-model/Documentation/ordering.txt
> @@ -346,7 +346,7 @@ o Accessing RCU-protected pointers via rcu_dereference()
>
> If there is any significant processing of the pointer value
> between the rcu_dereference() that returned it and a later
> - dereference(), please read Documentation/RCU/rcu_dereference.txt.
> + dereference(), please read Documentation/RCU/rcu_dereference.rst.
>
> It can also be quite helpful to review uses in the Linux kernel.
>
> --
> 2.26.2
>
On 10/13/2020 5:14 AM, Mauro Carvalho Chehab wrote:
> Changeset 410d06879c01 ("ice: add the DDP Track ID to devlink info")
> added description for a new devlink field, but forgot to add
> one of its columns, causing it to break:
>
> .../Documentation/networking/devlink/ice.rst:15: WARNING: Error parsing content block for the "list-table" directive: uniform two-level bullet list expected, but row 11 does not contain the same number of items as row 1 (3 vs 4).
>
> .. list-table:: devlink info versions implemented
> :widths: 5 5 5 90
> ...
> * - ``fw.app.bundle_id``
> - 0xc0000001
> - Unique identifier for the DDP package loaded in the device. Also
> referred to as the DDP Track ID. Can be used to uniquely identify
> the specific DDP package.
>
> Add the type field to the ``fw.app.bundle_id`` row.
>
> Fixes: 410d06879c01 ("ice: add the DDP Track ID to devlink info")
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Yep, looks correct. Thanks for the fix!
Reviewed-by: Jacob Keller <[email protected]>
> ---
> Documentation/networking/devlink/ice.rst | 1 +
> 1 file changed, 1 insertion(+)
>
> diff --git a/Documentation/networking/devlink/ice.rst b/Documentation/networking/devlink/ice.rst
> index b165181d5d4d..a432dc419fa4 100644
> --- a/Documentation/networking/devlink/ice.rst
> +++ b/Documentation/networking/devlink/ice.rst
> @@ -70,6 +70,7 @@ The ``ice`` driver reports the following versions
> that both the name (as reported by ``fw.app.name``) and version are
> required to uniquely identify the package.
> * - ``fw.app.bundle_id``
> + - running
> - 0xc0000001
> - Unique identifier for the DDP package loaded in the device. Also
> referred to as the DDP Track ID. Can be used to uniquely identify
>
Em Tue, 13 Oct 2020 18:58:40 -0700
"Paul E. McKenney" <[email protected]> escreveu:
> On Tue, Oct 13, 2020 at 12:38:36PM -0400, Alan Stern wrote:
> > On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote:
> > > On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote:
> > > > - The sysfs.txt file was converted to ReST and renamed;
> > > > - The control-dependencies.txt is not at
> > > > Documentation/control-dependencies.txt. As it is at the
> > > > same dir as the README file, which mentions it, just
> > > > remove Documentation/.
> > > >
> > > > With that, ./scripts/documentation-file-ref-check script
> > > > is now happy again for files under tools/.
> > > >
> > > > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> > >
> > > Queued for review and testing, likely target v5.11.
> >
> > Instead of changing the path in the README reference, shouldn't
> > tools/memory-model/control-dependencies.txt be moved to its proper
> > position in .../Documentation?
>
> You are of course quite right. My thought is to let Mauro go ahead,
> given his short deadline. We can then make this "git mv" change once
> v5.10-rc1 comes out, given that it should have Mauro's patches. I have
> added a reminder to my calendar.
Sounds like a plan to me.
If it helps on 5.11 plans, converting this file to ReST format is quite
trivial: it just needs to use "::" for C/asm code literal blocks, and
to replace "(*) " by something that matches ReST syntax for lists,
like "(#) " or just "* ":
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bullet-lists
See enclosed.
Thanks,
Mauro
[PATCH] convert control-dependencies.rst to ReST
- Mark literal blocks as such;
- Use a numbered list at the summary.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
diff --git a/tools/memory-model/Documentation/control-dependencies.rst b/tools/memory-model/Documentation/control-dependencies.rst
index 366520cac937..52dc6a5bc173 100644
--- a/tools/memory-model/Documentation/control-dependencies.rst
+++ b/tools/memory-model/Documentation/control-dependencies.rst
@@ -7,7 +7,7 @@ the compiler's ignorance from breaking your code.
A load-load control dependency requires a full read memory barrier, not
simply a data dependency barrier to make it work correctly. Consider the
-following bit of code:
+following bit of code::
q = READ_ONCE(a);
if (q) {
@@ -19,7 +19,7 @@ This will not have the desired effect because there is no actual data
dependency, but rather a control dependency that the CPU may short-circuit
by attempting to predict the outcome in advance, so that other CPUs see
the load from b as having happened before the load from a. In such a
-case what's actually required is:
+case what's actually required is::
q = READ_ONCE(a);
if (q) {
@@ -28,7 +28,7 @@ case what's actually required is:
}
However, stores are not speculated. This means that ordering -is- provided
-for load-store control dependencies, as in the following example:
+for load-store control dependencies, as in the following example::
q = READ_ONCE(a);
if (q) {
@@ -45,7 +45,7 @@ or, worse yet, convert the store into a check followed by a store.
Worse yet, if the compiler is able to prove (say) that the value of
variable "a" is always non-zero, it would be well within its rights
to optimize the original example by eliminating the "if" statement
-as follows:
+as follows::
q = a;
b = 1; /* BUG: Compiler and CPU can both reorder!!! */
@@ -53,7 +53,7 @@ as follows:
So don't leave out either the READ_ONCE() or the WRITE_ONCE().
It is tempting to try to enforce ordering on identical stores on both
-branches of the "if" statement as follows:
+branches of the "if" statement as follows::
q = READ_ONCE(a);
if (q) {
@@ -67,7 +67,7 @@ branches of the "if" statement as follows:
}
Unfortunately, current compilers will transform this as follows at high
-optimization levels:
+optimization levels::
q = READ_ONCE(a);
barrier();
@@ -85,7 +85,7 @@ Now there is no conditional between the load from "a" and the store to
The conditional is absolutely required, and must be present in the
assembly code even after all compiler optimizations have been applied.
Therefore, if you need ordering in this example, you need explicit
-memory barriers, for example, smp_store_release():
+memory barriers, for example, smp_store_release()::
q = READ_ONCE(a);
if (q) {
@@ -97,7 +97,7 @@ memory barriers, for example, smp_store_release():
}
In contrast, without explicit memory barriers, two-legged-if control
-ordering is guaranteed only when the stores differ, for example:
+ordering is guaranteed only when the stores differ, for example::
q = READ_ONCE(a);
if (q) {
@@ -113,7 +113,7 @@ proving the value of "a".
In addition, you need to be careful what you do with the local variable "q",
otherwise the compiler might be able to guess the value and again remove
-the needed conditional. For example:
+the needed conditional. For example::
q = READ_ONCE(a);
if (q % MAX) {
@@ -126,7 +126,7 @@ the needed conditional. For example:
If MAX is defined to be 1, then the compiler knows that (q % MAX) is
equal to zero, in which case the compiler is within its rights to
-transform the above code into the following:
+transform the above code into the following::
q = READ_ONCE(a);
WRITE_ONCE(b, 2);
@@ -137,7 +137,7 @@ between the load from variable "a" and the store to variable "b". It is
tempting to add a barrier(), but this does not help. The conditional
is gone, and the barrier won't bring it back. Therefore, if you are
relying on this ordering, you should make sure that MAX is greater than
-one, perhaps as follows:
+one, perhaps as follows::
q = READ_ONCE(a);
BUILD_BUG_ON(MAX <= 1); /* Order load from a with store to b. */
@@ -154,7 +154,7 @@ identical, as noted earlier, the compiler could pull this store outside
of the 'if' statement.
You must also be careful not to rely too much on boolean short-circuit
-evaluation. Consider this example:
+evaluation. Consider this example::
q = READ_ONCE(a);
if (q || 1 > 0)
@@ -162,7 +162,7 @@ evaluation. Consider this example:
Because the first condition cannot fault and the second condition is
always true, the compiler can transform this example as following,
-defeating control dependency:
+defeating control dependency::
q = READ_ONCE(a);
WRITE_ONCE(b, 1);
@@ -174,7 +174,7 @@ the compiler to use the results.
In addition, control dependencies apply only to the then-clause and
else-clause of the if-statement in question. In particular, it does
-not necessarily apply to code following the if-statement:
+not necessarily apply to code following the if-statement::
q = READ_ONCE(a);
if (q) {
@@ -189,7 +189,7 @@ compiler cannot reorder volatile accesses and also cannot reorder
the writes to "b" with the condition. Unfortunately for this line
of reasoning, the compiler might compile the two writes to "b" as
conditional-move instructions, as in this fanciful pseudo-assembly
-language:
+language::
ld r1,a
cmp r1,$0
@@ -213,14 +213,14 @@ for more information.
In summary:
- (*) Control dependencies can order prior loads against later stores.
+ (#) Control dependencies can order prior loads against later stores.
However, they do -not- guarantee any other sort of ordering:
Not prior loads against later loads, nor prior stores against
later anything. If you need these other forms of ordering,
use smp_rmb(), smp_wmb(), or, in the case of prior stores and
later loads, smp_mb().
- (*) If both legs of the "if" statement begin with identical stores to
+ (#) If both legs of the "if" statement begin with identical stores to
the same variable, then those stores must be ordered, either by
preceding both of them with smp_mb() or by using smp_store_release()
to carry out the stores. Please note that it is -not- sufficient
@@ -229,28 +229,28 @@ In summary:
destroy the control dependency while respecting the letter of the
barrier() law.
- (*) Control dependencies require at least one run-time conditional
+ (#) Control dependencies require at least one run-time conditional
between the prior load and the subsequent store, and this
conditional must involve the prior load. If the compiler is able
to optimize the conditional away, it will have also optimized
away the ordering. Careful use of READ_ONCE() and WRITE_ONCE()
can help to preserve the needed conditional.
- (*) Control dependencies require that the compiler avoid reordering the
+ (#) Control dependencies require that the compiler avoid reordering the
dependency into nonexistence. Careful use of READ_ONCE() or
atomic{,64}_read() can help to preserve your control dependency.
Please see the COMPILER BARRIER section for more information.
- (*) Control dependencies apply only to the then-clause and else-clause
+ (#) Control dependencies apply only to the then-clause and else-clause
of the if-statement containing the control dependency, including
any functions that these two clauses call. Control dependencies
do -not- apply to code following the if-statement containing the
control dependency.
- (*) Control dependencies pair normally with other types of barriers.
+ (#) Control dependencies pair normally with other types of barriers.
- (*) Control dependencies do -not- provide multicopy atomicity. If you
+ (#) Control dependencies do -not- provide multicopy atomicity. If you
need all the CPUs to see a given store at the same time, use smp_mb().
- (*) Compilers do not understand control dependencies. It is therefore
+ (#) Compilers do not understand control dependencies. It is therefore
your job to ensure that they do not break your code.
On Tue, Oct 13, 2020 at 12:38:36PM -0400, Alan Stern wrote:
> On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote:
> > On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote:
> > > - The sysfs.txt file was converted to ReST and renamed;
> > > - The control-dependencies.txt is not at
> > > Documentation/control-dependencies.txt. As it is at the
> > > same dir as the README file, which mentions it, just
> > > remove Documentation/.
> > >
> > > With that, ./scripts/documentation-file-ref-check script
> > > is now happy again for files under tools/.
> > >
> > > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> >
> > Queued for review and testing, likely target v5.11.
>
> Instead of changing the path in the README reference, shouldn't
> tools/memory-model/control-dependencies.txt be moved to its proper
> position in .../Documentation?
You are of course quite right. My thought is to let Mauro go ahead,
given his short deadline. We can then make this "git mv" change once
v5.10-rc1 comes out, given that it should have Mauro's patches. I have
added a reminder to my calendar.
Thanx, Paul
On Wed, 14 Oct 2020 09:56:03 +0200, Mauro Carvalho Chehab wrote:
> Em Tue, 13 Oct 2020 18:58:40 -0700
> "Paul E. McKenney" <[email protected]> escreveu:
>
>> On Tue, Oct 13, 2020 at 12:38:36PM -0400, Alan Stern wrote:
>>> On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote:
>>>> On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote:
>>>>> - The sysfs.txt file was converted to ReST and renamed;
>>>>> - The control-dependencies.txt is not at
>>>>> Documentation/control-dependencies.txt. As it is at the
>>>>> same dir as the README file, which mentions it, just
>>>>> remove Documentation/.
>>>>>
>>>>> With that, ./scripts/documentation-file-ref-check script
>>>>> is now happy again for files under tools/.
>>>>>
>>>>> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
>>>>
>>>> Queued for review and testing, likely target v5.11.
>>>
>>> Instead of changing the path in the README reference, shouldn't
>>> tools/memory-model/control-dependencies.txt be moved to its proper
>>> position in .../Documentation?
>>
>> You are of course quite right. My thought is to let Mauro go ahead,
>> given his short deadline. We can then make this "git mv" change once
>> v5.10-rc1 comes out, given that it should have Mauro's patches. I have
>> added a reminder to my calendar.
>
> Sounds like a plan to me.
>
>
> If it helps on 5.11 plans, converting this file to ReST format is quite
> trivial: it just needs to use "::" for C/asm code literal blocks, and
> to replace "(*) " by something that matches ReST syntax for lists,
> like "(#) " or just "* ":
>
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bullet-lists
>
> See enclosed.
I'm afraid conversion of LKMM documents to ReST is unlikely to happen
any time soon.
It should wait until such time comes when the auto markup tools become
clever enough and .rst files looks exactly the same as plain .txt files.
Am I asking too much? :-)
Thanks, Akira
>
> Thanks,
> Mauro
>
> [PATCH] convert control-dependencies.rst to ReST
>
[snip]
Em Tue, 13 Oct 2020 16:02:50 +0100
Matthew Wilcox <[email protected]> escreveu:
> On Tue, Oct 13, 2020 at 04:09:41PM +0200, Peter Zijlstra wrote:
> > On Tue, Oct 13, 2020 at 02:11:16PM +0100, Matthew Wilcox wrote:
> > > On Tue, Oct 13, 2020 at 02:52:06PM +0200, Peter Zijlstra wrote:
> > > > On Tue, Oct 13, 2020 at 02:14:31PM +0200, Mauro Carvalho Chehab wrote:
> > > > > + ===== ===================================================
> > > > > + ``.`` acquired while irqs disabled and not in irq context
> > > > > + ``-`` acquired in irq context
> > > > > + ``+`` acquired with irqs enabled
> > > > > + ``?`` acquired in irq context with irqs enabled.
> > > > > + ===== ===================================================
> > > >
> > > > NAK!
> > >
> > > You're seriously suggesting that:
> > >
> > > - === ===================================================
> > > - '.' acquired while irqs disabled and not in irq context
> > > - '-' acquired in irq context
> > > - '+' acquired with irqs enabled
> > > - '?' acquired in irq context with irqs enabled.
> > > - === ===================================================
> > > + ===== ===================================================
> > > + ``.`` acquired while irqs disabled and not in irq context
> > > + ``-`` acquired in irq context
> > > + ``+`` acquired with irqs enabled
> > > + ``?`` acquired in irq context with irqs enabled.
> > > + ===== ===================================================
> > >
> > > this change makes the lockdep docs less readable?
> >
> > Definitely makes it harder to read for me. My C trained eyes go WTF at
> > seeing it, which breaks the flow. ',' is a regular single character
> > constant, '','' a syntax error.
>
> OK, that's fair. 'a' is definitely a character constant. Perhaps
> the automarkup script can take care of this for us? We'd have to
> be careful not to catch anything we shouldn't've [1], but I'm sure
> there's a regex for it. Something like "\<'.'\>", perhaps?
I guess that this regex could work:
/\b\'\S\'\b/
would get this very specific case, or maybe even:
/\b\'\S+\'\b/
in order to get things like 'foo'.
Adding support for something like this at
Documentation/sphinx/automarkup.py should be trivial. However,
checking if this won't be doing anything wrong with the other existing
files can be painful.
Yet, there are 3 issues related to '.' character usage.
See, the first table is:
=== ===================================================
'.' acquired while irqs disabled and not in irq context
'-' acquired in irq context
'+' acquired with irqs enabled
'?' acquired in irq context with irqs enabled.
=== ===================================================
There, it uses '.' in order to indicate the dot character and so on.
The second table uses a different notation:
+--------------+-------------+--------------+
| | irq enabled | irq disabled |
+--------------+-------------+--------------+
| ever in irq | ? | - |
+--------------+-------------+--------------+
| never in irq | + | . |
+--------------+-------------+--------------+
which uses just a question mark without aphostrophes, instead of
'?' (and the same for the other symbols).
The text describing them returns back to the notation used at the
first table:
"The character '-' suggests irq is disabled because if otherwise the
charactor '?' would have been shown instead. Similar deduction can be
applied for '+' too."
-
The above has actually 3 separate problems:
1) This problem has nothing to do with Sphinx notation. The notation
is not coherent: It should use either ., ``.`` or '.' everywhere.
2) This is Sphinx-specific: a single minus or a single plus character
indicates a list. On both cases, this is actually replaced by an UTF-8
bullet character: '•'.
3) This is a minor issue:
using '.' will produce an html table that will display, using
a normal font, as '.', while ``.`` would use a monospaced
font and won't display the apostrophes. IMO, at the html output,
it would be better to just a dot without apostrophes, as the
text of the dmesg output doesn't have apostrophes either:
"When locking rules are violated, these usage bits are presented in the
locking error messages, inside curlies, with a total of 2 * n STATEs bits.
A contrived example::
modprobe/2287 is trying to acquire lock:
(&sio_locks[i].lock){-.-.}, at: [<c02867fd>] mutex_lock+0x21/0x24
but task is already holding lock:
(&sio_locks[i].lock){-.-.}, at: [<c02867fd>] mutex_lock+0x21/0x24"
Yet, we could live without addressing this one.
> [1] I'm quite proud of that one.
>
> > > It's not the markup that makes the lockdep documentation hard to
> > > understand.
> >
> > I'm not sure what you're alluding to, the subject just isn't easy to
> > begin with.
>
> Absolutely. The problem is (similar to most Linux documentation)
> the document doesn't know who its audience is. It mixes internal
> implementation details of lockdep with what people need to know who
> are just trying to understand what a lockdep splat means. I don't
> have time to restructure it right now though.
Yeah, that is one of the the main issues with this. This specific
section of the file describes something that a sysadmin or a Kernel
newbie may see on his system. He'll likely seek the web for some
documentation about that, in order to try to understand it.
If someone is willing to do that, it will get this:
https://www.kernel.org/doc/html/latest/locking/lockdep-design.html#state
Where it presents a plain wrong table that it would look like this:
+--------------+-------------+--------------+
| | irq enabled | irq disabled |
+--------------+-------------+--------------+
| ever in irq | ? | • |
+--------------+-------------+--------------+
| never in irq | • | . |
+--------------+-------------+--------------+
If you prefer, I can send a new version of this patch using this at
the second table:
+--------------+-------------+--------------+
| | irq enabled | irq disabled |
+--------------+-------------+--------------+
| ever in irq | '?' | '-' |
+--------------+-------------+--------------+
| never in irq | '+' | '.' |
+--------------+-------------+--------------+
and keep using '.' at the other parts of the document.
This should solve the Sphinx issue, although the Sphinx output
won't be using a monospaced font.
Thanks,
Mauro
On Tue, Oct 13, 2020 at 06:58:40PM -0700, Paul E. McKenney wrote:
> On Tue, Oct 13, 2020 at 12:38:36PM -0400, Alan Stern wrote:
> > On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote:
> > > On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote:
> > > > - The sysfs.txt file was converted to ReST and renamed;
> > > > - The control-dependencies.txt is not at
> > > > Documentation/control-dependencies.txt. As it is at the
> > > > same dir as the README file, which mentions it, just
> > > > remove Documentation/.
> > > >
> > > > With that, ./scripts/documentation-file-ref-check script
> > > > is now happy again for files under tools/.
> > > >
> > > > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> > >
> > > Queued for review and testing, likely target v5.11.
> >
> > Instead of changing the path in the README reference, shouldn't
> > tools/memory-model/control-dependencies.txt be moved to its proper
> > position in .../Documentation?
>
> You are of course quite right. My thought is to let Mauro go ahead,
> given his short deadline. We can then make this "git mv" change once
> v5.10-rc1 comes out, given that it should have Mauro's patches. I have
> added a reminder to my calendar.
Except that I cannot find a commit where control-dependencies.txt is
in tools/memory-model. And this file is not yet in mainline, but
only in -rcu and -next. In both places, it is here:
tools/memory-model/Documentation/control-dependencies.txt
Mauro, to what commit in what tree are you applying this patch?
Thanx, Paul
Em Wed, 14 Oct 2020 23:14:00 +0900
Akira Yokosawa <[email protected]> escreveu:
> On Wed, 14 Oct 2020 09:56:03 +0200, Mauro Carvalho Chehab wrote:
> > Em Tue, 13 Oct 2020 18:58:40 -0700
> > "Paul E. McKenney" <[email protected]> escreveu:
> >
> >> On Tue, Oct 13, 2020 at 12:38:36PM -0400, Alan Stern wrote:
> >>> On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote:
> >>>> On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote:
> >>>>> - The sysfs.txt file was converted to ReST and renamed;
> >>>>> - The control-dependencies.txt is not at
> >>>>> Documentation/control-dependencies.txt. As it is at the
> >>>>> same dir as the README file, which mentions it, just
> >>>>> remove Documentation/.
> >>>>>
> >>>>> With that, ./scripts/documentation-file-ref-check script
> >>>>> is now happy again for files under tools/.
> >>>>>
> >>>>> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> >>>>
> >>>> Queued for review and testing, likely target v5.11.
> >>>
> >>> Instead of changing the path in the README reference, shouldn't
> >>> tools/memory-model/control-dependencies.txt be moved to its proper
> >>> position in .../Documentation?
> >>
> >> You are of course quite right. My thought is to let Mauro go ahead,
> >> given his short deadline. We can then make this "git mv" change once
> >> v5.10-rc1 comes out, given that it should have Mauro's patches. I have
> >> added a reminder to my calendar.
> >
> > Sounds like a plan to me.
> >
> >
> > If it helps on 5.11 plans, converting this file to ReST format is quite
> > trivial: it just needs to use "::" for C/asm code literal blocks, and
> > to replace "(*) " by something that matches ReST syntax for lists,
> > like "(#) " or just "* ":
> >
> > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bullet-lists
> >
> > See enclosed.
>
> I'm afraid conversion of LKMM documents to ReST is unlikely to happen
> any time soon.
> It should wait until such time comes when the auto markup tools become
> clever enough and .rst files looks exactly the same as plain .txt files.
>
> Am I asking too much? :-)
>
> Thanks, Akira
Yes :-)
$ git log --author [email protected] Documentation/sphinx
$
The auto markup tools don't write themselves alone. Someone needs
to write them and test if no regressions will happen with the existing
documents.
-
That's said, I suspect that one of the hardest things for something
like that to be possible is to be able to distinguish something
like:
(some text)
From something like:
/* some C code snippet or bash script, or other literal block */
So, at least "::" (or some other markup replacing it) is needed.
If you have some bright idea about how to implement it, feel free
to contribute with patches.
Thanks,
Mauro
On 10/13/20 6:14 AM, Mauro Carvalho Chehab wrote:
> Changeset 37a0dbf631f6 ("counters: Introduce counter_atomic* counters")
>
> Is causing two new warnings:
>
> .../Documentation/core-api/counters.rst:8: WARNING: Undefined substitution referenced: "copy".
> .../Documentation/core-api/counters.rst:9: WARNING: Undefined substitution referenced: "copy".
>
> Because it forgot to include isonum.txt, which defines |copy|
> macro.
>
> While here, also add it to core-api index file, in order to
> solve this warning:
>
> .../Documentation/core-api/counters.rst: WARNING: document isn't included in any toctree
>
> Fixes: 37a0dbf631f6 ("counters: Introduce counter_atomic* counters")
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> Documentation/core-api/counters.rst | 1 +
> Documentation/core-api/index.rst | 1 +
> 2 files changed, 2 insertions(+)
>
> diff --git a/Documentation/core-api/counters.rst b/Documentation/core-api/counters.rst
> index 642d907f4d3a..2821aebf3f45 100644
> --- a/Documentation/core-api/counters.rst
> +++ b/Documentation/core-api/counters.rst
> @@ -1,4 +1,5 @@
> .. SPDX-License-Identifier: GPL-2.0
> +.. include:: <isonum.txt>
>
> ======================
> Simple atomic counters
> diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
> index 69171b1799f2..cf9cd44c1191 100644
> --- a/Documentation/core-api/index.rst
> +++ b/Documentation/core-api/index.rst
> @@ -43,6 +43,7 @@ Library functionality that is used throughout the kernel.
> this_cpu_ops
> timekeeping
> errseq
> + counters
>
> Concurrency primitives
> ======================
>
Thank you for the patch. I will add this to my patch series.
thanks,
-- Shuah
Hi Paul,
Em Wed, 14 Oct 2020 11:57:20 -0700
"Paul E. McKenney" <[email protected]> escreveu:
> On Tue, Oct 13, 2020 at 06:58:40PM -0700, Paul E. McKenney wrote:
> > On Tue, Oct 13, 2020 at 12:38:36PM -0400, Alan Stern wrote:
> > > On Tue, Oct 13, 2020 at 09:33:54AM -0700, Paul E. McKenney wrote:
> > > > On Tue, Oct 13, 2020 at 02:14:29PM +0200, Mauro Carvalho Chehab wrote:
> > > > > - The sysfs.txt file was converted to ReST and renamed;
> > > > > - The control-dependencies.txt is not at
> > > > > Documentation/control-dependencies.txt. As it is at the
> > > > > same dir as the README file, which mentions it, just
> > > > > remove Documentation/.
> > > > >
> > > > > With that, ./scripts/documentation-file-ref-check script
> > > > > is now happy again for files under tools/.
> > > > >
> > > > > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> > > >
> > > > Queued for review and testing, likely target v5.11.
> > >
> > > Instead of changing the path in the README reference, shouldn't
> > > tools/memory-model/control-dependencies.txt be moved to its proper
> > > position in .../Documentation?
> >
> > You are of course quite right. My thought is to let Mauro go ahead,
> > given his short deadline.
I guess there might be some misunderstanding here. My fault. The plan
is to have zero doc warnings for 5.10[1].
In order to get there, The patches for it were split on two series,
both for 5.10:
- The /80 series with patches that already applies on the top of master;
- This /24 patch series, which depends on trees that weren't merged
upstream yet (back on Oct, 13). Those applies on the top of
next-20201013.
I'm intending to submit later today (after next-20201015) a PR with
patches from the /80 series.
The remaining ones should be sent as a late pull request by the end
of the merge window, if the patch that caused the issue gets merged
for 5.10. That's the case of this patch.
[1] With Sphinx < 3. Sphinx 3 and above brings some additional
warnings that depends on a fix at the toolset. The fixup patches
for Sphinx were proposed yesterday by the Sphinx maintainer
of the C domain parser. More details can be seen here:
https://github.com/sphinx-doc/sphinx/pull/8313
> > We can then make this "git mv" change once
> > v5.10-rc1 comes out, given that it should have Mauro's patches. I have
> > added a reminder to my calendar.
>
> Except that I cannot find a commit where control-dependencies.txt is
> in tools/memory-model. And this file is not yet in mainline, but
> only in -rcu and -next. In both places, it is here:
>
> tools/memory-model/Documentation/control-dependencies.txt
>
> Mauro, to what commit in what tree are you applying this patch?
This is against next-20201013. The specific commit adding
README and control-dependencies.txt is this one:
commit d34a972f67252457158122e5ba7a0ce5ece62067
Author: Paul E. McKenney <[email protected]>
AuthorDate: Tue Aug 11 11:27:33 2020 -0700
Commit: Paul E. McKenney <[email protected]>
CommitDate: Sun Oct 4 17:21:31 2020 -0700
tools/memory-model: Document categories of ordering primitives
The Linux kernel has a number of categories of ordering primitives, which
are recorded in the LKMM implementation and hinted at by cheatsheet.txt.
But there is no overview of these categories, and such an overview
is needed in order to understand multithreaded LKMM litmus tests.
This commit therefore adds an ordering.txt as well as extracting a
control-dependencies.txt from memory-barriers.txt. It also updates the
README file.
[ paulmck: Apply Akira Yokosawa file-placement feedback. ]
[ paulmck: Apply Alan Stern feedback. ]
Signed-off-by: Paul E. McKenney <[email protected]>
Btw, after re-checking the patch, I would drop this hunk:
diff --git a/tools/memory-model/Documentation/README b/tools/memory-model/Documentation/README
index 16177aaa9752..004969992bac 100644
--- a/tools/memory-model/Documentation/README
+++ b/tools/memory-model/Documentation/README
@@ -55,7 +55,7 @@ README
Documentation/cheatsheet.txt
Quick-reference guide to the Linux-kernel memory model.
-Documentation/control-dependencies.txt
+control-dependencies.txt
A guide to preventing compiler optimizations from destroying
your control dependencies.
The ./scripts/documentation-file-ref-check doesn't complain about
broken references for Documentation/ files outside the main
docs dir. So, this hunk is not really needed to fix warnings with
5.10. Besides that, there are other references to those files:
$ git grep Documentation tools/memory-model/Documentation/README
tools/memory-model/Documentation/README:tools/memory-model/Documentation directory. It has been said that at
tools/memory-model/Documentation/README:Documentation/cheatsheet.txt
tools/memory-model/Documentation/README:Documentation/control-dependencies.txt
tools/memory-model/Documentation/README:Documentation/explanation.txt
tools/memory-model/Documentation/README:Documentation/litmus-tests.txt
tools/memory-model/Documentation/README:Documentation/ordering.txt
tools/memory-model/Documentation/README:Documentation/recipes.txt
tools/memory-model/Documentation/README:Documentation/references.txt
tools/memory-model/Documentation/README:Documentation/simple.txt
That also refer to the files inside tools/memory-model/Documentation/.
So, they should ether all be replaced to just the file name without
the directory (IMHO, that makes more sense) or kept as-is.
In any case, for 5.10, all we need is to fix this reference:
Documentation/RCU/rcu_dereference.txt -> Documentation/RCU/rcu_dereference.rst
Also, the patch description is wrong. I suspect that, when this patch
was originally written, there were more hunks being touched, but
fixes for everything else were already merged. So, the only thing that
is left is the above change.
It follows a new version. feel free to either pick (or merge) this one at
the same tree as tools/memory-model/Documentation/ordering.txt if you
think that this works best for you.
Otherwise, I'll keep this on my -next tree together with this series,
aiming to submit by the end of the merge window, if ordering.txt gets
merged for 5.10.
Thanks,
Mauro
[PATCH v2.1 02/24] tools/memory-model: fix a broken doc reference
Documentation/RCU/rcu_dereference.txt -> Documentation/RCU/rcu_dereference.rst
Fixes: d34a972f6725 ("tools/memory-model: Document categories of ordering primitives")
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
diff --git a/tools/memory-model/Documentation/ordering.txt b/tools/memory-model/Documentation/ordering.txt
index 3d020bed8585..629b19ae64a6 100644
--- a/tools/memory-model/Documentation/ordering.txt
+++ b/tools/memory-model/Documentation/ordering.txt
@@ -346,7 +346,7 @@ o Accessing RCU-protected pointers via rcu_dereference()
If there is any significant processing of the pointer value
between the rcu_dereference() that returned it and a later
- dereference(), please read Documentation/RCU/rcu_dereference.txt.
+ dereference(), please read Documentation/RCU/rcu_dereference.rst.
It can also be quite helpful to review uses in the Linux kernel.
On Thu, Oct 15, 2020 at 07:15:18AM +0200, Mauro Carvalho Chehab wrote:
> I guess there might be some misunderstanding here. My fault. The plan
> is to have zero doc warnings for 5.10[1].
I'd be glad to help and convert all the documentation under my
maintainership to .txt files for you.
On Tue, Oct 13, 2020 at 02:14:50PM +0200, Mauro Carvalho Chehab wrote:
> Changeset 54816d3e69d1 ("RDMA: Explicitly pass in the dma_device to ib_register_device")
> added a new parameter to ib_register_device().
>
> Document it.
>
> Fixes: 54816d3e69d1 ("RDMA: Explicitly pass in the dma_device to ib_register_device")
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> drivers/infiniband/core/device.c | 5 ++++-
> 1 file changed, 4 insertions(+), 1 deletion(-)
This is in linux-next, not Linus's tree.
I've fixed it up in the rdma tree
Thanks,
Jason
Hi Matthew,
Em Tue, 13 Oct 2020 13:26:54 +0100
Matthew Wilcox <[email protected]> escreveu:
> On Tue, Oct 13, 2020 at 02:14:37PM +0200, Mauro Carvalho Chehab wrote:
> > Changeset 6c8adf8446a3 ("mm: add find_lock_head") renamed the
> > index parameter, but forgot to update the kernel-doc markups
> > accordingly.
>
> The patch is correct (thank you!), but the description here references
> a git commit id that's only found in the -next tree and is unstable.
>
> Andrew, can you fold this into the offending commit?
Patch already reached upstream. So, it gained a stable reference.
So, I'm changing its description to:
Author: Mauro Carvalho Chehab <[email protected]>
Date: Thu Sep 10 08:38:07 2020 +0200
locking/refcount: move kernel-doc markups to the proper place
Changeset a435b9a14356 ("locking/refcount: Provide __refcount API to obtain the old value")
added a set of functions starting with __ that have a new
parameter, adding a series of new warnings:
$ ./scripts/kernel-doc -none include/linux/refcount.h
include/linux/refcount.h:169: warning: Function parameter or member 'oldp' not described in '__refcount_add_not_zero'
include/linux/refcount.h:208: warning: Function parameter or member 'oldp' not described in '__refcount_add'
include/linux/refcount.h:239: warning: Function parameter or member 'oldp' not described in '__refcount_inc_not_zero'
include/linux/refcount.h:261: warning: Function parameter or member 'oldp' not described in '__refcount_inc'
include/linux/refcount.h:291: warning: Function parameter or member 'oldp' not described in '__refcount_sub_and_test'
include/linux/refcount.h:327: warning: Function parameter or member 'oldp' not described in '__refcount_dec_and_test'
include/linux/refcount.h:347: warning: Function parameter or member 'oldp' not described in '__refcount_dec'
The issue is that the kernel-doc markups are now misplaced,
as they should be added just before the functions.
So, move the kernel-doc markups to the proper places,
in order to drop the warnings.
It should be noticed that git show produces a crappy output,
for this patch without "--patience" flag.
Fixes: a435b9a14356 ("locking/refcount: Provide __refcount API to obtain the old value")
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
If ok for you, I should be sending it upstream on a next pull request
for the documentation warning fix series.
Regards,
Mauro
>
> > Fixes: 6c8adf8446a3 ("mm: add find_lock_head")
> > Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> > ---
> > include/linux/pagemap.h | 8 ++++----
> > 1 file changed, 4 insertions(+), 4 deletions(-)
> >
> > diff --git a/include/linux/pagemap.h b/include/linux/pagemap.h
> > index 7dd3523093db..932a260a29f2 100644
> > --- a/include/linux/pagemap.h
> > +++ b/include/linux/pagemap.h
> > @@ -342,9 +342,9 @@ static inline struct page *find_get_page_flags(struct address_space *mapping,
> > /**
> > * find_lock_page - locate, pin and lock a pagecache page
> > * @mapping: the address_space to search
> > - * @offset: the page index
> > + * @index: the page index
> > *
> > - * Looks up the page cache entry at @mapping & @offset. If there is a
> > + * Looks up the page cache entry at @mapping & @index. If there is a
> > * page cache page, it is returned locked and with an increased
> > * refcount.
> > *
> > @@ -361,9 +361,9 @@ static inline struct page *find_lock_page(struct address_space *mapping,
> > /**
> > * find_lock_head - Locate, pin and lock a pagecache page.
> > * @mapping: The address_space to search.
> > - * @offset: The page index.
> > + * @index: The page index.
> > *
> > - * Looks up the page cache entry at @mapping & @offset. If there is a
> > + * Looks up the page cache entry at @mapping & @index. If there is a
> > * page cache page, its head page is returned locked and with an increased
> > * refcount.
> > *
> > --
> > 2.26.2
> >
Thanks,
Mauro
On Wed, Oct 21, 2020 at 11:55:57AM +0200, Mauro Carvalho Chehab wrote:
> Hi Matthew,
>
> Em Tue, 13 Oct 2020 13:26:54 +0100
> Matthew Wilcox <[email protected]> escreveu:
>
> > On Tue, Oct 13, 2020 at 02:14:37PM +0200, Mauro Carvalho Chehab wrote:
> > > Changeset 6c8adf8446a3 ("mm: add find_lock_head") renamed the
> > > index parameter, but forgot to update the kernel-doc markups
> > > accordingly.
> >
> > The patch is correct (thank you!), but the description here references
> > a git commit id that's only found in the -next tree and is unstable.
> >
> > Andrew, can you fold this into the offending commit?
>
> Patch already reached upstream. So, it gained a stable reference.
>
> So, I'm changing its description to:
>
> Author: Mauro Carvalho Chehab <[email protected]>
> Date: Thu Sep 10 08:38:07 2020 +0200
>
> locking/refcount: move kernel-doc markups to the proper place
This is the wrong changelog?
Em Wed, 21 Oct 2020 12:28:19 +0100
Matthew Wilcox <[email protected]> escreveu:
> On Wed, Oct 21, 2020 at 11:55:57AM +0200, Mauro Carvalho Chehab wrote:
> > Hi Matthew,
> >
> > Em Tue, 13 Oct 2020 13:26:54 +0100
> > Matthew Wilcox <[email protected]> escreveu:
> >
> > > On Tue, Oct 13, 2020 at 02:14:37PM +0200, Mauro Carvalho Chehab wrote:
> > > > Changeset 6c8adf8446a3 ("mm: add find_lock_head") renamed the
> > > > index parameter, but forgot to update the kernel-doc markups
> > > > accordingly.
> > >
> > > The patch is correct (thank you!), but the description here references
> > > a git commit id that's only found in the -next tree and is unstable.
> > >
> > > Andrew, can you fold this into the offending commit?
> >
> > Patch already reached upstream. So, it gained a stable reference.
> >
> > So, I'm changing its description to:
> >
> > Author: Mauro Carvalho Chehab <[email protected]>
> > Date: Thu Sep 10 08:38:07 2020 +0200
> >
> > locking/refcount: move kernel-doc markups to the proper place
>
> This is the wrong changelog?
Sorry! Yeah, that was the wrong one. I'm enclosing the right one
with the complete patch.
Thanks,
Mauro
[PATCH] mm: pagemap.h: fix two kernel-doc markups
Changeset a8cf7f272b5a ("mm: add find_lock_head") renamed the
index parameter, but forgot to update the kernel-doc markups
accordingly.
Fixes: a8cf7f272b5a ("mm: add find_lock_head")
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
diff --git a/include/linux/pagemap.h b/include/linux/pagemap.h
index c77b7c31b2e4..e1e19c1f9ec9 100644
--- a/include/linux/pagemap.h
+++ b/include/linux/pagemap.h
@@ -344,9 +344,9 @@ static inline struct page *find_get_page_flags(struct address_space *mapping,
/**
* find_lock_page - locate, pin and lock a pagecache page
* @mapping: the address_space to search
- * @offset: the page index
+ * @index: the page index
*
- * Looks up the page cache entry at @mapping & @offset. If there is a
+ * Looks up the page cache entry at @mapping & @index. If there is a
* page cache page, it is returned locked and with an increased
* refcount.
*
@@ -363,9 +363,9 @@ static inline struct page *find_lock_page(struct address_space *mapping,
/**
* find_lock_head - Locate, pin and lock a pagecache page.
* @mapping: The address_space to search.
- * @offset: The page index.
+ * @index: The page index.
*
- * Looks up the page cache entry at @mapping & @offset. If there is a
+ * Looks up the page cache entry at @mapping & @index. If there is a
* page cache page, its head page is returned locked and with an increased
* refcount.
*
On Wed, Oct 21, 2020 at 01:59:03PM +0200, Mauro Carvalho Chehab wrote:
> [PATCH] mm: pagemap.h: fix two kernel-doc markups
>
> Changeset a8cf7f272b5a ("mm: add find_lock_head") renamed the
> index parameter, but forgot to update the kernel-doc markups
> accordingly.
>
> Fixes: a8cf7f272b5a ("mm: add find_lock_head")
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Matthew Wilcox (Oracle) <[email protected]>