1/*	$NetBSD: efs.h,v 1.1 2007/06/29 23:30:27 rumble Exp $	*/
2
3/*
4 * Copyright (c) 2006 Stephen M. Rumble <rumble@ephemeral.org>
5 *
6 * Permission to use, copy, modify, and distribute this software for any
7 * purpose with or without fee is hereby granted, provided that the above
8 * copyright notice and this permission notice appear in all copies.
9 *
10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 */
18
19/*
20 * See IRIX efs(4)
21 */
22
23#ifndef _FS_EFS_EFS_H_
24#define _FS_EFS_EFS_H_
25
26#define EFS_DEBUG
27
28/*
29 * SGI EFS - Extent File System
30 *
31 * The EFS filesystem is comprised of 512-byte sectors, or "basic blocks" (bb).
32 * These blocks are divided into cylinder groups (cg), from which extents are
33 * allocated. An extent is a contiguous region of blocks with minimal length
34 * of 1 and maximal length of 248.
35 *
36 * The filesystem is limited to 8GB by struct efs_extent's ex_bn field, which
37 * specifies an extent's offset in terms of basic blocks. Unfortunately, it was
38 * squished into a bitfield and given only 24bits so we are left with
39 * 2**24 * 512 bytes. Individual files are maximally 2GB, but not due to any
40 * limitation of on-disk structures. All sizes and offsets are stored as block,
41 * not byte values, with the exception of sb.sb_bmsize and efs_dinode.di_size.
42 *
43 * An EFS filesystem begins with the superblock (struct efs_sb) at bb offset 1
44 * (offset 0 is reserved for bootblocks and other forms of contraband). The
45 * superblock contains various parameters including magic, checksum, filesystem
46 * size, number of cylinder groups, size of cylinder groups, and location of the
47 * first cylinder group. A bitmap may begin at offset bb 2. This is true of
48 * filesystems whose magic flag is EFS_MAGIC. However, the ability to grow an
49 * efs filesystem was added in IRIX 3.3 and a grown efs's bitmap is located
50 * toward the end of the disk, pointed to by sb.sb_bmblock. A grown filesystem
51 * is detected with the EFS_NEWMAGIC flag. See below for more details and
52 * differences.
53 *
54 * In order to promote inode and data locality, the disk is separated into
55 * sb.sb_ncg cylinder groups, which consist of sb.sb_cgfsize blocks each.
56 * The cylinder groups are laid out consecutively beginning from block offset
57 * sb.sb_firstcg. The beginning of each cylinder group is comprised of
58 * sb.sb_cgisize inodes (struct efs_dinode). The remaining space contains
59 * file extents, which are preferentially allocated to files whose inodes are
60 * within the same cylinder group.
61 *
62 * EFS increases I/O performance by storing files in contiguous chunks called
63 * 'extents' (struct efs_extent). Extents are variably sized from 1 to 248
64 * blocks, but please don't ask me why 256 isn't the limit.
65 *
66 * Each inode (struct efs_dinode) contains space for twelve extent descriptors,
67 * allowing for up to 1,523,712 byte files (12 * 248 * 512) to be described
68 * without indirection. When indirection is employed, each of the twelve
69 * descriptors may reference extents that contain up to 248 more direct
70 * descriptors. Since each descriptor is 8 bytes we could theoretically have
71 * in total 15,872 * 12 direct descriptors, allowing for 15,872 * 12 * 248 *
72 * 512 = ~22GB files. However, since ei_numextents is a signed 16-bit quantity,
73 * we're limited to only 32767 indirect extents, which leaves us with a ~3.87GB
74 * maximum file size. (Of course, with a maximum filesystem size of 8GB, such a
75 * restriction isn't so bad.) Note that a single full indirect extent could
76 * reference approximately 1.877GB of data, but SGI strikes again! Earlier
77 * versions of IRIX (4.0.5H certainly, and perhaps prior) limit indirect
78 * extents to 32 basic blocks worth. This caps the number of extents at 12 *
79 * 32 * 64, permitting ~2.91GB files. SGI later raised this limit to 64 blocks
80 * worth, which exceeds the range of ei_numextents and gives a maximum
81 * theoretical file size of ~3.87GB. However, EFS purportedly only permits
82 * files up to 2GB in length.
83 *
84 * The bitmap referred to by sb_bmsize and (optionally) sb_bmblock contains
85 * data block allocation information. I haven't looked at this at all, nor
86 * am I aware of how inode allocation is performed.
87 *
88 * An EFS disk layout looks like the following:
89 *     ____________________________________________________________________
90 *    | unused | superblock | bitmap | pad | cyl grp | ..cyl grps... | pad |
91 *     --------------------------------------------------------------------
92 * bb:     0          1         2          ^-sb.sb_firstcg      sb.sb_size-^
93 *
94 * A cylinder group looks like the following:
95 *     ____________________________________________________________________
96 *    |    inodes    |           ... extents and free space ...            |
97 *     --------------------------------------------------------------------
98 *           0       ^-(sb.sb_cgisize *                      sb.sb_cgfsize-^
99 *                      sizeof(struct efs_dinode))
100 *
101 * So far as I am aware, EFS file systems have always been big endian, existing
102 * on mips (and perhaps earlier on m68k) machines only. While mips chips are
103 * bi-endian, I am unaware of any sgimips machine that was used in mipsel mode.
104 *
105 * See efs_sb.h, efs_dir.h, and efs_dinode.h for more information regarding
106 * directory layout and on-disk inodes, and the superblock accordingly.
107 */
108
109/*
110 * Basic blocks are always 512 bytes.
111 */
112#define EFS_BB_SHFT	9
113#define EFS_BB_SIZE	(1 << EFS_BB_SHFT)
114
115/*
116 * EFS basic block layout:
117 */
118#define EFS_BB_UNUSED	0	/* bb 0 is unused */
119#define EFS_BB_SB	1	/* bb 1 is superblock */
120#define EFS_BB_BITMAP	2	/* bb 2 is bitmap (unless moved by growfs) */
121/* bitmap continues, then padding up to first aligned cylinder group */
122
123/*
124 * basic block <-> byte conversions
125 */
126#define EFS_BB2BY(_x)		((_x) << EFS_BB_SHFT)
127#define EFS_BY2BB(_x)		(((_x) + EFS_BB_SIZE - 1) >> EFS_BB_SHFT)
128
129/*
130 * Struct efs_extent limits us to 24 bit offsets, therefore the maximum
131 * efs.sb_size is 2**24 blocks (8GB).
132 *
133 * Trivia: IRIX's mkfs_efs(1M) has claimed the maximum to be 0xfffffe for years.
134 */
135#define EFS_SIZE_MAX		0x01000000
136
137#ifdef _KERNEL
138
139#define	VFSTOEFS(mp)    ((struct efs_mount *)(mp)->mnt_data)
140
141/* debug goo */
142#ifdef DEBUG
143#define EFS_DEBUG
144#endif
145#ifdef EFS_DEBUG
146#define EFS_DPRINTF(_x)	printf _x
147#else
148#define EFS_DPRINTF(_x)
149#endif
150
151#endif
152
153#endif /* !_FS_EFS_EFS_H_ */
154