btrfs-progs: docs: update btrfs-property docs to include compression level

[koraynilay]

This is a documentation update to clear up how the btrfs.compression xattr behaves, there is a corresponding patch series¹² that is still WIP.

Discussion about it happened on the mailing list and on #btrfs on irc.

Thanks.

Footnotes

1. https://lore.kernel.org/linux-btrfs/e476f197-dc26-4f41-a9e5-0e23623496af@gmx.com/T/#t ↩

2. https://lore.kernel.org/linux-btrfs/20260809185303.600071-1-koray.fra@gmail.com/T/#t ↩

[adam900710]

Again, I'm not a huge fan of option 2, as the doc updates also touched the kernel part, which shows a very different behavior than XATTR.

If kernel mount option has no level specified, it goes the default level. Meanwhile for XATTR it goes the mount option level if that algo matches.
And the "algo matches" part is also kernel version dependent.

I think it would be much simpler, just stating that, before 7.x, the compression level of XATTR is not fully determined, behavior may vary on different kernels.

I'd prefer to have the option 3 fix backported to all older kernels, and call it a day other than maintain a complex matrix.

[koraynilay]

If kernel mount option has no level specified, it goes the default level. Meanwhile for XATTR it goes the mount option level if that algo matches.

Yeah, what I thought was that it could be useful to have the semantics of level 0 be:

"check the compression level specified upper in the hierarchy, if at the top with nothing more specific found, use default, otherwise use the specified level (only if algo matches)"

although, this would mean that it has to check back on all the parent folders, which wouldn't be the best solution probably, so it could be thought like:

"if 0, check the mount option, if that is not specified use default, otherwise (only if the algo matches) use the mount option level".

And the "algo matches" part is also kernel version dependent.

Ah, I'm sorry but why? Isn't it just a string compare on the algorithm?
Oh, unless you mean for very old kernels that didn't have the algorithm string anywhere because it was only 1 possible algorithm (?).

I think it would be much simpler, just stating that, before 7.x, the compression level of XATTR is not fully determined, behavior may vary on different kernels.
I'd prefer to have the option 3 fix backported to all older kernels, and call it a day other than maintain a complex matrix.

Ah yes, that could be added, and maybe even explain how the "bug" worked (or this may be better left to community wikis).

behavior may vary on different kernels.

You mentioned this because someone with a < 7.x kernel may have the bugfix patch, while others may not, so it won't be determined?

Thanks.

[adam900710]

And the "algo matches" part is also kernel version dependent.

Ah, I'm sorry but why? Isn't it just a string compare on the algorithm?

No, I mean for older kernels like the current upstream, they do not follow this at all. They just unconditionally follow the level no matter if the algo matches.

So it would be something like: "Before v7.x, the kernel follows the mount option level even it's not applicable, at and after v7.x the kernel follows the mount option level if the algo matches, otherwise uses default level".

behavior may vary on different kernels.

You mentioned this because someone with a < 7.x kernel may have the bugfix patch, while others may not, so it won't be determined?

Yes.

[koraynilay]

And the "algo matches" part is also kernel version dependent.
Ah, I'm sorry but why? Isn't it just a string compare on the algorithm?

No, I mean for older kernels like the current upstream, they do not follow this at all. They just unconditionally follow the level no matter if the algo matches.

So it would be something like: "Before v7.x, the kernel follows the mount option level even it's not applicable, at and after v7.x the kernel follows the mount option level if the algo matches, otherwise uses default level".

Ah ok, error on my part, I didn't think of adding a disclaimer about that.

behavior may vary on different kernels.
You mentioned this because someone with a < 7.x kernel may have the bugfix patch, while others may not, so it won't be determined?

Yes.

Ah ok, makes sense, I would also add it as a .. note::, mentioning the old behaviour and the bugfix behaviour, which would need to be mentioned anyway to let users know about the cross-algo bug (IMO).

[adam900710]

And if you're sending the final version, please keep the doc update in one commit, and remove the WIP tag, so that I can properly review the whole changes and merge PR in the end.

Of course, that will be after we have settled down the final solution (option 2 or 3) and merged the kernel fix.