[PATCH v2 00/15] Documentation fixes

[PATCH v2 00/15] Documentation fixes

[Mauro Carvalho Chehab]

Hi Jon,

As requested, this is a rebase of a previous series posted on Jan, 15.

Since then, several patches got merged via other trees or became
obsolete. There were also 2 patches before that fits better at the
ReST conversion patchset. So, I'll be sending it on another patch
series together with the remaining ReST conversions.

I also added reviews/acks received.

So, the series reduced from 29 to 15 patches.

Let's hope b4 would be able to properly handle this one.

Regards,
Mauro

Mauro Carvalho Chehab (15):
  mm: vmalloc.c: remove a kernel-doc annotation from a removed parameter
  net: dev: add a missing kernel-doc annotation
  net: netdevice.h: add a description for napi_defer_hard_irqs
  scripts/kernel-doc: parse __ETHTOOL_DECLARE_LINK_MODE_MASK
  net: pylink.h: add kernel-doc descriptions for new fields at
    phylink_config
  scripts/kernel-doc: handle function pointer prototypes
  fs: fs.h: fix a kernel-doc parameter description
  kcsan: fix a kernel-doc warning
  selftests/vm/keys: fix a broken reference at protection_keys.c
  docs: hugetlbpage.rst: fix some warnings
  docs: powerpc: fix some issues at vas-api.rst
  docs: driver-model: remove a duplicated markup at driver.rst
  docs: ABI: fix a typo when pointing to w1-generic.rst
  docs: fix references for DMA*.txt files
  docs: fs: proc.rst: convert a new chapter to ReST

 .../ABI/testing/sysfs-driver-w1_therm         |  2 +-
 Documentation/PCI/pci.rst                     |  6 +--
 Documentation/admin-guide/mm/hugetlbpage.rst  | 23 +++++++---
 Documentation/block/biodoc.rst                |  2 +-
 Documentation/bus-virt-phys-mapping.txt       |  2 +-
 Documentation/core-api/dma-api.rst            |  6 +--
 Documentation/core-api/dma-isa-lpc.rst        |  2 +-
 .../driver-api/driver-model/driver.rst        |  2 -
 Documentation/driver-api/usb/dma.rst          |  6 +--
 Documentation/filesystems/proc.rst            | 44 +++++++++----------
 Documentation/powerpc/vas-api.rst             | 23 +++++++---
 .../translations/ko_KR/memory-barriers.txt    |  6 +--
 arch/ia64/hp/common/sba_iommu.c               | 12 ++---
 arch/parisc/kernel/pci-dma.c                  |  2 +-
 arch/x86/include/asm/dma-mapping.h            |  4 +-
 arch/x86/kernel/amd_gart_64.c                 |  2 +-
 drivers/parisc/sba_iommu.c                    | 14 +++---
 include/linux/dma-mapping.h                   |  2 +-
 include/linux/fs.h                            |  2 +-
 include/linux/kcsan-checks.h                  | 10 +++--
 include/linux/netdevice.h                     |  2 +
 include/linux/phylink.h                       |  4 ++
 include/media/videobuf-dma-sg.h               |  2 +-
 kernel/dma/debug.c                            |  2 +-
 mm/vmalloc.c                                  |  1 -
 net/core/dev.c                                |  1 +
 scripts/kernel-doc                            |  7 +++
 tools/testing/selftests/vm/protection_keys.c  |  2 +-
 28 files changed, 114 insertions(+), 79 deletions(-)

-- 
2.26.2

[PATCH v2 01/15] mm: vmalloc.c: remove a kernel-doc annotation from a removed parameter

[Mauro Carvalho Chehab]

The prot argument was removed. Drop it als from the kernel-doc
markup.

Fixes: 3c8ce1be43d3 ("mm: remove the prot argument from vm_map_ram")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 mm/vmalloc.c | 1 -
 1 file changed, 1 deletion(-)

diff --git a/mm/vmalloc.c b/mm/vmalloc.c
index 963db1037f61..c3b3f94e08da 100644
--- a/mm/vmalloc.c
+++ b/mm/vmalloc.c
@@ -1809,7 +1809,6 @@ EXPORT_SYMBOL(vm_unmap_ram);
  * @pages: an array of pointers to the pages to be mapped
  * @count: number of pages
  * @node: prefer to allocate data structures on this node
- * @prot: memory protection to use. PAGE_KERNEL for regular RAM
  *
  * If you use this function for less than VMAP_MAX_ALLOC pages, it could be
  * faster than vmap so it's good.  But if you mix long-life and short-life
-- 
2.26.2

[PATCH v2 10/15] docs: hugetlbpage.rst: fix some warnings

[Mauro Carvalho Chehab]

