Skip to content

docs: improve clarity in xattrs and chunked format documentation#29

Open
SKM2227229725 wants to merge 5 commits intoerofs:mainfrom
SKM2227229725:docs-pr28-followup
Open

docs: improve clarity in xattrs and chunked format documentation#29
SKM2227229725 wants to merge 5 commits intoerofs:mainfrom
SKM2227229725:docs-pr28-followup

Conversation

@SKM2227229725
Copy link
Contributor

This PR improves clarity in xattr and chunk-based format documentation.

Changes:

  • Added note about reserved e_name_index values (0 and 5)
  • Standardized "Bloom filter" capitalization
  • Improved wording for long xattr prefix structure
  • Clarified chunk size formula expression to avoid ambiguity

These changes are based on discussion in #28.

SToPire and others added 4 commits March 21, 2026 01:22
[ 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>
Copilot AI review requested due to automatic review settings March 21, 2026 18:21
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 xattrs on-disk format documentation, including reserved e_name_index notes 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.
Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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.

Copilot uses AI. Check for mistakes.
Comment on lines +119 to +126
| Value | Prefix |
|-------|--------|
| 1 | `user.` |
| 2 | `system.posix_acl_access` |
| 3 | `system.posix_acl_default` |
| 4 | `trusted.` |
| 6 | `security.` |

Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
| 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`.

Copilot uses AI. Check for mistakes.
Signed-off-by: SKM2227229725 <shailesh91199477@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants