[PATCH 00/34] fs: convert remaining docs to ReST file format

[PATCH 00/34] fs: convert remaining docs to ReST file format

[Mauro Carvalho Chehab]

This patch series convert the remaining files under Documentation/filesystems
to the ReST file format. It is based on linux-next (next-20200414).

PS.: I opted to add mainly ML from the output of get_maintainers.pl to the c/c
list of patch 00/34, because  otherwise the number of c/c would be too many,
with would very likely cause ML servers to reject it.

The results of those changes (together with other changes from my pending
doc patches) are available at:

   https://www.infradead.org/~mchehab/kernel_docs/filesystems/index.html

Mauro Carvalho Chehab (34):
  docs: filesystems: fix references for doc files there
  docs: filesystems: convert caching/object.txt to ReST
  docs: filesystems: convert caching/fscache.txt to ReST format
  docs: filesystems: caching/netfs-api.txt: convert it to ReST
  docs: filesystems: caching/operations.txt: convert it to ReST
  docs: filesystems: caching/cachefiles.txt: convert to ReST
  docs: filesystems: caching/backend-api.txt: convert it to ReST
  docs: filesystems: convert cifs/cifsroot.rst to ReST
  docs: filesystems: convert configfs.txt to ReST
  docs: filesystems: convert automount-support.txt to ReST
  docs: filesystems: convert coda.txt to ReST
  docs: filesystems: convert dax.txt to ReST
  docs: filesystems: convert devpts.txt to ReST
  docs: filesystems: convert dnotify.txt to ReST
  docs: filesystems: convert fiemap.txt to ReST
  docs: filesystems: convert files.txt to ReST
  docs: filesystems: convert fuse-io.txt to ReST
  docs: filesystems: convert gfs2-glocks.txt to ReST
  docs: filesystems: convert locks.txt to ReST
  docs: filesystems: convert mandatory-locking.txt to ReST
  docs: filesystems: convert mount_api.txt to ReST
  docs: filesystems: rename path-lookup.txt file
  docs: filesystems: convert path-walking.txt to ReST
  docs: filesystems: convert quota.txt to ReST
  docs: filesystems: convert seq_file.txt to ReST
  docs: filesystems: convert sharedsubtree.txt to ReST
  docs: filesystems: split spufs.txt into 3 separate files
  docs: filesystems: convert spufs/spu_create.txt to ReST
  docs: filesystems: convert spufs/spufs.txt to ReST
  docs: filesystems: convert spufs/spu_run.txt to ReST
  docs: filesystems: convert sysfs-pci.txt to ReST
  docs: filesystems: convert sysfs-tagging.txt to ReST
  docs: filesystems: convert xfs-delayed-logging-design.txt to ReST
  docs: filesystems: convert xfs-self-describing-metadata.txt to ReST

 Documentation/ABI/stable/sysfs-devices-node   |    2 +-
 Documentation/ABI/testing/procfs-smaps_rollup |    2 +-
 Documentation/admin-guide/cpu-load.rst        |    2 +-
 Documentation/admin-guide/ext4.rst            |    2 +-
 Documentation/admin-guide/nfs/nfsroot.rst     |    2 +-
 Documentation/admin-guide/sysctl/kernel.rst   |    2 +-
 .../driver-api/driver-model/device.rst        |    2 +-
 .../driver-api/driver-model/overview.rst      |    2 +-
 ...ount-support.txt => automount-support.rst} |   23 +-
 .../{backend-api.txt => backend-api.rst}      |  165 +-
 .../{cachefiles.txt => cachefiles.rst}        |  139 +-
 Documentation/filesystems/caching/fscache.rst |  565 ++++++
 Documentation/filesystems/caching/fscache.txt |  448 -----
 Documentation/filesystems/caching/index.rst   |   14 +
 .../caching/{netfs-api.txt => netfs-api.rst}  |  172 +-
 .../caching/{object.txt => object.rst}        |   43 +-
 .../{operations.txt => operations.rst}        |   45 +-
 .../cifs/{cifsroot.txt => cifsroot.rst}       |   56 +-
 Documentation/filesystems/coda.rst            | 1670 ++++++++++++++++
 Documentation/filesystems/coda.txt            | 1676 -----------------
 .../{configfs/configfs.txt => configfs.rst}   |  129 +-
 .../filesystems/{dax.txt => dax.rst}          |   11 +-
 Documentation/filesystems/devpts.rst          |   36 +
 Documentation/filesystems/devpts.txt          |   26 -
 .../filesystems/{dnotify.txt => dnotify.rst}  |   13 +-
 Documentation/filesystems/ext2.rst            |    2 +-
 .../filesystems/{fiemap.txt => fiemap.rst}    |  133 +-
 .../filesystems/{files.txt => files.rst}      |   15 +-
 .../filesystems/{fuse-io.txt => fuse-io.rst}  |    6 +
 .../{gfs2-glocks.txt => gfs2-glocks.rst}      |  147 +-
 Documentation/filesystems/index.rst           |   26 +
 .../filesystems/{locks.txt => locks.rst}      |   14 +-
 ...tory-locking.txt => mandatory-locking.rst} |   25 +-
 .../{mount_api.txt => mount_api.rst}          |  329 ++--
 .../{path-lookup.txt => path-walking.rst}     |   88 +-
 Documentation/filesystems/porting.rst         |    2 +-
 Documentation/filesystems/proc.rst            |    2 +-
 .../filesystems/{quota.txt => quota.rst}      |   41 +-
 .../filesystems/ramfs-rootfs-initramfs.rst    |    2 +-
 .../{seq_file.txt => seq_file.rst}            |   61 +-
 .../{sharedsubtree.txt => sharedsubtree.rst}  |  394 ++--
 Documentation/filesystems/spufs/index.rst     |   13 +
 .../filesystems/spufs/spu_create.rst          |  131 ++
 Documentation/filesystems/spufs/spu_run.rst   |  138 ++
 .../{spufs.txt => spufs/spufs.rst}            |  304 +--
 .../{sysfs-pci.txt => sysfs-pci.rst}          |   23 +-
 .../{sysfs-tagging.txt => sysfs-tagging.rst}  |   22 +-
 ...ign.txt => xfs-delayed-logging-design.rst} |   65 +-
 ...a.txt => xfs-self-describing-metadata.rst} |  182 +-
 Documentation/iio/iio_configfs.rst            |    2 +-
 .../powerpc/firmware-assisted-dump.rst        |    2 +-
 Documentation/process/adding-syscalls.rst     |    2 +-
 .../it_IT/process/adding-syscalls.rst         |    2 +-
 .../translations/zh_CN/filesystems/sysfs.txt  |    6 +-
 Documentation/usb/gadget_configfs.rst         |    4 +-
 MAINTAINERS                                   |   16 +-
 drivers/gpu/drm/msm/disp/dpu1/dpu_kms.h       |    2 +-
 fs/Kconfig                                    |    2 +-
 fs/Kconfig.binfmt                             |    2 +-
 fs/adfs/Kconfig                               |    2 +-
 fs/affs/Kconfig                               |    2 +-
 fs/afs/Kconfig                                |    6 +-
 fs/bfs/Kconfig                                |    2 +-
 fs/cachefiles/Kconfig                         |    4 +-
 fs/coda/Kconfig                               |    2 +-
 fs/configfs/inode.c                           |    2 +-
 fs/configfs/item.c                            |    2 +-
 fs/cramfs/Kconfig                             |    2 +-
 fs/dcache.c                                   |    6 +-
 fs/ecryptfs/Kconfig                           |    2 +-
 fs/fat/Kconfig                                |    8 +-
 fs/fscache/Kconfig                            |    8 +-
 fs/fscache/cache.c                            |    8 +-
 fs/fscache/cookie.c                           |    2 +-
 fs/fscache/object.c                           |    4 +-
 fs/fscache/operation.c                        |    2 +-
 fs/fuse/Kconfig                               |    2 +-
 fs/fuse/dev.c                                 |    2 +-
 fs/hfs/Kconfig                                |    2 +-
 fs/hpfs/Kconfig                               |    2 +-
 fs/isofs/Kconfig                              |    2 +-
 fs/locks.c                                    |    2 +-
 fs/namei.c                                    |    2 +-
 fs/namespace.c                                |    2 +-
 fs/notify/inotify/Kconfig                     |    2 +-
 fs/ntfs/Kconfig                               |    2 +-
 fs/ocfs2/Kconfig                              |    2 +-
 fs/overlayfs/Kconfig                          |    6 +-
 fs/proc/Kconfig                               |    4 +-
 fs/romfs/Kconfig                              |    2 +-
 fs/sysfs/dir.c                                |    2 +-
 fs/sysfs/file.c                               |    2 +-
 fs/sysfs/mount.c                              |    2 +-
 fs/sysfs/symlink.c                            |    2 +-
 fs/sysv/Kconfig                               |    2 +-
 fs/udf/Kconfig                                |    2 +-
 include/linux/configfs.h                      |    2 +-
 include/linux/fs_context.h                    |    2 +-
 include/linux/fscache-cache.h                 |    4 +-
 include/linux/fscache.h                       |   42 +-
 include/linux/lsm_hooks.h                     |    2 +-
 include/linux/relay.h                         |    2 +-
 include/linux/sysfs.h                         |    2 +-
 kernel/relay.c                                |    2 +-
 104 files changed, 4048 insertions(+), 3572 deletions(-)
 rename Documentation/filesystems/{automount-support.txt => automount-support.rst} (92%)
 rename Documentation/filesystems/caching/{backend-api.txt => backend-api.rst} (87%)
 rename Documentation/filesystems/caching/{cachefiles.txt => cachefiles.rst} (90%)
 create mode 100644 Documentation/filesystems/caching/fscache.rst
 delete mode 100644 Documentation/filesystems/caching/fscache.txt
 create mode 100644 Documentation/filesystems/caching/index.rst
 rename Documentation/filesystems/caching/{netfs-api.txt => netfs-api.rst} (91%)
 rename Documentation/filesystems/caching/{object.txt => object.rst} (95%)
 rename Documentation/filesystems/caching/{operations.txt => operations.rst} (90%)
 rename Documentation/filesystems/cifs/{cifsroot.txt => cifsroot.rst} (72%)
 create mode 100644 Documentation/filesystems/coda.rst
 delete mode 100644 Documentation/filesystems/coda.txt
 rename Documentation/filesystems/{configfs/configfs.txt => configfs.rst} (87%)
 rename Documentation/filesystems/{dax.txt => dax.rst} (96%)
 create mode 100644 Documentation/filesystems/devpts.rst
 delete mode 100644 Documentation/filesystems/devpts.txt
 rename Documentation/filesystems/{dnotify.txt => dnotify.rst} (88%)
 rename Documentation/filesystems/{fiemap.txt => fiemap.rst} (70%)
 rename Documentation/filesystems/{files.txt => files.rst} (95%)
 rename Documentation/filesystems/{fuse-io.txt => fuse-io.rst} (95%)
 rename Documentation/filesystems/{gfs2-glocks.txt => gfs2-glocks.rst} (63%)
 rename Documentation/filesystems/{locks.txt => locks.rst} (91%)
 rename Documentation/filesystems/{mandatory-locking.txt => mandatory-locking.rst} (91%)
 rename Documentation/filesystems/{mount_api.txt => mount_api.rst} (79%)
 rename Documentation/filesystems/{path-lookup.txt => path-walking.rst} (91%)
 rename Documentation/filesystems/{quota.txt => quota.rst} (81%)
 rename Documentation/filesystems/{seq_file.txt => seq_file.rst} (92%)
 rename Documentation/filesystems/{sharedsubtree.txt => sharedsubtree.rst} (72%)
 create mode 100644 Documentation/filesystems/spufs/index.rst
 create mode 100644 Documentation/filesystems/spufs/spu_create.rst
 create mode 100644 Documentation/filesystems/spufs/spu_run.rst
 rename Documentation/filesystems/{spufs.txt => spufs/spufs.rst} (57%)
 rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst} (92%)
 rename Documentation/filesystems/{sysfs-tagging.txt => sysfs-tagging.rst} (72%)
 rename Documentation/filesystems/{xfs-delayed-logging-design.txt => xfs-delayed-logging-design.rst} (97%)
 rename Documentation/filesystems/{xfs-self-describing-metadata.txt => xfs-self-describing-metadata.rst} (83%)

