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

Copyright M-Systems (c) 1999

DiskOnChip (R) Software 	April-15, 1999

Installation Guide for DiskOnChip(R) Product Family on QNX Operating 
System (Version 4.23 or higher).

VERSION MARK
------------
Version 1.21 April-15, 1999

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


General
--------
The following directory contains M-Systems' TrueFFS programming 
files for QNX (version 4.23 or higher) for DiskOnChip 2000, 
DiskOnChip DIMM and DiskOnChip Millennium products.

For detailed information on how to use TrueFFS utilities, 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: 
info@m-sys.com.


New Features
------------

Version 1.21 is M-Systems' most updated TrueFFS version (as of 
15-April, 1999) for DiskOnChip products. It is backward compatible 
with all DiskOnChip products and supports M-Systems' latest 
products.
Customers that use previous TrueFFS version DO NOT necessarily 
have to upgrade their software drivers (unless M-systems' new 
products are used), although it is recommended.

The new DiskOnChip products supported in this release are:

DiskOnChip 2000 Series (5V and 3.3V)
  MD2200-D32	
  MD2200-D48	
  MD2201-D80
  MD2201-D112
  D2201-D144

DiskOnChip 2000 DIMM Series (5V and 3.3V)
  MD2220-D02 up to MD2220-D160 

DiskOnChip Millennium Series
  MD2800-D08 	
  MD2800-D08-V3	
  MD2810-D08	


Note: Customers that are using BDK version 1.21 or higher 
should use the DFORMAT utility of version 1.21 (or higher).
Please refer to Application Note APP-DOC-20 "DiskOnChip 
Boot Developer Kit" for further information.

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



SOFTWARE LICENSE AGREEMENT

IMPORTANT! READ CAREFULLY: 
THIS SOFTWARE LICENSE AGREEMENT (the Agreement) is a legal 
agreement between you (either an individual or a single entity) and 
M-Systems Flash Disk Pioneers Ltd. ("M-Systems").  
This Agreement relates to the M-Systems software accompanying this 
Agreement, which includes computer software and may include associated
media, printed materials, and online or electronic documentation 
(the Licensed Software).  
By downloading, installing, copying, or otherwise using the Licensed
Software, you agree to be bound by the terms of this Agreement.
If you do not agree to the terms of this Agreement, do not install, 
copy or use the Licensed Software.

The Licensed Software is protected by copyright laws and international
copyright treaties, as well as other intellectual property laws and 
treaties.  The Licensed Software is licensed, not sold.  
The Licensed Software is being provided solely for use with M-Systems
DiskOnChip product lines.
1.	License Grant. 
(a)	Grant of License. Subject to the terms and conditions of this 
        Agreement, M-Systems hereby grants you a nonexclusive, 
        royalty-free, worldwide license (including the right to 
        sublicense) to use, copy and distribute the Licensed Software 
        with M-Systems DiskOnChip products.
(b)	Restrictions on Use.  The Licensed Software is licensed solely
        for use with and to support M-Systems DiskOnChip products. 
        Use of this Licensed Software with, or to support, any other 
        flash disk, flash card, resident flash array or solid state 
        disk of any kind is expressly prohibited, and constitutes an 
        illegal infringement of M-Systems patent, copyright and other 
        rights in and to the Licensed Software. 
2.	Limitations on Reverse Engineering, Decompilation, and 
        Disassembly.  You may not reverse engineer, decompile, or 
        disassemble the Licensed Software, except and only to the 
        extent that such activity is expressly permitted by applicable 
        law notwithstanding this limitation.
3.	Termination. Without prejudice to any other rights, M-Systems 
        may terminate this Agreement if you fail to comply with the 
        terms and conditions of this Agreement. In such event, you must
        destroy all copies of the Licensed Software and all of its 
        component parts.
4.	Intellectual Property Rights.  Title to the Licensed Software, 
        and all rights with respect to the Software not specifically 
        granted under this Agreement, including without limitation 
        all rights of modification, disassembly and decompilation and 
        all copyright, patent, trademark, trade secret and other 
        proprietary rights and interests are reserved to M-Systems. 
        You may not remove or alter the "read-me" file or copyright 
        notices in the Licensed Software.
