ae960519c54aab698154026f5d8c5298f44f79ab
[linux-3.10.git] / fs / logfs / logfs_abi.h
1 /*
2  * fs/logfs/logfs_abi.h
3  *
4  * As should be obvious for Linux kernel code, license is GPLv2
5  *
6  * Copyright (c) 2005-2008 Joern Engel <joern@logfs.org>
7  *
8  * Public header for logfs.
9  */
10 #ifndef FS_LOGFS_LOGFS_ABI_H
11 #define FS_LOGFS_LOGFS_ABI_H
12
13 /* For out-of-kernel compiles */
14 #ifndef BUILD_BUG_ON
15 #define BUILD_BUG_ON(condition) /**/
16 #endif
17
18 #define SIZE_CHECK(type, size)                                  \
19 static inline void check_##type(void)                           \
20 {                                                               \
21         BUILD_BUG_ON(sizeof(struct type) != (size));            \
22 }
23
24 /*
25  * Throughout the logfs code, we're constantly dealing with blocks at
26  * various positions or offsets.  To remove confusion, we stricly
27  * distinguish between a "position" - the logical position within a
28  * file and an "offset" - the physical location within the device.
29  *
30  * Any usage of the term offset for a logical location or position for
31  * a physical one is a bug and should get fixed.
32  */
33
34 /*
35  * Block are allocated in one of several segments depending on their
36  * level.  The following levels are used:
37  *  0   - regular data block
38  *  1   - i1 indirect blocks
39  *  2   - i2 indirect blocks
40  *  3   - i3 indirect blocks
41  *  4   - i4 indirect blocks
42  *  5   - i5 indirect blocks
43  *  6   - ifile data blocks
44  *  7   - ifile i1 indirect blocks
45  *  8   - ifile i2 indirect blocks
46  *  9   - ifile i3 indirect blocks
47  * 10   - ifile i4 indirect blocks
48  * 11   - ifile i5 indirect blocks
49  * Potential levels to be used in the future:
50  * 12   - gc recycled blocks, long-lived data
51  * 13   - replacement blocks, short-lived data
52  *
53  * Levels 1-11 are necessary for robust gc operations and help separate
54  * short-lived metadata from longer-lived file data.  In the future,
55  * file data should get separated into several segments based on simple
56  * heuristics.  Old data recycled during gc operation is expected to be
57  * long-lived.  New data is of uncertain life expectancy.  New data
58  * used to replace older blocks in existing files is expected to be
59  * short-lived.
60  */
61
62
63 /* Magic numbers.  64bit for superblock, 32bit for statfs f_type */
64 #define LOGFS_MAGIC             0x7a3a8e5cb9d5bf67ull
65 #define LOGFS_MAGIC_U32         0xc97e8168u
66
67 /*
68  * Various blocksize related macros.  Blocksize is currently fixed at 4KiB.
69  * Sooner or later that should become configurable and the macros replaced
70  * by something superblock-dependent.  Pointers in indirect blocks are and
71  * will remain 64bit.
72  *
73  * LOGFS_BLOCKSIZE      - self-explaining
74  * LOGFS_BLOCK_FACTOR   - number of pointers per indirect block
75  * LOGFS_BLOCK_BITS     - log2 of LOGFS_BLOCK_FACTOR, used for shifts
76  */
77 #define LOGFS_BLOCKSIZE         (4096ull)
78 #define LOGFS_BLOCK_FACTOR      (LOGFS_BLOCKSIZE / sizeof(u64))
79 #define LOGFS_BLOCK_BITS        (9)
80
81 /*
82  * Number of blocks at various levels of indirection.  There are 16 direct
83  * block pointers plus a single indirect pointer.
84  */
85 #define I0_BLOCKS               (16)
86 #define I1_BLOCKS               LOGFS_BLOCK_FACTOR
87 #define I2_BLOCKS               (LOGFS_BLOCK_FACTOR * I1_BLOCKS)
88 #define I3_BLOCKS               (LOGFS_BLOCK_FACTOR * I2_BLOCKS)
89 #define I4_BLOCKS               (LOGFS_BLOCK_FACTOR * I3_BLOCKS)
90 #define I5_BLOCKS               (LOGFS_BLOCK_FACTOR * I4_BLOCKS)
91
92 #define INDIRECT_INDEX          I0_BLOCKS
93 #define LOGFS_EMBEDDED_FIELDS   (I0_BLOCKS + 1)
94
95 /*
96  * Sizes at which files require another level of indirection.  Files smaller
97  * than LOGFS_EMBEDDED_SIZE can be completely stored in the inode itself,
98  * similar like ext2 fast symlinks.
99  *
100  * Data at a position smaller than LOGFS_I0_SIZE is accessed through the
101  * direct pointers, else through the 1x indirect pointer and so forth.
102  */
103 #define LOGFS_EMBEDDED_SIZE     (LOGFS_EMBEDDED_FIELDS * sizeof(u64))
104 #define LOGFS_I0_SIZE           (I0_BLOCKS * LOGFS_BLOCKSIZE)
105 #define LOGFS_I1_SIZE           (I1_BLOCKS * LOGFS_BLOCKSIZE)
106 #define LOGFS_I2_SIZE           (I2_BLOCKS * LOGFS_BLOCKSIZE)
107 #define LOGFS_I3_SIZE           (I3_BLOCKS * LOGFS_BLOCKSIZE)
108 #define LOGFS_I4_SIZE           (I4_BLOCKS * LOGFS_BLOCKSIZE)
109 #define LOGFS_I5_SIZE           (I5_BLOCKS * LOGFS_BLOCKSIZE)
110
111 /*
112  * Each indirect block pointer must have this flag set, if all block pointers
113  * behind it are set, i.e. there is no hole hidden in the shadow of this
114  * indirect block pointer.
115  */
116 #define LOGFS_FULLY_POPULATED (1ULL << 63)
117 #define pure_ofs(ofs) (ofs & ~LOGFS_FULLY_POPULATED)
118
119 /*
120  * LogFS needs to separate data into levels.  Each level is defined as the
121  * maximal possible distance from the master inode (inode of the inode file).
122  * Data blocks reside on level 0, 1x indirect block on level 1, etc.
123  * Inodes reside on level 6, indirect blocks for the inode file on levels 7-11.
124  * This effort is necessary to guarantee garbage collection to always make
125  * progress.
126  *
127  * LOGFS_MAX_INDIRECT is the maximal indirection through indirect blocks,
128  * LOGFS_MAX_LEVELS is one more for the actual data level of a file.  It is
129  * the maximal number of levels for one file.
130  * LOGFS_NO_AREAS is twice that, as the inode file and regular files are
131  * effectively stacked on top of each other.
132  */
133 #define LOGFS_MAX_INDIRECT      (5)
134 #define LOGFS_MAX_LEVELS        (LOGFS_MAX_INDIRECT + 1)
135 #define LOGFS_NO_AREAS          (2 * LOGFS_MAX_LEVELS)
136
137 /* Maximum size of filenames */
138 #define LOGFS_MAX_NAMELEN       (255)
139
140 /* Number of segments in the primary journal. */
141 #define LOGFS_JOURNAL_SEGS      (16)
142
143 /* Maximum number of free/erased/etc. segments in journal entries */
144 #define MAX_CACHED_SEGS         (64)
145
146
147 /*
148  * LOGFS_OBJECT_HEADERSIZE is the size of a single header in the object store,
149  * LOGFS_MAX_OBJECTSIZE the size of the largest possible object, including
150  * its header,
151  * LOGFS_SEGMENT_RESERVE is the amount of space reserved for each segment for
152  * its segment header and the padded space at the end when no further objects
153  * fit.
154  */
155 #define LOGFS_OBJECT_HEADERSIZE (0x1c)
156 #define LOGFS_SEGMENT_HEADERSIZE (0x18)
157 #define LOGFS_MAX_OBJECTSIZE    (LOGFS_OBJECT_HEADERSIZE + LOGFS_BLOCKSIZE)
158 #define LOGFS_SEGMENT_RESERVE   \
159         (LOGFS_SEGMENT_HEADERSIZE + LOGFS_MAX_OBJECTSIZE - 1)
160
161 /*
162  * Segment types:
163  * SEG_SUPER    - Data or indirect block
164  * SEG_JOURNAL  - Inode
165  * SEG_OSTORE   - Dentry
166  */
167 enum {
168         SEG_SUPER       = 0x01,
169         SEG_JOURNAL     = 0x02,
170         SEG_OSTORE      = 0x03,
171 };
172
173 /**
174  * struct logfs_segment_header - per-segment header in the ostore
175  *
176  * @crc:                        crc32 of header (there is no data)
177  * @pad:                        unused, must be 0
178  * @type:                       segment type, see above
179  * @level:                      GC level for all objects in this segment
180  * @segno:                      segment number
181  * @ec:                         erase count for this segment
182  * @gec:                        global erase count at time of writing
183  */
184 struct logfs_segment_header {
185         __be32  crc;
186         __be16  pad;
187         __u8    type;
188         __u8    level;
189         __be32  segno;
190         __be32  ec;
191         __be64  gec;
192 };
193
194 SIZE_CHECK(logfs_segment_header, LOGFS_SEGMENT_HEADERSIZE);
195
196 #define LOGFS_FEATURES_INCOMPAT         (0ull)
197 #define LOGFS_FEATURES_RO_COMPAT        (0ull)
198 #define LOGFS_FEATURES_COMPAT           (0ull)
199
200 /**
201  * struct logfs_disk_super - on-medium superblock
202  *
203  * @ds_magic:                   magic number, must equal LOGFS_MAGIC
204  * @ds_crc:                     crc32 of structure starting with the next field
205  * @ds_ifile_levels:            maximum number of levels for ifile
206  * @ds_iblock_levels:           maximum number of levels for regular files
207  * @ds_data_levels:             number of separate levels for data
208  * @pad0:                       reserved, must be 0
209  * @ds_feature_incompat:        incompatible filesystem features
210  * @ds_feature_ro_compat:       read-only compatible filesystem features
211  * @ds_feature_compat:          compatible filesystem features
212  * @ds_flags:                   flags
213  * @ds_segment_shift:           log2 of segment size
214  * @ds_block_shift:             log2 of block size
215  * @ds_write_shift:             log2 of write size
216  * @pad1:                       reserved, must be 0
217  * @ds_journal_seg:             segments used by primary journal
218  * @ds_root_reserve:            bytes reserved for the superuser
219  * @ds_speed_reserve:           bytes reserved to speed up GC
220  * @ds_bad_seg_reserve:         number of segments reserved to handle bad blocks
221  * @pad2:                       reserved, must be 0
222  * @pad3:                       reserved, must be 0
223  *
224  * Contains only read-only fields.  Read-write fields like the amount of used
225  * space is tracked in the dynamic superblock, which is stored in the journal.
226  */
227 struct logfs_disk_super {
228         struct logfs_segment_header ds_sh;
229         __be64  ds_magic;
230
231         __be32  ds_crc;
232         __u8    ds_ifile_levels;
233         __u8    ds_iblock_levels;
234         __u8    ds_data_levels;
235         __u8    ds_segment_shift;
236         __u8    ds_block_shift;
237         __u8    ds_write_shift;
238         __u8    pad0[6];
239
240         __be64  ds_filesystem_size;
241         __be32  ds_segment_size;
242         __be32  ds_bad_seg_reserve;
243
244         __be64  ds_feature_incompat;
245         __be64  ds_feature_ro_compat;
246
247         __be64  ds_feature_compat;
248         __be64  ds_feature_flags;
249
250         __be64  ds_root_reserve;
251         __be64  ds_speed_reserve;
252
253         __be32  ds_journal_seg[LOGFS_JOURNAL_SEGS];
254
255         __be64  ds_super_ofs[2];
256         __be64  pad3[8];
257 };
258
259 SIZE_CHECK(logfs_disk_super, 256);
260
261 /*
262  * Object types:
263  * OBJ_BLOCK    - Data or indirect block
264  * OBJ_INODE    - Inode
265  * OBJ_DENTRY   - Dentry
266  */
267 enum {
268         OBJ_BLOCK       = 0x04,
269         OBJ_INODE       = 0x05,
270         OBJ_DENTRY      = 0x06,
271 };
272
273 /**
274  * struct logfs_object_header - per-object header in the ostore
275  *
276  * @crc:                        crc32 of header, excluding data_crc
277  * @len:                        length of data
278  * @type:                       object type, see above
279  * @compr:                      compression type
280  * @ino:                        inode number
281  * @bix:                        block index
282  * @data_crc:                   crc32 of payload
283  */
284 struct logfs_object_header {
285         __be32  crc;
286         __be16  len;
287         __u8    type;
288         __u8    compr;
289         __be64  ino;
290         __be64  bix;
291         __be32  data_crc;
292 } __attribute__((packed));
293
294 SIZE_CHECK(logfs_object_header, LOGFS_OBJECT_HEADERSIZE);
295
296 /*
297  * Reserved inode numbers:
298  * LOGFS_INO_MASTER     - master inode (for inode file)
299  * LOGFS_INO_ROOT       - root directory
300  * LOGFS_INO_SEGFILE    - per-segment used bytes and erase count
301  */
302 enum {
303         LOGFS_INO_MAPPING       = 0x00,
304         LOGFS_INO_MASTER        = 0x01,
305         LOGFS_INO_ROOT          = 0x02,
306         LOGFS_INO_SEGFILE       = 0x03,
307         LOGFS_RESERVED_INOS     = 0x10,
308 };
309
310 /*
311  * Inode flags.  High bits should never be written to the medium.  They are
312  * reserved for in-memory usage.
313  * Low bits should either remain in sync with the corresponding FS_*_FL or
314  * reuse slots that obviously don't make sense for logfs.
315  *
316  * LOGFS_IF_DIRTY       Inode must be written back
317  * LOGFS_IF_ZOMBIE      Inode has been deleted
318  * LOGFS_IF_STILLBORN   -ENOSPC happened when creating inode
319  */
320 #define LOGFS_IF_COMPRESSED     0x00000004 /* == FS_COMPR_FL */
321 #define LOGFS_IF_DIRTY          0x20000000
322 #define LOGFS_IF_ZOMBIE         0x40000000
323 #define LOGFS_IF_STILLBORN      0x80000000
324
325 /* Flags available to chattr */
326 #define LOGFS_FL_USER_VISIBLE   (LOGFS_IF_COMPRESSED)
327 #define LOGFS_FL_USER_MODIFIABLE (LOGFS_IF_COMPRESSED)
328 /* Flags inherited from parent directory on file/directory creation */
329 #define LOGFS_FL_INHERITED      (LOGFS_IF_COMPRESSED)
330
331 /**
332  * struct logfs_disk_inode - on-medium inode
333  *
334  * @di_mode:                    file mode
335  * @di_pad:                     reserved, must be 0
336  * @di_flags:                   inode flags, see above
337  * @di_uid:                     user id
338  * @di_gid:                     group id
339  * @di_ctime:                   change time
340  * @di_mtime:                   modify time
341  * @di_refcount:                reference count (aka nlink or link count)
342  * @di_generation:              inode generation, for nfs
343  * @di_used_bytes:              number of bytes used
344  * @di_size:                    file size
345  * @di_data:                    data pointers
346  */
347 struct logfs_disk_inode {
348         __be16  di_mode;
349         __u8    di_height;
350         __u8    di_pad;
351         __be32  di_flags;
352         __be32  di_uid;
353         __be32  di_gid;
354
355         __be64  di_ctime;
356         __be64  di_mtime;
357
358         __be64  di_atime;
359         __be32  di_refcount;
360         __be32  di_generation;
361
362         __be64  di_used_bytes;
363         __be64  di_size;
364
365         __be64  di_data[LOGFS_EMBEDDED_FIELDS];
366 };
367
368 SIZE_CHECK(logfs_disk_inode, 200);
369
370 #define INODE_POINTER_OFS \
371         (offsetof(struct logfs_disk_inode, di_data) / sizeof(__be64))
372 #define INODE_USED_OFS \
373         (offsetof(struct logfs_disk_inode, di_used_bytes) / sizeof(__be64))
374 #define INODE_SIZE_OFS \
375         (offsetof(struct logfs_disk_inode, di_size) / sizeof(__be64))
376 #define INODE_HEIGHT_OFS        (0)
377
378 /**
379  * struct logfs_disk_dentry - on-medium dentry structure
380  *
381  * @ino:                        inode number
382  * @namelen:                    length of file name
383  * @type:                       file type, identical to bits 12..15 of mode
384  * @name:                       file name
385  */
386 /* FIXME: add 6 bytes of padding to remove the __packed */
387 struct logfs_disk_dentry {
388         __be64  ino;
389         __be16  namelen;
390         __u8    type;
391         __u8    name[LOGFS_MAX_NAMELEN];
392 } __attribute__((packed));
393
394 SIZE_CHECK(logfs_disk_dentry, 266);
395
396 #define RESERVED                0xffffffff
397 #define BADSEG                  0xffffffff
398 /**
399  * struct logfs_segment_entry - segment file entry
400  *
401  * @ec_level:                   erase count and level
402  * @valid:                      number of valid bytes
403  *
404  * Segment file contains one entry for every segment.  ec_level contains the
405  * erasecount in the upper 28 bits and the level in the lower 4 bits.  An
406  * ec_level of BADSEG (-1) identifies bad segments.  valid contains the number
407  * of valid bytes or RESERVED (-1 again) if the segment is used for either the
408  * superblock or the journal, or when the segment is bad.
409  */
410 struct logfs_segment_entry {
411         __be32  ec_level;
412         __be32  valid;
413 };
414
415 SIZE_CHECK(logfs_segment_entry, 8);
416
417 /**
418  * struct logfs_journal_header - header for journal entries (JEs)
419  *
420  * @h_crc:                      crc32 of journal entry
421  * @h_len:                      length of compressed journal entry,
422  *                              not including header
423  * @h_datalen:                  length of uncompressed data
424  * @h_type:                     JE type
425  * @h_compr:                    compression type
426  * @h_pad:                      reserved
427  */
428 struct logfs_journal_header {
429         __be32  h_crc;
430         __be16  h_len;
431         __be16  h_datalen;
432         __be16  h_type;
433         __u8    h_compr;
434         __u8    h_pad[5];
435 };
436
437 SIZE_CHECK(logfs_journal_header, 16);
438
439 /*
440  * Life expectency of data.
441  * VIM_DEFAULT          - default vim
442  * VIM_SEGFILE          - for segment file only - very short-living
443  * VIM_GC               - GC'd data - likely long-living
444  */
445 enum logfs_vim {
446         VIM_DEFAULT     = 0,
447         VIM_SEGFILE     = 1,
448 };
449
450 /**
451  * struct logfs_je_area - wbuf header
452  *
453  * @segno:                      segment number of area
454  * @used_bytes:                 number of bytes already used
455  * @gc_level:                   GC level
456  * @vim:                        life expectancy of data
457  *
458  * "Areas" are segments currently being used for writing.  There is at least
459  * one area per GC level.  Several may be used to separate long-living from
460  * short-living data.  If an area with unknown vim is encountered, it can
461  * simply be closed.
462  * The write buffer immediately follow this header.
463  */
464 struct logfs_je_area {
465         __be32  segno;
466         __be32  used_bytes;
467         __u8    gc_level;
468         __u8    vim;
469 } __attribute__((packed));
470
471 SIZE_CHECK(logfs_je_area, 10);
472
473 #define MAX_JOURNAL_HEADER \
474         (sizeof(struct logfs_journal_header) + sizeof(struct logfs_je_area))
475
476 /**
477  * struct logfs_je_dynsb - dynamic superblock
478  *
479  * @ds_gec:                     global erase count
480  * @ds_sweeper:                 current position of GC "sweeper"
481  * @ds_rename_dir:              source directory ino (see dir.c documentation)
482  * @ds_rename_pos:              position of source dd (see dir.c documentation)
483  * @ds_victim_ino:              victims of incomplete dir operation (see dir.c)
484  * @ds_victim_ino:              parent inode of victim (see dir.c)
485  * @ds_used_bytes:              number of used bytes
486  */
487 struct logfs_je_dynsb {
488         __be64  ds_gec;
489         __be64  ds_sweeper;
490
491         __be64  ds_rename_dir;
492         __be64  ds_rename_pos;
493
494         __be64  ds_victim_ino;
495         __be64  ds_victim_parent; /* XXX */
496
497         __be64  ds_used_bytes;
498         __be32  ds_generation;
499         __be32  pad;
500 };
501
502 SIZE_CHECK(logfs_je_dynsb, 64);
503
504 /**
505  * struct logfs_je_anchor - anchor of filesystem tree, aka master inode
506  *
507  * @da_size:                    size of inode file
508  * @da_last_ino:                last created inode
509  * @da_used_bytes:              number of bytes used
510  * @da_data:                    data pointers
511  */
512 struct logfs_je_anchor {
513         __be64  da_size;
514         __be64  da_last_ino;
515
516         __be64  da_used_bytes;
517         u8      da_height;
518         u8      pad[7];
519
520         __be64  da_data[LOGFS_EMBEDDED_FIELDS];
521 };
522
523 SIZE_CHECK(logfs_je_anchor, 168);
524
525 /**
526  * struct logfs_je_spillout - spillout entry (from 1st to 2nd journal)
527  *
528  * @so_segment:                 segments used for 2nd journal
529  *
530  * Length of the array is given by h_len field in the header.
531  */
532 struct logfs_je_spillout {
533         __be64  so_segment[0];
534 };
535
536 SIZE_CHECK(logfs_je_spillout, 0);
537
538 /**
539  * struct logfs_je_journal_ec - erase counts for all journal segments
540  *
541  * @ec:                         erase count
542  *
543  * Length of the array is given by h_len field in the header.
544  */
545 struct logfs_je_journal_ec {
546         __be32  ec[0];
547 };
548
549 SIZE_CHECK(logfs_je_journal_ec, 0);
550
551 /**
552  * struct logfs_je_free_segments - list of free segmetns with erase count
553  */
554 struct logfs_je_free_segments {
555         __be32  segno;
556         __be32  ec;
557 };
558
559 SIZE_CHECK(logfs_je_free_segments, 8);
560
561 /**
562  * struct logfs_seg_alias - list of segment aliases
563  */
564 struct logfs_seg_alias {
565         __be32  old_segno;
566         __be32  new_segno;
567 };
568
569 SIZE_CHECK(logfs_seg_alias, 8);
570
571 /**
572  * struct logfs_obj_alias - list of object aliases
573  */
574 struct logfs_obj_alias {
575         __be64  ino;
576         __be64  bix;
577         __be64  val;
578         u8      level;
579         u8      pad[5];
580         __be16  child_no;
581 };
582
583 SIZE_CHECK(logfs_obj_alias, 32);
584
585 /**
586  * Compression types.
587  *
588  * COMPR_NONE   - uncompressed
589  * COMPR_ZLIB   - compressed with zlib
590  */
591 enum {
592         COMPR_NONE      = 0,
593         COMPR_ZLIB      = 1,
594 };
595
596 /*
597  * Journal entries come in groups of 16.  First group contains unique
598  * entries, next groups contain one entry per level
599  *
600  * JE_FIRST     - smallest possible journal entry number
601  *
602  * JEG_BASE     - base group, containing unique entries
603  * JE_COMMIT    - commit entry, validates all previous entries
604  * JE_DYNSB     - dynamic superblock, anything that ought to be in the
605  *                superblock but cannot because it is read-write data
606  * JE_ANCHOR    - anchor aka master inode aka inode file's inode
607  * JE_ERASECOUNT  erasecounts for all journal segments
608  * JE_SPILLOUT  - unused
609  * JE_SEG_ALIAS - aliases segments
610  * JE_AREA      - area description
611  *
612  * JE_LAST      - largest possible journal entry number
613  */
614 enum {
615         JE_FIRST        = 0x01,
616
617         JEG_BASE        = 0x00,
618         JE_COMMIT       = 0x02,
619         JE_DYNSB        = 0x03,
620         JE_ANCHOR       = 0x04,
621         JE_ERASECOUNT   = 0x05,
622         JE_SPILLOUT     = 0x06,
623         JE_OBJ_ALIAS    = 0x0d,
624         JE_AREA         = 0x0e,
625
626         JE_LAST         = 0x0e,
627 };
628
629 #endif