-- 
2.25.2

[PATCH 12/34] docs: filesystems: convert dax.txt to ReST

[Mauro Carvalho Chehab]

- Add a SPDX header;
- Adjust document title;
- Some whitespace fixes and new line breaks;
- Add it to filesystems/index.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/admin-guide/ext4.rst             | 2 +-
 Documentation/filesystems/{dax.txt => dax.rst} | 9 +++++++--
 Documentation/filesystems/ext2.rst             | 2 +-
 Documentation/filesystems/index.rst            | 1 +
 4 files changed, 10 insertions(+), 4 deletions(-)
 rename Documentation/filesystems/{dax.txt => dax.rst} (97%)

diff --git a/Documentation/admin-guide/ext4.rst b/Documentation/admin-guide/ext4.rst
index 9443fcef1876..103bcc345bad 100644
--- a/Documentation/admin-guide/ext4.rst
+++ b/Documentation/admin-guide/ext4.rst
@@ -392,7 +392,7 @@ When mounting an ext4 filesystem, the following option are accepted:
 
   dax
         Use direct access (no page cache).  See
-        Documentation/filesystems/dax.txt.  Note that this option is
+        Documentation/filesystems/dax.rst.  Note that this option is
         incompatible with data=journal.
 
 Data Mode
diff --git a/Documentation/filesystems/dax.txt b/Documentation/filesystems/dax.rst
similarity index 97%
rename from Documentation/filesystems/dax.txt
rename to Documentation/filesystems/dax.rst
index 735f3859b19f..5838144f80f0 100644
--- a/Documentation/filesystems/dax.txt
+++ b/Documentation/filesystems/dax.rst
@@ -1,5 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================
 Direct Access for files