5.	DISCLAIMER OF WARRANTIES. To the maximum extent permitted by 
        applicable law, M-Systems and its suppliers provide the Product
        and any (if any) support services related to the Product 
        ("Support Services") AS IS AND WITH ALL FAULTS, and hereby 
        disclaim all warranties and conditions, either express, 
        implied or statutory, including, but not limited to, any 
        (if any) implied warranties or conditions of merchantability, 
        of fitness for a particular purpose, of lack of viruses, of 
        accuracy or completeness of responses, of results, and of lack
        of negligence or lack of workmanlike effort, all with regard 
        to the Product, and the provision of or failure to provide 
        Support Services. ALSO, THERE IS NO WARRANTY OR CONDITION OF
        TITLE, QUIET ENJOYMENT, QUIET POSSESSION, CORRESPONDENCE TO 
        DESCRIPTION OR NON-INFRINGEMENT, WITH REGARD TO THE PRODUCT. 
        THE ENTIRE RISK AS TO THE QUALITY OF OR ARISING OUT OF USE OR 
        PERFORMANCE OF THE PRODUCT AND SUPPORT SERVICES, IF ANY, 
        REMAINS WITH YOU.
6.	EXCLUSION OF INCIDENTAL, CONSEQUENTIAL AND CERTAIN OTHER 
        DAMAGES. To the maximum extent permitted by applicable law, 
        in no event shall M-Systems or its suppliers be liable for 
        any special, incidental, indirect, or consequential damages 
        whatsoever (including, but not limited to, damages for loss 
        of profits or confidential or other information, for business 
        interruption, for personal injury, for loss of privacy, for 
        failure to meet any duty including of good faith or of 
        reasonable care, for negligence, and for any other pecuniary 
        or other loss whatsoever) arising out of or in any way related
        to the use of or inability to use the Product, the provision 
        of or failure to provide Support Services, or otherwise under 
        or in connection with any provision of Agreement, even in the 
        event of the fault, tort (including negligence), strict 
        liability, breach of contract or breach of warranty of 
        M-Systems or any supplier, and even if M-Systems or any 
        supplier has been advised of the possibility of such damages. 
7.	LIMITATION OF LIABILITY AND REMEDIES. Notwithstanding any 
        damages that you might incur for any reason whatsoever 
        (including, without limitation, all damages referenced above 
        and all direct or general damages), the entire liability of 
        M-Systems and any of its suppliers under any provision of this
        Agreement and your exclusive remedy for all of the foregoing 
        shall be limited to the greater of the amount actually paid by
        you for the Product or U.S.$5.00. The foregoing limitations, 
        exclusions and disclaimers shall apply to the maximum extent 
        permitted by applicable law, even if any remedy fails its 
        essential purpose.
8.	Miscellaneous
        The laws of the State of California, United States of America, 
        exclusive of conflict-of-laws provisions, shall govern this 
        Agreement in all respects. 



Contents
--------
1. Introduction
2. Installing the DiskOnChip software
3. Installing the DiskOnChip 
4. DiskOnChip driver parameters
5. DiskOnChip utilities
6. Troubleshooting



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

The DiskOnChip 2000, DiskOnChip Millennium and DiskOnChip DIMM are
the members of the new generation of the high performance 
single-chip flash disks by M-Systems. They feature built-in firmware
containing TrueFFS (True Flash File System) technology, which provides 
full read/write hard disk emulation and allows the DiskOnChip to 
serve as a boot device for the various operating systems, including
QNX. When used under QNX, the DiskOnChip is managed by the 
TrueFFS-based device driver attached to the standard QNX filesystem 
('Fsys'). The DiskOnChip can be installed in the QNX system as an
 additional disk or as a boot device.



2. Installing the DiskOnChip software
-------------------------------------

The compressed file doc2_tar.F on the M-Systems distribution 
diskette contains the following files:

Fsys.diskonchip    DiskOnChip device driver (version 1.21) for QNX

dformat		   DiskOnChip formatting utility

copy2doc           Shell script containing list of files essential
                   for booting QNX from the hard disk (see Section
		   3.12 below).

doc2000            Sample build file for a building custom QNX
                   bootimage including the DiskOnChip driver.



2.1. Before you begin, you must be logged in as the superuser 
     (root) and the floppy driver must be running. To check, type:
         # sin ver

     If "Floppy" doesn't appear in the NAME column, type:
         # Fsys.floppy

     Run 'Dosfsys' program to access the DOS floppy drives:
         #  Dosfsys &

     It is assumed below that M-Systems' distribution floppy is 
     mounted at /dos/a.

2.2.  Create a 'tffs' sub-directory under the directory /usr/local 
      and change to this directory:
          # mkdir /usr/local/tffs
          # cd /usr/local/tffs

2.3.  Copy the file doc2_tar.F as doc2_tar.tar.F to the directory
      /usr/local/tffs :
          # cp /dos/a/doc2_tar.F doc2_tar.tar.F

2.4.  Melt and un-tar file doc2_tar.F :
          # freeze -d doc2_tar.tar.F
          # tar -xf doc2_tar.tar

2.5.  Make a link to the DiskOnChip driver:
          # ln -f ./Fsys.diskonchip /bin/Fsys.diskonchip

2.6.  Copy the file doc2000 to /boot/build :
          # cp doc2000 /boot/build



3.   Installing the DiskOnChip 
------------------------------

3.1.  Shutdown your computer and plug in the DiskOnChip.

3.2.  Log in to QNX as superuser (root).

3.3.  Change to /usr/local/tffs :
          # cd /usr/local/tffs

3.4.  Run the 'dformat' utility to format the DiskOnChip:
          # ./dformat

3.5.  Run the DiskOnChip driver to create a 'raw' device 
      '/dev/tffs0' :
          # Fsys.diskonchip

      Use the 'ls' utility to make sure the 'tffs0' device has been
      successfully created:
          # ls /dev/tffs0
 
3.6.  Run the 'fdisk' utility to create a QNX partition spanning 
      the entire DiskOnChip. Mark this partition as bootable and 
      write the QNX partition loader to it :
 	  # fdisk /dev/tffs0 add -f 1 QNX ALL
	  # fdisk /dev/tffs0 boot QNX
	  # fdisk /dev/tffs0 loader

      Use the following command to display the contents of the
      DiskOnChip partition table :
	  # fdisk /dev/tffs0 show

      Check the description of 'fdisk' utility in the QNX Utilities 
      Reference for details.

3.7.  Mount the partitions of the 'raw' DiskOnChip device :
	  # mount -p /dev/tffs0

      Use 'ls' to make sure that QNX partition has been successfully
      mounted as '/dev/tffs0t77' :
	  # ls /dev/tffs0t77

3.8.  Initialize the filesystem on the QNX partition :
          # dinit -h /dev/tffs0t77
          # dinit -hb /dev/tffs0t77


Note: The 'dinit' might issue a warning that initialization
      has being attempted on a hard disk; you should simply
      ignore it.


3.9.  Mount the file system on QNX partition as '/mnt/diskonchip':
	  # mkdir /mnt/diskonchip
	  # mount /dev/tffs0t77 /mnt/diskonchip

      Use 'chkfsys' and 'ls' utilities to make sure that the mount
      succeeded :
	  # chkfsys -u /mnt/diskonchip
	  # ls /mnt/diskonchip

