code: mafs

ref: 4210fbecf4d94bd5873037bc3f5c721f47f42a2c
dir: /docs/mafs.ms/

View raw version
.\" The current font is \n(.f
.\" The current point size is \n(.s
.\" The current vertical line spacing is \n(.v
.\" The line length is \n(.l
.\" The page length is \n(.p
.\" The page offset is \n(.o
.\" need this RT call else, the subsequent pages are losing the indent
.RT
.ft B
.ce
Mafs - Plan 9 userspace file systems
.ft R
.sp
Mafs wants you to be able to understand it, so you can be self-sufficient and fix a crash at two in the morning or satisfy your need for speed or a feature. This empowerment is priceless for those with skin in the game.
.sp
Mafs is a user space file systems to provide system stability and security. It is based on kfs.
.sp
As this document aims to also provide working knowledge, it gratuitously uses the actual commands and the relevant C data structure definitions to convey information.
.sp
.ft B
Mafs Workflow
.ft R
.sp
.PS
right;
{
	Client: box invis height 4*boxht wid 2*boxwid "" "" "" "Chan.aux has" "file offset, etc.";
	"Client" at Client.n
	line from Client.ne to Client.se
}
move 2*boxwid
{
	Multiple: box invis
	{
		" multiple" at Multiple.nw - 0,0.1 ljust
		" workers" at Multiple.sw + 0,0.1 ljust
		line <-> from Client to Multiple.w "9p" above
	}
	move 0.5*boxwid
	Abstractions: box invis "Abstractions"
	{ "Directory" "File" at Abstractions.s }
	move 0.75*boxwid
	Datastructures: box invis "Data Structures"
	{ "Dentry" at Datastructures.s }
	Buffercache: box invis "Buffer cache" "used blocks" with .sw at Datastructures.ne + 0.5i,0
	Extents: box invis "Extents" "free blocks" with .nw at Datastructures.se + 0.5i,0
	move 0.5*boxwid
	Inmemory: box invis "In-memory" "block contents" with .sw at Buffercache.n + 0.5i,0
	down
	move 0.5*boxwid
	Disk: box "Disk" "blocks" height 1.5*boxht with .sw at Extents.se + 0.4i,0
}
	line <-> from Multiple.e to Abstractions.w - 0.1i,0
	line <-> from Abstractions.e + 0.1i,0 to Datastructures.w - 0.2i,0
	line <-> from Datastructures.e + 0,0.1i to Buffercache.w - 0.1i,0
	line <-> from Datastructures.e - 0,0.1i to Extents.w
	line <-> from Buffercache.se + 0.1i,0 to Disk.w
	line <-> from Extents.e to Disk.w
	line <-> from Buffercache.s to Extents.n
	line <-> from Buffercache.ne - 0,0.1i to Inmemory.sw + 0,0.1i
.PE
.sp
.sp
.ft B
Disk Contents
.ft R
.sp
Mafs organizes and saves content on a disk as directories and files, just like any other filesystem.
.sp
The unit of storage is a logical block (not physical sector) of data. Disk space is split into blocks of 512 bytes. A directory entry uses 2 blocks (1KiB) and a data block could use upto 2048 blocks (1MiB).
.sp
.ne 14
A sample disk of 2048 bytes with 4 blocks.
.PS
right
{
	down;
."	{box dashed; box dashed; box dashed; box dashed;}
	box height 4*boxht;
	move 0.2i;
	"disk of" " 2048 bytes"
}
move; move
{
	move 0.5i;
	down;
	{
		Block0: box dashed;
		Block1: box dashed;
		Block2: box dashed;
		Block3: box dashed;
	}
	box height 4*boxht;
	move 0.2i
	"disk of" " 2048 bytes"
	"Block  " at Block0.nw rjust
	"0  " at Block0.w rjust
	"1  " at Block1.w rjust
	"2  " at Block2.w rjust
	"3  " at Block3.w rjust
}
.PE
.sp
A block is stored to the disk with a tag in the first byte and the Qid.path in the last 8 bytes. The different types of blocks on a disk are:
.br
.nf
enum
{
	Tblank = 0,
	Tfree  = 0,	/* free block */
	Tnone  = 0,
	Tdata,		/* actual file contents */
	Tdentry,	/* directory entry, size = Dentrysize */
				/* Tdata & indirect blocks are last, to allow for greater depth */
	Tind0,		/* contains a list of Tdata block numbers for files
					and Tdentry block numbers for directories.*/
	Tind1,		/* contains a list of Tind0 block numbers */
	Tind2,		/* contains a list of Tind1 block numbers */
	Tind3,		/* contains a list of Tind1 block numbers */
	Tind4,		/* contains a list of Tind1 block numbers */
				/* gap for more indirect block depth in future.
					It can be put upto Tind7 without needing any code changes */
	Maxtind,	/* should be Tind0+Niblock */
	MAXTAG = Maxtind,

	Tmaxind = Maxtind - 1,
};
.fi
.sp
Every file or directory is represented on the disk by a directory entry (Dentry). A directory entry uses a unit sized block (tag = Tdentry) and is uniquely identifiable by a Qid.
.sp
A file's contents are stored in the directory entry itself if they are 320 bytes or lesser. A file stores its contents in blocks with a tag of Tdata if the file size is more than that. A directory holds the directory entries of it's children in blocks each with a tag of Tdentry.
.sp
The blocks used by a file or directory entry are listed in their directory entry. As it is not possible to represent big files using the list of blocks available in the directory entry, the blocks are structured to use multiple levels of indirection as the file size increases.
.sp
A file's data blocks are identified by a tag of Tdata and that file's Qid.path. A directory's data blocks are identified by a tag of Tdentry and Qid.path of the child directory entry. (Is this quirky? Should the child's directory entry have a tag with the parent's Qid.path?)
.sp
A block number of zero represents the end of the file's contents. If a file is truncated, the data and indirect blocks are given up and the dentry.dblocks[0] = 0.
.sp
Mafs does not store the last access time of a file or directory.
.ne 20
.sp
A directory entry is defined as:
.nf
enum {
	Blocksize	= 512ULL,	/* minimum data unit size */

	Metadataunits	= 2,
	Metadatablocksize = Metadataunits*Blocksize, /* Keep the original and a copy together */

	Maxdatablockunits = 2048,
	Nindperblock= (Blocksize-3*sizeof(u64))/sizeof(u64),/* number of pointers per block */