------------------------
+=======================
 
 Motivation
 ----------
@@ -46,6 +49,7 @@ stall the CPU for an extended period, you should also not attempt to
 implement direct_access.
 
 These block devices may be used for inspiration:
+
 - brd: RAM backed block device driver
 - dcssblk: s390 dcss block device driver
 - pmem: NVDIMM persistent memory driver
@@ -55,6 +59,7 @@ Implementation Tips for Filesystem Writers
 ------------------------------------------
 
 Filesystem support consists of
+
 - adding support to mark inodes as being DAX by setting the S_DAX flag in
   i_flags
 - implementing ->read_iter and ->write_iter operations which use dax_iomap_rw()
@@ -127,6 +132,6 @@ by adding optional struct page support for pages under the control of
 the driver (see CONFIG_NVDIMM_PFN in drivers/nvdimm for an example of
 how to do this). In the non struct page cases O_DIRECT reads/writes to
 those memory ranges from a non-DAX file will fail (note that O_DIRECT
-reads/writes _of a DAX file_ do work, it is the memory that is being
+reads/writes _of a DAX ``file_`` do work, it is the memory that is being
 accessed that is key here).  Other things that will not work in the
 non struct page case include RDMA, sendfile() and splice().
diff --git a/Documentation/filesystems/ext2.rst b/Documentation/filesystems/ext2.rst
index d83dbbb162e2..fa416b7a5802 100644
--- a/Documentation/filesystems/ext2.rst
+++ b/Documentation/filesystems/ext2.rst
@@ -24,7 +24,7 @@ check=none, nocheck	(*)	Don't do extra checking of bitmaps on mount
 				(check=normal and check=strict options removed)
 
 dax				Use direct access (no page cache).  See