3.10. If you wish to boot QNX from the DiskOnChip, then skip to 
      step 3.11. Otherwise proceed.

      To automatically mount the DiskOnChip during boot, add these 
      two lines to your system initialization file
      /etc/config/sysinit.NNN (NNN is your local node number; if you
      don't have any network connection NNN should be equal to 1):

          Fsys.diskonchip
	  mount -p /dev/tffs0 /dev/tffs0t77 /mnt/diskonchip

      The DiskOnChip will be mounted at /mnt/diskonchip and ready 
      for use upon boot.

      If you are NOT planning to boot QNX from the DiskOnChip and 
      intent to use it as an additional disk in the system, then you
      are done and you can skip the rest of section 3.

3.11. If you are planning to boot QNX from the DiskOnChip, please 
      find out the capacity of the DiskOnChip.

      Note: The capacity of the DiskOnChip 2000 is usually included 
	    in the parts # (for instance MD2200-D08 is an 8MB part, 
	    MD2200-D16 is a 16 MB part etc.). 

      If you have a DiskOnChip with 16 MB or higher capacity, then
      skip to section 3.13.

      If you have a DiskOnChip with capacity below 16 MB, then 
      proceed with section 3.12.

      Note: The procedures described below in paragraphs 3.12 - 3.13
            are typically performed only once, for the very first 
            DiskOnChip you use. Once you have successfully gone 
            through these procedures, it is possible to copy the 
            binary image of the DiskOnChip to other DiskOnChips 
            (i.e. cloning the first DiskOnChip). The easiest way 
            to clone a DiskOnChip is to use M-System's DiskOnChip 
            Gang Programmer. This special tool makes the cloning 
            operation very fast and fully automatic. Please contact 
            M-Systems for availability of this product. 

3.12. If you have a DiskOnChip with capacity below 16 MB, then you
      need to build the custom QNX image including the DiskOnChip
      driver. To do this, change to the /boot directory:
	 # cd /boot

      Run the 'make' utility to create a custom QNX bootimage 
      /boot/images/doc2000 :
	 # make b=doc2000

      Copy the new custom QNX bootimage /boot/images/doc2000 to
      /mnt/diskonchip/.boot (assuming the DiskOnChip has been 
      mounted at /mnt/diskonchip) :
         # cp /boot/images/doc2000 /mnt/diskonchip/.boot

      Copy all the required system and shell files to the
      appropriate directories under /mnt/diskonchip. If you are
      unclear about which files are needed at boot time you can try
      out the shell script file /usr/local/tffs/copy2doc we have
      provided for you:
	 # cd /usr/local/tffs
	 # chmod a+x copy2doc
	 # ./copy2doc

      Note: The shell script file 'copy2doc' is essentially the 
            edited output of the command 
            'ls -lR / >/usr/local/tffs/copy2doc'.
            It references configuration files, license files etc. 
            which could have different names on your machine. We 
            strongly encourage you to look closely at the contents 
            of the 'copy2doc' to see what needs to be changed there.

      If you are planning to use 32-bit device drivers (which is 
      the QNX 4.23 default) copy the following files from /bin to 
      /mnt/diskonchip/bin :
	 # cp /bin/Dev32       /mnt/diskonchip/bin/Dev32
	 # cp /bin/Dev32.ansi  /mnt/diskonchip/bin/Dev32.ansi
	 # cp /bin/Dev32.par   /mnt/diskonchip/bin/Dev32.par
	 # cp /bin/Dev32.pty   /mnt/diskonchip/bin/Dev32.pty
	 # cp /bin/Dev32.ser   /mnt/diskonchip/bin/Dev32.ser

      If you are planning to use 16-bit device drivers, copy the 
      following files from /bin to /mnt/diskonchip/bin :
	 # cp /bin/Dev16       /mnt/diskonchip/bin/Dev16
	 # cp /bin/Dev16.ansi  /mnt/diskonchip/bin/Dev16.ansi
	 # cp /bin/Dev16.par   /mnt/diskonchip/bin/Dev16.par
	 # cp /bin/Dev16.pty   /mnt/diskonchip/bin/Dev16.pty
	 # cp /bin/Dev16.ser   /mnt/diskonchip/bin/Dev16.ser

      In case of doubt which drivers will actually be used, simply 
      copy both 32-bit and 16-bit versions as shown above.

      Establish all the necessary symbolic links (assuming you are 
      using 32-bit device drivers, which is QNX 4.23 default):
	 # cd /mnt/diskonchip/bin
	 # ln -s Dev32      Dev
	 # ln -s Dev32.ansi Dev.ansi
	 # ln -s Dev.ansi   Dev.con
	 # ln -s Dev.ansi   Dev.ditto
	 # ln -s Dev32.par  Dev.par
	 # ln -s Dev32.pty  Dev.pty
	 # ln -s Dev32.ser  Dev.ser

      Enter the following command to reboot your computer:
         # shutdown
 
      Please proceed with paragraph 3.14.

