Home | History | Annotate | Line # | Download | only in efs 
      1 /*	$NetBSD: efs.h,v 1.2 2007/06/30 15:56:16 rumble Exp $	*/
      2 
      3 /*
      4  * Copyright (c) 2006 Stephen M. Rumble <rumble (at) 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