1 |
1275 |
phoenix |
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 |
|
|
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 |
|
|
|
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 (*zero_out_cluster) (struct 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 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 |
|
|
|
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).
|