Some new command line parameters were added at hugetlbpage.rst.
Adjust them in order to properly parse that part of the file,
avoiding those warnings:

    Documentation/admin-guide/mm/hugetlbpage.rst:105: WARNING: Unexpected indentation.
    Documentation/admin-guide/mm/hugetlbpage.rst:108: WARNING: Unexpected indentation.
    Documentation/admin-guide/mm/hugetlbpage.rst:109: WARNING: Block quote ends without a blank line; unexpected unindent.
    Documentation/admin-guide/mm/hugetlbpage.rst:112: WARNING: Block quote ends without a blank line; unexpected unindent.
    Documentation/admin-guide/mm/hugetlbpage.rst:120: WARNING: Unexpected indentation.
    Documentation/admin-guide/mm/hugetlbpage.rst:121: WARNING: Block quote ends without a blank line; unexpected unindent.
    Documentation/admin-guide/mm/hugetlbpage.rst:132: WARNING: Unexpected indentation.
    Documentation/admin-guide/mm/hugetlbpage.rst:135: WARNING: Block quote ends without a blank line; unexpected unindent.

Fixes: cd9fa28b5351 ("hugetlbfs: clean up command line processing")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/admin-guide/mm/hugetlbpage.rst | 23 +++++++++++++++-----
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/Documentation/admin-guide/mm/hugetlbpage.rst b/Documentation/admin-guide/mm/hugetlbpage.rst
index 5026e58826e2..015a5f7d7854 100644
--- a/Documentation/admin-guide/mm/hugetlbpage.rst
+++ b/Documentation/admin-guide/mm/hugetlbpage.rst
@@ -101,37 +101,48 @@ be specified in bytes with optional scale suffix [kKmMgG].  The default huge
 page size may be selected with the "default_hugepagesz=<size>" boot parameter.
 
 Hugetlb boot command line parameter semantics
-hugepagesz - Specify a huge page size.  Used in conjunction with hugepages
+
+hugepagesz
+	Specify a huge page size.  Used in conjunction with hugepages
 	parameter to preallocate a number of huge pages of the specified
 	size.  Hence, hugepagesz and hugepages are typically specified in
-	pairs such as:
+	pairs such as::
+
 		hugepagesz=2M hugepages=512
+
 	hugepagesz can only be specified once on the command line for a
 	specific huge page size.  Valid huge page sizes are architecture
 	dependent.
-hugepages - Specify the number of huge pages to preallocate.  This typically
+hugepages
+	Specify the number of huge pages to preallocate.  This typically
 	follows a valid hugepagesz or default_hugepagesz parameter.  However,
 	if hugepages is the first or only hugetlb command line parameter it
 	implicitly specifies the number of huge pages of default size to
 	allocate.  If the number of huge pages of default size is implicitly
 	specified, it can not be overwritten by a hugepagesz,hugepages
 	parameter pair for the default size.
-	For example, on an architecture with 2M default huge page size:
+
+	For example, on an architecture with 2M default huge page size::
+
 		hugepages=256 hugepagesz=2M hugepages=512
+
 	will result in 256 2M huge pages being allocated and a warning message
 	indicating that the hugepages=512 parameter is ignored.  If a hugepages
 	parameter is preceded by an invalid hugepagesz parameter, it will
 	be ignored.
-default_hugepagesz - Specify the default huge page size.  This parameter can
+default_hugepagesz
+	pecify the default huge page size.  This parameter can
 	only be specified once on the command line.  default_hugepagesz can
 	optionally be followed by the hugepages parameter to preallocate a
 	specific number of huge pages of default size.  The number of default
 	sized huge pages to preallocate can also be implicitly specified as
 	mentioned in the hugepages section above.  Therefore, on an
-	architecture with 2M default huge page size:
+	architecture with 2M default huge page size::
+
 		hugepages=256
 		default_hugepagesz=2M hugepages=256
 		hugepages=256 default_hugepagesz=2M
+
 	will all result in 256 2M huge pages being allocated.  Valid default
 	huge page size is architecture dependent.
 
-- 
2.26.2

Re: [PATCH v2 10/15] docs: hugetlbpage.rst: fix some warnings

[Mike Kravetz]

