Return to fat_cvf.txt-2.3.99 CVS log

Up to [GPL Stacker compression] / dmsdos / patches

Annotation of dmsdos/patches/fat_cvf.txt-2.3.99, revision 1.1

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.