![[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.