![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to cvf-fat.doc CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GPL Stacker compression] / dmsdos / doc|
Return to cvf-fat.doc CVS log | Up to [GPL Stacker compression] / dmsdos / doc |
1.1 ! root 1: cvf-fat.doc ! 2: ! 3: This is the main documentation for the CVF-FAT filesystem extension. 31DEC1997 ! 4: ! 5: ! 6: Table of Contents: ! 7: ! 8: 1. The idea of CVF-FAT ! 9: 2. Restrictions ! 10: 3. Mount options ! 11: 4. Installation ! 12: 5. Description of the CVF-FAT interface ! 13: 6. Authors and email addresses ! 14: ! 15: ------------------------------------------------------------------------------ ! 16: ! 17: ! 18: 1. The idea of CVF-FAT ! 19: ------------------------------------------------------------------------------ ! 20: ! 21: CVF-FAT is a FAT filesystem extension that provides a generic interface for ! 22: Compressed Volume Files in FAT partitions. Popular CVF software, for ! 23: example, are Microsoft's Doublespace/Drivespace and Stac's Stacker. ! 24: Using the CVF-FAT interface, it is possible to load a module that handles ! 25: all the low-level disk access that has to do with on-the-fly compression ! 26: and decompression. All other part of FAT filesystem access is still handled ! 27: by the FAT, MSDOS or VFAT or even UMSDOS driver. ! 28: ! 29: CVF access works by redirecting certain low-level routines from the FAT ! 30: driver to a loadable, CVF-format specific module. This module must fake ! 31: a normal FAT filesystem to the FAT driver while doing all the extra stuff ! 32: like compression and decompression silently. ! 33: ! 34: ! 35: 2. Restrictions ! 36: ------------------------------------------------------------------------------ ! 37: ! 38: - BMAP problems ! 39: ! 40: CVF filesystems cannot do bmap. It's impossible by principle. Thus ! 41: all actions that require bmap do not work (swapping). Writable mmapping ! 42: should work via readpage, but is untested. Does anyone know an application ! 43: that is doing writable mmaps? This would be needed for tests :) ! 44: ! 45: - DOSEMU users attention ! 46: ! 47: You may have to unmount all CVF partitions before running DOSEMU depending ! 48: on your configuration. If DOSEMU is configured to use wholedisk or ! 49: partition access (this is often the case to let DOSEMU access ! 50: compressed partitions) there's a risk of destroying your compressed ! 51: partitions or crashing your system because of confused drivers. ! 52: ! 53: Note that it is always safe to redirect the compressed partitions with ! 54: lredir or emufs.sys. Refer to the DOSEMU documentation for details. ! 55: ! 56: ! 57: 3. Mount options ! 58: ------------------------------------------------------------------------------ ! 59: ! 60: The CVF-FAT extension currently adds the following options to the FAT ! 61: driver's standard options: ! 62: ! 63: cvf_format=xxx ! 64: Forces the driver to use the CVF module "xxx" instead of auto-detection. ! 65: This is only necessary if the CVF format is not recognized correctly ! 66: because of bugs or incompatibilities in the CVF modules. (It skips ! 67: the detect_cvf call.) "xxx" may be the text "none" (without the quotes) ! 68: to inhibit using any of the loaded CVF modules, just in case a CVF ! 69: module insists on mounting plain FAT filesystems by misunderstanding :) ! 70: ! 71: cvf_options=yyy ! 72: Option string passed to the CVF module. I.e. only the "yyy" is passed ! 73: (without the quotes). The documentation for each CVF module should ! 74: explain it since it is interpreted only by the CVF module. Note that ! 75: the string must not contain a comma (",") - this would lead to ! 76: misinterpretation by the FAT driver, which would recognize the text ! 77: after a comma as a FAT driver option and might get confused or print ! 78: strange error messages. The documentation for the CVF module should ! 79: offer a different seperation symbol, for example the dot ".", which ! 80: is only valid inside the string "yyy". ! 81: ! 82: ! 83: 4. Installation ! 84: ------------------------------------------------------------------------------ ! 85: ! 86: Just apply the diff cvf.diff-x.y.z to your kernel. I hope the diff will ! 87: make it into the standard kernel some day, but it's not up to me to decide ! 88: this :) Note that the diff has been created using kernel x.y.z so it might ! 89: fail or need manual interaction for other kernels. Modified diffs for ! 90: other kernels welcome :) ! 91: ! 92: Well, you also need a CVF module to load. Otherwise CVF-FAT is quite useless ! 93: to you :) dmsdos is such a module. ! 94: ! 95: ! 96: 5. Description of the CVF-FAT interface ! 97: ------------------------------------------------------------------------------ ! 98: ! 99: Assuming you want to write your own CVF module, you need to write a lot of ! 100: interface funtions. Most of them are covered in the kernel documentation ! 101: you can find on the net, and thus won't be described here. They have been ! 102: marked with "[...]" :-) Take a look at include/linux/fat_cvf.h. ! 103: ! 104: struct cvf_format ! 105: { int cvf_version; ! 106: char* cvf_version_text; ! 107: unsigned long int flags; ! 108: int (*detect_cvf) (struct super_block*sb); ! 109: int (*mount_cvf) (struct super_block*sb,char*options); ! 110: int (*unmount_cvf) (struct super_block*sb); ! 111: [...] ! 112: void (*cvf_zero_cluster) (struct inode*inode,int clusternr); ! 113: } ! 114: ! 115: This structure defines the capabilities of a CVF module. It must be filled ! 116: out completely by a CVF module. Consider it as a kind of form that is used ! 117: to introduce the module to the FAT/CVF-FAT driver. ! 118: ! 119: It contains... ! 120: - cvf_version: ! 121: A version id which must be uniqe. Choose one. ! 122: - cvf_version_text: ! 123: A human readable version string that should be one short word ! 124: describing the CVF format the module implements. This text is used ! 125: for the cvf_format option. This name must also be uniqe. ! 126: - flags: ! 127: Bit coded flags, currently only used for a readpage/mmap hack that ! 128: provides both mmap and readpage functionality. If CVF_USE_READPAGE ! 129: is set, mmap is set to generic_file_mmap and readpage is caught ! 130: and redirected to the cvf_readpage function. If it is not set, ! 131: readpage is set to generic_readpage and mmap is caught and redirected ! 132: to cvf_mmap. ! 133: - detect_cvf: ! 134: A function that is called to decide whether the filesystem is a CVF of ! 135: the type the module supports. The detect_cvf function must return 0 ! 136: for "NO, I DON'T KNOW THIS GARBAGE" or anything !=0 for "YES, THIS IS ! 137: THE KIND OF CVF I SUPPORT". The function must maintain the module ! 138: usage counters for safety, i.e. do MOD_INC_USE_COUNT at the beginning ! 139: and MOD_DEC_USE_COUNT at the end. The function *must not* assume that ! 140: successful recognition would lead to a call of the mount_cvf function ! 141: later. ! 142: - mount_cvf: ! 143: A function that sets up some values or initializes something additional ! 144: to what has to be done when a CVF is mounted. This is called at the ! 145: end of fat_read_super and must return 0 on success. Definitely, this ! 146: function must increment the module usage counter by MOD_INC_USE_COUNT. ! 147: This mount_cvf function is also responsible for interpreting a CVF ! 148: module specific option string (the "yyy" from the FAT mount option ! 149: "cvf_options=yyy") which cannot contain a comma (use for example the ! 150: dot "." as option separator symbol). ! 151: - unmount_cvf: ! 152: A function that is called when the filesystem is unmounted. Most likely ! 153: it only frees up some memory and calls MOD_DEC_USE_COUNT. The return ! 154: value might be ignored (it currently is ignored). ! 155: - [...]: ! 156: All other interface functions are "caught" FAT driver functions, i.e. ! 157: are executed by the FAT driver *instead* of the original FAT driver ! 158: functions. NULL means use the original FAT driver functions. ! 159: If you really want "no action", write a function that does nothing and ! 160: hang it in instead. ! 161: WARNING: Do not call a fat driver function from these routines without ! 162: looking at the fat driver source code first. You might end up in an ! 163: endless recursion. :( ! 164: - cvf_zero_cluster: ! 165: The cvf_zero_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: ! 171: Notes: ! 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: ! 179: int 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 occured. ! 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: ! 189: int 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 uniqe. ! 194: ! 195: Refer to the dmsdos module (the successor of the dmsdos filesystem) for a ! 196: sample implementation. ! 197: ! 198: ! 199: 6. Authors and email addresses: ! 200: ------------------------------------------------------------------------------ ! 201: ! 202: The CVF-FAT extensions are the official successor of the dmsdos filesystem. ! 203: The dmsdos filesystem was initially written by Frank Gockel. Stacker support ! 204: was added by Pavel Pisa. Meanwhile, it contains several parts of code that ! 205: was directly provided or code that is based on the ideas from a lot of people ! 206: over the net in order to fix bugs, to improve performance, and to add features. ! 207: ! 208: The code is distributed under the GNU General Public Licence (see file ! 209: COPYING). ! 210: ! 211: The code is currently maintained by Pavel Pisa and me, Frank Gockel. ! 212: ! 213: Pavel's email address is [email protected], ! 214: my email address is [email protected]. ! 215: ! 216: If you want to contact me via email, please write in English or take a close ! 217: look at the country code in the email address :-)
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.