	Namelen = 127,	/* maximum length of a file name, calculated manually */
	Ndblock	= 32,	/* number of direct blocks in a Dentry */
	Niblock	= 5,	/* maximum depth of indirect blocks, can increase it to 8 without issues */
};
struct Dentryhdr
{
	u8 tag;
	u8 verd;
	s16 uid;
	s16 gid;
	s16 muid;		/* 8 */
	u64 size;		/* 0 for directories. For files, size in bytes of the content - 16 */
	u64 pdblkno; 	/* block number of the parent directory entry. Will be 0 for root. - 24 */
	u64 pqpath; 	/* parent path - 32 */
	u64 mtime;		/* modified time in nano seconds from epoch - 40 */
	u64 qpath;		/* unique identifier Qid.path 48 */
	u32 version;	/* Qid.version 52 */
	u32 mode;		/* same bits as defined in /sys/include/libc.h:/Dir\.mode/ - 56 */
	u8 namelen;		/* store name as a counted string 57 */
	s8 name[Namelen]; /* Namelen = 127 - 184*/
};
struct Datahdr
{
	u8 tag;
	u8 unused;	/* for alignment and future use */
	u16 len;
	u64 dblkno;	/* block number of the directory entry */
	u64 path;	/* same as path */
};

enum {
	/* max possible size of data that can be stuffed into a Dentry */
	Ddatasize = Blocksize -sizeof(u64 /* path */) -sizeof(Dentryhdr),
	Maxdatablocksize = Maxdatablockunits*Blocksize -sizeof(Datahdr) -sizeof(u64 /* trailing path */),
};

struct Dentry
{
	Dentryhdr;
	union
	{
		struct
		{
			u64 dblocks[Ndblock];	/* direct blocks. */
									/* List of Tdata block numbers for files and
										Tdentry block numbers for directories */
			u64 iblocks[Niblock];	/* indirect blocks */
		};
		Super;

		/* when size <= Dentrysize-184-sizeof(Tag), store the data here itself */
		s8 buf[Ddatasize];
	};
	u64 path;	/* same as path */
};
struct Indirect
{
	u8 tag;
	u8 veri;
	u8 pad[6];	/* unused, to align to a multiple of 8 */
	u64 dblkno;	/* block number of the directory entry */
	u64 bufa[Nindperblock];
	u64 path;	/* same as path */
};
struct Metadataunit
{
	union
	{
		Indirect;
		Dentry;
	};
};
struct Metadata
{
	union
	{
		Indirect i[2];
		Dentry d[2];
	};
};
struct Data		/* used to unmarshall the disk contents */
{
	Datahdr;
	u8 buf[1];	/* upto Maxdatablocksize, followed by u64 path */
	/* u64 path; same as path at the end of the data content */
};
.fi
.sp
A directory entry once assigned is not given up until the parent directory is removed. It is zero'ed if the directory entry is removed. It is reused by the next directory entry created under that parent directory. This removes the need for garbage collection of directory entries on removals and also avoids zero block numbers in the middle of a directory entry's list of blocks. A zero block number while traversing a directory entry's dblocks or iblocks represents the end of directory or file contents. When a directory is removed, the parent will have a directory entry with a tag of Tdentry and Qpnone and the rest of the contents set to zero.
.sp
A directory entry is stored in two blocks to have a copy on write. These entries are in consecutive blocks.
.sp
A directory's size is always zero.
.sp
.nf
	; tests/6.sizes
		Blocksize 512 Metadataunits 2 Maxdatablockunits 2048
		Dentryhdr size 184 Ddatasize 320
		Dentry size 512 Namelen 127
		Namelen 127 Ndblock 32 Niblock 5
		Nindperblock 61 Maxdatablocksize 1048548
		A Tind0 unit points to 1 data blocks (1048548 bytes)
				block points to 61 data blocks
				reli start 32	max 92
				max size 93*Maxdatablocksize = 97514964 bytes	= 92 MiB
		A Tind1 unit points to 61 data blocks (63961428 bytes)
				block points to 3721 data blocks
				reli start 93	max 3813
				max size 3814*Maxdatablocksize = 3999162072 bytes	= 3 GiB
		A Tind2 unit points to 3721 data blocks (3901647108 bytes)
				block points to 226981 data blocks
				reli start 3814	max 230794
				max size 230795*Maxdatablocksize = 241999635660 bytes	= 225 GiB
		A Tind3 unit points to 226981 data blocks (238000473588 bytes)
				block points to 13845841 data blocks
				reli start 230795	max 14076635
				max size 14076636*Maxdatablocksize = 14760028524528 bytes	= 13 TiB
		A Tind4 unit points to 13845841 data blocks (14518028888868 bytes)
				block points to 844596301 data blocks
				reli start 14076636	max 858672936
				max size 858672937*Maxdatablocksize = 900359790745476 bytes	= 818 TiB
