readme

电子硬盘驱动

        #ifdef	INCLUDE_DISKONCHIP
           /*
            * Call tffsSetup() as appropriate for your application. See
            * Section 2.6 above for details.
            */

           /*
            * If you want to change the settings of the driver's configuration
            * variables flUse8bit, flUseNFTLCache and fl_useDebug, do it here.
            * See Chapter 4 for details.
            */

            tffsDrv ();
        #endif	/* INCLUDE_DISKONCHIP */

        #ifdef  INCLUDE_PCMCIA
        #ifdef  INCLUDE_SHOW_ROUTINES
            pcmciaShowInit ();			/* install PCMCIA show routines */
        #endif  /* INCLUDE_SHOW_ROUTINES */
            pcmciaInit ();			/* init PCMCIA Lib */
        #endif  /* INCLUDE_PCMCIA */

3.18. If you are using boot scenario 'C', change the #define SYS_WARM_TYPE 
      in the BSP configuration .H file (i.e. Traget/target/config/pc486/config.h 
      in case of pc486 BSP) to look like this:

        #define SYS_WARM_TYPE   SYS_WARM_BIOS

3.19. Recompile your bootloader (normally 'bootrom') and copy it to the 
      DiskOnChip using WindRiver's standard VXCOPY utility:

        VXCOPY bootrom c:\BOOTROM.SYS 

3.20. Copy the VxWorks application itself to the DiskOnChip:

        COPY vxWorks c:\
 
3.21. Reboot the target board. You should see BOOTROM.SYS loading and
      executing vxWorks application. Once vxWorks is up and running,
      the DiskOnChip should be installed under the name '/tffs0/'.




4. Driver's run-time configuration options
------------------------------------------

4.1. The TrueFFS driver comes with a number of run-time configuration
     options. The default settings of these options are adequate
     for most applications. However, in some situations there may be
     reason to change these settings. Sections 4.2 - 4.5 below
     describe all the driver's configuration options in detail.


     ******************************************************************
     *                     W A R N I N G.                             *
     *                                                                *
     * All the configuration variables must be set to desired values  *
     * before the driver's initialization routine tffsDrv() is called.*
     * The value of configuration variables must NOT be changed after *
     * the call to tffsDrv().                                         *
     *                                                                *
     ******************************************************************


4.2. By default, the TrueFFS driver accesses the DiskOnChip in
     32-bit mode. Most boards (but not all) are capable of breaking
     down a single 32-bit cycle into correct sequences of 8-bit access
     cycles to the DiskOnChip. To configure the TrueFFS driver to work
     with those boards that are not capable of accessing it in fast
     32-bit mode, set the 'fluse8bit' configuration variable to '1':

	extern unsigned char flUse8bit;

	/* access DiskOnChip strictly in 8-bit mode */
	flUse8bit = (unsigned char) 1;

     ===> NOTE.  The DiskOnChip I/O performance is usually lower by 10%
                 to 20% (depending on the board) when the driver is
                 configured to run strictly in 8-bit mode.

4.3. By default, the TrueFFS driver is configured to maintain the
     internal lookup and translation tables in RAM which allows to
     double the DiskOnChip I/O performance. However, the amount of RAM
     taken by these tables could be significant for the high capacity
     DiskOnChips. To minimize the driver's RAM requirements, set the
     'flUseNFTLCache' configuration variables to zero:

	extern unsigned char flUseNFTLCache;

        /* minimize TrueFFS driver's RAM requirements */
	flUseNFTLCache = (unsigned char) 0;

     ===> NOTE.  The configuration variable 'flUseNFTLCache' does
                 not relate to the issue of unexpected power shutdowns.
                 The settings of these variables are purely a matter
                 of "I/O performance vs RAM requirements".

4.4. The TrueFFS driver features built-in diagnostics that are
     disabled by default. To enable diagnostics, set the TrueFFS
     driver's configuration variable 'fl_useDebug' to any non-zero
     value:

	extern int fl_useDebug;

	/* enable built-in diagnostics */
	fl_useDebug = 4;

     When the built-in diagnostics has been enabled, important
     messages issued at critical points of the DiskOnChip
     operations will be logged into the driver's internal buffer. The
     size of the buffer (in KBytes) will be equal to the numerical
     value of the 'fl_useDebug' variable (for instance, in the
     example above the buffer size will be 4KB). The diagnostics buffer
     will contain number of C-style zero-terminated strings which
     could be either viewed (using the debugger) or printed on the
     console at any time. A pointer to the beginning of the
     diagnostics buffer is returned by the routine tffsViewDebugLog()
     (see fldrvvxw.h).

     ===> NOTE.  It is normally sufficient to set the 'fl_useDebug'
                 to '2'(thus allocate 2KB for the diagnostic buffer).

