[PATCH] filesystems.5, erofs.5: add erofs documentation

[PATCH] filesystems.5, erofs.5: add erofs documentation

[наб]

[-- Attachment #1: Type: text/plain, Size: 3829 bytes --]

Modelled after tmpfs(5) ‒ there's a listing of mount options,
and a summary of limitations. The feature flags are described in
mkfs.erofs, and they're versioned and maintained upstream quite well
there, so no need to duplicate those, since you only care on image
creation.

The real value add is the mount options, but I cannot figure out
how device_id and fsid interact with the system at large,
so I just noted they're there.

State as of 6.3-rc5.

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man5/erofs.5       | 84 ++++++++++++++++++++++++++++++++++++++++++++++
 man5/filesystems.5 |  6 ++++
 2 files changed, 90 insertions(+)
 create mode 100644 man5/erofs.5

diff --git a/man5/erofs.5 b/man5/erofs.5
new file mode 100644
index 000000000..de5b56121
--- /dev/null
+++ b/man5/erofs.5
@@ -0,0 +1,84 @@
+.\" Copyright (c) 2016 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH erofs 5 (date) "Linux man-pages (unreleased)"
+.SH NAME
+erofs \- the Enhanced Read-Only File System
+.SH DESCRIPTION
+.B erofs
+is a create-once read-only filesystem,
+with support for compression and a multi-device backing store.
+.PP
+There are two inode formats:
+32-byte compact with 16-bit UID/GID, 32-bit file size, and no file times,
+and 64-byte extended with 32-bit UID/GID, 64-bit file size,
+and a modification time
+.RI ( st_mtim ).
+.\" See fs/erofs/super.c:shmem_parse_options for options it supports.
+.SS Mount options
+.TP
+.BR user_xattr / nouser_xattr
+Controls whether
+.I user
+extended attributes are exposed.
+Defaults to yes
+.TP
+.BR acl / noacl
+Controls whether POSIX
+.BR acl (5)s
+are exposed.
+Defaults to yes.
+.TP
+.BR cache_strategy = disabled | readahead | readaround
+Cache allocation for compressed files:
+never, if reading from start of file, regardless of position.
+Defaults to
+.BR readaround .
+.TP
+.BR dax ", " dax = always | never
+Direct Access control.
+If
+.B always
+and the source device supports DAX, uncompressed non-inlined files
+will be read directly, without going through the page cache.
+.B dax
+is a synonym for
+.BR always .
+Defaults to unset, which is equivalent to
+.BR never .
+.TP
+.BR device = \fIblobdev\fP
+Add extra device holding some of the data.
+Must be given as many times and in the same order as 
+.B \-\-blobdev
+was to
+.BR mkfs.erofs (8).
+.\" Nominally there's a device_table feature and it somehow scans(?) for them,
+.\" cf. super.c:erofs_scan_devices(), but I haven't gotten it to work
+.TP
+.BR domain_id = \fIdid\fP ", " fsid = \fIid\fP
+Control CacheFiles on-demand read support.
+To be documented.
+.RE
+.IP
+.SH VERSIONS
+.B erofs
+images are versioed through the use of feature flags;
+these are listed in the
+.B \-E
+section of
+.BR mkfs.erofs (1),
+.SH NOTES
+The kernel must be configured with the
+.B CONFIG_EROFS_FS
+option to mount EROFS filesystems.
+There are sub-configuration items that restrict the availability
+of some of the parameters above.
+.SH SEE ALSO
+.BR mkfs.erofs (1),
+.BR fsck.erofs (1),
+.BR dump.erofs (1)
+.PP
+.I Documentation/filesystems/erofs.txt
+in the kernel source.
diff --git a/man5/filesystems.5 b/man5/filesystems.5
index 3c15f14da..c9b0bf695 100644
--- a/man5/filesystems.5
+++ b/man5/filesystems.5
@@ -48,6 +48,12 @@ filesystems in the Linux kernel.
 See the kernel documentation for a comprehensive
 description of all options and limitations.
 .TP 10
+.B erofs
+is the Enhanced Read-Only File System, stable since Linux 5.4.
+.\" commit 47e4937a4a7ca4184fd282791dfee76c6799966a moves it out of staging
+See
+.BR erofs (5).
+.TP
 .B ext
 is an elaborate extension of the
 .B minix
-- 
2.30.2

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] filesystems.5, erofs.5: add erofs documentation

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 5152 bytes --]