On 6/23/20 12:09 AM, Mauro Carvalho Chehab wrote:
> Some new command line parameters were added at hugetlbpage.rst.
> Adjust them in order to properly parse that part of the file,
> avoiding those warnings:
> 
>     Documentation/admin-guide/mm/hugetlbpage.rst:105: WARNING: Unexpected indentation.
>     Documentation/admin-guide/mm/hugetlbpage.rst:108: WARNING: Unexpected indentation.
>     Documentation/admin-guide/mm/hugetlbpage.rst:109: WARNING: Block quote ends without a blank line; unexpected unindent.
>     Documentation/admin-guide/mm/hugetlbpage.rst:112: WARNING: Block quote ends without a blank line; unexpected unindent.
>     Documentation/admin-guide/mm/hugetlbpage.rst:120: WARNING: Unexpected indentation.
>     Documentation/admin-guide/mm/hugetlbpage.rst:121: WARNING: Block quote ends without a blank line; unexpected unindent.
>     Documentation/admin-guide/mm/hugetlbpage.rst:132: WARNING: Unexpected indentation.
>     Documentation/admin-guide/mm/hugetlbpage.rst:135: WARNING: Block quote ends without a blank line; unexpected unindent.
> 
> Fixes: cd9fa28b5351 ("hugetlbfs: clean up command line processing")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/admin-guide/mm/hugetlbpage.rst | 23 +++++++++++++++-----
>  1 file changed, 17 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/admin-guide/mm/hugetlbpage.rst b/Documentation/admin-guide/mm/hugetlbpage.rst
> index 5026e58826e2..015a5f7d7854 100644
> --- a/Documentation/admin-guide/mm/hugetlbpage.rst
> +++ b/Documentation/admin-guide/mm/hugetlbpage.rst
> @@ -101,37 +101,48 @@ be specified in bytes with optional scale suffix [kKmMgG].  The default huge
>  page size may be selected with the "default_hugepagesz=<size>" boot parameter.
>  
>  Hugetlb boot command line parameter semantics
> -hugepagesz - Specify a huge page size.  Used in conjunction with hugepages
> +
> +hugepagesz
> +	Specify a huge page size.  Used in conjunction with hugepages
>  	parameter to preallocate a number of huge pages of the specified
>  	size.  Hence, hugepagesz and hugepages are typically specified in
> -	pairs such as:
> +	pairs such as::
> +
>  		hugepagesz=2M hugepages=512
> +
>  	hugepagesz can only be specified once on the command line for a
>  	specific huge page size.  Valid huge page sizes are architecture
>  	dependent.
> -hugepages - Specify the number of huge pages to preallocate.  This typically
> +hugepages
> +	Specify the number of huge pages to preallocate.  This typically
>  	follows a valid hugepagesz or default_hugepagesz parameter.  However,
>  	if hugepages is the first or only hugetlb command line parameter it
>  	implicitly specifies the number of huge pages of default size to
>  	allocate.  If the number of huge pages of default size is implicitly
>  	specified, it can not be overwritten by a hugepagesz,hugepages
>  	parameter pair for the default size.
> -	For example, on an architecture with 2M default huge page size:
> +
> +	For example, on an architecture with 2M default huge page size::
> +
>  		hugepages=256 hugepagesz=2M hugepages=512
> +
>  	will result in 256 2M huge pages being allocated and a warning message
>  	indicating that the hugepages=512 parameter is ignored.  If a hugepages
>  	parameter is preceded by an invalid hugepagesz parameter, it will
>  	be ignored.
> -default_hugepagesz - Specify the default huge page size.  This parameter can
> +default_hugepagesz
> +	pecify the default huge page size.  This parameter can

Oops, should be 'Specify' not 'pecify'

Other than that, this looks good.  Thanks!
-- 
Mike Kravetz

>  	only be specified once on the command line.  default_hugepagesz can
>  	optionally be followed by the hugepages parameter to preallocate a
>  	specific number of huge pages of default size.  The number of default
>  	sized huge pages to preallocate can also be implicitly specified as
>  	mentioned in the hugepages section above.  Therefore, on an
> -	architecture with 2M default huge page size:
> +	architecture with 2M default huge page size::
> +
>  		hugepages=256
>  		default_hugepagesz=2M hugepages=256
>  		hugepages=256 default_hugepagesz=2M
> +
>  	will all result in 256 2M huge pages being allocated.  Valid default
>  	huge page size is architecture dependent.
>  
> 

Re: [PATCH v2 00/15] Documentation fixes

[Jonathan Corbet]

On Tue, 23 Jun 2020 09:08:56 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> As requested, this is a rebase of a previous series posted on Jan, 15.
> 
> Since then, several patches got merged via other trees or became
> obsolete. There were also 2 patches before that fits better at the
> ReST conversion patchset. So, I'll be sending it on another patch
> series together with the remaining ReST conversions.
> 
> I also added reviews/acks received.
> 
> So, the series reduced from 29 to 15 patches.
> 
> Let's hope b4 would be able to properly handle this one.

Nope.  I don't know what it is about your patch series, but b4 is never
able to put them together.

I've applied the series except for #1, which already went through the -mm
tree.

Thanks,

jon