4.5. At some random point in time during the write operation the
     TrueFFS driver needs to erase a particular region of the
     flash media. A flash erase operation usually takes around 4
     millisec to complete. By default, the driver is busy polling
     the DiskOnChip, waiting for the erase operation to complete. The
     alternative would be to let the driver sleep during the erase
     operation. In this case other application tasks will have a chance
     to use the CPU resources. To instruct the TrueFFS driver to always
     release the CPU right after starting the erase operation, set the
     configuration variable 'flDelay' to non-zero value:

	extern unsigned char flDelay;

	flDelay = (unsigned char) 1;

     Please note that the suspension of the TrueFFS driver can
     negatively affect the 'write' performance. There are two factors
     that are responsible for this. First of all, there is a good chance that
     the TrueFFS driver will not be given a CPU right after the
     specified number of clock ticks, but rather put at the end of the
     queue of tasks waiting for the CPU. Secondly, the default
     duration of a clock tick in VxWorks (usually 10 millisec, or 2.5
     times longer than the duration of the flash erase operation)
     provides poor granularity for suspending the TrueFFS driver.

     The decision whether to use the 'sleep during flash erase'
     option is mostly a matter of meeting the performance requirements
     of the particular application.




5. Formatting the DiskOnChip from VxWorks application.
------------------------------------------------------

   To format the DiskOnChip, the application should call the routine
   tffsDevFormat(). Here is an example of this routine taken from
   fldrvvxw.h:

	extern STATUS  tffsDevFormat (int tffsDriveNo, int arg);

   where 'tffsDriveNo' is the DiskOnChip sequential number (zero-based)
   and 'arg' is a pointer (type casted to 'int') to the struct
   tffsDevFormatParams containing the parameters of the format call.
   A description of the fields in the struct tffsDevFormatParams
   can be found in the file fldrvvxw.h.
   The whole struct tffsDevFormatParams can be initialized using
   the #define TFFS_STD_FORMAT_PARAMS (see fldrvvxw.h) as shown below:

        struct tffsDevFormatParams format_params = TFFS_STD_FORMAT_PARAMS;

   For instance, if the system features three DiskOnChips (possibly of
   different types and capacities), the application can include the
   following code fragment in order to re-format the 2nd and 3rd
   DiskOnChips:

        #include "fldrvvxw.h"

        /* use standard format parameters */
        struct tffsDevFormatParams  format_params = TFFS_STD_FORMAT_PARAMS;

        /* format the 2nd DiskOnChip */
        tffsDevFormat(1, (int) (&format_params));

        /* format the 3rd DiskOnChip */
        tffsDevFormat(2, (int) (&format_params));

   Note that the 1st DiskOnChip (which is the VxWorks boot disk) is
   not included in the example above. This is because the formatting
   wipes out both the VxWorks bootimage and the VxWorks boot sector
   from the device. The Appendix A contains the complete code example
   for formatting the DiskOnChip which is used to boot VxWorks from.

     ===> NOTE.  If the support for dosFs's long names is enabled, the
                 DiskOnChip must be re-partitioned, and partitions must 
                 be initialized as described in Sections 2.14 - 2.27
                 above.  
                 



6. Considerations related to unexpected power shutdowns
-------------------------------------------------------

There are two levels of data format on the DiskOnChip - low-level
and filesystem-level. The low-level format is M-Systems' proprietary
flash-specific data format which is maintained by the TrueFFS driver.
The filesystem-level format is maintained by the VxWorks's dosFs
filesystem and basically consists of well known things like FAT,
root directory etc.

M-Systems guarantees that under no circumstances the low-level format
will be corrupted by an unexpected system shutdown. All the flash
management algorithms, used by the TrueFFS driver, have been carefully
designed and thoroughly tested to make sure that the low-level format
is kept consistent at any given moment of time.

As far as the filesystem-level format is concerned, it is completely up to
the filesystem to keep it consistent. By default, the dosFs filesystem
does not immediately writes data onto the storage device, but instead
caches data in RAM. While the filesystem cache increases the I/O
performance, it also makes filesystem more vulnerable
to the corruption when the system shuts down unexpectedly. It
is possible to prevent dosFs from caching the data in RAM by using the
DOS_OPT_CHANGENOWARN option (see Section 2.9 above). Unfortunately,
the possibility that the filesystem-level format will be corrupted by
an unexpected system shutdown cannot be reduced to a zero. To repair
the possible filesystem-level data structure inconsistencies, such as
broken FAT chains or corrupted directory entries, the user will need a
functionality similar to that of MS-DOS's CHKDSK.
Contact WindRiver Systems regarding the availability of a CHKDSK-like
tool for VxWorks's dosFs filesystem.




