1This is the main documentation for the CVF-FAT filesystem extension. 18Nov1998 2 3 4Table of Contents: 5 61. The idea of CVF-FAT 72. Restrictions 83. Mount options 94. Description of the CVF-FAT interface 105. CVF Modules 11 12------------------------------------------------------------------------------ 13 14 151. The idea of CVF-FAT 16------------------------------------------------------------------------------ 17 18CVF-FAT is a FAT filesystem extension that provides a generic interface for 19Compressed Volume Files in FAT partitions. Popular CVF software, for 20example, are Microsoft's Doublespace/Drivespace and Stac's Stacker. 21Using the CVF-FAT interface, it is possible to load a module that handles 22all the low-level disk access that has to do with on-the-fly compression 23and decompression. Any other part of FAT filesystem access is still handled 24by the FAT, MSDOS or VFAT or even UMSDOS driver. 25 26CVF access works by redirecting certain low-level routines from the FAT 27driver to a loadable, CVF-format specific module. This module must fake 28a normal FAT filesystem to the FAT driver while doing all the extra stuff 29like compression and decompression silently. 30 31 322. Restrictions 33------------------------------------------------------------------------------ 34 35- BMAP problems 36 37 CVF filesystems cannot do bmap. It's impossible in principle. Thus 38 all actions that require bmap do not work (swapping, writable mmapping). 39 Read-only mmapping works because the FAT driver has a hack for this 40 situation :) Well, writable mmapping should now work using the readpage 41 interface function which has been hacked into the FAT driver just for 42 CVF-FAT :) 43 44- attention, DOSEmu users 45 46 You may have to unmount all CVF partitions before running DOSEmu depending 47 on your configuration. If DOSEmu is configured to use wholedisk or 48 partition access (this is often the case to let DOSEmu access 49 compressed partitions) there's a risk of destroying your compressed 50 partitions or crashing your system because of confused drivers. 51 52 Note that it is always safe to redirect the compressed partitions with 53 lredir or emufs.sys. Refer to the DOSEmu documentation for details. 54 55 563. Mount options 57------------------------------------------------------------------------------ 58 59The CVF-FAT extension currently adds the following options to the FAT 60driver's standard options: 61 62 cvf_format=xxx 63 Forces the driver to use the CVF module "xxx" instead of auto-detection. 64 Without this option, the CVF-FAT interface asks all currently loaded 65 CVF modules whether they recognize the CVF. Therefore, this option is 66 only necessary if the CVF format is not recognized correctly 67 because of bugs or incompatibilities in the CVF modules. (It skips 68 the detect_cvf call.) "xxx" may be the text "none" (without the quotes) 69 to inhibit using any of the loaded CVF modules, just in case a CVF 70 module insists on mounting plain FAT filesystems by misunderstanding. 71 "xxx" may also be the text "autoload", which has a special meaning for 72 a module loader, but does not skip auto-detection. 73 74 If the kernel supports kmod, the cvf_format=xxx option also controls 75 on-demand CVF module loading. Without this option, nothing is loaded 76 on demand. With cvf_format=xxx, a module "xxx" is requested automatically 77 before mounting the compressed filesystem (unless "xxx" is "none"). In 78 case there is a difference between the CVF format name and the module 79 name, setup aliases in your modules configuration. If the string "xxx" 80 is "autoload", a non-existent module "cvf_autoload" is requested which 81 can be used together with a special modules configuration (alias and 82 pre-install statements) in order to load more than one CVF module, let 83 them detect automatically which kind of CVF is to be mounted, and only 84 keep the "right" module in memory. For examples please refer to the 85 dmsdos documentation (ftp and http addresses see below). 86 87 cvf_options=yyy 88 Option string passed to the CVF module. I.e. only the "yyy" is passed 89 (without the quotes). The documentation for each CVF module should 90 explain it since it is interpreted only by the CVF module. Note that 91 the string must not contain a comma (",") - this would lead to 92 misinterpretation by the FAT driver, which would recognize the text 93 after a comma as a FAT driver option and might get confused or print 94 strange error messages. The documentation for the CVF module should 95 offer a different separation symbol, for example the dot "." or the 96 plus sign "+", which is only valid inside the string "yyy". 97 98 994. Description of the CVF-FAT interface 100------------------------------------------------------------------------------ 101 102Assuming you want to write your own CVF module, you need to write a lot of 103interface functions. Most of them are covered in the kernel documentation 104you can find on the net, and thus won't be described here. They have been 105marked with "[...]" :-) Take a look at include/linux/fat_cvf.h. 106 107struct cvf_format 108{ int cvf_version; 109 char* cvf_version_text; 110 unsigned long int flags; 111 int (*detect_cvf) (struct super_block*sb); 112 int (*mount_cvf) (struct super_block*sb,char*options); 113 int (*unmount_cvf) (struct super_block*sb); 114 [...] 115 void (*zero_out_cluster) (struct inode*, int clusternr); 116} 117 118This structure defines the capabilities of a CVF module. It must be filled 119out completely by a CVF module. Consider it as a kind of form that is used 120to introduce the module to the FAT/CVF-FAT driver. 121 122It contains... 123 - cvf_version: 124 A version id which must be unique. Choose one. 125 - cvf_version_text: 126 A human readable version string that should be one short word 127 describing the CVF format the module implements. This text is used 128 for the cvf_format option. This name must also be unique. 129 - flags: 130 Bit coded flags, currently only used for a readpage/mmap hack that 131 provides both mmap and readpage functionality. If CVF_USE_READPAGE 132 is set, mmap is set to generic_file_mmap and readpage is caught 133 and redirected to the cvf_readpage function. If it is not set, 134 readpage is set to generic_readpage and mmap is caught and redirected 135 to cvf_mmap. (If you want writable mmap use the readpage interface.) 136 - detect_cvf: 137 A function that is called to decide whether the filesystem is a CVF of 138 the type the module supports. The detect_cvf function must return 0 139 for "NO, I DON'T KNOW THIS GARBAGE" or anything >0 for "YES, THIS IS 140 THE KIND OF CVF I SUPPORT". The function must maintain the module 141 usage counters for safety, i.e. do MOD_INC_USE_COUNT at the beginning 142 and MOD_DEC_USE_COUNT at the end. The function *must not* assume that 143 successful recognition would lead to a call of the mount_cvf function 144 later. 145 - mount_cvf: 146 A function that sets up some values or initializes something additional 147 to what has to be done when a CVF is mounted. This is called at the 148 end of fat_read_super and must return 0 on success. Definitely, this 149 function must increment the module usage counter by MOD_INC_USE_COUNT. 150 This mount_cvf function is also responsible for interpreting a CVF 151 module specific option string (the "yyy" from the FAT mount option 152 "cvf_options=yyy") which cannot contain a comma (use for example the 153 dot "." as option separator symbol). 154 - unmount_cvf: 155 A function that is called when the filesystem is unmounted. Most likely 156 it only frees up some memory and calls MOD_DEC_USE_COUNT. The return 157 value might be ignored (it currently is ignored). 158 - [...]: 159 All other interface functions are "caught" FAT driver functions, i.e. 160 are executed by the FAT driver *instead* of the original FAT driver 161 functions. NULL means use the original FAT driver functions instead. 162 If you really want "no action", write a function that does nothing and 163 hang it in instead. 164 - zero_out_cluster: 165 The zero_out_cluster function is called when the fat driver wants to 166 zero out a (new) cluster. This is important for directories (mkdir). 167 If it is NULL, the FAT driver defaults to overwriting the whole 168 cluster with zeros. Note that clusternr is absolute, not relative 169 to the provided inode. 170 171Notes: 172 1. The cvf_bmap function should be ignored. It really should never 173 get called from somewhere. I recommend redirecting it to a panic 174 or fatal error message so bugs show up immediately. 175 2. The cvf_writepage function is ignored. This is because the fat 176 driver doesn't support it. This might change in future. I recommend 177 setting it to NULL (i.e use default). 178 179int register_cvf_format(struct cvf_format*cvf_format); 180 If you have just set up a variable containing the above structure, 181 call this function to introduce your CVF format to the FAT/CVF-FAT 182 driver. This is usually done in init_module. Be sure to check the 183 return value. Zero means success, everything else causes a kernel 184 message printed in the syslog describing the error that occurred. 185 Typical errors are: 186 - a module with the same version id is already registered or 187 - too many CVF formats. Hack fs/fat/cvf.c if you need more. 188 189int unregister_cvf_format(struct cvf_format*cvf_format); 190 This is usually called in cleanup_module. Return value =0 means 191 success. An error only occurs if you try to unregister a CVF format 192 that has not been previously registered. The code uses the version id 193 to distinguish the modules, so be sure to keep it unique. 194 1955. CVF Modules 196------------------------------------------------------------------------------ 197 198Refer to the dmsdos module (the successor of the dmsdos filesystem) for a 199sample implementation. It can currently be found at 200 201 ftp://fb9nt.uni-duisburg.de/pub/linux/dmsdos/dmsdos-x.y.z.tgz 202 ftp://sunsite.unc.edu/pub/Linux/system/Filesystems/dosfs/dmsdos-x.y.z.tgz 203 ftp://ftp.uni-stuttgart.de/pub/systems/linux/local/system/dmsdos-x.y.z.tgz 204 205(where x.y.z is to be replaced with the actual version number). Full 206documentation about dmsdos is included in the dmsdos package, but can also 207be found at 208 209 http://fb9nt.uni-duisburg.de/mitarbeiter/gockel/software/dmsdos/index.html 210 http://www.yk.rim.or.jp/~takafumi/dmsdos/index.html (in Japanese). 211