.fi
.ne 30
.sp
On an empty mafs filesystem mounted at /n/mafs, the disk contents added by the below commands are:
.nf
mkdir /n/mafs/dir1
echo test > /n/mafs/dir1/file1
.fi
\" from test.9
.PS
right
bigboxht = boxht
fieldht = 0.35*boxht
{
	down
	{ Bound: box height 9*bigboxht width 3.3*boxwid }
	move 0.1i
	box height fieldht invis "Tdentry 64 2"
	box height fieldht invis "name dir1"
	box height fieldht invis "version 0"
	box height fieldht invis "path 64"
	box height fieldht invis "size 0"
	box height fieldht invis "pdblkno 20"
	box height fieldht invis "pqpath 20"
	box height fieldht invis "mtime 1653302180819962729"
	box height fieldht invis "mode 20000000777"
	box height fieldht invis "uid 10006"
	box height fieldht invis "gid -1"
	box height fieldht invis "muid 10006"
	box height fieldht invis "direct blocks"
	box height fieldht invis "        0 24"
	box height fieldht invis "        1 0"
	box height fieldht invis "        2 0"
	box height fieldht invis "."
	box height fieldht invis "."
	box height fieldht invis "."
	box height fieldht invis "        30 0"
	box height fieldht invis "        31 0"
	box height fieldht invis "indirect blocks"
	box height fieldht invis "        0 0"
	box height fieldht invis "        1 0"
	box height fieldht invis "        2 0"
	"Block 22 contents: /dir1 Dentry" at Bound.nw + 0,0.1i ljust
	"Representation of a file in a directory: /dir1/file1" ljust at Bound.n + 0,0.3i
}
move 4*boxwid
{
	down
	{ Bound: box height 5*bigboxht width 3.3*boxwid }
	move 0.1i
	box height fieldht invis "Tdentry 65 2"
	box height fieldht invis "name file1"
	box height fieldht invis ",version 0"
	box height fieldht invis "path 65"
	box height fieldht invis "size 5"
	box height fieldht invis "pdblkno "
	box height fieldht invis "pqpath 64"
	box height fieldht invis "mtime 1653302180823455071"
	box height fieldht invis "mode 666"
	box height fieldht invis "uid 10006"
	box height fieldht invis "gid -1"
	box height fieldht invis "muid 10006"
	"Block 24 contents: file1 Dentry" at Bound.nw + 0,0.1i ljust
}
down
move 9*bigboxht
{
	down
	{ Bound: box height 5*bigboxht width 3.3*boxwid }
	move 0.1i
	box height fieldht invis "Tdentry 65 3"
	box height fieldht invis "name file1"
	box height fieldht invis "version 0"
	box height fieldht invis "path 65"
	box height fieldht invis "size 5"
	box height fieldht invis "pdblkno "
	box height fieldht invis "pqpath 64"
	box height fieldht invis "mtime 1653302180823455071"
	box height fieldht invis "mode 666"
	box height fieldht invis "uid 10006"
	box height fieldht invis "gid -1"
	box height fieldht invis "muid 10006"
	box height fieldht invis "test"
	"Block 25 contents: file1 Dentry" at Bound.nw + 0,0.1i ljust
}
.PE
.sp
.PS
right
Start: {
	down
	{ Bound: box height 8.5*bigboxht width 3.3*boxwid }
	move 0.1i
	box height fieldht invis "Tdentry 66 3"
	box height fieldht invis "name dir2"
	box height fieldht invis "version 0"
	box height fieldht invis "path 66"
	box height fieldht invis "size 0"
	box height fieldht invis "pdblkno 10"
	box height fieldht invis "pqpath 10"
	box height fieldht invis "mtime 1653302180819962729"
	box height fieldht invis "mode 20000000777"
	box height fieldht invis "uid 10006"
	box height fieldht invis "gid -1"
	box height fieldht invis "muid 10006"
	box height fieldht invis "direct blocks"
	box height fieldht invis "        0 28"
	box height fieldht invis "        1 30"
	box height fieldht invis "."
	box height fieldht invis "."
	box height fieldht invis "."
	box height fieldht invis "        31 0"
	box height fieldht invis "indirect blocks"
	box height fieldht invis "        0 0"
	box height fieldht invis "        1 0"
	box height fieldht invis "        2 0"
	"Block 27 contents: /dir2 directory entry" at Bound.nw + 0,0.1i ljust
	"Representation of two files in a directory (/dir2/file1 and /dir2/file2)" ljust at Bound.nw + 0.2,0.3i
}
move 4*boxwid
{
	down
	{ Bound: box height 8.5*bigboxht width 3.3*boxwid }
	move 0.1i
	box height fieldht invis "Tdentry 67 3"
	box height fieldht invis "name file1"
	box height fieldht invis "version 0"
	box height fieldht invis "path 67"
	box height fieldht invis "size 5"
	box height fieldht invis "pdblkno 13"
	box height fieldht invis "pqpath 66"
	box height fieldht invis "mtime 1653302180823455071"
	box height fieldht invis "mode 666"
	box height fieldht invis "uid 10006"
	box height fieldht invis "gid -1"
	box height fieldht invis "muid 10006"
	box height fieldht invis "test"
	"Block 29 contents: file1 directory entry" at Bound.nw + 0,0.1i ljust
}
down
move 9*bigboxht
{
	down
	{ Bound: box height 8.5*bigboxht width 3.3*boxwid }
	move 0.1i
	box height fieldht invis "Tdentry 68 3"
	box height fieldht invis "name file2"
	box height fieldht invis "version 0"
	box height fieldht invis "path 68"
	box height fieldht invis "size 5"
	box height fieldht invis "pdblkno 13"
	box height fieldht invis "pqpath 66"
	box height fieldht invis "mtime 1653302180823455071"
	box height fieldht invis "mode 666"
	box height fieldht invis "uid 10006"
	box height fieldht invis "gid -1"
	box height fieldht invis "muid 10006"
	box height fieldht invis "test"
	"Block 31 contents: file2 directory entry" at Bound.nw + 0,0.1i ljust
}
.PE
.sp
iblocks[0] holds the block number of a Tind0 block. A Tind0 block contains a list of Tdata block numbers for files or a list of Tdentry block numbers for directories.
.sp
iblocks[1] has the block number of a Tind1 block. A Tind1 block contains a list of Tind0 block numbers.
.sp
Similarly, for other iblocks[n] entries, iblocks[n] has the block number of a Tind\fIn\fR block. A Tind\fIn\fR block contains a list of Tind\fI(n-1)\fR block numbers.
.sp
.sp
Relative index
.sp
The zero'th relative index in a directory entry is the first data block. The next relative index is the second data block of the directory entry, and so on.
.sp
tests/6.reli shows how a relative index (reli) is translated into an actual disk block number.
.sp
To find the actual block number where the first block (zero'th as zero indexed) of a file is stored:
.nf
	tests/6.reli 0 # command, below is the output of this command
	reli 0
	dblock[0]
.fi
.sp
To find the actual block number where the second block of a file is stored:
.nf
	tests/6.reli 1
	reli 1
	dblock[1]
.fi
.sp
And so on, for the 32nd and 33rd blocks of a file:
.nf
	tests/6.reli 31
	reli 31
	dblock[31]

	tests/6.reli 32
	reli 32
	iblock[0] tagstartreli 32
	Tind0 reli 0 is at [0] nperindunit 1
.fi
.sp
.PS
right
Start: {
	down
	{ Bound: box height 8.5*bigboxht width 3.3*boxwid }
	move 0.1i
	box height fieldht invis "Tdentry 70 5"
	box height fieldht invis "name 2MB.file"
	box height fieldht invis "version 0"
	box height fieldht invis "path 70"
	box height fieldht invis "size 2056192"
	box height fieldht invis "pdblkno 16"
	box height fieldht invis "pqpath 69"
	box height fieldht invis "mtime 1653302180819962729"
	box height fieldht invis "mode 20000000777"
	box height fieldht invis "uid 10006"
	box height fieldht invis "gid -1"
	box height fieldht invis "muid 10006"
	box height fieldht invis "direct blocks"
	box height fieldht invis "        0 36"
	box height fieldht invis "        1 41000"
	box height fieldht invis "        2 0"
	box height fieldht invis "."
	box height fieldht invis "."
	box height fieldht invis "indirect blocks"
	box height fieldht invis "       0 0"
	box height fieldht invis "       1 0"
	box height fieldht invis "       2 0"
	"Block 35 contents" at Bound.nw + 0,0.1i ljust
	"Representation of a 2 MiB file (/dir3/2MB.file)" ljust at Bound.n + 0,0.3i
}
move 4*boxwid
{
	down
	{ Bound: box height 6*bigboxht width 3.3*boxwid }
	move 0.1i
	box height fieldht invis "Tdata 70 34 2048"
	box height fieldht invis "0 0123456789"; {"contents of 2MB.file" at last box.e + 1i,0 ljust}
	"Block 36 contents" at Bound.nw + 0,0.1i ljust
}
.PE
\" from test.a
.PS
right
Start: {
	down
	{ Bound: box height 9*bigboxht width 3.3*boxwid }
	move 0.1i
	box height fieldht invis "Tdentry 64 104"
	box height fieldht invis "name big.file"
	box height fieldht invis "version 0"
	box height fieldht invis "path 64"
	box height fieldht invis "size 26214400"
	box height fieldht invis "pdblkno 20"
	box height fieldht invis "pqpath 20"
	box height fieldht invis "mtime 1653302180819962729"
	box height fieldht invis "mode 664"
	box height fieldht invis "uid 10006"
	box height fieldht invis "gid -1"
	box height fieldht invis "muid 10006"
	box height fieldht invis "direct blocks"
	box height fieldht invis "       0 24"
	box height fieldht invis "       1 2072"
	box height fieldht invis "       2 4120"
	box height fieldht invis "."
	box height fieldht invis "."
	box height fieldht invis "       31 63512"
	box height fieldht invis "indirect blocks"
	box height fieldht invis "       0 67608"
	box height fieldht invis "       1 192538"
	box height fieldht invis "       2 0"
	"Block 22 contents" at Bound.nw + 0,0.1i ljust
	"Representation of a 100 MiB file (/big.file)" ljust at Bound.n + 0,0.3i
}
move 4*boxwid
{
	down
	{ Bound: box height 4*bigboxht width 3.3*boxwid }
	move 0.1i
	box height fieldht invis "Tdata 64 22 2048"
	box height fieldht invis "0 0123456789"; {"starting contents" at last box.e + 1i,0 ljust;}
	box height fieldht invis "."; {"of big.file" at last box.e + 1i,0 ljust}
	box height fieldht invis "."
	box height fieldht invis "."
	"Block 24 contents" at Bound.nw + 0,0.1i ljust
}
move to Start - 0,9.5*bigboxht
{
	down
	{ Bound: box height 3*bigboxht width 3.3*boxwid }
	move 0.1i
	box height fieldht invis "Tind0 64 60 22"
	box height fieldht invis "	0 65560"
	box height fieldht invis "	1 67610"
	box height fieldht invis "	2 69658"
	box height fieldht invis "."
	box height fieldht invis "."
	"Block 67608 contents" at Bound.nw + 0,0.1i ljust
}
right
move 4*boxwid
{
	down
	{ Bound: box height 3*bigboxht width 3.3*boxwid }
	move 0.1i
	box height fieldht invis "Tdata 64 22 2048"
	box height fieldht invis "+06 0123456789"; {"more content" at last box.e + 1i,0 ljust}
	box height fieldht invis "."; {"of big.file" at last box.e + 1i,0 ljust}
	box height fieldht invis "."
	"Block 65560 contents" at Bound.nw + 0,0.1i ljust
}
.PE
.sp
.TS
box;
c s
c l
l a .
System Files
=
Block	Description
0	magic dir entry and data
2	/adm/config dir entry
4	/adm/super dir entry
_
6	/adm/ dir entry
8	/adm/users/ dir entry
10	/adm/bkp/ dir entry
_
12	/adm/users/inuse dir entry
14	/adm/frees dir entry
16	/adm/ctl dir entry -- virtual file, empty contents
_
18	/adm/users/staging dir entry
20	/ direntry
_
.TE
.ta 5n 10n 15n 20n 25n 30n 35n 40n 45n 50n 55n 60n 65n 70n 75n 80n
.sp
The /adm/ctl file is used to halt or sync the file system. /adm/users is a r/w file that will reload users when written to it. The owner of the /adm/ctl file or any user belonging to the sys group can ream the disk.
.sp
There is no /adm/magic directory entry as the block number of the magic block is zero and zero block in a directory entry signifies the end of the directory contents.
.sp
.sp
.ne 4
Backup blocks
.sp
A copy of Config, Super and Root blocks is maintained. This ensures a backup of config, Super and root blocks.
.sp
The backup block numbers on the disk are calculated during ream based on the disk size.
.sp
.TS
box;
c l c
l a a .
Block	Description	Backup Block
_
1	/adm/config	last block number -2
2	/adm/super	last block number -4
10	/	last block number -6
.TE
.ta 5n 10n 15n 20n 25n 30n 35n 40n 45n 50n 55n 60n 65n 70n 75n 80n
.sp
Mafs needs atleast Nminblocks=28 blocks (14 KiB).
.fi
.sp
kfs and cwfs use 8192 byte blocks. Hence, they store multiple directory entries (Dentry) per block. They use slot numbers to identify a particular directory entry in a block of directory entries. Mafs avoids that be using 512 byte blocks thus having only one directory entry per block. This avoids locking up other sibling directory entries on access.
.sp
.sp
.ne 4
Users
.sp
Users are defined in /adm/users/inuse file. Any changes to it are made through the /adm/users/staging file. All changes are written to the staging file and then inuse file is updated by writing the command users to the /adm/ctl file.
.sp
Either all changes to /adm/users/inuse are installed or nothing is installed from the /adm/users/staging file.
.sp
The format of /adm/users/inuse is described in users(6).
.sp
.sp
.ft B
Buffer cache - Hash buckets with a circular linked list of Iobuf's for collisions.
.ft R
.sp
An Iobuf is used to represent a block in memory. An Iobuf is unique to a block. All disk interaction, except for free block management, happens through an Iobuf. We read a block from the disk into an Iobuf. To update a block on the disk, we write to an Iobuf, which, in-turn gets written to the disk.
.sp
An Iobuf is protected by a read-write lock (RWlock). This ensures synchronization across multiple processes updating the same file.
.sp
getbuf(), putbuf(), putbufs() and putbuffree() are used to manage Iobuf's. The contents of an Iobuf is not touched unless it is locked by getbuf(). It is unlocked by putbuf(), putbufs() or putbuffree() calls. The Iobuf.dirties Ref is decremented by the mafs writer's dowrite() without a lock(). This is to avoid deadlocks between putbuf() and the writer especially when the writer queue is full.
.sp
allocblock() allocates a free block into an Iobuf. allocblocks() allocates a bunch of free blocks with their own Iobuf's.
.sp
freeblock() erases the Iobuf and returns the block to the free block management routines.
.sp
Iobuf's are organized into a list of hash buckets to speed up access.
.sp
.nf
Hiob *hiob = nil;	/* array of nbuckets */
struct Hiob		/* Hash bucket */
{
	Iobuf* link;	/* least recently used Iobuf in the circular linked list */
	QLock;		/* controls access to this hash bucket */
};
struct Iobuf
{
	Ref;
	RWLock;			/* controls access to this Iobuf */
	u64	blkno;		/* block number on the disk, primary key */
	u16	len;		/* number of Units */
	Iobuf *fore;	/* for lru */
	Iobuf *back;	/* for lru */
	union{
		u8	*xiobuf;	/* "real" buffer pointer */
		Data *io;
		Metadata *m;
	};
	Metadataunit *cur;	/* this has the current Indirect or Dentry values */
	Metadataunit *new;	/* use this unit for Indirect or Dentry changes */

	u8 *append;		/* appended data added not yet written to disk */
	u64 appendsize;
	u8 freshalloc;	/* uninitialized blocks on the disk */
};
.fi
.sp
The Iobuf's are arranged into a list of hash buckets. Each bucket points a circular linked list of Iobuf's to handle collisions. If all the Iobuf's in the circular linked list are locked, new Iobuf's are added to this linked list. This circular list is ordered on a least recently used basis. Iobuf's once added to this list are not removed. When an Iobuf is not in the list, the oldest unlocked Iobuf is reused.
.sp
Hiob hiob[nbuckets] is a valid representation of the list of hash buckets. The block number is hashed to arrive at the relevant hash bucket index.
.sp
hiob[hash(block number)].link = Address of Iobuf0, where Iobuf0 is the least recently used Iobuf.
.PS
{
	right
	Iobuf0: box "Iobuf 0"; move
	Iobuf1: box "Iobuf 1"; move
	Iobuf2: box "Iobuf 2"
}
down
move; move
{
	right
	Iobufn: box "Iobuf n"; move
	Iobufn1: box "Iobuf n-1"; move
	Iobufn2: box "Iobuf n-2"
}
arrow from Iobuf0.ne - 0,0.05i to Iobuf1.nw - 0,0.05i
arrow from Iobuf1.sw + 0,0.05i to Iobuf0.se + 0,0.05i
arrow from Iobuf1.ne - 0,0.05i to Iobuf2.nw - 0,0.05i
arrow from Iobuf2.sw + 0,0.05i to Iobuf1.se + 0,0.05i

arrow from Iobufn.ne - 0,0.05i to Iobufn1.nw - 0,0.05i
arrow from Iobufn1.sw + 0,0.05i to Iobufn.se + 0,0.05i
arrow from Iobufn1.ne - 0,0.05i to Iobufn2.nw - 0,0.05i
arrow from Iobufn2.sw + 0,0.05i to Iobufn1.se + 0,0.05i

arrow dashed from Iobuf0.sw + 0.05i,0 to Iobufn.nw + 0.05i,0
arrow dashed from Iobufn.ne - 0.05i,0 to Iobuf0.se - 0.05i,0
arrow dashed from Iobuf2.sw + 0.05i,0 to Iobufn2.nw + 0.05i,0
arrow dashed from Iobufn2.ne - 0.05i,0 to Iobuf2.se - 0.05i,0
.PE
.sp
The size of the buffer cache is: number of hash buckets * collisions per hash bucket * block size. The approximate size of the buffer cache = Nbuckets * Ncollisions * Rawblocksize = 256 * 10 * 512 bytes = 1.28GiB. The -h parameter can be used to change the number of hash buckets.
.sp
If you have RAM to spare, increase Nbuckets instead of Ncollisions as the hash index lookup is faster than searching through a linked list.
.sp
Iobuf.Ref is used to avoid locking up the hash bucket when a process is waiting for a lock on an Iobuf in that hash bucket.
.sp
Iobuf.Ref ensures that an Iobuf is not stolen before another process can get to wlock()'ing it after letting go of the lock on the hash bucket. We cannot hold the lock on the hash bucket until we wlock() the iobuf as that blocks other processes from using the hash bucket. This could also result in a deadlock. For example, the directory entry is block 18, which hashes to a hash index of 7. A writer() locked the directory entry iobuf and wants to add a data block 84 to the directory entry. Block 84 hashes to the same hash index of 7. Another process wanting to access the directory entry is waiting for a lock on that io buffer. While doing so, it has locked the hash bucket. Now, this has caused a deadlock between both these processes. The first process cannot proceed until it can lock the hash bucket holding block 84 and is still holding the lock on the directory entry in block 18. The second process cannot lock block 18 and is holding the lock on the hash bucket.
.nf
	for locking a buffer:
		qlock(hash bucket); incref(buffer); qunlock(hash bucket);
			wlock(buffer); decref(buffer);

	for stealing an unused buffer:
		qlock(hash bucket);
		find a buffer with ref == 0 and wlock()'able.
		qunlock(hash bucket);

	for unlocking a buffer:
		wunlock(buffer);
.fi
.sp
.sp
.ne 4
.ft B
Free blocks
.ft R
.sp
Free blocks are managed using Extents. The list of free blocks is stored to the disk when shutting down. If this state is not written, then the file system needs to be checked and the list of free blocks should be updated.
.sp
When shutting down, the Extents are written to free blocks. This information can be accessed from /adm/frees. Also, fsok in the super block is set to 1. Mafs does not start until fsok is 1. When fsok = 0, run the sanity check that the unused blocks and the free blocks in /adm/frees match up. disk/reconcile identifies any missing blocks or blocks that are marked as both used and free.
.sp
This process of fixing issues and setting fsok to 1 is manual. There is no automatic file system checker as in other file systems. This document aims to empower you with the knowledge to fix your file system issues instead of entrusting your precious data to an arbitrary decision maker such as the file system checker.
.sp
A tag of Tfree and Qpnone represent a free block. If a directory entry is removed, the parent will have a zero'ed out child directory entry (Qid.path = 0) and a tag of Tdentry and Qpnone.
.sp
.sp
.ne 4
.ft B
Extents
.ft R
.sp
Free blocks and memory are managed using Extents, an abstraction used to manage a continuous list of items.
.sp
An Extent represents a continuous list of items. An Extents is a list of such Extent's.
.sp
.nf
struct Extent {
	struct Extent *low, *high;	/* sorted by start */
	u64 start;				/* where this extent starts from */
	u64 len; 				/* how many units in this extent */

	/* circular least recently used linked list limited to Nlru items */
	struct Extent *prev, *next;
};
struct Extents {
	Extent *head;	/* find the first block in a jiffy */
	QLock lck;
	u32 n;			/* number of extents */
	Rendez isempty;	/* fully used, nothing available */

	u8 nlru;		/* number of items in the lru linked list */
	Extent *lru;	/* least recently used extent in the circular lru linked list */
};
.fi
.sp
To allocate n items from Extents, we find the lowest (by block number or memory address) extent that can satisfy our request. If a bigger Extent is available, slice it and take the portion we need.
.sp
If there is no available Extent to satisfy our request, panic().
.sp
allocblock() and freeblock() use balloc() and bfree() respectively. balloc() assigns blocks from an extent and bfree() adds them to an extent for next allocation.
.sp
.PS
# define field { [right; box invis $1 ljust; box invis $2 rjust; down] }
# define field { [right; box $1 ljust; box $2 rjust; down] }
define field { [right; box invis $1; box invis $2; down] }
boxht = 0.5*boxht
down
{
	box invis "Extents at memory location 1"
	Extents: {box ht 3*boxht wid 2*boxwid}
	Lru: field("lru", "100")
	{ "  assuming that the Extent at 100 was used last" ljust at Lru.e }
	El: field("el","0")
	{ "  unlocked" ljust at El.e }
	field("n","3")
}
.PE
.PS
down
move 4*boxht
define extent {
	[
		down
		Extent: {box ht 4*boxht wid 2*boxwid}
		field("blkno", $1)
		Len: field("len",$2)
		{ right line dashed from Len.sw to Len.se }
		field("low",$3)
		High: field("high",$4)
		if $5 > 0 then {
			"Extent at" ljust above at Extent.nw
			"$5" ljust above at Extent.n
		}
	]
}
{
	right
	extent("10", "1", "0", "200", 100);
	move
	extent("20", "3", "100", "300", 200);
	move
	extent("30", "2", "200", "0", 300);
}
down
{
	move boxht*5
	right
	box invis "+"
	box invis width 2 "freed block numbers" "11,12,13,14"
	box invis "="
}
down
move boxht*10
{
	right
	extent("10", "5", "0", "200", 100);
	move
	extent("20", "3", "100", "300", 200);
	move
	extent("30", "2", "200", "0", 300);
}
.PE
.PS
# ../tests/extents/addabove
define delimiter {
	down
	line right 5 dashed
	move down 0.25
}
define headingfield {
	[
		right;
		Blkno: box invis $1;
		Len: box invis $2;
	]
}
define order {
	down
	arrowwid=0.15
	arrowht=0.15
	arrow 0.25i at $1
}
right
Before: [
	down
	Head: headingfield("blkno", "len", Blkno.w)
	{ order(Head.w) }
	field("20", "3")
]
{ "Extents before" above ljust at Before.nw }
[
	right
	box invis "+"
	box invis "Block number 40" "followed" "by 3 free blocks"
	box invis "="
]
move
After: [
	down
	Headb: headingfield("blkno", "len", Blkno.w)
	{ order(Headb.w) }
	field("20", "3")
	field("40", "4")
]
{ "Extents after" above ljust at After.nw }
.PE
.PS
delimiter
.PE
.PS
# ../tests/extents/mergeabove
right
Before: [
	down
	Head: headingfield("blkno", "len", Blkno.w)
	{ order(Head.w) }
	field("100", "5")
	field("110", "3")
]
{ "Extents before" above ljust at Before.nw }
[
	right
	box invis "+"
	box invis "Block number 105" "followed" "by 4 free blocks"
	box invis "="
]
move
After: [
	down
	Headb: headingfield("blkno", "len", Blkno.w)
	{ order(Headb.w) }
	field("100", "13")
]
{ "Extents after" above ljust at After.nw }
.PE
.PS
delimiter
.PE
.PS
# ../tests/extents/mergeprevious
right
Before: [
	down
	Head: headingfield("blkno", "len", Blkno.w)
	{ order(Head.w) }
	field("105", "4")
]
{ "Extents before" above ljust at Before.nw }
[
	right
	box invis "+"
	box invis "Block number 101" "followed" "by 3 free blocks"
	box invis "="
]
move
After: [
	down
	Headb: headingfield("blkno", "len", Blkno.w)
	{ order(Headb.w) }
	field("101", "8")
]
{ "Extents after" above ljust at After.nw }
.PE
.PS
delimiter
.PE
.PS
# ../tests/extents/mergenext
right
Before: [
	down
	Head: headingfield("blkno", "len", Blkno.w)
	{ order(Head.w) }
	field("101", "4")
]
{ "Extents before" above ljust at Before.nw }
[
	right
	box invis "+"
	box invis "Block number 105" "followed" "by 3 free blocks"
	box invis "="
]
move
After: [
	down
	Headb: headingfield("blkno", "len", Blkno.w)
	{ order(Headb.w) }
	field("100", "8")
]
{ "Extents after" above ljust at After.nw }
.PE
.PS
delimiter
.PE
.PS
# ../tests/extents/addabove1
right
Before: [
	down
	Head: headingfield("blkno", "len", Blkno.w)
	{ order(Head.w) }
	field("180", "4")
]
{ "Extents before" above ljust at Before.nw }
[
	right
	box invis "+"
	box invis "Block number 250" "followed" "by 3 free blocks"
	box invis "="
]
move
After: [
	down
	Headb: headingfield("blkno", "len", Blkno.w)
	{ order(Headb.w) }
	field("180", "4")
	field("250", "4")
]
{ "Extents after" above ljust at After.nw }
.PE
.PS
delimiter
.PE
.PS
# ../tests/extents/addbelow
right
Before: [
	down
	Head: headingfield("blkno", "len", Blkno.w)
	{ order(Head.w) }
	field("250", "4")
]
{ "Extents before" above ljust at Before.nw }
[
	right
	box invis "+"
	box invis "Block number 180" "followed" "by 3 free blocks"
	box invis "="
]
move
After: [
	down
	Headb: headingfield("blkno", "len", Blkno.w)
	{ order(Headb.w) }
	field("180", "4")
	field("250", "4")
]
{ "Extents after" above ljust at After.nw }
.PE
.sp
Kfs stores the list of free blocks in a Tfrees block and the Superblock. Instead we use block management routines, similar to pool.h, to allocate and monitor free blocks. On shutdown(), the block management routines (extents.[ch]) store state into the free blocks. This can be read from /adm/frees. On startup, this is read back by the block management routines. On a crash, the fsck can walk the directory structure to identify the free blocks and recreate /adm/frees.
.sp
.sp
.ne 12
.ft B
Code details
.ft R
.sp
.TS
allbox;
c c
l a .
Program	Description
_
disk/mafs	Start mafs on a disk.
disk/free	List the free blocks. It reads the contents of /adm/frees.
disk/used	List the used blocks by traversing all directory entries.
disk/block	Show the contents of a block.
disk/unused	Given a list of used blocks, lists the unused blocks.
disk/updatefrees	Update the contents of /adm/frees.
.TE
.sp
.TS
allbox;
c c r
l a r .
File	Description	chatty9p
_
9p.c	9p transactions	2
blk.c	routines to show blocks.
console.c	obsolete. /adm/ctl is the console.
ctl.c	/adm/ctl operations.
dentry.c	encode/decode the file system abstraction into block operations.	3
extents.[ch]	routines to manage the free blocks.	6
iobuf.c	routines on Iobuf's. The bkp() routines operate on Iobuf's.	5
sub.c	initialization and super block related routines.	2
tag.c	routines to manage a relative index (reli) in a directory entry.
user.c	user management routines.
.TE
.ta 5n 10n 15n 20n 25n 30n 35n 40n 45n 50n 55n 60n 65n 70n 75n 80n
.in 0
.sp
A Chan's state could get out of sync with the contents if another process changes the on-disk state. Ephase error occurs when that happens.
.sp
For throughput, multiple processes are used to service 9p i/o requests when the -s flag is not used.
.sp
.sp
.ne 4
.ft B
Useful commands:
.ft R
.sp
Ream and start single process Mafs on a disk and also mount it for use.
.sp
.nf
	mount -c <{disk/mafs -s -r mafs_myservice mydisk <[0=1]} /n/mafs_myservice
.in 3n
.br
	-s: use stdin and stdout for communication
	-r mafs_myservice: ream the disk using mafs_myservice as the service name
	 mydisk: running mafs on the disk, mydisk
.in 0
.fi
.sp
Ream and start multiple-process mafs on a disk.
.sp
.nf
	disk/mafs -r mafs_myservice mydisk
	mount -c /srv/mafs_myservice /n/mafs_myservice
.fi
.sp
.ne 7
Ream and start mafs on a file. Also, mount thet filesystem at /n/mafs_myservice.
.sp
.nf
	dd -if /dev/zero -of myfile -bs 512 -count 128 # 64KB file
	mount -c <{disk/mafs -s -r mafs_service myfile <[0=1]} /n/mafs_myservice

	# to reuse the contents of myfile later, remove -r (ream) from the above command.
	mount -c <{disk/mafs -s myfile <[0=1]} /n/mafs_myservice
.fi
.sp
Prepare and use a disk (/dev/sdF1) for mafs.
.sp
.nf
	disk/fdisk -bawp /dev/sdF1/data	# partition the disk
	echo '
	a fs 9  $-7
	w
	p
	q' | disk/prep -b  /dev/sdF1/plan9	# add an fs plan 9 partition to the disk
	disk/mafs -r mafs_sdF1 /dev/sdF1/fs	# -r to ream the disk
	mount -c /srv/mafs_sdF1 /n/mafs_sdF1

	# for using the mafs file system on the disk later on
	disk/mafs  /dev/sdF1/fs	# no -r
	mount -c /srv/mafs_sdF1 /n/mafs_sdF1
.fi
.sp
Starting mafs on a 2MB byte file. The below commands create a disk.file to use as a disk. Mount /n/mafs_disk.file for the file system.
.sp
.nf
	dd -if /dev/zero -of disk.file -bs 512 -count 4096;
	mount -c <{disk/mafs -s -r mafs_disk.file disk.file \\
		  <[0=1]} /n/mafs_disk.file
.fi
.sp
Starting mafs on a RAM file. The below commands create a ramfs filesystem to use as a disk.
.sp
.nf
	ramfs -m /n/mafs_ramfs
	touch /n/mafs_ramfs/file
	dd -if /dev/zero -of /n/mafs_ramfs/file -count 700 -bs 1m
	disk/mafs -r mafs_ramfs_file /n/mafs_ramfs/file
	mount -c /srv/mafs_ramfs_file /n/mafs_ramfs_file
.fi
.sp
Sync Mafs. This command does not return until all the writes are written to the disk. So, could take a long time if you have a long writer queue.
.sp
	echo sync >> /n/mafs_myservice/adm/ctl
.sp
.sp
.ne 4
Stop Mafs: There are 2 ways to shutdown:
.br
.in 3n
1. Unmount and remove the /srv/mfs_service file (can be rm and unmount too).
.br
2. Write halt into the /adm/ctl file. Unmount() the mafs file system to keep it clean.
.in 0
.sp
In the first instance, the srv() process is driving the shutdown. It calls fsend(). rm /srv/mfs_service file does not wait for fsend() to finish. Hence, there is no way to ensure that memory contents have been flushed to the disk. If the system is shutdown or restarted immediately, there is a very high possibility that the filesystem will be in an inconsistent state.
.sp
In the second instance, fsend() is called by the worker process. It does not return until all the pending writes have been flushed to the disk. It also removes the /srv/mafs_service file and also stops the srv() process. Hence, this is the preferred approach to shutting down the file system.
.sp
There is no way to unmount() automatically on shutdown. The mount() and unmount() calls are client driven and it is not the responsibility of the server to find all the clients that mounted it. Just shutdown and let the respective clients deal with their mess.
.sp
The below command does not return until all the writes are written to the disk. So, could take a long time if you have a long writer queue. This is the proper way to shutdown the mafs file system.
.sp
	echo halt >> /n/mafs_myservice/adm/ctl
.sp
Interpret the contents of a block based on the tag and write out a single formatted block based on the tag
.sp
	disk/block  tests/test.0/disk 22
.sp
Traverse the directory heirarchy and write out all the used block numbers. disk/reconcile uses the output of this to reconcile the list of used blocks with the list of free blocks. Also, writes the invalid blocks to stderr. Starting from root, walk down each directory entry printing out the linked blocks with invalid tags. (Why not just write out the list of dirty blocks too? instead of using a different command for it?)
.sp
	disk/used  tests/test.0/disk
.sp
From the contents of /adm/frees show the list of free blocks. disk/reconcile uses the output of this to reconcile the list of used blocks with the list of free blocks.
.sp
	disk/free  tests/test.0/disk
.sp
Read two lists of block numbers and flag the common and missing blocks.
.sp
.nf
	disk/reconcile -u <{disk/used tests/test.0/disk} \\
		-F <{disk/free  tests/test.0/disk} 32
.fi
.sp
.ne 3
Find traverses the directory heirarchy and identifies the file that a block number belongs to.
.sp
	disk/find tests/test.0/disk 17
.sp
.ne 3
Find the total number of blocks on a disk.
.sp
.nf
	dd -if /dev/sdF1/fs -bs 512 -iseek 1 -count 1 -quiet 1 | awk '$1 == "nblocks" { print $2 }'

	disk/block /dev/sdF1/fs 1 | awk '$1 == "nblocks" { print $2 }'
.fi
.sp
.ne 5
Build the list of free blocks. This should match the contents of /adm/frees.
.sp
.nf
	disk/unused <{disk/used /dev/sdF1/fs} 11721040049 # 11721040049 = total number of disk blocks
	disk/unused <{disk/used test.0/disk} 32 # 32 = total number of disk blocks
.fi
.sp
.ne 5
Change the contents of /adm/frees.
.sp
.nf
	disk/updatefrees tests/test.0/disk <{disk/unused <{disk/used tests/test.0/disk} 32}
	disk/updatefrees /dev/sdF1/fs <{disk/unused <{disk/used /dev/sdF1/fs} 11721040049}
.fi
.sp
.ne 5
A sanity check that the file system is not corrupt by comparing that the unused blocks and free blocks match up. $nblocks is the total number of disk blocks. $disk is the disk.
.sp
.nf
	diff <{disk/unused -l <{disk/used tests/test.0/disk} 32}} <{disk/free tests/test.0/disk}
