********************************************************************************
 *                                                                              *
 *  mDOC driver for VxWorks(R).                                                 *
 *                                                                              *
 *  Installation Guide.                                                         *
 *                                                                              *
 *  Version 1.0.0.0 Alpha released on Aug 24 2006                               *
 *  Based on DOC driver version 1.0.0 Alpha                                     *
 *                                                                              *
 *  Copyright msystems (c) 2006                                                 *
 *                                                                              *
 ********************************************************************************
 *                                                                              *
 *  Tornado, VxWorks, VxSim, Wind River Systems, are registered trademarks or   *
 *  service marks of Wind River Systems, Inc. This is the partial list. For a   *
 *  complete list of Wind River trademarks and service marks, see the following *
 *  URL:                                                                        *
 *                                                                              *
 *      http://www.windriver.com/company/terms/trademark.html                   *
 *                                                                              *
 *  All the other trademarks mentioned herein are the property of their         *
 *  respective owners.                                                          *
 *                                                                              *
 ********************************************************************************
 *                                                                              *
 *                            I M P O R T A N T                                 *
 *                                                                              *
 *  This version works ONLY with mDOC H3 product family                         *
 *                                                                              *
 ********************************************************************************


VERSION MARK
------------

  Version 1.0.0.0 Alpha  Aug 24, 2006