-				Documentation/filesystems/dax.txt.
+				Documentation/filesystems/dax.rst.
 
 debug				Extra debugging information is sent to the
 				kernel syslog.  Useful for developers.
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index c4f95f76ba6a..8e3ccb4ed483 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -24,6 +24,7 @@ algorithms work.
    splice
    locking
    directory-locking
+   dax
 
    automount-support
 
-- 
2.25.2

Re: [PATCH 12/34] docs: filesystems: convert dax.txt to ReST

[Darrick J. Wong]

[add ira weiny to cc]

On Wed, Apr 15, 2020 at 04:32:25PM +0200, Mauro Carvalho Chehab wrote:
> - Add a SPDX header;
> - Adjust document title;
> - Some whitespace fixes and new line breaks;
> - Add it to filesystems/index.rst.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/admin-guide/ext4.rst             | 2 +-
>  Documentation/filesystems/{dax.txt => dax.rst} | 9 +++++++--
>  Documentation/filesystems/ext2.rst             | 2 +-
>  Documentation/filesystems/index.rst            | 1 +
>  4 files changed, 10 insertions(+), 4 deletions(-)
>  rename Documentation/filesystems/{dax.txt => dax.rst} (97%)
> 
> diff --git a/Documentation/admin-guide/ext4.rst b/Documentation/admin-guide/ext4.rst
> index 9443fcef1876..103bcc345bad 100644
> --- a/Documentation/admin-guide/ext4.rst
> +++ b/Documentation/admin-guide/ext4.rst
> @@ -392,7 +392,7 @@ When mounting an ext4 filesystem, the following option are accepted:
>  
>    dax
>          Use direct access (no page cache).  See
> -        Documentation/filesystems/dax.txt.  Note that this option is
> +        Documentation/filesystems/dax.rst.  Note that this option is
>          incompatible with data=journal.
>  
>  Data Mode
> diff --git a/Documentation/filesystems/dax.txt b/Documentation/filesystems/dax.rst
> similarity index 97%
> rename from Documentation/filesystems/dax.txt
> rename to Documentation/filesystems/dax.rst
> index 735f3859b19f..5838144f80f0 100644
> --- a/Documentation/filesystems/dax.txt
> +++ b/Documentation/filesystems/dax.rst

Err, this will collide with the work that Ira's doing on DAX for 5.8[1].
Can the dax.txt conversion wait?

--D

[1] https://lore.kernel.org/linux-xfs/20200415152942.GS6742@magnolia/T/#m804562299416d865d8829caa82589a522b2080a5