3.13. If you have a DiskOnChip with 16 MB capacity or higher, then
      you can use the standard QNX installation procedure to install
      QNX directly onto the DiskOnChip. To do this, you first need 
      to go through a simple procedure of making the custom QNX 
      boot diskette including the DiskOnChip software. Please make 
      an exact copy of the standard QNX boot diskette using the 
      standard DOS DISKCOPY utility:
	 DISKCOPY A: B:

      Then move this diskette to a QNX machine and mount it 
      (assuming Fsys.floppy driver has already been started) at 
      /mnt/floppy :
	 # mount /dev/fd0 /mnt/floppy

      Finally copy the DiskOnChip software to /mnt/floppy/bin :
	 # cp /usr/local/tffs/Fsys.diskonchip /mnt/floppy
	 # cp /usr/local/tffs/dformat         /mnt/floppy
	 # cp /usr/local/tffs/doc107.exb      /mnt/floppy


      Note: To create space for the DiskOnChip software, you might
	    need to delete some unnecessary device drivers (e.g. all
	    files named Fsys.* in the directory /mnt/floppy/bin)
     
      From now on you could use this diskette instead of the 
      standard QNX boot diskette when installing QNX directly 
      onto the DiskOnChip.

      Start the standard QNX installation procedure by booting QNX 
      from the newly created QNX boot diskette. When presented an 
      operating system prompt, format the DiskOnChip by running:
	 # dformat

      Finally start the installation by typing :
	 # install -d -p "-n:hd0"

      When prompted for "third party disk" just press RETURN. When
      presented the list of device drivers to select from, simply 
      pick up Fsys.diskonchip and continue the normal installation.


      Note: Upon the boot the DiskOnChip appears as /dev/hd0 (and 
            it's QNX partition as /dev/hd0t77 respectively). 
            Any hard disk installed in your system might not be 
            immediately accessible. 
            If this is the case, simply add the following two lines
            to your /etc/config/sysinit.NNN file (assuming you have 
            an IDE hard disk):

		 Fsys.ide &
		 mount -p /dev/hd1 /dev/hd1t77 /mnt/hard_disk

      The first line starts the IDE hard disk device driver
      (in case if you have hard disk of some other type start
      the appropriate driver, for instance Fsys.eide,
      Fsys.ata etc.). The second line causes the QNX partition
      on the hard disk to be mounted at /mnt/hard_disk.

3.14  By default the DiskOnChip allows you to boot QNX on a diskless
      machine. In case your machine is equipped with the hard disk(s)
      and you still want to boot from the DiskOnChip, you will need 
      to install the DiskOnChip as the first (i.e. boot) drive. In 
      order to do this, please boot DOS from the floppy and run the
      M-Systems DUPDATE.EXE utility as shown below:
         
         DUPDATE /WIN:{address} /S:DOC110.EXB /FIRST 

      Note: The {address} above is the base address of the DiskOnChip, 
            (i.e. D000, D400, etc.). 
            The "110" in the filename DOC110.EXB represents the 
            firmware version. The actual firmware version used might 
            be a higher version, i.e. DOC121.EXB, DOC122.EXB, etc.

      Alternatively you could disable hard disk(s) in the CMOS setup.
      In this case the above DOS command is not necessary.

      After booting from the DiskOnChip, any hard disks installed 
      in your system might not be immediately accessible. If this 
      is the case, simply add the following lines to your 
      /etc/config/sysinit.NNN file (assuming you have an IDE 
      hard disk):

          Fsys.ide &
          mount -p /dev/hd1 /dev/hd1t77 /mnt/hard_disk

      The first line starts the IDE hard disk device driver (in
      case if you have hard disk of some other type start
      the appropriate driver, for instance Fsys.eide, Fsys.ata,
      etc.).
      The second line causes QNX partition on the hard disk to
      be mounted at /mnt/hard_disk.

      In some cases it is useful to prevent the DiskOnChip firmware 
      from installing at boot time. You can achieve this by performing 
      the following DOS command:

          DUPDATE /WIN:{address} /S:DOC2.FFF 

      Note: The file DOC2.FFF may be found on the DiskOnChip utilities
            diskette supplied with the DiskOnChip.




4. DiskOnChip driver parameters
-------------------------------

The DiskOnChip has built-in firmware that is visible in the CPU 
address range, reserved for BIOS expansions. Being executed by the 
BIOS, the DiskOnChip firmware installs itself at INT 13h (BIOS disk 
services), thus providing full read/write emulation of a hard disk. 
Since QNX runs entirely in 32-bit protected mode and does not rely on
BIOS services, the Fsys.diskonchip device driver must be active at 
boot time to allow access to the DiskOnChip. The installation 
procedure described in the last paragraphs guarantees this.
Normally, the driver is started without any parameters. Since the 
DiskOnChip is a memory-mapped device, the driver should locate it 
in memory. By default, the driver looks in the memory range 0C8000h 
to 0E0000h. If the memory window address is known, it is possible to 
pass it to the driver from the command line, thus eliminating the 
search. For example, if the DiskOnChip address is D4000h, the driver 
can be started as follows:

	# Fsys.diskonchip -w:D4000 &

The DiskOnChip driver creates a raw DiskOnChip device, named tffs0 
by default. This default name can be overridden by specifying a 
different one at the command line:

	# Fsys.diskonchip -n:MyName &

In this case the device will be named MyName.


5. DiskOnChip utilities
-----------------------

5.1. dformat : DiskOnChip format utility

     The DiskOnChip must be unmounted before re-formatting (assuming
     it has been mounted at /mnt/diskonchip) :
    	# umount /mnt/diskonchip
    	# rm /dev/tffs0

     The DiskOnChip can be formatted as follows:
	# cd /usr/tffs/local
    	# ./dformat

     The media may be re-formatted many times. However,
     ALL THE DATA ON THE DiskOnChip IS DESTROYED EACH TIME
     IT IS FORMATTED !

     It is strongly suggested to re-boot the machine after you have
     formatted the DiskOnChip and before you run the Fsys.diskonchip
     driver.

     When formatting, the DiskOnChip firmware is retained by 
     default. If you wish to upgrade the DiskOnChip firmware, you 
     will need to boot DOS and use the standard M-Systems 
     DUPDATE.EXE utility for DOS for that purpose.



6. Troubleshooting
------------------

6.1. Fsys.diskonchip driver cannot detect the DiskOnChip 

     Possible solutions:

     a. There is a memory conflict due to other hardware or software
        using the same memory space. Try to install the DiskOnChip 
        at a different memory address.

     b. Check if the DiskOnChip is properly connected.

     c. Check the BIOS setup, and verify that there is no memory
        shadowing that coincides with the DiskOnChip memory region.

6.2. System files residing on the DiskOnChip were accidentally 
     erased, and system hangs while trying to boot.

     Possible solution:
     Boot using QNX boot floppy.
     Run the DiskOnChip device driver:
         # Fsys.diskonchip
     Mount the DiskOnChip at /mnt/diskonchip:
         # mount -p /dev/tffs0
         # mount /dev/tffs0t77 /mnt/diskonchip
     Now you can access the DiskOnChip:
         # chkfsys -u /mnt/diskonchip
         # ls /mnt/diskonchip

6.3. Data errors and inconsistency problems.
     
     Possible solution:
     Run the chkfsys QNX utility (assuming system was booted from
     a DiskOnChip, so it is mounted at '/') :
         # chkfsys -u /