GENERAL
--------

  Updated manuals and documentation, can be found on msystems web site
  (http://www.m-systems.com). For more information, contact msystems
  via e-mail to info@m-systems.com, or by calling your local msystems
  office (see Chapter 12 below).


CONTENTS
--------

  1. Introduction
  2. Installing mDOC driver
  3. Booting VxWorks from mDOC
  4. Formatting mDOC from VxWorks application
  5. Excluded.
  6. Considerations related to unexpected power shutdowns
  7. Excluded.
  8. Driver's runtime configuration options
  9. Access to advanced features of mDOC
 10. Built-in diagnostics
 11. Known limitations
 12. Contact information


1. INTRODUCTION
---------------

1.1. When used under VxWorks, mDOC is managed by a dedicated device driver.
     mDOC driver is normally attached to the standard VxWorks's file
     system (dosFs-2). VxWorks disk oriented calls (including all
     ANSI C file I/O facilities) work correctly with mDOC.

1.2. mDOC driver uses term "socket" to refer to either of the following:
         - single mDOC MD25xx part, or up to 2 such cascaded parts

     The term 'cascaded' refers to the parts which all share the same address
     in the host's address space, and form a single continuous flash media of
     capacity equal to the sum of capacities of individual cascaded parts.

     mDOC driver supports up to 4 "sockets".

1.3. The flash media that constitutes mDOC "socket", can be optionally
     divided into up to six independent regions (refered to as "disks"). All
     such regions ("disks") can be read/write accessed independently from the 
     other "disks" of that "socket", and can have it's own hardware-level 
     read/write access permissions.

1.4. Each "disk" could be partitioned (by using dosFs-2's 'dpartLib' library
     under VxWorks) into up to 11 file system partitions (primary and extended).
     Each such file system partition could be individually formatted with any
     type of FAT that dosFs-2 file system supports.

1.5. The mDOC driver is fully re-entrant, and takes care of all issues
     related to the multitasking VxWorks environment, thereby freeing application
     from any concerns of this kind.


2. INSTALLING mDOC DRIVER
-------------------------------

2.1. This version works ONLY with mDOC H3 product family.

2.2. Remove all object modules and libraries associated with the previous 
     versions of mDOC driver,as well as with WindRiver's TFFS, from your
     Tornado installation. Here is the list of object modules that you will
     need to remove:

         MSYSVXW-<cpu>.o
         abs_lyr.o
         bch_hm.o
         bdstub.o
         blockdev.o
         defs.o
         diskonc.o
         doc2exb.o
         docbdk.o
         docdrv.o
         dochstub.o
         dochtl.o
         doch_api.o
         doch_ata.o
         docsoc.o
         docsys.o
         docsysp.o
         dosformt.o
         fatfilt.o
         fatlite.o
         flbase.o
         flcustom.o
         fldrvvxw.o
         flflash.o
         flioctl.o
         flmalloc.o
         flmtl.o
         flsim.o
         flsocket.o
         flsysvxw.o
         fltl.o
         g4_lgc.o
         g4_mtd.o
         geometry.o
         hal_nor.o
         h1h1glgc.o
         h1h1gmtd.o
         h1h_lgc.o
         h1h_mtd.o
         h1_lgc.o
         h1_mtd.o
         inftl.o
         m512_lgc.o
         m512_mtd.o
         matchalg.o
         mdocplus.o
         nfdc2148.o
         nftllite.o
         oren_lgc.o
         oren_mtd.o
         protectp.o
         reedsol.o
         saftl.o
         tffsDrv.o
         tffsLib.o
         tffs_api.o

     ===> NOTE.  Please be advised that object module names are case sensitive, 
                 i.e. "MSYSVXW-PPC860.o" and "MSYSVXW-ppc860.o" refer to two 
                 different object modules that can be both present in the same 
                 library. You will need to remove all such object modules from 
                 this library.
 
     If you are using Tornado versions 2.0x and 2.1, skip to Section 2.2.1.
     If you are using Tornado version 2.2 or higher or Workbench version 2.x ,
     skip to Section 2.2.2.

     ===> NOTE. You can find out which Tornado version is it by look at
                file SETUP.LOG in Tornado installation directory. 

2.2.1. If you are using Tornado version 2.2 or higher or Workbench 2.x,
       skip this Section, and follow instructions in Section 2.2.2 instead.

2.2.1.1. List the contents of Tornado' object library that you are linking your
         application with (<tornado>/target/lib<cpu>gnuvx.a) to check if it 
         contains any of the object modules listed in Section 2.2.

         To find out which Tornado's object library your application is linked
         with, and which archiver tool to use with this library, locate your 
         applications' BSP directory, and check how macro 'CPU' is defined in 
         Makefile there. The object library that your application is linked with,
         will be <tornado>/target/lib<cpu>gnuvx.a. For example, in case of 
         WindRiver' mcp750 PowerPC BSP, 'CPU' is defined as "PPC604" in
         <tornado>/target/config/mcp750/Makefile. Respectively all applications
         that are based on this BSP, are linked with 
         <tornado>/target/libPPC604gnuvx.a library, and the name of the archiver
         tool to use with this library is "arppc".  

         ===> NOTE.  On Windows hosts, Tornado tools can be added to system's PATH 
                     by executing <tornado>/host/x86-win32/bin/torVars.bat.

         To list contents of <tornado>/target/lib/lib<cpu>gnuvx.a object library,
         use appropriate archiver tool with '-tv' command line option. For example,
         to list contents of <tornado>/target/lib/libPPC860gnuvx.a library:

             arppc -tv  <tornado>/target/lib/libPPC860gnuvx.a

         If any of the above listed object modules will be present in your
         <tornado>/target/lib<cpu>gnuvx.a library, use appropriate archiver with
         '-dv' command line option to remove this object module from the library.
         For example, to remove object module fltl.o from 
         <tornado>/target/lib/libPPC860gnuvx.a library: 

             arppc -dv <tornado>/target/lib/libPPC860gnuvx.a fltl.o

2.2.1.2. Delete all object modules listed in Section 2.2, from object directory
         <tornado>/target/lib/obj<cpu>gnuvx.

         Skip to Section 2.3.

2.2.2. If you are using Tornado versions 2.0x or 2.1, skip this Section, and
       follow instructions in Section 2.2.1 instead.

2.2.2.1. Check if directory <tornado>/target/lib/<arch>/<cpu>/common
         contains WindRiver's TFFS library libtffs.a. For example, if you link
         your application with PowerPC 440 libraries, you should check if 
         library <tornado>/target/lib/ppc/PPC440/common/libtffs.a exists.
         If it does, rename this library as libtffs.a.windriver.

2.2.2.2. Check if directory <tornado>/target/lib/<arch>/<cpu>/common
         contains directory 'objtffs'. For example, if you link
         your application with PowerPC 440 libraries, you should check if 
         directory <tornado>/target/lib/ppc/PPC440/common/objtffs exists.
         If it does, rename this directory as "objtffs.windriver".

2.2.2.3. Check if directory <tornado>/target/lib/<arch>/<cpu>/common
         contains existing mDOC driver library libmsystems.a. For example,
         if you link your application with PowerPC 440 libraries, you should check
         if library <tornado>/target/lib/ppc/PPC440/common/libmsystems.a exists.
         If it does, delete this library.

2.2.2.4. Check if directory <tornado>/target/lib/obj<cpu><tool>test contains any
         of the object modules listed in Section 2.2, and if it does, remove
         them. For example, if you link you application with PowerPC 440 
         libraries, and use DIAB compiler, you should check directory
         <tornado>/target/lib/objPPC440diabtest.

2.3. mDOC driver for VxWorks is distributed in source code form, and must
     be compiled at the customer site. In order to do this, create directory in
     your application's source code tree where you want to place mDOC
     driver's source code to, and copy all the files listed below, from their 
     indicated locations to that directory:

     ===> NOTE.  If any of file names listed below, appear on your UNIX host in
                 upper case ("FLSYSTEM.H", "FLCUSTOM.H" etc.) or mixed case
                 ("Flsystem.h", "iNFTL.C" etc.), change all these file names
                 to lowercase ("flsystem.h", "flcustom.h" etc.).

	<m-systems>/src/defs.c
	<m-systems>/src/docdrv.c
	<m-systems>/src/doch_api.c
	<m-systems>/src/doch_ata.c
	<m-systems>/src/dochstub.c
	<m-systems>/src/dochtl.c
	<m-systems>/src/docsoc.c
	<m-systems>/src/docsys.c
	<m-systems>/src/dosformt.c
	<m-systems>/src/fatfilt.c
	<m-systems>/src/flbase.c
	<m-systems>/src/flioctl.c
	<m-systems>/src/flmalloc.c
	<m-systems>/src/geometry.c
	<m-systems>/src/hal_nor.c
	<m-systems>/src/tffs_api.c
	<m-systems>/examples/drivers/vxworks/fldrvvxw.c
	<m-systems>/examples/drivers/vxworks/system/flsysvxw.c
	<m-systems>/examples/drivers/vxworks/custom/flcustom.c

     Copy all the headers listed below, from their indicated locations to 
     <tornado>/target/h directory:

	<m-systems>/src/_common.h
	<m-systems>/src/_dochapi.h
	<m-systems>/src/_docsys.h
	<m-systems>/src/_fltl.h
	<m-systems>/src/bddefs.h
	<m-systems>/src/bdkemul.h
	<m-systems>/src/blockdev.h
	<m-systems>/src/defs.h
	<m-systems>/src/docbdk.h
	<m-systems>/src/doch_api.h
	<m-systems>/src/doch_ata.h
	<m-systems>/src/doch_func.h
	<m-systems>/src/doch_sys.h
	<m-systems>/src/dochstub.h
	<m-systems>/src/dochtl.h
	<m-systems>/src/docsys.h
	<m-systems>/src/dosformt.h
	<m-systems>/src/fatfilt.h
	<m-systems>/src/flbase.h
	<m-systems>/src/flbuffer.h
	<m-systems>/src/flchkdef.h
	<m-systems>/src/flcommon.h
	<m-systems>/src/flioctl.h
	<m-systems>/src/flmalloc.h
	<m-systems>/src/flstdcmp.h
	<m-systems>/src/flstruct.h
	<m-systems>/src/flsysfun.h
	<m-systems>/src/flsystyp.h
	<m-systems>/src/fltl.h
	<m-systems>/src/hal_nor.h
	<m-systems>/src/hib.h
	<m-systems>/src/part_inf.h
	<m-systems>/src/tffs_api.h
	<m-systems>/examples/drivers/vxworks/fldrvvxw.h
	<m-systems>/examples/drivers/vxworks/custom/flcustom.h
	<m-systems>/examples/drivers/vxworks/system/flsystem.h

2.4. Make sure your BSP configuration header file 
     (<tornado>/target/config/<bsp>/config.h) excludes the following VxWorks 
     components:

         #undef INCLUDE_TFFS
         #undef INCLUDE_PCMCIA      /* include PCMCIA driver */

2.6. To tell mDOC driver where to look for mDOC(s), application
     must call routine tffsSetup(). 

     ===> NOTE.  The tffsSetup() routine must be called exactly once, BEFORE 
                 driver has been initialized by routine tffsDrv(). 

     Here is declaration of routine tffsSetup() taken from fldrvvxw.h:

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

     where 'mDOCs' is the number of mDOC "sockets" installed in the
     system; 'addressRange' is an array of address pairs bounding regions to
     search for mDOCs. For instance, if your particular board allows
     installation of up to three mDOCs, and regions to search for
     mDOCs are as follows:
  
         [0xc00d0000 ... 0xc00d1fff]     1st mDOC
         [0xc00d2000 ... 0xc00d3fff]     2nd
         [0xc00d4000 ... 0xc00d5fff]     3rd

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