> @@ -1,5 +1,8 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=======================
>  Direct Access for files
> ------------------------
> +=======================
>  
>  Motivation
>  ----------
> @@ -46,6 +49,7 @@ stall the CPU for an extended period, you should also not attempt to
>  implement direct_access.
>  
>  These block devices may be used for inspiration:
> +
>  - brd: RAM backed block device driver
>  - dcssblk: s390 dcss block device driver
>  - pmem: NVDIMM persistent memory driver
> @@ -55,6 +59,7 @@ Implementation Tips for Filesystem Writers
>  ------------------------------------------
>  
>  Filesystem support consists of
> +
>  - adding support to mark inodes as being DAX by setting the S_DAX flag in
>    i_flags
>  - implementing ->read_iter and ->write_iter operations which use dax_iomap_rw()
> @@ -127,6 +132,6 @@ by adding optional struct page support for pages under the control of
>  the driver (see CONFIG_NVDIMM_PFN in drivers/nvdimm for an example of
>  how to do this). In the non struct page cases O_DIRECT reads/writes to
>  those memory ranges from a non-DAX file will fail (note that O_DIRECT
> -reads/writes _of a DAX file_ do work, it is the memory that is being
> +reads/writes _of a DAX ``file_`` do work, it is the memory that is being
>  accessed that is key here).  Other things that will not work in the
>  non struct page case include RDMA, sendfile() and splice().
> diff --git a/Documentation/filesystems/ext2.rst b/Documentation/filesystems/ext2.rst
> index d83dbbb162e2..fa416b7a5802 100644
> --- a/Documentation/filesystems/ext2.rst
> +++ b/Documentation/filesystems/ext2.rst
> @@ -24,7 +24,7 @@ check=none, nocheck	(*)	Don't do extra checking of bitmaps on mount
>  				(check=normal and check=strict options removed)
>  
>  dax				Use direct access (no page cache).  See
> -				Documentation/filesystems/dax.txt.
> +				Documentation/filesystems/dax.rst.
>  
>  debug				Extra debugging information is sent to the
>  				kernel syslog.  Useful for developers.
> diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
> index c4f95f76ba6a..8e3ccb4ed483 100644
> --- a/Documentation/filesystems/index.rst
> +++ b/Documentation/filesystems/index.rst
> @@ -24,6 +24,7 @@ algorithms work.
>     splice
>     locking
>     directory-locking
> +   dax
>  
>     automount-support
>  
> -- 
> 2.25.2
> 

Re: [PATCH 12/34] docs: filesystems: convert dax.txt to ReST

[Mauro Carvalho Chehab]

Em Wed, 15 Apr 2020 08:41:44 -0700
"Darrick J. Wong" <darrick.wong@oracle.com> escreveu:

> [add ira weiny to cc]
> 
> On Wed, Apr 15, 2020 at 04:32:25PM +0200, Mauro Carvalho Chehab wrote:
> > - Add a SPDX header;
> > - Adjust document title;
> > - Some whitespace fixes and new line breaks;
> > - Add it to filesystems/index.rst.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  Documentation/admin-guide/ext4.rst             | 2 +-
> >  Documentation/filesystems/{dax.txt => dax.rst} | 9 +++++++--
> >  Documentation/filesystems/ext2.rst             | 2 +-
> >  Documentation/filesystems/index.rst            | 1 +
> >  4 files changed, 10 insertions(+), 4 deletions(-)
> >  rename Documentation/filesystems/{dax.txt => dax.rst} (97%)
> > 
> > diff --git a/Documentation/admin-guide/ext4.rst b/Documentation/admin-guide/ext4.rst
> > index 9443fcef1876..103bcc345bad 100644
> > --- a/Documentation/admin-guide/ext4.rst
> > +++ b/Documentation/admin-guide/ext4.rst
> > @@ -392,7 +392,7 @@ When mounting an ext4 filesystem, the following option are accepted:
> >  
> >    dax
> >          Use direct access (no page cache).  See
> > -        Documentation/filesystems/dax.txt.  Note that this option is
> > +        Documentation/filesystems/dax.rst.  Note that this option is
> >          incompatible with data=journal.
> >  
> >  Data Mode
> > diff --git a/Documentation/filesystems/dax.txt b/Documentation/filesystems/dax.rst
> > similarity index 97%
> > rename from Documentation/filesystems/dax.txt
> > rename to Documentation/filesystems/dax.rst
> > index 735f3859b19f..5838144f80f0 100644
> > --- a/Documentation/filesystems/dax.txt
> > +++ b/Documentation/filesystems/dax.rst  
> 
> Err, this will collide with the work that Ira's doing on DAX for 5.8[1].
> Can the dax.txt conversion wait?

Well, I can re-schedule it to 5.9. Or, if you merge the dax changes
at linux-next, I can rebase my patch on the top of it.

