readme

电子硬盘驱动

===================================================================

Copyright M-Systems (c) 2000

DiskOnChip (R) Software         December 4, 2000

Installation Guide for DiskOnChip(R) Product Family on VxWorks(R)/x86
Operating System.

VERSION MARK
------------
Version 4.2.1    December 4, 2000
Version 4.2      September 15, 2000
Version 4.1      May 25, 2000
Version 1.21     July 26, 1999

===================================================================



General
--------
The following directory contains VxWorks programming files for
M-Systems' DiskOnChip 2000, DiskOnChip DIMM2000 and DiskOnChip
Millennium products, all capacities.

In the remainder of this Readme, the term "DiskOnChip" is used
to describe the above mentioned DiskOnChip Family Products.

For detailed information on how to use DiskOnChip utilities for DOS,
please refer to the DiskOnChip Utilities User Manual. For the most
updated manuals and documentation, please see M-Systems' web site
(http://www.m-sys.com) or send your requests to e-mail: [e-mail].




NEW FEATURES IN VERSION 4.2.1
-----------------------------
Version 4.2.1 is the latest version of the TrueFFS driver for VxWorks.
It is backward compatible with all DiskOnChip products and supports
M-Systems' latest products and capacities.

Version 4.2.1 contains the following new features:
   - support for dosFs's long filenames
   - Support for dos2Fs when used in dosFs compatibility mode

Version 4.2.1 also provides access to new features of the DiskOnChip,
like software write-protection, background garbage collection and
the ability to access the Binary partition on the DiskOnchip.

These features are available via standard VxWorks IOCTL calls to
the TrueFFS driver.




GANG PROGRAMMER SUPPORT
-----------------------
Customers that use the new DiskOnChip products should upgrade their
GANG Programmer with GANG software version 4.2.




Contents
--------
1. Introduction
2. Installing the TrueFFS driver
3. Booting VxWorks/x86 from the DiskOnChip
4. Driver's run-time configuration options
5. Formatting the DiskOnChip from VxWorks application
6. Considerations related to unexpected power shutdowns
7. Alternative "garbage collection" scenario
8. New DiskOnChip features available via IOCTL calls
9. Known problems
Appendix A. Formatting the bootable DiskOnChip.




1. Introduction
---------------

The DiskOnChip 2000, DiskOnChip Millennium and DiskOnChip DIMM 2000
are members of the new generation of high performance single-chip
flash disks by M-Systems.

When used under VxWorks, the DiskOnChip is managed by a dedicated
device driver attached to the standard VxWorks's 'dosFs' filesystem
and serves as both a data storage and a boot device.
Most of VxWorks disk oriented calls (including all ANSI C file I/O
facilities) work correctly with the DiskOnChip.

The TrueFFS driver is capable of supporting up to 4 DiskOnChip devices
in parallel, possibly of different types and capacities.
The TrueFFS driver is fully re-entrant and takes care of all issues
releated to a multitasking environment, thereby freeing the
application from any concerns of this kind.




2. Installing the TrueFFS driver
--------------------------------

2.1. The distribution of the TrueFFS driver for VxWorks/x86 consists
     of the following files:

	- MSYSVXW.o        x86 binaries of the TrueFFS driver for
                           VxWorks

	- fldrvvxw.h	   TrueFFS driver's "include" file. This file
			   must be #included by the application in
			   order to be able to access the driver's API

	- flioctl.h	   Extended functionality "include" file. This
                           file must be #included by the application in
			   order to be able to access the Extended
                           functionality API

	- Readme           This readme

2.2. Check if the BSP library (Tornado/target/lib<CPU>gnuvx.a) contains
     the following object modules:

          tffsDrv.o
          tffsLib.o
          dosformt.o
          fatlite.o
          fltl.o
          nftllite.o
          flflash.o
          nfdc2148.o
          reedsol.o
          flsocket.o
          flbase.o

     For instance, if you are using 'pc486' BSP, you could list the
     contents of the BSP library (libI80486gnuvx.a in this case)
     as follows:

       ar386 -tv libI80486gnuvx.a

     If the BSP library contains any of these modules, delete them from
     the library. For instance, to delete module fltl.o from the
     libI80486gnuvx.a, you could execute:

       ar386 -dv libI80486gnuvx.a fltl.o

2.3. Delete the following object modules:

          tffsDrv.o
          tffsLib.o
          dosformt.o
          fatlite.o
          fltl.o
          nftllite.o
          flflash.o
          nfdc2148.o
          reedsol.o
          flsocket.o
          flbase.o

     from the BSP object directory (Tornado/target/obj<CPU>gnuvx).

2.4. The object module MSYSVXW.o contains the x86 binaries of the
     TrueFFS driver for VxWorks. This object module should be added
     to the application's linking process either statically or
     dynamically.
     One possible way to accomplish this is to copy MSYSVXW.o to the
     Tornado/target/lib directory and add MSYSVXW.o to the existing
     VxWorks/I80486 object library:

       ar386 -cru libI80486gnuvx.a MSYSVXW.o

2.5. Make sure that the file fldrvvxw.h is on the compiler's INCLUDE
     path and is #included by your application.

2.6. The TrueFFS driver's initialization routine scans the host address
     space for the DiskOnChip(s). By default, the driver will look for
     a single DiskOnChip in the x86-specific address range of
     [0xc8000..0xe0000].
     In most of the cases the DiskOnChip's address is well known,
     and it makes sense to eliminate the memory scan by telling the
     driver explicitly where to look for the DiskOnChip. This can be
     accomplished by calling the tffsSetup() routine from your
     application.

     ===> NOTE.  The tffsSetup() routine must be called exactly once,
                 BEFORE the driver has been initialized by the routine
                 tffsDrv().
                 Normally, it is called from usrRoot.

     Here is a prototype of the tffsSetup() routine taken from
     fldrvvxw.h:

	extern void tffsSetup (int diskonchips, long *addressRange);

     where 'diskonchips' is the number of DiskOnChip devices installed
     in the system; 'addressRange' is an array of address pairs
     bounding the regions to search for DiskOnChips. For instance, if
     your particular board allows an installation of up to three
     DiskOnChips, and the regions to search for the DiskOnChips are
     as follows:

	[0xd0000 ... 0xd1fff]     1st DiskOnChip
	[0xd2000 ... 0xd3fff]     2nd
	[0xd4000 ... 0xd5fff]     3rd

     then you should include the following code fragment into your
     application:

	#include "fldrvvxw.h"

	/* address ranges to search for the DiskOnChip */
        long tffsAddresses[] =
           { 0xd0000, 0xd1fff,   /* 1st DiskOnChip */
	     0xd2000, 0xd3fff,   /* 2nd            */
	     0xd4000, 0xd5fff }; /* 3rd            */
         /* configure the driver to detect up to three DiskOnChips */
         tffsSetup(3, tffsAddresses);

     When there is a single DiskOnChip installed in the system at a
     well known address, it is desirable to prevent the driver from
     scanning the host address space for the DiskOnChip. In such
     cases both upper and lower bounds of the search range could be
     set to the exact DiskOnChip address. For instance, if the
     DiskOnChip is always installed at address 0xd0000, then the
     application can instruct the driver to look for the DiskOnChip
     at this particular address only by executing the following code
     fragment:

	#include "fldrvvxw.h"

	/* single address to look for a DiskOnChip */
        long tffsAddresses[] = { 0xd0000, 0xd0000 };

         /* configure the driver to detect single DiskOnChip */
        tffsSetup(1, tffsAddresses);

2.7. The TrueFFS driver features a number of configuration options,
     described in detail in Chapter 4 below. The default settings of
     these options should be adequate for most of applications.
     If you wish, for some reason, to change some of the driver's
     configuration options, then do it at this stage.
     For instance, if you want to enable the TrueFFS driver built-in
     diagnostics (see Section 4.4 below), you should include the
     following code fragment:

	#include "fldrvvxw.h"

	/* enable built-in diagnostics and allocate 4KB for */
        /* logging diagnostics messages.                    */
        fl_useDebug  = 4;

     ===> NOTE.  All the driver's configuration options must be
                 set to the desired values BEFORE calling the driver's
                 initialization routine tffsDrv(). Once the tffsDrv()
                 routine has been called, the configuration options
                 must NOT be changed.

2.8. The TrueFFS driver must be initialized by calling the tffsDrv()
     routine.

     ===> NOTE.  This routine must be called exactly once, AFTER call
                 to the tffsSetup() routine. Normally, it is called
                 from usrRoot.

2.9. The application must call the routine tffsDevCreate() to create a
     'device' for every physical DiskOnChip installed in the system.
     Here is a prototype of this routine taken from fldrvvxw.h :

        extern BLK_DEV* tffsDevCreate (int tffsDriveNo, int flags);

     where 'tffsDriveNo' is the DiskOnChip sequential number (zero-based).

     The argument 'flags' should be set to be zero, unless long filename
     option is enabled in dosFs (see Sections 2.13 - 2.27).

     The tffsDevCreate() routine returns a pointer of (BLK_DEV *) type
     which must be saved by the application for later use.

     For example, if there is only one DiskOnChip on the system, the 
     application should include the following code fragment :

	#include "fldrvvxw.h"

	BLK_DEV  *tffs_blk_dev = tffsDevCreate (0, 0);

     Here is another example for the system featuring three DiskOnChips:

	#include "fldrvvxw.h"

	BLK_DEV  *tffs_blk_dev[3] = { NULL, NULL, NULL };

        tffs_blk_dev[0] = tffsDevCreate (0, 0); /* 1st DiskOnChip */
	tffs_blk_dev[1] = tffsDevCreate (1, 0); /* 2nd            */
	tffs_blk_dev[2] = tffsDevCreate (2, 0); /* 3rd            */

     ===> NOTE.  The DiskOnChip devices in TSOP package (which measures 
                 approx. 20 x 10 mm) are usually shipped from the factory 
                 unformatted. If you happen to have such TSOP DiskOnChip, 
                 and tffsDevCreate() call has failed (i.e. returned NULL), 
                 the most likely cause of the failure is the fact that this 
                 TSOP DiskOnChip has never been formatted. Please call 
                 tffsDevCreate() to format DiskOnChip as desribed in 
                 Section 5, and then re-attempt tffsDevCreate() call. 

2.10 Once the 'device' has been created for every DiskOnChip, they must
     be given a name and associated with the file system (dosFs).
     This is accomplished by calling the dosFsDevInit() routine (see
     VxWorks Reference manual). This routine accepts as a parameter
     the pointer of type (BLK_DEV *) which has been returned by the
     preceeding call to tffsDevCreate() (see Section 2.9 above). The
     dosfsDevInit() routine returns a pointer of type (DOS_VOL_DESC *)
     which must be saved by the application for later use.

     For example, if there is only one DiskOnChip in the system, the
     following code section will name it '/tffs0/' and associate it with
     dosFs filesystem:

	#include "fldrvvxw.h"

        DOS_VOL_DESC *tffs_dosFs_vol =
	     dosFsDevInit ("/tffs0/", tffs_blk_dev, NULL);

     Here is another example for a system featuring three DiskOnChips:

	#include "fldrvvxw.h"

        DOS_VOL_DESC *tffs_dosFs_vol[3] = { NULL, NULL, NULL };

        tffs_dosFs_vol[0] = dosFsDevInit ("/tffs0/", tffs_blk_dev[0], NULL);
        tffs_dosFs_vol[1] = dosFsDevInit ("/tffs1/", tffs_blk_dev[1], NULL);
        tffs_dosFs_vol[2] = dosFsDevInit ("/tffs2/", tffs_blk_dev[2], NULL);

2.11 M-Systems guarantees that low-level format on the DiskOnChip
     (the one maintained by the TrueFFS driver) won't get corrupted
     by unexpected power shutdowns. Unfortunately, the default
     configuration of VxWorks's dosFs filesystem is aimed at providing
     high I/O performance by caching user data in RAM rather than
     immediately writing it onto the disk.
     If unexpected power shutdowns are likely to happen to your system,
     the data cached by the filesystem in RAM could be lost and the
     media could be left in an inconsistent state. To minimize the
     risk, avoid caching of data in RAM by calling the