README
1$NetBSD: README,v 1.9 2024/02/07 04:00:10 msaitoh Exp $
2
3makefs - build a file system image from a directory tree
4
5NOTES:
6
7 * This tool uses modified local copies of source found in other
8 parts of the tree. This is intentional.
9
10 * makefs is a work in progress, and subject to change.
11
12
13user overview:
14--------------
15
16makefs creates a file system image from a given directory tree.
17the following file system types can be built:
18
19 cd9660 ISO 9660 file system
20 chfs "Chip" file system, for flash devices
21 ffs BSD fast file system
22 msdos MS-DOS `FAT' file system (FAT12, FAT16, FAT32)
23 udf Universal Disk Format file system
24 v7fs 7th edition(V7) file system
25
26Support for the following file systems maybe be added in the future
27
28 ext2fs Linux EXT2 file system
29
30Various file system independent parameters and constraints can be
31specified, such as:
32
33 - minimum file system size (in KB)
34 - maximum file system size (in KB)
35 - free inodes
36 - free blocks (in KB)
37 - mtree(8) specification file containing permissions and ownership
38 to use in image, overriding the settings in the directory tree
39 - file containing list of files to specifically exclude or include
40 - fnmatch(3) pattern of filenames to exclude or include
41 - endianness of target file system
42
43File system specific parameters can be given as well, with a command
44line option such as "-o fsspeccific-options,comma-separated".
45For example, ffs would allow tuning of:
46
47 - block & fragment size
48 - cylinder groups
49 - number of blocks per inode
50 - minimum free space
51
52Other file systems might have controls on how to "munge" file names to
53fit within the constraints of the target file system.
54
55Exit codes:
56 0 all ok
57 1 fatal error
58 2 some files couldn't be added during image creation
59 (bad perms, missing file, etc). image will continue
60 to be made
61
62
63Implementation overview:
64------------------------
65
66The implementation must allow for easy addition of extra file systems
67with minimal changes to the file system independent sections.
68
69The main program will:
70 - parse the options, including calling fs-specific routines to
71 validate fs-specific options
72 - walk the tree, building up a data structure which represents
73 the tree to stuff into the image. The structure will
74 probably be a similar tree to what mtree(8) uses internally;
75 a linked list of entries per directory with a child pointer
76 to children of directories. ".." won't be stored in the list;
77 the fs-specific tree walker should add this if required by the fs.
78 this builder have the smarts to handle hard links correctly.
79 - (optionally) Change the permissions in the tree according to
80 the mtree(8) specfile
81 - Call an fs-specific routine to build the image based on the
82 data structures.
83
84Each fs-specific module should have the following external interfaces:
85
86 prepare_options optional file system specific defaults that need to be
87 setup before parsing fs-specific options.
88
89 parse_options parse the string for fs-specific options, feeding
90 errors back to the user as appropriate
91
92 cleanup_options optional file system specific data that need to be
93 cleaned up when done with this filesystem.
94
95 make_fs take the data structures representing the
96 directory tree and fs parameters,
97 validate that the parameters are valid
98 (e.g, the requested image will be large enough),
99 create the image, and
100 populate the image
101
102prepare_options and cleanup_options are optional and can be NULL.
103
104NOTE: All file system specific options are referenced via the fs_specific
105pointer from the fsinfo_t structure. It is up to the filesystem to allocate
106and free any data needed for this via the prepare and cleanup callbacks.
107
108Each fs-specific module will need to add its routines to the dispatch array
109in makefs.c and add prototypes for these to makefs.h
110
111All other implementation details should not need to change any of the
112generic code.
113
114ffs implementation
115------------------
116
117In the ffs case, we can leverage off sbin/newfs/mkfs.c to actually build
118the image. When building and populating the image, the implementation
119can be greatly simplified if some assumptions are made:
120 - the total required size (in blocks and inodes) is determined
121 as part of the validation phase
122 - a "file" (including a directory) has a known size, so
123 support for growing a file is not necessary
124
125Two underlying primitives are provided:
126 make_inode create an inode, returning the inode number
127
128 write_file write file (from memory if DIR, file descriptor
129 if FILE or SYMLINK), referencing given inode.
130 it is smart enough to know if a short symlink
131 can be stuffed into the inode, etc.
132
133When creating a directory, the directory entries in the previously
134built tree data structure is scanned and built in memory so it can
135be written entirely as a single write_file() operation.
136