> 
> --D
> 
> [1] https://lore.kernel.org/linux-xfs/20200415152942.GS6742@magnolia/T/#m804562299416d865d8829caa82589a522b2080a5
> 
> > @@ -1,5 +1,8 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +=======================
> >  Direct Access for files
> > ------------------------
> > +=======================
> >  
> >  Motivation
> >  ----------
> > @@ -46,6 +49,7 @@ stall the CPU for an extended period, you should also not attempt to
> >  implement direct_access.
> >  
> >  These block devices may be used for inspiration:
> > +
> >  - brd: RAM backed block device driver
> >  - dcssblk: s390 dcss block device driver
> >  - pmem: NVDIMM persistent memory driver
> > @@ -55,6 +59,7 @@ Implementation Tips for Filesystem Writers
> >  ------------------------------------------
> >  
> >  Filesystem support consists of
> > +
> >  - adding support to mark inodes as being DAX by setting the S_DAX flag in
> >    i_flags
> >  - implementing ->read_iter and ->write_iter operations which use dax_iomap_rw()
> > @@ -127,6 +132,6 @@ by adding optional struct page support for pages under the control of
> >  the driver (see CONFIG_NVDIMM_PFN in drivers/nvdimm for an example of
> >  how to do this). In the non struct page cases O_DIRECT reads/writes to
> >  those memory ranges from a non-DAX file will fail (note that O_DIRECT
> > -reads/writes _of a DAX file_ do work, it is the memory that is being
> > +reads/writes _of a DAX ``file_`` do work, it is the memory that is being
> >  accessed that is key here).  Other things that will not work in the
> >  non struct page case include RDMA, sendfile() and splice().
> > diff --git a/Documentation/filesystems/ext2.rst b/Documentation/filesystems/ext2.rst
> > index d83dbbb162e2..fa416b7a5802 100644
> > --- a/Documentation/filesystems/ext2.rst
> > +++ b/Documentation/filesystems/ext2.rst
> > @@ -24,7 +24,7 @@ check=none, nocheck	(*)	Don't do extra checking of bitmaps on mount
> >  				(check=normal and check=strict options removed)
> >  
> >  dax				Use direct access (no page cache).  See
> > -				Documentation/filesystems/dax.txt.
> > +				Documentation/filesystems/dax.rst.
> >  
> >  debug				Extra debugging information is sent to the
> >  				kernel syslog.  Useful for developers.
> > diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
> > index c4f95f76ba6a..8e3ccb4ed483 100644
> > --- a/Documentation/filesystems/index.rst
> > +++ b/Documentation/filesystems/index.rst
> > @@ -24,6 +24,7 @@ algorithms work.
> >     splice
> >     locking
> >     directory-locking
> > +   dax
> >  
> >     automount-support
> >  
> > -- 
> > 2.25.2
> >   



Thanks,
Mauro

Re: [PATCH 12/34] docs: filesystems: convert dax.txt to ReST

[Darrick J. Wong]

On Tue, Apr 21, 2020 at 06:31:17PM +0200, Mauro Carvalho Chehab wrote:
> Em Wed, 15 Apr 2020 08:41:44 -0700
> "Darrick J. Wong" <darrick.wong@oracle.com> escreveu:
> 
> > [add ira weiny to cc]
> > 
> > On Wed, Apr 15, 2020 at 04:32:25PM +0200, Mauro Carvalho Chehab wrote:
> > > - Add a SPDX header;
> > > - Adjust document title;
> > > - Some whitespace fixes and new line breaks;
> > > - Add it to filesystems/index.rst.
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > > ---
> > >  Documentation/admin-guide/ext4.rst             | 2 +-
> > >  Documentation/filesystems/{dax.txt => dax.rst} | 9 +++++++--
> > >  Documentation/filesystems/ext2.rst             | 2 +-
> > >  Documentation/filesystems/index.rst            | 1 +
> > >  4 files changed, 10 insertions(+), 4 deletions(-)
> > >  rename Documentation/filesystems/{dax.txt => dax.rst} (97%)
> > > 
> > > diff --git a/Documentation/admin-guide/ext4.rst b/Documentation/admin-guide/ext4.rst
> > > index 9443fcef1876..103bcc345bad 100644
> > > --- a/Documentation/admin-guide/ext4.rst
> > > +++ b/Documentation/admin-guide/ext4.rst
> > > @@ -392,7 +392,7 @@ When mounting an ext4 filesystem, the following option are accepted:
> > >  
> > >    dax
> > >          Use direct access (no page cache).  See
> > > -        Documentation/filesystems/dax.txt.  Note that this option is
> > > +        Documentation/filesystems/dax.rst.  Note that this option is
> > >          incompatible with data=journal.
> > >  
> > >  Data Mode
> > > diff --git a/Documentation/filesystems/dax.txt b/Documentation/filesystems/dax.rst
> > > similarity index 97%
> > > rename from Documentation/filesystems/dax.txt
> > > rename to Documentation/filesystems/dax.rst
> > > index 735f3859b19f..5838144f80f0 100644
> > > --- a/Documentation/filesystems/dax.txt
> > > +++ b/Documentation/filesystems/dax.rst  
> > 
> > Err, this will collide with the work that Ira's doing on DAX for 5.8[1].
> > Can the dax.txt conversion wait?
> 
> Well, I can re-schedule it to 5.9. Or, if you merge the dax changes
> at linux-next, I can rebase my patch on the top of it.

That depends on how quick Ira can get the series merged. :)

I personally think (hope) everyone's tired of arguing and we can just
get it done for 5.8, but past experience tells me that rescheduling the
rst conversion to 5.90 is at least a safer bet.

--D