Hi наб!

On 4/9/23 19:16, наб wrote:
> Modelled after tmpfs(5) ‒ there's a listing of mount options,
> and a summary of limitations. The feature flags are described in
> mkfs.erofs, and they're versioned and maintained upstream quite well
> there, so no need to duplicate those, since you only care on image
> creation.
> 
> The real value add is the mount options, but I cannot figure out
> how device_id and fsid interact with the system at large,
> so I just noted they're there.
> 
> State as of 6.3-rc5.
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>

Applying: filesystems.5, erofs.5: add erofs documentation
/home/alx/src/linux/man-pages/man-pages/.bare.git/worktrees/master/rebase-apply/patch:65: trailing whitespace.
Must be given as many times and in the same order as 
warning: 1 line adds whitespace errors.

> ---
>  man5/erofs.5       | 84 ++++++++++++++++++++++++++++++++++++++++++++++
>  man5/filesystems.5 |  6 ++++
>  2 files changed, 90 insertions(+)
>  create mode 100644 man5/erofs.5
> 
> diff --git a/man5/erofs.5 b/man5/erofs.5
> new file mode 100644
> index 000000000..de5b56121
> --- /dev/null
> +++ b/man5/erofs.5
> @@ -0,0 +1,84 @@
> +.\" Copyright (c) 2016 by Michael Kerrisk <mtk.manpages@gmail.com>
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.TH erofs 5 (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +erofs \- the Enhanced Read-Only File System
> +.SH DESCRIPTION
> +.B erofs
> +is a create-once read-only filesystem,
> +with support for compression and a multi-device backing store.
> +.PP
> +There are two inode formats:
> +32-byte compact with 16-bit UID/GID, 32-bit file size, and no file times,
> +and 64-byte extended with 32-bit UID/GID, 64-bit file size,
> +and a modification time
> +.RI ( st_mtim ).

The above is a bit difficult to parse due to the ands and commas.
How about a list (.IP \[bu] 3) with the two entries or something
like that?

> +.\" See fs/erofs/super.c:shmem_parse_options for options it supports.
> +.SS Mount options
> +.TP
> +.BR user_xattr / nouser_xattr
> +Controls whether
> +.I user
> +extended attributes are exposed.
> +Defaults to yes
> +.TP
> +.BR acl / noacl
> +Controls whether POSIX
> +.BR acl (5)s
> +are exposed.
> +Defaults to yes.
> +.TP
> +.BR cache_strategy = disabled | readahead | readaround
> +Cache allocation for compressed files:
> +never, if reading from start of file, regardless of position.
> +Defaults to
> +.BR readaround .
> +.TP
> +.BR dax ", " dax = always | never
> +Direct Access control.
> +If
> +.B always
> +and the source device supports DAX, uncompressed non-inlined files
> +will be read directly, without going through the page cache.
> +.B dax
> +is a synonym for
> +.BR always .
> +Defaults to unset, which is equivalent to
> +.BR never .
> +.TP
> +.BR device = \fIblobdev\fP
> +Add extra device holding some of the data.
> +Must be given as many times and in the same order as 
> +.B \-\-blobdev
> +was to
> +.BR mkfs.erofs (8).
> +.\" Nominally there's a device_table feature and it somehow scans(?) for them,
> +.\" cf. super.c:erofs_scan_devices(), but I haven't gotten it to work
> +.TP
> +.BR domain_id = \fIdid\fP ", " fsid = \fIid\fP

You could use .TQ:

.TP
.BR domain_id = \fIdid\fP
.TQ
.BR fsid = \fIid\fP

(similarly above in dax, acl, and user_xattr)


That helps searching with
/    <opt-name>

> +Control CacheFiles on-demand read support.
> +To be documented.
> +.RE
> +.IP
> +.SH VERSIONS
> +.B erofs
> +images are versioed through the use of feature flags;

s/ioe/ione/

> +these are listed in the
> +.B \-E
> +section of
> +.BR mkfs.erofs (1),
> +.SH NOTES

You could use the CONFIGURATION section for this.  :)
Check man-pages(7).

