readme.txt

H3 M-system NAND flash driver in Linux OS, M-DOC driver

       performance is too low, try increasing <num> value. If DOC driver's
       load on CPU will be too high, try decreasing <num> value until you
       reduced the load on CPU to the desired level.
 


 14. Access to DOC driver's Extended Functions
 =============================================

 14.1. In addition to standard block device functionality, DOC driver provides
       access to DOC driver's Extended Functions, which is not a part of the
       standard file system API. See included manual "DOC Driver Extended
       Functions Developer Guide" for detailed explanation of all DOC driver's
       Extended Functions.

       ===> NOTE. For security reasons, FL_IOCTL_DELETE_SECTORS Extended
                  function was disabled in the current version of DOC
                  driver.

       The following section describes only the functionality that is not
       supported by DOC drivers for other operating systems.

       Your application code which utilizes DOC driver's IOCTLs, should contain
       the following:

           #include "tffsioct.h"

       Your application's Makefile should add DOC driver's headers to
       compiler's include path. For example, if you added DOC driver to
       kernel's source tree (see Section 8.2):

           -I<your_kernel>/drivers/tffs

       The 'ioctl_example' sub-directory in DOC driver archive contains
       example application code which shows how to access Extended Functions
       via IOCTL calls to DOC driver.

 14.2. IOCTL limitations

 14.2.1. All pointers in IOCTL structures should be valid values or null, even
         if not used in IOCTL.

 14.2.2. For FL_IOCTL_FLASH_FORMAT call, 'volumeLabel, 'embeddedSIC' and
         'progressCallback' fields of formatParams must be NULL. The DOC
         driver must be restarted right after calling this IOCTL.

 14.2.3. The FL_IOCTL_SET_ACCESS_ROUTINE and FL_IOCTL_GET_ACCESS_ROUTINE are
         not supported.

                

 15. Formatting mDOC
 ===================

 15.1. The easiest way to format mDOC is to start DOC driver with
       "tffs_format=<number>" command line parameter. The argument <number>
       specifies which mDOC to format; it is usually specified as zero:

           insmod tffs.ko tffs_format=0

       In this case DOC driver will re-format mDOC using standard formatting
       parameters.

 15.2. If you are interested in formatting mDOC using custom formatting
       parameters, you can accomplish this using FL_IOCTL_FLASH_FORMAT mDOC
       Extended Function. See Chapter 14 for more information on mDOC
       Extended Functions.

 15.3. Although not mandatory, it's a good idea to reset mDOC (for example
       by rebotting the system) right after formatting it.

 

 16. Updating firmware in mDOC devices
 =====================================

 16.1. DOC driver comes with the utility program 'doch-firmware' which can be
       used to upgrade firmware in mDOC devices. The source code and Makefile
       for this utility program reside in subdirectory 'doch-firmware' in DOC
       driver's archive.

 16.1.1. By default, doch-firmware/Makefile assumes XScale compiler
         'iwmmxt_le-gcc'. If you are using different compiler, change
         definition of macro 'CC' in this Makefile accordingly.

 16.1.2. You will need to change definition of macro 'INCLUDE_DIR' in
         doch-firmware/Makefile to point to the directory where all your
         applications #include .h files from. 

         ===> NOTE. The applications' 'INCLUDE_DIR' is different from
                    the your kernel's <top>/include directory that is used
                    in kernel builds. For example, header <stdio.h>
                    exists in the former but not in the latter directories.

 16.1.3. Change to 'doch-firmware' subdirectory, and build 'doch-firmware'
         utility program:

             cd doch-firmware
             make

 16.1.4. Copy doch-firmware/doch-firmware utility program to the
         appropriate location on the target's root file system, and
         set permissions accordingly. For example:

             cp doch-firmware <target_root_fs>/sbin
             chmod 750 <target_root_fs>/sbin/doch-firmware

 16.2. Login to the target as superuser ("root"), and verify that DOC driver is
       loaded and running.

 16.3. Copy mDOC firmware file to the target.

 16.4. To prevent corruption of the file systems that reside on mDOC,
       unmount previously mounted mDOC partition(s) (see Chapter 10
       for more details on mouting mDOC partition(s)).

 16.5. Execute:

           /sbin/doch-firmware /dev/tffsa <mdoc_firmware_file>

       where <mdoc_firmware_file> is mDOC firmware file (see Section 16.3).

 16.6. Reset target system to put new mDOC firmware into effect.



 17. Memory footprint
 ====================

 17.1. This Section describes DOC driver's memory footprint (amount of RAM
       that DOC driver's code and data take at runtime) for the reference
       case of Intel's PXA27x ("Mainstone") board (ARM processer). DOC
       driver's memory footprint varies significabtly between various
       processor architectures and compiler optimizations.

       In case of Intel's PXA27x ("Mainstone") board, if compiled without
       any optimizations, DOC driver takes about 240 KB of kernel memory
       for it's code and data.

       In addition to the above, DOC driver may also do the following
       dynamic memory allocations if respective runtime configuration
       options are enabled:

           - The buffer for internal scatter/gather operations (see
             Section 12.6). By default, size of this buffer is 64 KB.

           - If DMA is used (see Chapter 6), DOC driver allocates internal
             4 KB buffer for use with DMA operations.

             

 18. Known limitations
 =====================

     - Current version of DOC driver limits number of "disks" per mDOC
       "socket" to 12.

     - Current version of DOC driver doesn't support FL_IOCTL_GET_INFO
       Extended Function on OTW BDTL partitions ("disks").

     - Current version of DOC driver fails to re-format 16Gbit mDOC
       H3 devices that have protected BDTL partitions ("disks") on them.

     - Current version of DOC driver will not recognize mDOC H3 devices if
       they are configured to work in 128KB window mode. 

     - When formatting with flCreateLogicalPartitions
        - Minimal size for logical partition is twice flash unit size
        - Usable user space is one flash unit size less than allocated (FAT
           alignment overhead)

          Device                   Minimal Partition Size    Overhead

          mDOC H3 128MB and MCP45   512 KB                    256KB
          mDOC H3 1GB                 4 MB                    2MB
          mDOC H3 2GB                 8 MB                    4MB
        
     - More than one device of mDOC H3 in one system is not supported.

     - Using PortaDOC when DOC is configured for 128KB window, requires flSystem
       adaptation.

     - IPL size in normal mode 128KB window should not exceed 8KB.
       This limitation is not applicable to paged RAM mode and Virtual mode.

     - The field fastAreaLength in structure BDTLPartitionFormatParams3 must
       always be set to zero (already set to zero in SDK default).

     - Burst mode not supported.

     - In MCP45: DOCH_IM_IDLE and DOCH_IM_DPD disables AutoDPD. Selecting
       DOCH_IM_IDLE_2_DPD (default) is required in order to have autoDPD enabled.

     - In MCP45: Inserting wrong key to a protected partition more than 16
       times will cause rejection of any further attempt until host reset.

     - When using 8KB memory window, only boot from lowest mDOC address
       (mDOC base address, typically address zero) is supported.
       Boot from top address (mDOC base address + 0x1ffe) is not supported, as mDOC
       top address range (0x1800-0x1ffe) does not alias IPL in this mode.

     - flIdentifyProtection will return flHWProtection when the requested
       partition is RW protected and the key is not inserted.



 19. Disclaimer of Liability
 ===========================

 SanDisk IL Ltd.'s general policy does not recommend the use of its products
 in life support applications wherein a failure or malfunction of the
 product may directly threaten life or injury.
 Accordingly, in any use of products in life support systems or other
 applications where failure could cause damage, injury or loss of life,
 the products should only be incorporated in systems designed with
 appropriate redundancy, fault tolerant or back-up features.

 SanDisk IL shall not be liable for any loss, injury or damage caused by
 use of the Products in any of the following applications:

 Special applications such as military related equipment, nuclear reactor
 control, and aerospace

 Control devices for automotive vehicles, train, ship and traffic
 equipment

 Safety system for disaster prevention and crime prevention

 Medical-related equipment including medical measurement device.



 20. Contact information
 =======================

 For comments, questions and bug reports, please contact your SanDisk 
 representative or e-mail us at [e-mail].

    This document is for information use only and is subject to change
    without prior notice.

    SanDisk IL Ltd. assumes no responsibility for any errors that may 
    appear in this document, nor for incidental or consequential damages
    resulting from the furnishing, performance or use of this material.

    SanDisk IL's products are not warranted to operate without failure.
    SanDisk IL's general policy does not recommend the use of its products
    in life support applications where a failure or malfunction of the
    product could cause injury or loss of life. Per SanDisk IL's Terms and
    Conditions of Sale, the user of SanDisk IL's products in life support
    applications assumes all risk of such use and indemnifies SanDisk IL
    against all damages. See "Disclaimer of Liability". Accordingly, in
    any use of the Product in life support systems or other applications
    where failure could cause injury or loss of life, the Product should
    only be incorporated in systems designed with appropriate and
    sufficient redundancy or backup features.

    All parts of the SanDisk IL's documentation are protected by copyright
    law and all rights reserved.

    Contact your local SanDisk sales office or distributor to obtain the
    latest specifications before placing your order.

    (C) 1995-2007 SanDisk IL Ltd. All rights reserved.

    mDOC, DOC, TrueFFS, SureFS, SanDisk and SanDisk logo are registered
    trademarks of SanDisk IL Ltd. and SanDisk Corporation, respectively.
    Other product names or service marks mentioned herein may be trademarks
    or registered trademarks of their respective owners and are hereby 
    acknowledged.