7. Alternative "garbage collection" scenario.
---------------------------------------------

It is a well known fact that flash media needs to be erased prior to any
attempt to write data to it. The process of erasing and re-formatting
previously used regions of flash is known as "garbage collection". The
TrueFFS driver is based on flash management algorithms that take automatic
care of this issue whenever there is no sufficient "clean" space on the
flash medium for a particular write operation to complete. In other
words, by default the "garbage collection" takes place during a regular
write operation. However, the process of erasing and re-formatting the
"dirty" flash region takes much longer than a regular write operation.
It appears as if at some random points in time the write operation
takes longer than usual. For most applications the fact that the length
of write operation fluctuates is usually only a minor concern. However,
those application that have special requirements in part of the write
operation's deterministic timing, might opt to create a separate "garbage
collection" task. This task should be created by the application and run
at relatively low priority, when the system is mostly idle. The sole
purpose of this task is to perform a "garbage collection" on the
DiskOnChip and guarantee that there is enough "clean" flash space
available when the write operation will eventually take place. The routine
tffsRecycle() from the TrueFFS driver's API can be used to implement the
"garbage collection" task. Here is an example of this routine taken from
fldrvvxw.h:

	extern STATUS  tffsRecycle (int volNo, int mode);

   where 'volNo' is 0 for the first DiskOnChip in the system, 1 for
   the second DiskOnChip etc.; 'mode' is 0 for single, quick
   "garbage collection" action, or -1 for long, full "recycling" of
   all "dirty" flash memory regions.

    ==> NOTE: The second parameter of the routine tfssRecycle has been
              changed from the "number of flash KBytes to recycle" to
              the "mode of recycling" (0 or 1) in version 4.2.

   For example, if there is only one DiskOnChip in the system, then
   the "garbage collection" task can be implemented as shown below:

	#include "fldrvvxw.h"

        void garbageCollectionTask(void)
        {
          while (1) {

            /* quick "recycle" action on the first DiskOnChip */
            if (tffsRecycle(0, 0) != OK)
		break;

	    /* sleep for a while (5 ticks) */
            taskDelay(5);
          }
        }

The priority of the "garbage collection" task should be slightly lower
than the priorities of all other tasks that write/read data to/from the
DiskOnChip. On the other hand, it should not be very low since in this
case the "garbage collection" task, once given a chance to run and then
being preempted shortly afterward, could effectively block the access to
DiskOnChip for a long time.

The TrueFFS driver performs all the necessary synchronization between
multiple tasks that access the DiskOnChip concurrently. This means that
there is no need in application's part to synchronize the "garbage
collection" task with all the other tasks that access the DiskOnChip.

Note that the "garbage collection" task should be started after
the application has called all the routines mentioned in Chapter 2.

     ===> NOTE. The TrueFFS driver also provides the FL_IOCTL_DEFRAGMENT
                IOCTL call which could be used instead of the routine
                tffsRecycle(). See Section 8.3 for details.




8. New DiskOnChip features available via IOCTL calls
----------------------------------------------------

8.1. Version 4.2.1 of the TrueFFS driver for VxWorks allows developers
     to access and initiate the following DiskOnChip operations:

     a. Obtain information on DiskOnChip
     b. Software write protection
     c. Run "garbage collection" in the background
     d. Access to the Binary partition on the DiskOnChip (the Binary
        partition allows the user to boot VxWorks on BIOS-less systems)
     e. Bypass the filesystem and access the DiskOnChip at virtual sector
        level

     These new features are accessible through standard VxWorks IOCTL
     calls to the TrueFFS driver  (i.e. via standard VxWorks ioctl()
     routine). In addition to this the file flioctl.h must be #included 
     by the application in order to be able to access the Extended 
     functionality API.

     The following IOCTL calls are supported:

        FL_IOCTL_GET_INFO
        FL_IOCTL_DEFRAGMENT
        FL_IOCTL_WRITE_PROTECT
        FL_IOCTL_BDK_OPERATION
        FL_IOCTL_READ_SECTORS
        FL_IOCTL_WRITE_SECTORS

     Note: For further detailed information on IOCTL calls, refer to
           Application Note AP-DOC-046 Extended functionality of TrueFFS
           driver for DiskOnChip.