> +The kernel must be configured with the
> +.B CONFIG_EROFS_FS
> +option to mount EROFS filesystems.
> +There are sub-configuration items that restrict the availability
> +of some of the parameters above.
> +.SH SEE ALSO
> +.BR mkfs.erofs (1),
> +.BR fsck.erofs (1),
> +.BR dump.erofs (1)
> +.PP
> +.I Documentation/filesystems/erofs.txt
> +in the kernel source.

I prefer saying Linux rather than kernel.

> diff --git a/man5/filesystems.5 b/man5/filesystems.5
> index 3c15f14da..c9b0bf695 100644
> --- a/man5/filesystems.5
> +++ b/man5/filesystems.5
> @@ -48,6 +48,12 @@ filesystems in the Linux kernel.
>  See the kernel documentation for a comprehensive
>  description of all options and limitations.
>  .TP 10

Bruh, still have pages that specify the indentation...
Would you mind sending a patch that removes these in fs(5),
or in all the pages you feel like, if you want?

Cheers,
Alex

> +.B erofs
> +is the Enhanced Read-Only File System, stable since Linux 5.4.
> +.\" commit 47e4937a4a7ca4184fd282791dfee76c6799966a moves it out of staging
> +See
> +.BR erofs (5).
> +.TP
>  .B ext
>  is an elaborate extension of the
>  .B minix

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] filesystems.5, erofs.5: add erofs documentation

[наб]

[-- Attachment #1: Type: text/plain, Size: 6793 bytes --]

Hi!

On Sun, Apr 09, 2023 at 11:43:05PM +0200, Alejandro Colomar wrote:
> Applying: filesystems.5, erofs.5: add erofs documentation
> /home/alx/src/linux/man-pages/man-pages/.bare.git/worktrees/master/rebase-apply/patch:65: trailing whitespace.
> Must be given as many times and in the same order as 
> warning: 1 line adds whitespace errors.
Fixed.

> On 4/9/23 19:16, наб wrote:
> > +There are two inode formats:
> > +32-byte compact with 16-bit UID/GID, 32-bit file size, and no file times,
> > +and 64-byte extended with 32-bit UID/GID, 64-bit file size,
> > +and a modification time
> > +.RI ( st_mtim ).
> The above is a bit difficult to parse due to the ands and commas.
> How about a list (.IP \[bu] 3) with the two entries or something
> like that?
Opted for .br and \[bu], .IP gets too tall and sparse and for my taste;
feel free to editorialise it to the .IP spelling tho.

> > +Defaults to yes
.

> > +.BR domain_id = \fIdid\fP ", " fsid = \fIid\fP
> You could use .TQ:
> 
> .TP
> .BR domain_id = \fIdid\fP
> .TQ
> .BR fsid = \fIid\fP
> 
> (similarly above in dax, acl, and user_xattr)
Applied.

> > +.B erofs
> > +images are versioed through the use of feature flags;
> s/ioe/ione/
Applied.

> > +these are listed in the
> > +.B \-E
> > +section of
> > +.BR mkfs.erofs (1),
> > +.SH NOTES
> You could use the CONFIGURATION section for this.  :)
Had it in NOTES because that's where tmpfs.5 has its
  In order for user-space tools and applications to create tmpfs
  filesystems, the kernel must be configured with the CONFIG_TMPFS
  option.

Moved to CONFIGURATION, you might want to move it in tmpfs.5 too.

> > +The kernel must be configured with the
> > +.B CONFIG_EROFS_FS
> > +option to mount EROFS filesystems.

