![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to fat_cvf.txt CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GPL Stacker compression] / dmsdos / patches|
Return to fat_cvf.txt CVS log | Up to [GPL Stacker compression] / dmsdos / patches |
1.1 root 1: This is the main documentation for the CVF-FAT filesystem extension. 18Nov1998
2:
3:
4: Table of Contents:
5:
6: 1. The idea of CVF-FAT
7: 2. Restrictions
8: 3. Mount options
9: 4. Description of the CVF-FAT interface
10: 5. CVF Modules
11:
12: ------------------------------------------------------------------------------
13:
14:
15: 1. The idea of CVF-FAT
16: ------------------------------------------------------------------------------
17:
18: CVF-FAT is a FAT filesystem extension that provides a generic interface for
19: Compressed Volume Files in FAT partitions. Popular CVF software, for
20: example, are Microsoft's Doublespace/Drivespace and Stac's Stacker.
21: Using the CVF-FAT interface, it is possible to load a module that handles
22: all the low-level disk access that has to do with on-the-fly compression
23: and decompression. Any other part of FAT filesystem access is still handled
24: by the FAT, MSDOS or VFAT or even UMSDOS driver.
25:
26: CVF access works by redirecting certain low-level routines from the FAT
27: driver to a loadable, CVF-format specific module. This module must fake
28: a normal FAT filesystem to the FAT driver while doing all the extra stuff
29: like compression and decompression silently.
30:
31:
32: 2. 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:
56: 3. Mount options
57: ------------------------------------------------------------------------------
58:
59: The CVF-FAT extension currently adds the following options to the FAT
60: driver'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: kerneld, but does not skip auto-detection.
73:
74: If the kernel supports kerneld, 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 kerneld 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 kerneld 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:
99: 4. Description of the CVF-FAT interface
100: ------------------------------------------------------------------------------
101:
102: Assuming you want to write your own CVF module, you need to write a lot of
103: interface functions. Most of them are covered in the kernel documentation
104: you can find on the net, and thus won't be described here. They have been
105: marked with "[...]" :-) Take a look at include/linux/fat_cvf.h.
106:
107: struct 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 (*cvf_zero_cluster) (struct inode*inode,int clusternr);
116: }
117:
118: This structure defines the capabilities of a CVF module. It must be filled
119: out completely by a CVF module. Consider it as a kind of form that is used
120: to introduce the module to the FAT/CVF-FAT driver.
121:
122: It 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 recongition 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: - 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 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:
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 unique.
194:
195: 5. CVF Modules
196: ------------------------------------------------------------------------------
197:
198: Refer to the dmsdos module (the successor of the dmsdos filesystem) for a
199: sample 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
206: documentation about dmsdos is included in the dmsdos package, but can also
207: be 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).
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.