![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to fat_cvf.txt-2.3.99 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-2.3.99 CVS log | Up to [GPL Stacker compression] / dmsdos / patches |
1.1 root 1: This is the main documentation for the CVF-FAT filesystem extension. 15Apr2000
2: CVF-FAT-VERSION-ID: 2.0.0
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/MMAP 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: Writable mmap could work through large address_operations hacks, but
40: they have not yet been implemented in CVF-FAT for kernel 2.3.99. So
41: mmap is read-only and you have to live with it for now :)
42:
43: - attention, DOSEmu users
44:
45: You may have to unmount all CVF partitions before running DOSEmu depending
46: on your configuration. If DOSEmu is configured to use wholedisk or
47: partition access (this is often the case to let DOSEmu access
48: compressed partitions) there's a risk of destroying your compressed
49: partitions or crashing your system because of confused drivers.
50:
51: Note that it is always safe to redirect the compressed partitions with
52: lredir or emufs.sys. Refer to the DOSEmu documentation for details.
53:
54:
55: 3. Mount options
56: ------------------------------------------------------------------------------
57:
58: The CVF-FAT extension currently adds the following options to the FAT
59: driver's standard options:
60:
61: cvf_format=xxx
62: Forces the driver to use the CVF module "xxx" instead of auto-detection.
63: Without this option, the CVF-FAT interface asks all currently loaded
64: CVF modules whether they recognize the CVF. Therefore, this option is
65: 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: "xxx" may also be the text "autoload", which has a special meaning for
71: a module loader, but does not skip auto-detection.
72:
73: If the kernel supports kmod, the cvf_format=xxx option also controls
74: on-demand CVF module loading. Without this option, nothing is loaded
75: on demand. With cvf_format=xxx, a module "xxx" is requested automatically
76: before mounting the compressed filesystem (unless "xxx" is "none"). In
77: case there is a difference between the CVF format name and the module
78: name, setup aliases in your modules configuration. If the string "xxx"
79: is "autoload", a non-existent module "cvf_autoload" is requested which
80: can be used together with a special modules configuration (alias and
81: pre-install statements) in order to load more than one CVF module, let
82: them detect automatically which kind of CVF is to be mounted, and only
83: keep the "right" module in memory. For examples please refer to the
84: dmsdos documentation (ftp and http addresses see below).
85:
86: cvf_options=yyy
87: Option string passed to the CVF module. I.e. only the "yyy" is passed
88: (without the quotes). The documentation for each CVF module should
89: explain it since it is interpreted only by the CVF module. Note that
90: the string must not contain a comma (",") - this would lead to
91: misinterpretation by the FAT driver, which would recognize the text
92: after a comma as a FAT driver option and might get confused or print
93: strange error messages. The documentation for the CVF module should
94: offer a different separation symbol, for example the dot "." or the
95: plus sign "+", which is only valid inside the string "yyy".
96:
97:
98: 4. Description of the CVF-FAT interface
99: ------------------------------------------------------------------------------
100:
101: Assuming you want to write your own CVF module, you need to write a lot of
102: interface functions. Most of them are covered in the kernel documentation
103: you can find on the net, and thus won't be described here. They have been
104: marked with "[...]" :-) Take a look at include/linux/fat_cvf.h.
105:
106: struct cvf_format
107: { int cvf_version;
108: char* cvf_version_text;
109: unsigned long int flags;
110: int (*detect_cvf) (struct super_block*sb);
111: int (*mount_cvf) (struct super_block*sb,char*options);
112: int (*unmount_cvf) (struct super_block*sb);
113: [...]
114: void (*cvf_zero_cluster) (struct inode*inode,int clusternr);
115: }
116:
117: This structure defines the capabilities of a CVF module. It must be filled
118: out completely by a CVF module. Consider it as a kind of form that is used
119: to introduce the module to the FAT/CVF-FAT driver.
120:
121: It contains...
122: - cvf_version:
123: A version id which must be unique. Choose one.
124: - cvf_version_text:
125: A human readable version string that should be one short word
126: describing the CVF format the module implements. This text is used
127: for the cvf_format option. This name must also be unique.
128: - flags:
129: Currently without function. Only used for information purpose.
130: CVF_TRANSPARENT: marks a cvf structure for transparent access (i.e.
131: plain FAT filesystem).
132: CVF_BIGBLOCK: indicates that the cvf module is capable of handling
133: block sizes larger than 512 bytes. *As the loop
134: driver can do blocksize conversion, a cvf module
135: usually does not need to handle this.*
136: CVF_USE_READPAGE: indicates that mmap uses the new readpage interface
137: and thus supports writable mmap.
138: - detect_cvf:
139: A function that is called to decide whether the filesystem is a CVF of
140: the type the module supports. The detect_cvf function must return 0
141: for "NO, I DON'T KNOW THIS GARBAGE" or anything >0 for "YES, THIS IS
142: THE KIND OF CVF I SUPPORT". The function must maintain the module
143: usage counters for safety, i.e. do MOD_INC_USE_COUNT at the beginning
144: and MOD_DEC_USE_COUNT at the end. The function *must not* assume that
145: successful recongition would lead to a call of the mount_cvf function
146: later.
147: - mount_cvf:
148: A function that sets up some values or initializes something additional
149: to what has to be done when a CVF is mounted. This is called at the
150: end of fat_read_super and must return 0 on success. Definitely, this
151: function must increment the module usage counter by MOD_INC_USE_COUNT.
152: This mount_cvf function is also responsible for interpreting a CVF
153: module specific option string (the "yyy" from the FAT mount option
154: "cvf_options=yyy") which cannot contain a comma (use for example the
155: dot "." as option separator symbol).
156: - unmount_cvf:
157: A function that is called when the filesystem is unmounted. Most likely
158: it only frees up some memory and calls MOD_DEC_USE_COUNT. The return
159: value might be ignored (it currently is ignored).
160: - [...]:
161: All other interface functions are "caught" FAT driver functions, i.e.
162: are executed by the FAT driver *instead* of the original FAT driver
163: functions. If you want to use the original FAT driver functions,
164: hang then in here (please no longer use NULL for this purpose).
165: If you really want "no action", write a function that does nothing and
166: hang it in instead. Consider the meaning of NULL undefined.
167: - cvf_zero_cluster:
168: The cvf_zero_cluster function is called when the fat driver wants to
169: zero out a (new) cluster. This is important for directories (mkdir).
170: If it is NULL, the FAT driver defaults to overwriting the whole
171: cluster with zeros. Note that clusternr is absolute, not relative
172: to the provided inode. Note that since kernel 2.3.99, this function is
173: only called when a *directory* cluster is handled.
174:
175: Notes:
176: The cvf_bmap function should be ignored. It really should never
177: get called from somewhere. I recommend redirecting it to a panic
178: or fatal error message so bugs show up immediately.
179:
180: int register_cvf_format(struct cvf_format*cvf_format);
181: If you have just set up a variable containing the above structure,
182: call this function to introduce your CVF format to the FAT/CVF-FAT
183: driver. This is usually done in init_module. Be sure to check the
184: return value. Zero means success, everything else causes a kernel
185: message printed in the syslog describing the error that occurred.
186: Typical errors are:
187: - a module with the same version id is already registered or
188: - too many CVF formats. Hack fs/fat/cvf.c if you need more.
189:
190: int unregister_cvf_format(struct cvf_format*cvf_format);
191: This is usually called in cleanup_module. Return value =0 means
192: success. An error only occurs if you try to unregister a CVF format
193: that has not been previously registered. The code uses the version id
194: to distinguish the modules, so be sure to keep it unique.
195:
196: 5. CVF Modules
197: ------------------------------------------------------------------------------
198:
199: Refer to the dmsdos module (the successor of the dmsdos filesystem) for a
200: sample implementation. It can currently be found at
201:
202: ftp://fb9nt.uni-duisburg.de/pub/linux/dmsdos/dmsdos-x.y.z.tgz
203: ftp://sunsite.unc.edu/pub/Linux/system/Filesystems/dosfs/dmsdos-x.y.z.tgz
204: ftp://ftp.uni-stuttgart.de/pub/systems/linux/local/system/dmsdos-x.y.z.tgz
205:
206: (where x.y.z is to be replaced with the actual version number). Full
207: documentation about dmsdos is included in the dmsdos package, but can also
208: be found at
209:
210: http://fb9nt.uni-duisburg.de/mitarbeiter/gockel/software/dmsdos/index.html
211: 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.