> > 
> > --D
> > 
> > [1] https://lore.kernel.org/linux-xfs/20200415152942.GS6742@magnolia/T/#m804562299416d865d8829caa82589a522b2080a5
> > 
> > > @@ -1,5 +1,8 @@
> > > +.. SPDX-License-Identifier: GPL-2.0
> > > +
> > > +=======================
> > >  Direct Access for files
> > > ------------------------
> > > +=======================
> > >  
> > >  Motivation
> > >  ----------
> > > @@ -46,6 +49,7 @@ stall the CPU for an extended period, you should also not attempt to
> > >  implement direct_access.
> > >  
> > >  These block devices may be used for inspiration:
> > > +
> > >  - brd: RAM backed block device driver
> > >  - dcssblk: s390 dcss block device driver
> > >  - pmem: NVDIMM persistent memory driver
> > > @@ -55,6 +59,7 @@ Implementation Tips for Filesystem Writers
> > >  ------------------------------------------
> > >  
> > >  Filesystem support consists of
> > > +
> > >  - adding support to mark inodes as being DAX by setting the S_DAX flag in
> > >    i_flags
> > >  - implementing ->read_iter and ->write_iter operations which use dax_iomap_rw()
> > > @@ -127,6 +132,6 @@ by adding optional struct page support for pages under the control of
> > >  the driver (see CONFIG_NVDIMM_PFN in drivers/nvdimm for an example of
> > >  how to do this). In the non struct page cases O_DIRECT reads/writes to
> > >  those memory ranges from a non-DAX file will fail (note that O_DIRECT
> > > -reads/writes _of a DAX file_ do work, it is the memory that is being
> > > +reads/writes _of a DAX ``file_`` do work, it is the memory that is being
> > >  accessed that is key here).  Other things that will not work in the
> > >  non struct page case include RDMA, sendfile() and splice().
> > > diff --git a/Documentation/filesystems/ext2.rst b/Documentation/filesystems/ext2.rst
> > > index d83dbbb162e2..fa416b7a5802 100644
> > > --- a/Documentation/filesystems/ext2.rst
> > > +++ b/Documentation/filesystems/ext2.rst
> > > @@ -24,7 +24,7 @@ check=none, nocheck	(*)	Don't do extra checking of bitmaps on mount
> > >  				(check=normal and check=strict options removed)
> > >  
> > >  dax				Use direct access (no page cache).  See
> > > -				Documentation/filesystems/dax.txt.
> > > +				Documentation/filesystems/dax.rst.
> > >  
> > >  debug				Extra debugging information is sent to the
> > >  				kernel syslog.  Useful for developers.
> > > diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
> > > index c4f95f76ba6a..8e3ccb4ed483 100644
> > > --- a/Documentation/filesystems/index.rst
> > > +++ b/Documentation/filesystems/index.rst
> > > @@ -24,6 +24,7 @@ algorithms work.
> > >     splice
> > >     locking
> > >     directory-locking
> > > +   dax
> > >  
> > >     automount-support
> > >  
> > > -- 
> > > 2.25.2
> > >   
> 
> 
> 
> Thanks,
> Mauro

Re: [PATCH 12/34] docs: filesystems: convert dax.txt to ReST

[Mauro Carvalho Chehab]

Em Tue, 21 Apr 2020 11:31:21 -0700
"Darrick J. Wong" <darrick.wong@oracle.com> escreveu:

> On Tue, Apr 21, 2020 at 06:31:17PM +0200, Mauro Carvalho Chehab wrote:
> > Em Wed, 15 Apr 2020 08:41:44 -0700
> > "Darrick J. Wong" <darrick.wong@oracle.com> escreveu:
> >   
> > > [add ira weiny to cc]
> > > 
> > > On Wed, Apr 15, 2020 at 04:32:25PM +0200, Mauro Carvalho Chehab wrote:  
> > > > - Add a SPDX header;
> > > > - Adjust document title;
> > > > - Some whitespace fixes and new line breaks;
> > > > - Add it to filesystems/index.rst.
> > > > 
> > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > > > ---
> > > >  Documentation/admin-guide/ext4.rst             | 2 +-
> > > >  Documentation/filesystems/{dax.txt => dax.rst} | 9 +++++++--
> > > >  Documentation/filesystems/ext2.rst             | 2 +-
> > > >  Documentation/filesystems/index.rst            | 1 +
> > > >  4 files changed, 10 insertions(+), 4 deletions(-)
> > > >  rename Documentation/filesystems/{dax.txt => dax.rst} (97%)
> > > > 
> > > > diff --git a/Documentation/admin-guide/ext4.rst b/Documentation/admin-guide/ext4.rst
> > > > index 9443fcef1876..103bcc345bad 100644
> > > > --- a/Documentation/admin-guide/ext4.rst
> > > > +++ b/Documentation/admin-guide/ext4.rst
> > > > @@ -392,7 +392,7 @@ When mounting an ext4 filesystem, the following option are accepted:
> > > >  
> > > >    dax
> > > >          Use direct access (no page cache).  See
> > > > -        Documentation/filesystems/dax.txt.  Note that this option is
> > > > +        Documentation/filesystems/dax.rst.  Note that this option is
> > > >          incompatible with data=journal.
> > > >  
> > > >  Data Mode
> > > > diff --git a/Documentation/filesystems/dax.txt b/Documentation/filesystems/dax.rst
> > > > similarity index 97%
> > > > rename from Documentation/filesystems/dax.txt
> > > > rename to Documentation/filesystems/dax.rst
> > > > index 735f3859b19f..5838144f80f0 100644
> > > > --- a/Documentation/filesystems/dax.txt
> > > > +++ b/Documentation/filesystems/dax.rst    
> > > 
> > > Err, this will collide with the work that Ira's doing on DAX for 5.8[1].
> > > Can the dax.txt conversion wait?  
> > 
> > Well, I can re-schedule it to 5.9. Or, if you merge the dax changes
> > at linux-next, I can rebase my patch on the top of it.  
> 
> That depends on how quick Ira can get the series merged. :)
> 
> I personally think (hope) everyone's tired of arguing and we can just
> get it done for 5.8, but past experience tells me that rescheduling the
> rst conversion to 5.90 is at least a safer bet.

