docs: improve clarity in xattrs and chunked format documentation#29
docs: improve clarity in xattrs and chunked format documentation#29SKM2227229725 wants to merge 5 commits intoerofs:mainfrom
Conversation
[ Assisted with revisions and language polishing using GPT-5.4. ] Signed-off-by: Yifan Zhao <yifan.yfzhao@foxmail.com>
[ Assisted with revisions and language polishing using GPT-5.4. ] Signed-off-by: Yifan Zhao <yifan.yfzhao@foxmail.com>
Signed-off-by: Yifan Zhao <yifan.yfzhao@foxmail.com>
There was a problem hiding this comment.
Pull request overview
This PR expands and refines the EROFS on-disk format documentation by adding dedicated pages for extended attributes (xattrs) and the chunk-based file layout, and by improving phrasing/consistency in related docs.
Changes:
- Add new
xattrson-disk format documentation, including reservede_name_indexnotes and Bloom filter wording. - Add new chunk-based file format documentation, including clearer chunk size expression and multi-device addressing details.
- Update the on-disk docs index to link these optional-feature pages; minor wording fix in core superblock table.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| src/ondisk/xattrs.md | New xattr format page (superblock/inode fields, inline/shared xattrs, long prefixes, Bloom filter, image-share xattrs). |
| src/ondisk/chunked_format.md | New chunk-based inode format page (chunk info record, entry formats, device table, address resolution). |
| src/ondisk/index.md | Adds narrative + toctree entries to surface the new optional-feature docs. |
| src/ondisk/core_ondisk.md | Improves wording (“48-bit layout specific”) in the superblock table. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | 4 | `trusted.` | | ||
| | 6 | `security.` | | ||
|
|
||
| All other `e_name_index` values (including `0` and `5`) are reserved and must not be used unless defined by a future format extension. |
There was a problem hiding this comment.
Add a blank line before the (shared_xattr_area)= label. As written, the label is immediately adjacent to the preceding paragraph, which can cause MyST/Sphinx to treat it as part of the paragraph instead of a standalone label and may break cross-referencing.
| All other `e_name_index` values (including `0` and `5`) are reserved and must not be used unless defined by a future format extension. | |
| All other `e_name_index` values (including `0` and `5`) are reserved and must not be used unless defined by a future format extension. |
src/ondisk/xattrs.md
Outdated
| | Value | Prefix | | ||
| |-------|--------| | ||
| | 1 | `user.` | | ||
| | 2 | `system.posix_acl_access` | | ||
| | 3 | `system.posix_acl_default` | | ||
| | 4 | `trusted.` | | ||
| | 6 | `security.` | | ||
|
|
There was a problem hiding this comment.
The e_name_index mapping table is labeled as a "Prefix", but entries system.posix_acl_access and system.posix_acl_default are full xattr names rather than prefixes (they don't end with a dot). Consider renaming the column/wording (e.g. "Prefix or full name") and/or explicitly stating that for these indexes the stored name suffix length (e_name_len) is 0.
| | Value | Prefix | | |
| |-------|--------| | |
| | 1 | `user.` | | |
| | 2 | `system.posix_acl_access` | | |
| | 3 | `system.posix_acl_default` | | |
| | 4 | `trusted.` | | |
| | 6 | `security.` | | |
| | Value | Prefix or full name | | |
| |-------|----------------------| | |
| | 1 | `user.` | | |
| | 2 | `system.posix_acl_access` | | |
| | 3 | `system.posix_acl_default` | | |
| | 4 | `trusted.` | | |
| | 6 | `security.` | | |
| For indices `2` and `3`, the string shown above is the entire xattr name (no additional suffix bytes are stored), so `e_name_len` must be `0`. For the other indices, the string is a prefix and the remaining name bytes are stored as the suffix of length `e_name_len`. |
Signed-off-by: SKM2227229725 <shailesh91199477@gmail.com>
This PR improves clarity in xattr and chunk-based format documentation.
Changes:
These changes are based on discussion in #28.