> > +.I Documentation/filesystems/erofs.txt
> > +in the kernel source.
> I prefer saying Linux rather than kernel.
Also applied, but note that tmpfs.5 also spells it "kernel" in both
equivalent hunks.

> > --- a/man5/filesystems.5
> > +++ b/man5/filesystems.5
> > @@ -48,6 +48,12 @@ filesystems in the Linux kernel.
> >  See the kernel documentation for a comprehensive
> >  description of all options and limitations.
> >  .TP 10
> Bruh, still have pages that specify the indentation...
> Would you mind sending a patch that removes these in fs(5),
> or in all the pages you feel like, if you want?
Too drunk to evaluate all of them rn, killed the one in filesystems.5.

Scissor-patch below.

Best,
-- >8 --
Subject: [PATCH v2] filesystems.5, erofs.5: add erofs documentation,
 clean up indent

Modelled after tmpfs(5) ‒ there's a listing of mount options,
and a summary of limitations. The feature flags are described in
mkfs.erofs, and they're versioned and maintained upstream quite well
there, so no need to duplicate those, since you only care on image
creation.

The real value add is the mount options, but I cannot figure out
how device_id and fsid interact with the system at large,
so I just noted they're there.

State as of 6.3-rc5.

Also, remove explicit .TP indent in filesystems.5 since we're already
touching this hunk: all entries sans iso9660 and Reiserfs fall within
the default prevailing indent, so no need to specify a wide one.

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man5/erofs.5       | 95 ++++++++++++++++++++++++++++++++++++++++++++++
 man5/filesystems.5 |  8 +++-
 2 files changed, 102 insertions(+), 1 deletion(-)
 create mode 100644 man5/erofs.5

diff --git a/man5/erofs.5 b/man5/erofs.5
new file mode 100644
index 000000000..933e830b8
--- /dev/null
+++ b/man5/erofs.5
@@ -0,0 +1,95 @@
+.\" Copyright (c) 2016 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH erofs 5 (date) "Linux man-pages (unreleased)"
+.SH NAME
+erofs \- the Enhanced Read-Only File System
+.SH DESCRIPTION
+.B erofs
+is a create-once read-only filesystem,
+with support for compression and a multi-device backing store.
+.PP
+There are two inode formats:
+.br
+\[bu] 32-byte compact with 16-bit UID/GID, 32-bit file size, and no file times,
+and
+.br
+\[bu] 64-byte extended with 32-bit UID/GID, 64-bit file size,
+and a modification time
+.RI ( st_mtim ).
+.\" See fs/erofs/super.c:shmem_parse_options for options it supports.
+.SS Mount options
+.TP
+.B user_xattr
+.TQ
+.B nouser_xattr
+Controls whether
+.I user
+extended attributes are exposed.
+Defaults to yes.
+.TP
+.B acl
+.TQ
+.B noacl
+Controls whether POSIX
+.BR acl (5)s
+are exposed.
+Defaults to yes.
+.TP
+.BR cache_strategy = disabled | readahead | readaround
+Cache allocation for compressed files:
+never, if reading from start of file, regardless of position.
+Defaults to
+.BR readaround .
+.TP
+.BR dax
+.TQ
+.BR dax = always | never
+Direct Access control.
+If
+.B always
+and the source device supports DAX, uncompressed non-inlined files
+will be read directly, without going through the page cache.
+.B dax
+is a synonym for
+.BR always .
+Defaults to unset, which is equivalent to
+.BR never .
+.TP
+.BR device = \fIblobdev\fP
+Add extra device holding some of the data.
+Must be given as many times and in the same order as
+.B \-\-blobdev
+was to
+.BR mkfs.erofs (1).
+.\" Nominally there's a device_table feature and it somehow scans(?) for them,
+.\" cf. super.c:erofs_scan_devices(), but I haven't gotten it to work
+.TP
+.BR domain_id = \fIdid\fP
+.TQ
+.BR fsid = \fIid\fP
+Control CacheFiles on-demand read support.
+To be documented.
+.RE
+.IP
+.SH VERSIONS
+.B erofs
+images are versioned through the use of feature flags;
+these are listed in the
+.B \-E
+section of
+.BR mkfs.erofs (1),
+.SH CONFIGURATION
+Linux must be configured with the
+.B CONFIG_EROFS_FS
+option to mount EROFS filesystems.
+There are sub-configuration items that restrict the availability
+of some of the parameters above.
+.SH SEE ALSO
+.BR mkfs.erofs (1),
+.BR fsck.erofs (1),
+.BR dump.erofs (1)
+.PP
+.I Documentation/filesystems/erofs.txt
+in the Linux source.
diff --git a/man5/filesystems.5 b/man5/filesystems.5
index 3c15f14da..ba795f956 100644
--- a/man5/filesystems.5
+++ b/man5/filesystems.5
@@ -47,7 +47,13 @@ short description of the available or historically available
 filesystems in the Linux kernel.
 See the kernel documentation for a comprehensive
 description of all options and limitations.
