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