*************************************************************************
*									*
*  Copyright M-Systems (c) 2001						*
*									*
*  DiskOnChip (R) TrueFFS version 5.0.0 August 1st, 2001		*
*									*
*  TrueFFS Installation Guide for DiskOnChip(R) on Windows NT4		*
*									*
*************************************************************************

Contents
--------

1. Introduction
2. New Features in version 5.0
3. Installing the DiskOnChip(R) Product Family on Windows NT4
4. Extended functionality of DiskOnChip TrueFFS driver version 5.0
5. Example of using extended functionality.
6. Known limitations
7. Contact information


1. Introduction.
----------------
Version 5.0 of the the DiskOnChip TrueFFS driver for Windows NT4 includes 
support for the latest products in the DiskOnChip line. This driver provides 
block device functionality to the NT file system, thus emulating a hard drive. 
TrueFFS also includes advanced algorithms for flash management including wear 
leveling and bad block handling. The Windows NT version of the driver is 
provided as a SYS file and includes a header file that provides access to 
DiskOnChip extended functionality, such as data protection (where applicable), 
defragmentation, deep power down mode and many others.


2. New Features in version 5.0						
------------------------------
Version 5.0 is the latest version of the TrueFFS driver for Windows NT. 
It supports all DiskOnChip products and is backwards API compatible with 
TrueFFS 4.x. TrueFFS 5.0 supports M-Systems' latest products (DiskOnChip 
Millennium Plus 32MB and DiskOnChip 2000 TSOP 16MB) including support to 
all their extended hardware functionality such as data read/write protection, 
6KB ROM-like area (one time programming area or OTP), True 16-bit interface 
and multiple partition capabilities.

Version 5.0 contains the following new features:                    

2.1. This release supports the following DiskOnChip Products:
     - DiskOnChip 2000 TSOP (16MB)
     - DiskOnChip Millennium Plus (32MB)

2.2. Additional BDK functionalities  
     All of TrueFFS 4.x binary partition routines are available plus protection 
     and get info routines. TrueFFS 5.0 allows defining up to 3 binary partitions.

2.3. Hardware protection
     DiskOnChip Millennium Plus devices support read and write protection at 
     the Hardware level. Up to 2 of the volumes exported by the device can be 
     protected by a unique 8 byte (64-bit) key. On power up the device is 
     protected until the correct key is inserted. Once the key is in, the device
     can be freely accessed until one of the following occurs:
       (a) Power down.
       (b) Key removed.
       (c) Protection mechanism reinitialized.
     In addition to the key a HW LOCK signal can be asserted to prevent the affect 
     of the key therefore giving additional protection.  
 
2.5. Software write protection on selected partitions. 
     A Key-protected DiskOnChip is available to an unauthorized user in read-only 
     mode. All data may be read, but not written or modified. Any attempt to 
     write to the Flash disk will result in a write-protect error. 
     The protection can be removed in one of 2 ways:
     (a) Temporary unlock - The disk will accept write operation to the remainder 
         of the session, that is until the next dismount or power down. On the 
         next mount, the disk will return to its read only mode.
     (b) Unprotect - The disk will no longer be write protected and will behave 
         like a normal system drive.

2.6. Multiple Volumes (partitions)
     DiskOnChip Millennium Plus and DiskOnChip 2000 TSOP devices can be 
     partitioned to export up to 4 separated volumes. The separation is 
     made at the driver layer and therefore is not dependent on the host OS 
     or file system.

2.7. Security enabling features
     TrueFFS 5.0 provides access to the DiskOnChip Millennium Plus One time 
     Programming area and to it's unique device and customer ID, burned into 
     the device.

2.8. MultiDOC
     The TrueFFS 5.0 driver provides an option to combine all physical DiskOnChip 
     parts in the system, possibly of different types and capacities into a 
     single "MultiDOC". From Windows CE perspective, "MultiDOC" appears as the 
     only "DiskOnChip" in the system, with capacity equal to sum of capacities 
     of all physical DiskOnChip parts. 


