*************************************************************************
*                                                                       *
*  Copyright M-Systems (c) 2002	                                        *
*                                                                       *
*  DiskOnChip (R) TrueFFS version 5.1.4  Nov 20, 2002			*
*                                                                       *
*  TrueFFS Extended functionality source code example for DOS		*
*                                                                       *
*************************************************************************


This document describes how to use and compile the DOS IOCTLs example source 
code available under this directory:


Contents
-----------
A. Introduction
B. IOCTLs implemented by IOCTLTST
C. Using the IOCTLTST (binary version)
D. Building IOCTLTST.EXE
E. Contact information


A. Introduction.
----------------
In addition to the standard storage device (block device) functionality, 
the TrueFFS driver provides access to DiskOnChip 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 DOSIOCTL.H.

The example program described below explain and demonstrate the usage of 
the TrueFFS IOCTL interface in DOS.


B. IOCTLs implemented by IOCTLTST
---------------------------------
IOCTLTST implements the following IOCTLS:

 1. GET_INFO_IOCTL
    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.

 2. DEFRAG_IOCTL 
    Performs an early defragmentation (during idle time) through flDefragmentVolume.
 
 3. BDTL_HW_PROTECTION_IOCTL
    Performs standard operations on BDTL partitioned defined as hardware 
    protected (where applicable).
    
 4. HW_OTP_IOCTL
    Performs read / write to the OTP area and reports it's status.

 5. UNIQUE_ID_IOCTL
    Reports the device's unique ID.

 6. DELETE_SECTORS_IOCTL
    Deletes virtual sectors from disk partitions.

 7. DEEPOWER_MODE_IOCTL
    Places the DiskOnChip into deep power down mode (sleep), in which it 
    consumes minimal power.


C. Using the IOCTLTST (binary version)
--------------------------------------

Usage: IOCTLtst /D:[drive]  /C:[command]  [/S:[sectors]] [/F:[first]] 
                [/T:[type]]  [/P:[protection]] [/K:[key]] [/B:[batch]]
  
  drive      - Drive letter of the Device, such as C, D, E, etc...
  command    - IOCTL command: GETINFO, DELSECT, BDTLHW, BINHW, HWOTP, 
               CUSTOMER, UNIQUE,  DEEPOWER, DEFRAG
  first      - first sector, used for DELSECT
  sectors    - Number of sectors, used for DELSECT, DEFRAG
  protection - Protection attributes. The options are:
	       1-PROTECTABLE, 
	       2-READ_PROTECTED
	       4-WRITE_PROTECTED
	       8-LOCK_ENABLED
	       16-LOCK_ASSERTED
	       32-KEY_INSERTED
	       64-CHANGEABLE_PROTECTION
  type       - Type of protection operation: 
               0-PROTECTION_INSERT_KEY
               1-PROTECTION_REMOVE_KEY
	       2-PROTECTION_GET_TYPE
	       3-PROTECTION_DISABLE_LOCK
	       4-PROTECTION_ENABLE_LOCK
	       5-PROTECTION_CHANGE_KEY
	       6-PROTECTION_CHANGE_TYPE
  key        - An 8 byte protection key
  batch      - Batch test, implementing all of the above IOCTLs on DiskOnChip 
               Millennium Plus or Mobile DiskOnChip. To run the test the 
	       DiskOnChip must be formatted as follows:

	       DFORMAT /WIN:xxxx /Y /BDTLP:CW:12345678
 

D. Building IOCTLTST.EXE
----------------------
In order to build the example you need BorlandC 3.1 environment. Edit the IOCTL.MAK file 
macroes LIBPATH and INCLUDEPATH to match the path of your BC libraries and includes directories.
Then set the current path to the IOCTLTST directory and type 'make -fioctltst.mak'. 
An executable file will be built. It also possible to create new executable project using any 
compiler/linkey environment. The project should include all givven C files.



E. Contact Information
----------------------

 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.

 Corporate Headquarters    |    North American Headquarters
-----------------------	   |	---------------------------
 M-Systems Ltd.            |   	M-Systems Inc.
 Central Park 2000         |	8371 Central Avenue
 Kfar Saba 44425,	   |    Suite A
 Israel            	   |	Newark, CA 94560
             		   |	USA
                           |
 Tel: 972-9-764-5000 	   |   	Tel: (510) 494-2090
 Fax: 972-3-548-8666	   |   	Fax: (510) 494-5545
 
E-mail: info@m-sys.com     http://www.m-sys.com