Merge tag 'libnvdimm-fixes-5.2-rc1' of git://git.kernel.org/pub/scm/linux/kernel...
[sfrench/cifs-2.6.git] / Documentation / filesystems / omfs.txt
1 Optimized MPEG Filesystem (OMFS)
2
3 Overview
4 ========
5
6 OMFS is a filesystem created by SonicBlue for use in the ReplayTV DVR
7 and Rio Karma MP3 player.  The filesystem is extent-based, utilizing
8 block sizes from 2k to 8k, with hash-based directories.  This
9 filesystem driver may be used to read and write disks from these
10 devices.
11
12 Note, it is not recommended that this FS be used in place of a general
13 filesystem for your own streaming media device.  Native Linux filesystems
14 will likely perform better.
15
16 More information is available at:
17
18     http://linux-karma.sf.net/
19
20 Various utilities, including mkomfs and omfsck, are included with
21 omfsprogs, available at:
22
23     http://bobcopeland.com/karma/
24
25 Instructions are included in its README.
26
27 Options
28 =======
29
30 OMFS supports the following mount-time options:
31
32     uid=n        - make all files owned by specified user
33     gid=n        - make all files owned by specified group
34     umask=xxx    - set permission umask to xxx
35     fmask=xxx    - set umask to xxx for files
36     dmask=xxx    - set umask to xxx for directories
37
38 Disk format
39 ===========
40
41 OMFS discriminates between "sysblocks" and normal data blocks.  The sysblock
42 group consists of super block information, file metadata, directory structures,
43 and extents.  Each sysblock has a header containing CRCs of the entire
44 sysblock, and may be mirrored in successive blocks on the disk.  A sysblock may
45 have a smaller size than a data block, but since they are both addressed by the
46 same 64-bit block number, any remaining space in the smaller sysblock is
47 unused.
48
49 Sysblock header information:
50
51 struct omfs_header {
52         __be64 h_self;                  /* FS block where this is located */
53         __be32 h_body_size;             /* size of useful data after header */
54         __be16 h_crc;                   /* crc-ccitt of body_size bytes */
55         char h_fill1[2];
56         u8 h_version;                   /* version, always 1 */
57         char h_type;                    /* OMFS_INODE_X */
58         u8 h_magic;                     /* OMFS_IMAGIC */
59         u8 h_check_xor;                 /* XOR of header bytes before this */
60         __be32 h_fill2;
61 };
62
63 Files and directories are both represented by omfs_inode:
64
65 struct omfs_inode {
66         struct omfs_header i_head;      /* header */
67         __be64 i_parent;                /* parent containing this inode */
68         __be64 i_sibling;               /* next inode in hash bucket */
69         __be64 i_ctime;                 /* ctime, in milliseconds */
70         char i_fill1[35];
71         char i_type;                    /* OMFS_[DIR,FILE] */
72         __be32 i_fill2;
73         char i_fill3[64];
74         char i_name[OMFS_NAMELEN];      /* filename */
75         __be64 i_size;                  /* size of file, in bytes */
76 };
77
78 Directories in OMFS are implemented as a large hash table.  Filenames are
79 hashed then prepended into the bucket list beginning at OMFS_DIR_START.
80 Lookup requires hashing the filename, then seeking across i_sibling pointers
81 until a match is found on i_name.  Empty buckets are represented by block
82 pointers with all-1s (~0).
83
84 A file is an omfs_inode structure followed by an extent table beginning at
85 OMFS_EXTENT_START:
86
87 struct omfs_extent_entry {
88         __be64 e_cluster;               /* start location of a set of blocks */
89         __be64 e_blocks;                /* number of blocks after e_cluster */
90 };
91
92 struct omfs_extent {
93         __be64 e_next;                  /* next extent table location */
94         __be32 e_extent_count;          /* total # extents in this table */
95         __be32 e_fill;
96         struct omfs_extent_entry e_entry;       /* start of extent entries */
97 };
98
99 Each extent holds the block offset followed by number of blocks allocated to
100 the extent.  The final extent in each table is a terminator with e_cluster
101 being ~0 and e_blocks being ones'-complement of the total number of blocks
102 in the table.
103
104 If this table overflows, a continuation inode is written and pointed to by
105 e_next.  These have a header but lack the rest of the inode structure.
106