3. Installing DiskOnChip TrueFFS driver in Windows NT4 
   ----------------------------------------------------

   I. Installing DiskOnChip as additional drive in your system.

 1. Insert the disk with TrueFFS installation files into a drive.
 2. From the Windows NT display, open "My Computer" on your
    desktop or open the Windows NT Explorer.
 3. Open the disk with TrueFFS installation files.
 4. Click with the right mouse button on the file named Trueffs.inf.
    You will see a menu.
 5. In the menu choose "Install" and click on it.
 6. After Windows NT finishes copying the driver you will be
    asked to reboot your computer. After rebooting, the
    DiskOnChip will appear as another drive in your system.

   II. How to Change the DiskOnChip DriveLetter

 In Some cases NT4 will assign DiskOnChip the DriveLetter C: after
 the installation, to change the assigned DriveLetter please choose the 
 Disk Administrator option from the start-menu and assign other drive letter
 to your DiskOnChip as requested.

   III. How to format DiskOnChip with NTFS, compress it and make it bootable 
       on Windows NT 4.0

 Assuming you already have DiskOnChip working in your system as
 additional drive:

 1. Create a Windows NT 4.0 installation to be copied to the
    DiskOnChip. You may use Microsoft Embedded NT 4.0 Target Designer
    or VenturCom Component Integrator to create a small footprint 
    installation (see below more details).
 
 2. Open Explorer, go to DiskOnChip drive and right click on it, then choose 
    "Format" from the menu.
 
 3. Choose NTFS in "File System", Do NOT enable compression, press
    "Start". Press "Close" when formatting is finished.
 
 4. Go to the drive and create new folder with the name "Winnt".
    Right-click on this folder and choose "Properties" from the menu.
 
 5. Check "Compress" and press "Ok". You will be given another
    screen with exclamation point warning that this action compresses
    all files but does not compress subfolders. Check "Also compress
    subfolders" and click "Ok".
 
 6. Now copy all the files from your Windows NT 4.0 installation to
    the drive. You should copy all files from your \Winnt directory to 
    the newly created \Winnt directory on the DiskOnChip drive. Copy
    all files that should be in the root to the root of the DiskOnChip
    drive. 
    Do NOT compress files in the root directory! 
    
    The following files must reside in the root directory for Windows 
    NT to boot: NTLDR, NTDETECT.COM and BOOT.INI.

 7. DiskOnChip is ready to boot Windows NT. If you want to boot it
    in the system you just used, you may disable your hard disk drive
    in the BIOS Setup or disconnect it thus letting the DiskOnChip
    be a boot device instead of your hard disk. Another option is to 
    rewrite a firmware on the DiskOnChip using switch /FIRST. This will
    make DiskOnChip a first "hard disk" in the system while your
    original hard disk will became a second disk.

   IV. Using the embedded Windows NT4.0 Target Designer to prepare
        small footprint embedded Windows NT 4.0

    To use DiskOnChip as a bootable system disk, select the DiskOnChip As Disk 
    component under System\Devices\Storage\Fixed Disk. 
    
    After creation of embedded NT 4.0 image you need to copy new TrueFFS
    driver into \WINNT\SYSTEM32\DRIVERS\Trueffs.sys file.

    You can use flash media on a target system that has a FAT or an NTFS file 
    system.

   V. Using the VenturCom Component Integrator to prepare small footprint 
       Windows NT 4.0

    To add TrueFFS driver to the Component Integrator you will have to
    import a TrueFFS kit (TrueFFS driver and TrueFFS kit definition file).

    1. Go to the disk with TrueFFS installation files and find Trueffs.kdf 
       file. Open this file with any text editor, for example, Notepad. 
       You should change the "Repository" parameter in the [Header] section 
       and the "1" parameter in the [SourceMedia] section to the drive letter 
       of the disk with TrueFFS installation files. You should also change 
       the "1" parameter in the [Directories] section to the actual location 
       of the TrueFFS installation files.
 
    2. Open Component Integrator, go to "Workspace" menu, choose "Kit Import". 
       Click "Add" and open Trueffs.kdf file. Click "OK" after processing is 
       finished.
    
    3. Go to your configuration of Windows NT in the Component Integrator, 
       open "System" - "Disk Storage" - "Disks", click twice on "TrueFFS", 
       check "Add Component" and press "Ok".
    
    4. Build your configuration. It will now include DiskOnChip support.


4. Extended functionality of DiskOnChip TrueFFS driver version 5.0
-------------------------------------------------------------------
The basic function of TrueFFS is to enable regular file systems to access the
DiskOnChip as if it were a block device (disk). To do this, TrueFFS provides 
a standard block-device interface, with the capability of reading and writing 
logical sectors to and from the DiskOnChip. This capability, along with 
advanced Flash management features (transparent to the OS and file system) are 
enough to enable file-systems and operating systems to manage the DiskOnChip as 
a standard storage device.

In addition to the standard storage device functionality, the TrueFFS 5.0 
driver provides access to extended functionality, not part of standard 
file systems API.

The driver implements the interface of the extended functionality by exporting 
a list of extended functions (through IOCTLs). Every extended function is 
represented by a code defined as enumerated type defined in flioctl.h.

note: see implementation example of IOCTL Functionality of DiskOnChip at the end 
of this section.


4.1 IOCTL list and functionality
================================

For more explanations regarding the DiskOnChip extended functionality and it's 
usage please refer to application note #46 (Extended functions of TrueFFS 
driver for DiskOnChip).
 
4.1.1  IOCTL_TFFS_GET_INFO
       Returns general information about the partition, the socket where it 
       resides, software versions, high-level and low-level geometry and 
       estimated lifetime of the media.
           	
4.1.2 IOCTL_TFFS_DEFRAGMENT 
      Performers an early defragmentation (during idle time) through flDefragmentVolume.

4.1.3. IOCTL_TFFS_WRITE_PROTECT -
       Activates and handles the software write protection mechanism of the 
       TrueFFS driver for DiskOnChip.
	
4.1.4. IOCTL_TFFS_MOUNT_VOLUME -
       This function remounts the DiskOnChip. Remounting consists of 
       discarding all in-memory control information kept by the DiskOnChip 
       driver, and rebuilding it. 
       One of the most common uses of this function is when a user application 
       accesses and modifies the DiskOnChip not via the file system API. 

4.1.5. IOCTL_TFFS_BDK_OPERATION
       This function is used to perform standard operations on the binary 
       partitions (read/write/erase/create/get size of binary partitions). 
       The most common use for these partitions is to store system boot code. 
	
4.1.6. IOCTL_TFFS_FORMAT_PHYSICAL_DRIVE	
      Formats a volume and all its partitions.

4.1.7. IOCTL_TFFS_BDTL_HW_PROTECTION
       Performs standard operations on BDTL partitioned defined as hardware 
       protected (where applicable).
       
4.1.8. IOCTL_TFFS_BINARY_HW_PROTECTION
       Performs standard operations on Binary partitioned defined as hardware 
       protected (where applicable).

4.1.9. IOCTL_TFFS_OTP
       Performs standard operations on the One Time Programming (OTP) area
       of the DiskOnChip Millennium Plus.

4.1.10. IOCTL_TFFS_CUSTOMER_ID
        Returns the H/W embedded customer ID (where applicable)	

4.1.11. IOCTL_TFFS_UNIQUE_ID	
        Returns the H/W embedded unique device ID.

4.1.12. IOCTL_TFFS_NUMBER_OF_PARTITIONS
        Returns the number of partitions (BDTL) in a specific device

4.1.13. IOCTL_TFFS_INQUIRE_CAPABILITIES
        Return if the current hardware and software  supports a specific 
	feature.

4.1.14. IOCTL_TFFS_SET_ENVIRONMENT_VARIABLES
        Set the environment variable value. 

4.1.15. IOCTL_TFFS_WRITE_IPL
        Write IPL area for DiskOnChip family. Relevant only in INFTL formatted 
	devices, currently the DiskOnChip Millennium Plus and DiskOnChip 2000
	TSOP.

4.1.16. IOCTL_TFFS_DEEP_POWER_DOWN_MODE
        Changes the power consumption mode of the DiskOnChip Millennium Plus.	

4.1.17. IOCTL_TFFS_DELETE_SECTORS
        Marks one or more consecutive absolute sectors as logically deleted.

4.1.18. IOCTL_TFFS_PLACE_EXB_BY_BUFFER
        Place an EXB file using small buffers.

4.1.19. FL_IOCTL_FORMAT_VOLUME
        This extended function is left for backwards compatibility with 
	previous versions of TrueFFS SDK (former name TrueFFS-OSAK). 
	Whenever possible use FL_IOCTL_FORMAT_PHYSICAL_DRIVE instead.


5. Implementation example of IOCTL Functionality (IOCTL_TFFS_GET_INFO )
-----------------------------------------------------------------------
#include <stdio.h>
#include <ctype.h>
#include <stdlib.h>
#include "ntioctl.h"

int  main(int argc, char *argv[])
{
  HANDLE drvDev;
  CHAR drvName[TFFS_DRV_NAME];
  int  i;

  // Get Device Handle
  drvDev = CreateFile(	(LPCTSTR)drvName, GENERIC_READ | GENERIC_WRITE,
                        FILE_SHARE_READ | FILE_SHARE_WRITE,
						NULL, OPEN_EXISTING, 0, NULL );

  if( drvDev == INVALID_HANDLE_VALUE ) {
	printf("Device %s Handle - Fail, Error = %ld\n",drvName,GetLastError());
	return( 2 );
  }
  else printf("Device %s Handle - Ok\n",drvName);

   // Command Line processing
  for(i=ARG_START+1;( i < argc );i++) {            // Command Line Processing
    printf("%s\n",argv[i]);
    if( *argv[i] == '-' )
      switch( toupper(*(argv[i]+1)) ) {
	case 'I':                                // Info
	  printf("GetInfo..");
	  ioctlCall(drvDev,IOCTL_TFFS_GET_INFO,NULL);
	  break;

        default:
	      printf("Illegal option %s\n",argv[i]);
	      Usage();
	      return(1);
       }
    else {
      printf("Illegal option %s\n",argv[i]);
      Usage();
      return( 1 );
    }
  }

  CloseHandle(drvDev);
  drvDev = NULL;
  return( 0 );
}