-.TP 10
+.TP
+.B erofs
+is the Enhanced Read-Only File System, stable since Linux 5.4.
+.\" commit 47e4937a4a7ca4184fd282791dfee76c6799966a moves it out of staging
+See
+.BR erofs (5).
+.TP
 .B ext
 is an elaborate extension of the
 .B minix
-- 
2.30.2

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] filesystems.5, erofs.5: add erofs documentation

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 8214 bytes --]

Hi!

On 4/10/23 00:27, наб wrote:
> Hi!
> 
> On Sun, Apr 09, 2023 at 11:43:05PM +0200, Alejandro Colomar wrote:
>> Applying: filesystems.5, erofs.5: add erofs documentation
>> /home/alx/src/linux/man-pages/man-pages/.bare.git/worktrees/master/rebase-apply/patch:65: trailing whitespace.
>> Must be given as many times and in the same order as 
>> warning: 1 line adds whitespace errors.
> Fixed.
> 
>> On 4/9/23 19:16, наб wrote:
>>> +There are two inode formats:
>>> +32-byte compact with 16-bit UID/GID, 32-bit file size, and no file times,
>>> +and 64-byte extended with 32-bit UID/GID, 64-bit file size,
>>> +and a modification time
>>> +.RI ( st_mtim ).
>> The above is a bit difficult to parse due to the ands and commas.
>> How about a list (.IP \[bu] 3) with the two entries or something
>> like that?
> Opted for .br and \[bu], .IP gets too tall and sparse and for my taste;
> feel free to editorialise it to the .IP spelling tho.

You can use '.IP' without blank lines, with '.PD 0'.  I'll do that
myself.  It renders as:

       There are two inode formats:

       •  32‐byte compact with 16‐bit UID/GID, 32‐bit file  size,  and
          no file times
       •  64‐byte  extended with 32‐bit UID/GID, 64‐bit file size, and
          a modification time (st_mtim).


> 
>>> +Defaults to yes
> .
> 
>>> +.BR domain_id = \fIdid\fP ", " fsid = \fIid\fP
>> You could use .TQ:
>>
>> .TP
>> .BR domain_id = \fIdid\fP
>> .TQ
>> .BR fsid = \fIid\fP
>>
>> (similarly above in dax, acl, and user_xattr)
> Applied.
> 
>>> +.B erofs
>>> +images are versioed through the use of feature flags;
>> s/ioe/ione/
> Applied.
> 
>>> +these are listed in the
>>> +.B \-E
>>> +section of
>>> +.BR mkfs.erofs (1),
>>> +.SH NOTES
>> You could use the CONFIGURATION section for this.  :)
> Had it in NOTES because that's where tmpfs.5 has its
>   In order for user-space tools and applications to create tmpfs
>   filesystems, the kernel must be configured with the CONFIG_TMPFS
>   option.

Yeah, I guess.  I feel NOTES is a doesn't-fit-elsewhere section,
which is how it's been used so far.  I'm trying to improve that
by using the appropriate sections, but as you can see, it's not
fun fixing so much stuff.  :)

> 
> Moved to CONFIGURATION, you might want to move it in tmpfs.5 too.

I had enough with reorganizing VERSIONS, STANDARDS, and HISTORY.
Maybe for next year.  I do want to, but if I start, I don't know
where I'll stop.

> 
>>> +The kernel must be configured with the
>>> +.B CONFIG_EROFS_FS
>>> +option to mount EROFS filesystems.
> 
>>> +.I Documentation/filesystems/erofs.txt
>>> +in the kernel source.
>> I prefer saying Linux rather than kernel.
> Also applied, but note that tmpfs.5 also spells it "kernel" in both
> equivalent hunks.

Similar underlying issue as with NOTES.

> 
>>> --- a/man5/filesystems.5
>>> +++ b/man5/filesystems.5
>>> @@ -48,6 +48,12 @@ filesystems in the Linux kernel.
>>>  See the kernel documentation for a comprehensive
>>>  description of all options and limitations.
>>>  .TP 10
>> Bruh, still have pages that specify the indentation...
>> Would you mind sending a patch that removes these in fs(5),
>> or in all the pages you feel like, if you want?
> Too drunk to evaluate all of them rn, killed the one in filesystems.5.

Nice.

> 
> Scissor-patch below.
> 
> Best,
> -- >8 --
> Subject: [PATCH v2] filesystems.5, erofs.5: add erofs documentation,
>  clean up indent
> 
> Modelled after tmpfs(5) ‒ there's a listing of mount options,
> and a summary of limitations. The feature flags are described in
> mkfs.erofs, and they're versioned and maintained upstream quite well
> there, so no need to duplicate those, since you only care on image
> creation.
> 
> The real value add is the mount options, but I cannot figure out
> how device_id and fsid interact with the system at large,
> so I just noted they're there.
> 
> State as of 6.3-rc5.

I prefixed that version with "Linux ".

> 
> Also, remove explicit .TP indent in filesystems.5 since we're already
> touching this hunk: all entries sans iso9660 and Reiserfs fall within
> the default prevailing indent, so no need to specify a wide one.

Fair enough.

> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>

Patch applied.  Thanks!

Best,
Alex

