README.TXT                                         (C) Copyright 2006
DOSFS Level 1 Version 1.02      Lewin A.R.W. Edwards (sysadm@zws.com)
=====================================================================

Abstract
========
DOSFS is a FAT-compatible filesystem intended for fairly low-end
embedded applications. It is not the leanest possible implementation
(the leanest FAT implementations operate in << 512 bytes of RAM, with
heavy restrictions). This code strikes a good balance between size
and functionality, with an emphasis on RAM footprint.

Intended target systems would be in the ballpark of 1K RAM, 4K ROM
or more.

Features:
* Supports FAT12, FAT16 and FAT32 volumes
* Supports storage devices up to 2048Gbytes in size (LBA32)
* Supports devices with or without MBRs (hard disks vs. floppy disks
  or ZIP drives formatted as "big floppies")
* Supports multiple partitions on disks with MBRs
* Supports subdirectories
* Can be operated with a single global 512-byte sector buffer
* Fully reentrant code (assuming the underlying physical device driver
  is reentrant and global sector buffers are not used). There are no
  global variables in the filesystem
* Does not perform any memory allocation
* Partial support for random-access files

Applications:
* Firmware upgrades
* Failsafe IPL
* Media playback
* Data logging
* Configuration storage

There is no technical support for this free product; however, if you
have questions or suggestions, you are encouraged to email Lewin
Edwards at sysadm@zws.com. If you need custom additions to the code,
or if you have other projects for which you need engineering
assistance, please feel free to email or call (646) 549-3715.

License
=======
The license for DOSFS is very simple but verbose to state.

1. DOSFS is (C) Copyright 2006 by Lewin A.R.W. Edwards ("Author").
   All rights not explicitly granted herein are reserved. The DOSFS
   code is the permanent property of the Author and no transfer of
   ownership is implied by this license.

2. DOSFS is an educational project, provided as-is. No guarantee of
   performance or suitability for any application is stated or
   implied. You use this product entirely at your own risk. Use of
   this product in any manner automatically waives any right to seek
   compensation or damages of any sort from the Author.	Since the
   products you might make are entirely out of the Author's control,
   use of this product also constitutes an agreement by you to take
   full responsibility for and indemnify the Author against any
   action for any loss or damage (including economic loss of any
   type, and specifically including patent litigation) that arises
   from a product made by you that incorporates any portion of
   the DOSFS code.

3. If you live under the jurisdiction of any legislation that would
   prohibit or limit any condition in this license, you cannot be
   licensed to use this product.

4. If you do not fall into the excluded category in point 3, you are
   hereby licensed to use the DOSFS code in any application that you
   see fit. You are not required to pay any fee or notify the Author
   that you are using DOSFS. Any modifications made by you to the
   DOSFS code are your property and you may distribute the modified
   version in any manner that you wish. You are not required to
   disclose sourcecode to such modifications, either to the Author or
   to any third party. Any such disclosure made to the Author will
   irrevocably become the property of the Author in the absence of a
   formal agreement to the contrary, established prior to such
   disclosure being made.

To summarize the intent of the above: DOSFS is free. You can do what
you want with it. Anything that happens as a result is entirely your
responsibility. You can't take ownership of my code and stop me from
doing whatever I want with it. If you do something nifty with DOSFS
and send me the sourcecode, I may include your changes in the next
distribution and it will be released to the world as free software.
If someone sues you because your DOSFS-containing product causes
any sort of legal, financial or other problem, it's your lawsuit,
not mine, and you'll exclude me from the proceedings.

User-Supplied Functions
=======================
You must provide functions to read sectors into memory and write
them back to the target media. The demo suite includes an emulation
module that reads/writes a disk image file (#define HOSTVER pulls
in hostemu.h which wraps the prototypes for these functions).
There are various tools for UNIX, DOS, Windows et al, to create
images from storage media; my preferred utility is dd.

The functions you must supply in your embedded app are:

DFS_ReadSector(unit,buffer,sector,count)
DFS_WriteSector(unit,buffer,sector,count)

These two functions read and write, respectively, "count" sectors of
size SECTOR_SIZE (512 bytes; see below) from/to physical sector
#"sector" of device "unit", to/from the scratch buffer "buffer". They
should return 0 for success or nonzero for failure. In the current
implementation of DOSFS, count will always be 1.

The "unit" argument is designed to permit implementation of multiple
storage devices, for example multiple media slots on a single device,
or to differentiate between master and slave devices on an ATAPI bus.
		 
This code is designed for 512-byte sectors. Although the sector size
is a #define, you should not tinker with it because the vast majority
of FAT filesystems use 512-byte sectors, and the DOSFS code doesn't
support runtime determination of sector size. This will not affect the
vast majority of users.

Example Code
============
Refer to the tests in main.c to see how to call DOSFS functions.
(These tests are all commented out). Note that the only two files
you need to add to your project are dosfs.c and dosfs.h.


Mounting Volumes
================
--If the device has a partition table (practically all removable flash
  media are formatted this way), call DFS_GetPtnStart to get the
  starting sector# of the desired partition. You can optionally also
  retrieve the active state, partition type byte and partition size
  in this step. The reason this step is broken out separately is so
  you can support devices that are formatted like a floppy disk, i.e.
  the volume starts directly at physical sector 0 of the media.

--Call DFS_GetVolInfo to read filesystem info into a VOLINFO structure.
  DFS_GetVolInfo needs to know the unit number and partition starting
  sector (as returned by DFS_GetPtnStart, or 0 if this is a "floppy-
  format" volume without an MBR).

From this point on, the VOLINFO structure is all you'll need - you can
forget the unit and partition start sector numbers.

Enumerating Directory Contents
==============================
--Call DFS_Opendir and supply a path, populated VOLINFO and a
  DIRINFO structure to receive the results. Note - you must PREPOPULATE
  the DIRINFO.scratch field with a pointer to a sector scratch buffer.
  This buffer must remain unmolested while you have the directory open
  for searching.
--Call DFS_GetNext to receive the DIRENT contents for the next directory
  item. This function returns DFS_OK for no error, and DFS_EOF if there
  are no more entries in the directory being searched.
  Before using the DIRENT, check the first character of the name. If it
  is NULL, then this is an unusable entry - call DFS_GetNext again to
  keep searching. LFN directory entries are automatically tagged this way
  so your application will not be pestered by them.

  Note: A designed side-effect of this code is that when you locate the
  file of interest, the DIRINFO.currentcluster, DIRINFO.currentsector
  and DIRINFO.currententry-1 fields will identify the directory entry of
  interest.

Reading a File
==============
--Call DFS_OpenFile with mode = DFS_READ and supply a path and the relevant
  VOLINFO structure. DFS_OpenFile will populate a FILEINFO that can be used
  to refer to the file.
--Optionally call DFS_Seek to set the file pointer. If you attempt to set
  the file pointer past the end of file, the file will NOT be extended. Check
  the FILEINFO.pointer value after DFS_Seek to verify that the pointer is
  where you expect it to be.
--Observe that functionality similar to the "whence" parameter of fseek() can
  be obtained by using simple arithmetic on the FILEINFO.pointer and
  FILEINFO.filelen members.
--Call DFS_ReadFile with the FILEINFO you obtained from OpenFile, and a
  pointer to a buffer plus the desired number of bytes to read, and a
  pointer to a sector-sized scratch buffer. The reason a scratch sector is
  required is because the underlying sector read function doesn't know
  about partial reads.
--Note that a file opened for reading cannot be written. If you need r/w
  access, open with mode = DFS_WRITE (see below).