I can't tell much about Ira's patches, but, in the case of the ReST
conversion, there are not much left to convert anymore. The vast majority
of files under Documentation/*.txt are already in ReST format. They just
need to be renamed/moved to a better place. Besides that, there are
the fs patches on this series, network and a few misc text files.

I have patches for the remaining stuff already.

> 
> --D
> 
> > > 
> > > --D
> > > 
> > > [1] https://lore.kernel.org/linux-xfs/20200415152942.GS6742@magnolia/T/#m804562299416d865d8829caa82589a522b2080a5
> > >   
> > > > @@ -1,5 +1,8 @@
> > > > +.. SPDX-License-Identifier: GPL-2.0
> > > > +
> > > > +=======================
> > > >  Direct Access for files
> > > > ------------------------
> > > > +=======================
> > > >  
> > > >  Motivation
> > > >  ----------
> > > > @@ -46,6 +49,7 @@ stall the CPU for an extended period, you should also not attempt to
> > > >  implement direct_access.
> > > >  
> > > >  These block devices may be used for inspiration:
> > > > +
> > > >  - brd: RAM backed block device driver
> > > >  - dcssblk: s390 dcss block device driver
> > > >  - pmem: NVDIMM persistent memory driver
> > > > @@ -55,6 +59,7 @@ Implementation Tips for Filesystem Writers
> > > >  ------------------------------------------
> > > >  
> > > >  Filesystem support consists of
> > > > +
> > > >  - adding support to mark inodes as being DAX by setting the S_DAX flag in
> > > >    i_flags
> > > >  - implementing ->read_iter and ->write_iter operations which use dax_iomap_rw()
> > > > @@ -127,6 +132,6 @@ by adding optional struct page support for pages under the control of
> > > >  the driver (see CONFIG_NVDIMM_PFN in drivers/nvdimm for an example of
> > > >  how to do this). In the non struct page cases O_DIRECT reads/writes to
> > > >  those memory ranges from a non-DAX file will fail (note that O_DIRECT
> > > > -reads/writes _of a DAX file_ do work, it is the memory that is being
> > > > +reads/writes _of a DAX ``file_`` do work, it is the memory that is being
> > > >  accessed that is key here).  Other things that will not work in the
> > > >  non struct page case include RDMA, sendfile() and splice().
> > > > diff --git a/Documentation/filesystems/ext2.rst b/Documentation/filesystems/ext2.rst
> > > > index d83dbbb162e2..fa416b7a5802 100644
> > > > --- a/Documentation/filesystems/ext2.rst
> > > > +++ b/Documentation/filesystems/ext2.rst
> > > > @@ -24,7 +24,7 @@ check=none, nocheck	(*)	Don't do extra checking of bitmaps on mount
> > > >  				(check=normal and check=strict options removed)
> > > >  
> > > >  dax				Use direct access (no page cache).  See
> > > > -				Documentation/filesystems/dax.txt.
> > > > +				Documentation/filesystems/dax.rst.
> > > >  
> > > >  debug				Extra debugging information is sent to the
> > > >  				kernel syslog.  Useful for developers.
> > > > diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
> > > > index c4f95f76ba6a..8e3ccb4ed483 100644
> > > > --- a/Documentation/filesystems/index.rst
> > > > +++ b/Documentation/filesystems/index.rst
> > > > @@ -24,6 +24,7 @@ algorithms work.
> > > >     splice
> > > >     locking
> > > >     directory-locking
> > > > +   dax
> > > >  
> > > >     automount-support
> > > >  
> > > > -- 
> > > > 2.25.2
> > > >     
> > 
> > 
> > 
> > Thanks,
> > Mauro  



Thanks,
Mauro