> ---
>  man5/erofs.5       | 95 ++++++++++++++++++++++++++++++++++++++++++++++
>  man5/filesystems.5 |  8 +++-
>  2 files changed, 102 insertions(+), 1 deletion(-)
>  create mode 100644 man5/erofs.5
> 
> diff --git a/man5/erofs.5 b/man5/erofs.5
> new file mode 100644
> index 000000000..933e830b8
> --- /dev/null
> +++ b/man5/erofs.5
> @@ -0,0 +1,95 @@
> +.\" Copyright (c) 2016 by Michael Kerrisk <mtk.manpages@gmail.com>
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.TH erofs 5 (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +erofs \- the Enhanced Read-Only File System
> +.SH DESCRIPTION
> +.B erofs
> +is a create-once read-only filesystem,
> +with support for compression and a multi-device backing store.
> +.PP
> +There are two inode formats:
> +.br
> +\[bu] 32-byte compact with 16-bit UID/GID, 32-bit file size, and no file times,
> +and
> +.br
> +\[bu] 64-byte extended with 32-bit UID/GID, 64-bit file size,
> +and a modification time
> +.RI ( st_mtim ).
> +.\" See fs/erofs/super.c:shmem_parse_options for options it supports.
> +.SS Mount options
> +.TP
> +.B user_xattr
> +.TQ
> +.B nouser_xattr
> +Controls whether
> +.I user
> +extended attributes are exposed.
> +Defaults to yes.
> +.TP
> +.B acl
> +.TQ
> +.B noacl
> +Controls whether POSIX
> +.BR acl (5)s
> +are exposed.
> +Defaults to yes.
> +.TP
> +.BR cache_strategy = disabled | readahead | readaround
> +Cache allocation for compressed files:
> +never, if reading from start of file, regardless of position.
> +Defaults to
> +.BR readaround .
> +.TP
> +.BR dax
> +.TQ
> +.BR dax = always | never
> +Direct Access control.
> +If
> +.B always
> +and the source device supports DAX, uncompressed non-inlined files
> +will be read directly, without going through the page cache.
> +.B dax
> +is a synonym for
> +.BR always .
> +Defaults to unset, which is equivalent to
> +.BR never .
> +.TP
> +.BR device = \fIblobdev\fP
> +Add extra device holding some of the data.
> +Must be given as many times and in the same order as
> +.B \-\-blobdev
> +was to
> +.BR mkfs.erofs (1).
> +.\" Nominally there's a device_table feature and it somehow scans(?) for them,
> +.\" cf. super.c:erofs_scan_devices(), but I haven't gotten it to work
> +.TP
> +.BR domain_id = \fIdid\fP
> +.TQ
> +.BR fsid = \fIid\fP
> +Control CacheFiles on-demand read support.
> +To be documented.
> +.RE
> +.IP
> +.SH VERSIONS
> +.B erofs
> +images are versioned through the use of feature flags;
> +these are listed in the
> +.B \-E
> +section of
> +.BR mkfs.erofs (1),
> +.SH CONFIGURATION
> +Linux must be configured with the
> +.B CONFIG_EROFS_FS
> +option to mount EROFS filesystems.
> +There are sub-configuration items that restrict the availability
> +of some of the parameters above.
> +.SH SEE ALSO
> +.BR mkfs.erofs (1),
> +.BR fsck.erofs (1),
> +.BR dump.erofs (1)
> +.PP
> +.I Documentation/filesystems/erofs.txt
> +in the Linux source.
> diff --git a/man5/filesystems.5 b/man5/filesystems.5
> index 3c15f14da..ba795f956 100644
> --- a/man5/filesystems.5
> +++ b/man5/filesystems.5
> @@ -47,7 +47,13 @@ short description of the available or historically available
>  filesystems in the Linux kernel.
>  See the kernel documentation for a comprehensive
>  description of all options and limitations.
> -.TP 10
> +.TP
> +.B erofs
> +is the Enhanced Read-Only File System, stable since Linux 5.4.
> +.\" commit 47e4937a4a7ca4184fd282791dfee76c6799966a moves it out of staging
> +See
> +.BR erofs (5).
> +.TP
>  .B ext
>  is an elaborate extension of the
>  .B minix

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] filesystems.5, erofs.5: add erofs documentation

[Gao Xiang]

Hi!

On 2023/4/10 01:16, наб wrote:
> Modelled after tmpfs(5) ‒ there's a listing of mount options,
> and a summary of limitations. The feature flags are described in
> mkfs.erofs, and they're versioned and maintained upstream quite well
> there, so no need to duplicate those, since you only care on image
> creation.
> 
> The real value add is the mount options, but I cannot figure out
> how device_id and fsid interact with the system at large,
> so I just noted they're there.

Thanks for the document.

Currently EROFS has two main userspace progs --- erofs-utils and
Nydus [1].  Later maybe more userspace progs such as composefs[3].

device_id and fsid are mainly used for Nydus image service to keep
its multiple layers, so that the data source of each chunk could be
from such external blobs.

erofs-utils (with the upcoming tarerofs) is having such use case as
well, in that case, one image could consist of a manifest and several
original tar blobs with different device_ids.  So that you could
directly mount a EROFS merged image with several tarballs.  Note that
erofs-utils support is still under development, you could refer to [2]


[1] https://github.com/dragonflyoss/image-service
     https://github.com/dragonflyoss/image-service/blob/master/rafs/src/metadata/layout/v6.rs
[2] https://lore.kernel.org/r/20230401072705.99060-1-hsiangkao@linux.alibaba.com
[3] https://github.com/containers/composefs/pull/112

> 
> State as of 6.3-rc5.
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
> ---
>   man5/erofs.5       | 84 ++++++++++++++++++++++++++++++++++++++++++++++
>   man5/filesystems.5 |  6 ++++
>   2 files changed, 90 insertions(+)
>   create mode 100644 man5/erofs.5
> 
> diff --git a/man5/erofs.5 b/man5/erofs.5
> new file mode 100644
> index 000000000..de5b56121
> --- /dev/null
> +++ b/man5/erofs.5
> @@ -0,0 +1,84 @@
> +.\" Copyright (c) 2016 by Michael Kerrisk <mtk.manpages@gmail.com>
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.TH erofs 5 (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +erofs \- the Enhanced Read-Only File System
> +.SH DESCRIPTION
> +.B erofs
> +is a create-once read-only filesystem,
> +with support for compression and a multi-device backing store.
> +.PP
> +There are two inode formats:
> +32-byte compact with 16-bit UID/GID, 32-bit file size, and no file times,
> +and 64-byte extended with 32-bit UID/GID, 64-bit file size,
> +and a modification time
> +.RI ( st_mtim ).
> +.\" See fs/erofs/super.c:shmem_parse_options for options it supports.
> +.SS Mount options
> +.TP
> +.BR user_xattr / nouser_xattr
> +Controls whether
> +.I user
> +extended attributes are exposed.
> +Defaults to yes
> +.TP
> +.BR acl / noacl
> +Controls whether POSIX
> +.BR acl (5)s
> +are exposed.
> +Defaults to yes.
> +.TP
> +.BR cache_strategy = disabled | readahead | readaround
> +Cache allocation for compressed files:
> +never, if reading from start of file, regardless of position.
> +Defaults to
> +.BR readaround .
> +.TP
> +.BR dax ", " dax = always | never
> +Direct Access control.
> +If
> +.B always
> +and the source device supports DAX, uncompressed non-inlined files
> +will be read directly, without going through the page cache.
> +.B dax
> +is a synonym for
> +.BR always .
> +Defaults to unset, which is equivalent to
> +.BR never .
> +.TP
> +.BR device = \fIblobdev\fP
> +Add extra device holding some of the data.
> +Must be given as many times and in the same order as
> +.B \-\-blobdev
> +was to
> +.BR mkfs.erofs (8).
> +.\" Nominally there's a device_table feature and it somehow scans(?) for them,
> +.\" cf. super.c:erofs_scan_devices(), but I haven't gotten it to work

See above.

> +.TP
> +.BR domain_id = \fIdid\fP ", " fsid = \fIid\fP
> +Control CacheFiles on-demand read support.
> +To be documented.

See above and
https://github.com/dragonflyoss/image-service/blob/master/docs/nydus-fscache.md

Currently the main user is still Nydus since on-demand read
quite relies on high-level stuffs (such as container
registries, etc.). But we could develop a fscache API interfaces
to erofs-utils later as well if some new users would like to use
it with erofs-utils.

Thanks,
Gao Xiang

> +.RE
> +.IP
> +.SH VERSIONS
> +.B erofs
> +images are versioed through the use of feature flags;
> +these are listed in the
> +.B \-E
> +section of
> +.BR mkfs.erofs (1),
> +.SH NOTES
> +The kernel must be configured with the
> +.B CONFIG_EROFS_FS
> +option to mount EROFS filesystems.
> +There are sub-configuration items that restrict the availability
> +of some of the parameters above.
> +.SH SEE ALSO
> +.BR mkfs.erofs (1),
> +.BR fsck.erofs (1),
> +.BR dump.erofs (1)
> +.PP
> +.I Documentation/filesystems/erofs.txt
> +in the kernel source.
> diff --git a/man5/filesystems.5 b/man5/filesystems.5
> index 3c15f14da..c9b0bf695 100644
> --- a/man5/filesystems.5
> +++ b/man5/filesystems.5
> @@ -48,6 +48,12 @@ filesystems in the Linux kernel.
>   See the kernel documentation for a comprehensive
>   description of all options and limitations.
>   .TP 10
> +.B erofs
> +is the Enhanced Read-Only File System, stable since Linux 5.4.
> +.\" commit 47e4937a4a7ca4184fd282791dfee76c6799966a moves it out of staging
> +See
> +.BR erofs (5).
> +.TP
>   .B ext
>   is an elaborate extension of the
>   .B minix