void ioctlCall(HANDLE Dev, DWORD ioCtlCode, ... )
{
  va_list param;
  PCHAR paramPtr;
  BOOL status;
  DWORD inBufferSize, outBufferSize;
  DWORD retLength; // returned amount of data
  LPVOID lpInBuffer = NULL, lpOutBuffer = NULL;
  va_start(param,ioCtlCode);			// init parameter variable

  //IOCTL_TFFS_GET_INFO
  inBufferSize = 0;
  outBufferSize = sizeof(flDiskInfoOutput);
  lpOutBuffer = (LPVOID)malloc(outBufferSize);
  va_end(param);				// end parameter variable

  // ioctl call
  status = DeviceIoControl(Dev, ioCtlCode, lpInBuffer, inBufferSize,
			   lpOutBuffer, outBufferSize, &retLength, NULL);

	
  if( status == 0 ) {
    printf("Fail\n");
    if( lpInBuffer != NULL )
      free(lpInBuffer);
    if( lpOutBuffer != NULL )
      free(lpOutBuffer);
		return;
  }
  printf("Ok\n");

  // show returned data
	
      printf("Logical Sectors:    %x\n", 
        ((flDiskInfoOutput *)lpOutBuffer)->info.logicalSectors);
      printf("Boot Area Size:     %x Kbytes\n", 
          ((flDiskInfoOutput *)lpOutBuffer)->info.bootAreaSize / KBYTE);
      printf("Base Address:       %lx\n",
          ((flDiskInfoOutput *)lpOutBuffer)->info.baseAddress);
      printf("Flash Type:         %x\n",
          ((flDiskInfoOutput *)lpOutBuffer)->info.flashType);
      printf("Physical Size:      %x Mbytes\n",
          ((flDiskInfoOutput *)lpOutBuffer)->info.physicalSize / MBYTE);
      printf("Physical Unit Size: %d Kbytes\n",
          ((flDiskInfoOutput *)lpOutBuffer)->info.physicalUnitSize / KBYTE);
      printf("DOC Type:           %d\n", 
          ((flDiskInfoOutput *)lpOutBuffer)->info.DOCType);
      printf("Life Time (1-10):   %d\n", 
          ((flDiskInfoOutput *)lpOutBuffer)->info.lifeTime);
      printf("Driver version:     %s\n", 
          ((flDiskInfoOutput *)lpOutBuffer)->info.driverVer);
      printf("OSAK version:       %s\n", 
          ((flDiskInfoOutput *)lpOutBuffer)->info.OSAKVer);
      printf("Cyl/Head/Sec = %x/%x/%x\n",
              ((flDiskInfoOutput *)lpOutBuffer)->info.cylinders,
		      ((flDiskInfoOutput *)lpOutBuffer)->info.heads,
			  ((flDiskInfoOutput *)lpOutBuffer)->info.sectors);
 
  if( lpInBuffer != NULL )
    free(lpInBuffer);
  if( lpOutBuffer != NULL )
    free(lpOutBuffer);
}


6. Known limitations
--------------------
6.1 Read protected BDTL partitions must be set as the last partition.

6.2 IOCTL_TFFS_FORMAT_PHYSICAL_DRIVE is not functional.

6.3 When formatting an 8MB BDTL partition, use the native file systems high 
    level format and not the TrueFFS built in FAT formatter.

6.4 If write protection is activated on a partition that was not mounted as write 
    protected, then writing to a write protected partition will show a fail message 
    only after the data is flushed from the system cache.

6.5 Protected partitions must not use the key (password) "00000000" (ASCII 0)


7. Contact information
----------------------- 
For comments and questions please e-mail us to techsupport@m-sys.com. 
M-Systems full contact list can be found on our web site (www.m-sys.com).

TrueFFS is a registered trade mark of M-Systems Ltd. The TrueFFS software is 
protected by US Patent no. 5404485. All other trade marks, service marks, 
trade names are the property of their respective owners.