.fi
.sp
Changing the service name without a ream.
.sp
.nf
	disk/block /dev/sdF1/fs 1 | wc
	Tdata 2
	size 6001172505088
	nblocks 11721040049
	backup config 1 to 11721040048
	backup super 2 to 11721040046
	backup root 3 to 117210400464
	service mafs_ddf_1

	dd -if /dev/sdF1/fs -count 10 -skip 682 -bs 1
	mafs_ddf_110+0 records in
	10+0 records out

	dd -if <{echo m_ddf_1; cat /dev/zero} -of /dev/sdF1/fs -count 11 -oseek 682 -bs 1
	7+0 records in
	7+0 records out

	disk/block /dev/sdF1/fs 1
	Tdata 2
	size 6001172505088
	nblocks 11721040049
	backup config 1 to 11721040048
	backup super 2 to 11721040046
	backup root 3 to 11721040044
	service m_ddf_1
.fi
\".sp
\"Changing the magic phrase in the magic block. - the offsets and the block output format has changed.
\".sp
\".nf
\"	disk/block /dev/sdF1/fs 0
\"	Tmagic 1
\"	mafs device
\"	512
\"
\"	dd -if /dev/sdF1/fs -count 16 -iseek 256 -bs 1
\"	mafs device
\"	512
\"	20+0 records in
\"	20+0 records out
\"
\"	dd -if <{echo mafs device; echo 512; cat /dev/zero} -of /dev/sdF1/fs -count 18 -oseek 256 -bs 1
\"	18+0 records in
\"	18+0 records out
\"
\"	dd -if /dev/sdF1/fs -count 18 -iseek 256 -bs 1
\"	mafs device
\"	512
\"	18+0 records in
\"	18+0 records out
\"
\"	disk/block /dev/sdF1/fs 0
\"	Tmagic 1
\"	mafs device
\"	512
\".fi
.sp
.sp
.ne 20
.ft B
Tests
.ft R
.sp
.TS
box;
c l
l a .
Program	Description
_
tests/regress.rc	All regression tests
tests/chkextents.rc	Unit tests on extents
tests/chkreli.rc	Unit tests on relative index lookups
_
tests/6.offsets	Write file using different offsets to test mafswrite()
tests/6.sizes	Show the effects of the different parameters
tests/6.testextents	Test extents.[ch] state changes
tests/6.reli	Translate relative index to block number on a disk
.TE
.sp
The below disk state tests:
.in 3n
.br
.ti 0
1. Initialize a disk for mafs.
.br
.ti 0
2. Run mafs on that dsk.
.br
.ti 0
3. Stop mafs.
.br
.ti 0
4. Compare the contents with the expected contents (tests/test.0/blocks/*).
.in 0
.sp
.TS
box;
c s
c l
l a .
Disk State
=
Test	Description
_
tests/test.0	empty disk
tests/test.1	create a file /dir1/file1 and echo test into it
tests/test.2	writes at different offsets to a file and then removes the file
_
tests/test.3	write, read and delete files with sizes upto 16384 blocks
tests/test.4	directory copy
tests/test.5	fcp gzipped files
_
tests/test.6	df
tests/test.7	multiple processes working on the filesystem simultaneously
tests/test.8	check backup blocks locations
_
tests/test.9	examples used by this document
tests/test.a	write, read and delete a 100MB file
tests/test.b	duplicate of test.2 but seeded with random data
_
tests/test.d	seed with random data and do mkdir -p a/b/c/d/e/f/g/h
tests/test.e	seed with random data and test directory and file deletions
.TE
.sp
.TS
box;
c s
c l
l a .
Extents behaviour
=
Test	Description
_
tests/extents/addabove	Figure 1 of the Extents section
tests/extents/addabove1	Figure 2 of the Extents section
tests/extents/addbelow	Figure 3 of the Extents section
_
tests/extents/mergeabove	Figure 4 of the Extents section
tests/extents/mergenext	Figure 5 of the Extents section
tests/extents/mergeprevious	Figure 6 of the Extents section
.TE
.ta 5n 10n 15n 20n 25n 30n 35n 40n 45n 50n 55n 60n 65n 70n 75n 80n
.in 0
.sp
.ne 3
To run all the regression tests:
.br
.nf
	cd tests/; ./regress.rc
.fi
.sp
.ne 3
To loop through all the blocks of a test:
.br
.nf
	for(t in tests/test.2/blocks/^`{seq 0 39}*){ echo $t; echo '---------'; cat $t; echo }
.fi
.sp
.sp
.ft B
Performance metrics
.ft R
.sp
.nf
	ramfs -m /n/ramfs
	touch /n/ramfs/file
	cat /dev/zero | tput -p > /n/ramfs/file
		196.00 MB/s
		198.76 MB/s
		187.58 MB/s
		176.96 MB/s
		175.87 MB/s
		180.42 MB/s
		183.52 MB/s
		185.99 MB/s
		187.96 MB/s
		189.54 MB/s
		190.83 MB/s
		191.89 MB/s
		192.80 MB/s
	dd -if /dev/zero -of /n/ramfs/file -count 700 -bs 1m

	disk/mafs -r mafs_ramfs_file /n/ramfs/file
	mount -c /srv/mafs_ramfs_file /n/mafs_ramfs_file
	cat /dev/zero | tput -p > /n/mafs_ramfs_file/zeros.file # increase memunits for speed
		122.50 MB/s
		122.13 MB/s
		122.27 MB/s
		122.28 MB/s
	echo halt >> /n/mafs_ramfs_file/adm/ctl; lc /srv
	unmount /n/mafs_ramfs_file

	dd -if /dev/zero -of /n/ramfs/file -count 700 -bs 1m
	hjfs -f /n/ramfs/file -r
	echo allow >>/srv/hjfs.cmd
	mount -c /srv/hjfs /n/hjfs/
	cat /dev/zero | tput -p > /n/hjfs/zeros.file
		70.85 MB/s
		71.02 MB/s
		70.88 MB/s
		70.62 MB/s
		70.46 MB/s
		70.54 MB/s
		69.74 MB/s
		68.63 MB/s
		67.74 MB/s
		67.02 MB/s
		63.81 MB/s
	echo halt >>/srv/hjfs.cmd
	unmount /n/ramfs
.fi
.sp
Profiling instructions:
.nf
	Set LDFLAGS=-p in the mkfile and install the executables.
	profilesize=2000000
	ramfs -m /n/ramfs
	touch /n/ramfs/file
	dd -if /dev/zero -of /n/ramfs/file -count 700 -bs 1m
	mount -c <{disk/mafs -s -r mafs_disk.file /n/ramfs/file <[0=1]} /n/mafs_ramfs_file
	cat /dev/zero | tput -p > /n/mafs_ramfs_file/zeros.file
		57.94 MB/s
		55.27 MB/s
		46.67 MB/s
	echo halt >> /n/mafs_ramfs_file/adm/ctl; lc /srv
.fi
.sp
.sp
.ne 3
.ft B
Limitations
.ft R
.sp
As we use packed structs to store data to the disk, a disk with mafs is not portable to a machine using a different endian system.
.sp
.sp
.ft B
Design considerations
.ft R
.sp
For exclusive use (mode has DMEXCL bit set) files, there is no timeout.
.sp
Use an fs(3) device for RAID or other configuration involving multiple disks.
.sp
Why are you not using a checksum to verify the contents?
.br
Checksums are probabilistic and can be implemented as a bespoke application instead of complicating the file system implementation.
.sp
.sp
.ft B
Source
.ft R
.sp
http://git.9front.org/plan9front/mafs/HEAD/info.html
.sp
.sp
.ft B
References
.ft R
.sp
[1] Sean Quinlan, "A Cached WORM File System," Software--Practice and Experience, Vol 21., No 12., December 1991, pp. 1289-1299
.br
[2] Ken Thompson, Geoff Collyer, "The 64-bit Standalone Plan 9 File Server"