Hi,
I''ve been having a go at writing some code to read files from a ZFS
filesystem, using the ZFS On-Disk Specification draft dated 12/9/2005,
without peeking at opensolaris ZFS code.
Thanks Tabriz for a great document! I''m growing to like ZFS more as I
understand it better. Here is some feedback about the document which I
hope will be helpful.
Errors
- Section 6.1: ZPL Filesystem Layout, page 46:
This section says that the master node has an object number of 2,
but from looking at a filesystem, the master node appears to be
the second object (ie object number 1).
- Section 6.2: Directories and Directory Traversal, page 46:
DMU_OT_DIRECTORY is mentioned here, but is not listed in table 8
(page 20) nor table 9 (page 22); looking at a filesystem, I see
the value 20 in this context which is called
DMU_OT_DIRECTORY_CONTENTS in table 8.
- Section 6.2: Directories and Directory Traversal, page 47:
The lower 9 (not 8) bits of zp_mode contain the access mode bits.
- Mismatched names between Table 8 Object Types (page 20) and
Table 9 DMU Object Types (page 22):
DMU_OT_PLAIN_FILE_CONTENTS (tbl 8) vs DMU_OT_PLAIN_FILE (tbl 9)
DMU_OT_OBJSET_SNAP_MAP (tbl 8) vs DMU_OT_DSL_OBJSET_SNAP_MAP (tbl 9)
- Mismatched names / values between Table 8 Object Types (page 20)
and Table 10 Bonus Buffer Types (page 26):
12: DMU_OT_DSL_DATASET (tbl 8) vs DMU_OT_DSL_DIR (tbl 10)
16: DMU_OT_DSL_OBJSET (tbl 8) vs DMU_OT_DSL_DATASET (tbl 10)
If these tables are not supposed to be related, then perhaps they
should use a different prefix in the names of constants to avoid
this nameclash?
Omissions
- Need specs or references for the lzjb, fletcher2, and fletcher4
algorithms.
- Need specs or references for the XDR-encoding of nvlists.
There is a reference to the man pages for libnvpair(3LIB) and
nvlist_free(3NVPAIR), but these man pages only describe how to use
Solaris'' nvpair library and do not actually describe the encoding.
- RAID-Z on-disk format is not fully specified here (right?)
Presentation Comments
- The formatting used to present the physical layout of data is
not consistent. I can count four distinct styles:
1: bitfield diagram, eg illustration 8 (page 15)
2: diagram containing C definitions, eg illustration 9 (page 23)
3: C definitions mixed with descriptions, eg section 4.3 (page 33)
4: C struct definition, eg section 6.2 (page 46)
- The term "object identifier" (and abbreviations "object
id", "oid")
is used without being defined. I think it means the same as
"object number" which is specified in section 3.2 (page 27),
in which case it would be simpler if a single term was used.
- Often it is clear which object set an object number is referring to
from the context in which it is mentioned, but sometimes it is not
immediately obvious to me. The document could be made clearer by
always specifying which object set is being referred to when an
object number is mentioned.
regards,
Luke.