[f2fs-dev] f2fs-tools: Question about mkfs and fsck behavior for documentation purposes

[f2fs-dev] f2fs-tools: Question about mkfs and fsck behavior for documentation purposes

[ericonr]

Hi there!

I'm working on the man pages and usage messages of the various f2fs
tools, to make them more descriptive and correspond better to what the
code is doing.  So I'm hunting around the f2fs-tools tree to try to
understand things, but I'd like to confirm some ideas I have.

- Inside mkfs, the overprovision percentage is either provided by the
user (-o option) or determined by the program.  The current usage text
says the default is 5. Should I remove this default to make it clear
that if no percentage is provided, it is determined at runtime?

- For the -c option in mkfs, it says there's a maximum of 7 additional
devices, except for "meta devices". What is a meta device? Given that
the code for parsing arguments passed to -c doesn't seem to
distinguish between meta or normal devices, can I remove this part of
the text?

- The verity feature has a "Reserved" comment next to it, but it is used
by the Android default options. Should I therefore not document it in
the options for -O?

- I documented the -g option as "Add Android default options". Is there
a better description for it?

- mkfs uses -e and -E to specify the file extensions for cold and hot
files. Is there anywhere I can find a small explanation of what these
features mean to include in the man pages? I kind of understood that
they differ in what the filesystem expects will be their lifetime and
access patterns, but I don't know how to communicate this adequately.

- fsck, during the feature parsing phase, doesn't seem to pass any
specific argument to  parse_feature(). Does that mean all extra
features can be enabled by fsck, even if they weren't enabled when the
filesystem was created?

More generally, I've fixed a few typos along the way as well. Is it ok
if I put everything together into a single commit when I make a patch?

Another question regarding preferences: both here and in the
documentation of other tools like mkfs.ext4, "filesystem" is written all
together and as "file system". Is there any preferred spelling for new
content?

Thanks,

Érico Nogueira


_______________________________________________
Linux-f2fs-devel mailing list
Linux-f2fs-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/linux-f2fs-devel

Re: [f2fs-dev] f2fs-tools: Question about mkfs and fsck behavior for documentation purposes

[Jaegeuk Kim]

Hi,

On 04/09, ericonr@disroot.org wrote:
> Hi there!
> 
> I'm working on the man pages and usage messages of the various f2fs
> tools, to make them more descriptive and correspond better to what the
> code is doing.  So I'm hunting around the f2fs-tools tree to try to
> understand things, but I'd like to confirm some ideas I have.
> 
> - Inside mkfs, the overprovision percentage is either provided by the
> user (-o option) or determined by the program.  The current usage text
> says the default is 5. Should I remove this default to make it clear
> that if no percentage is provided, it is determined at runtime?

Yes, exactly. We need to remove the default value, 5.

> 
> - For the -c option in mkfs, it says there's a maximum of 7 additional
> devices, except for "meta devices". What is a meta device? Given that
> the code for parsing arguments passed to -c doesn't seem to
> distinguish between meta or normal devices, can I remove this part of
> the text?

Yes, I think it should be better to remove it.

> 
> - The verity feature has a "Reserved" comment next to it, but it is used
> by the Android default options. Should I therefore not document it in
> the options for -O?

Agreed.

> 
> - I documented the -g option as "Add Android default options". Is there
> a better description for it?

This is useful for Android build, since we don't need to change here and
there in AOSP when we want to add a new option.

> 
> - mkfs uses -e and -E to specify the file extensions for cold and hot
> files. Is there anywhere I can find a small explanation of what these
> features mean to include in the man pages? I kind of understood that
> they differ in what the filesystem expects will be their lifetime and
> access patterns, but I don't know how to communicate this adequately.

Once mkfs sets the extension list of hot and cold files, f2fs will 1) load
the list when mounting the disk, 2) set appropriate flag when creating files
according to the file name extension, 3) store all the data into hot or cold
logs separately per file temparature. This can give spatial as well as temporal
localities on top of the storage space.

> 
> - fsck, during the feature parsing phase, doesn't seem to pass any
> specific argument to  parse_feature(). Does that mean all extra
> features can be enabled by fsck, even if they weren't enabled when the
> filesystem was created?

tune_sb_features() will finally check whether new feature can be settable.
And, encryption and casefold are only allowed.

> 
> More generally, I've fixed a few typos along the way as well. Is it ok
> if I put everything together into a single commit when I make a patch?

Sure.

> 
> Another question regarding preferences: both here and in the
> documentation of other tools like mkfs.ext4, "filesystem" is written all
> together and as "file system". Is there any preferred spelling for new
> content?

It'd be great to have "filesystem" in all places.

Thank you so much for the hard work. :)


_______________________________________________
Linux-f2fs-devel mailing list
Linux-f2fs-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/linux-f2fs-devel