readme.txt

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

            # mknod /dev/tffsa2 b 100 2 
            # mknod /dev/tffsa3 b 100 3
            # mknod /dev/tffsa4 b 100 4

       ===> NOTE. If you have configured DOC driver to use different major
                  device number (see Section 4.1), you will need to replace
                  '100' in the commands above accordingly.

       These /dev entries refer to:

            /dev/tffsa    is the "raw disk" entry for the first mDOC "disk"
            /dev/tffsa1   refers to 1-st file system partitions on this disk
            /dev/tffsa2   refers to 2-nd file system partitions on this disk
            /dev/tffsa3   refers to 3-rd file system partitions on this disk
            /dev/tffsa4   refers to 4-th file system partitions on this disk

       ===> NOTE. While there is rarely a need to have more then four file
                  system partitions on mDOC, DOC driver actually supports
                  up to 15 of such partitions. If you opted to have more then
                  four file system partitions, simply add more 'mknod' commands
                  to the script above to create device entries for additional
                  partitions.

       ===> NOTE. Current version of mDOC driver doesn't take advantage of
                  devFs ability to allocate major driver numbers and create 
                  device entries under /dev dynamically.



 10. Using DOC driver
 ====================

 10.1. The DOC driver can be loaded in the same way that other kernel modules
       are loaded:

           insmod tffs.ko [params]

       The following command line parameters are currently supported by DOC
       driver:

           tffs_major       major device number to use (default is '100')
           tffs_addr        physical address of mDOC
           tffs_sg_read     "gather" data during read operations
           tffs_sg_write    "scatter" data during write operations
           tffs_irq         IRQ (interrupt request line) to use; '-1' for none
           tffs_dma_mode    DMA mode (default is don't use DMA)
           tffs_pio         polled I/O mode
           prio             controls priority of driver's I/O processing thread
           hardsect         size of the hardware sector in bytes
           rahead           read-ahead parameter
           fl_debug         controls verbosity level of driver's debug messages
           tffs_dpd_timeout delay before mDOC automatically enters powerdown mode

 10.2. To create disk partition table on mDOC:

           fdisk /dev/tffsa

       When 'fdisk' utility presents you with command prompt, you can choose
       'p' to print existing disk partition table, 'd' to delete existing disk
       partitions (if exists), or 'n' to create new disk partitions.

 10.3. If you created new disk partitions in Section 10.2, you will need to
       initialize file systems on these disk partition(s). For example,
       to initialize EXT2 file system on the first partition (/dev/tffsa1),
       use:

           mke2fs /dev/tffsa1

       When initializing file system on mDOC disk partition, 'mke2fs' utility
       calculated file system's block size based on the size of this disk
       partition. Currently EXT2 and EXT3 file systems supports file system
       blocks of 1024, 2048 and 4096 bytes. Smaller file system blocks (1024
       bytes) allow more efficient use of disk space, at the expense of DOC
       driver's 'write' performance. Larger file system blocks (4096 bytes)
       noticably increase 'write' performance, at the expense of some disk
       space. You can pass '-b <block-size>' parameter to 'mke2fs' utility to
       explicitely specify size of file system blocks.

       For example, if you want to maximize 'write' performance of DOC driver,
       you can do so by telling 'mke2fs' to use largest possible (4096 bytes)
       file system blocks: 

           mke2fs -b 4096 /dev/tffsa1

 10.4. Create mount point for mDOC partition(s), and mount them:

           mkdir -p /mnt/tffsa1
           mount /dev/tffsa1 /mnt/tffsa1

 10.5. You can now create files and directories on mDOC. For example:

           echo have a nice day > /mnt/tffsa1/greetings.txt

       To see if the above command worked as expected, execute:

           cat /mnt/tffsa1/greetings.txt

 10.6. Before shutting the system down, unmount all previously mounted mDOC
       partition(s):

           umount /dev/tffsa1



 11. Configuring DOC driver to reduce power consumption
 ======================================================

 11.1. This Chapter is only relevant to devices where power conservation is of
       major concern. Various battery powered systems (such as mobile phones
       and PDAs) fall into this category. 

 11.2. The mDOC device automatically switches from the normal power state into
       the low-power state after certain amount of time passes from the
       completion of the last read/write access to mDOC device. By default,
       this power-down timeout is set to 100 milliseconds; it can be changed
       via driver's command line option "tffs_dpd_timeout=<num>". The argument
       <num> specifies duration of power-down timeout in milliseconds, for
       example:

           insmod tffs.ko tffs_dpd_timeout=1000

       would cause mDOC device to automatically power itself down one second
       (1000 milliseconds) after the last read/write access.

       ===> NOTE. Currently mDOC firmware rounds down power-down timeout to
                  nearest 100 millisecons multiple, i.e. "tffs_dpd_timeout=345'
                  has the same effect as "tffs_dpd_timeout=300".

 11.3. DOC driver supports standard Linux 2.6 power management scheme (option
       CONFIG_PM in kernel's .config configuration file). The relevant power
       suspend/resume code resides in file tffs-pm26.c, and is
       self-explanatory.



 12. Improving DOC driver's I/O performance
 ==========================================

 12.1. This Chapter provides overview of the various means of improving
       'read' and 'write' performance of DOC driver.

 12.2. The duration of the access cycles to mDOC's registers is one of the
       major factors affecting both 'read' and 'write' performance of 
       DOC driver. The duration of these access cycles is usually
       determined by the settings of board's Chip Select that mDOC device
       is connected to. If duration of these access cycles substantially
       exceeds timings specified in documentation for your mDOC device,
       'write' and  especially 'read' performance of DOC driver will be
       sub-optimal.

 12.3. It is possible to improve I/O performance of DOC driver by enabling
       compiler optimizations when compiling DOC driver.

       If you have choosen to place DOC driver into Linux kernel's source code
       tree (see Section 8.2), you can instruct compiler to optimize generated
       code by adding the following line to DOC driver's Makefile:

            EXTRA_CFLAGS := -O2

       If you have choosen to build DOC driver outside of the Linux kernel's
       source code tree (see Section 8.3), you can instruct compiler to
       optimize generated code by adding the following line to DOC driver's
       Makefile:
      
            CFLAGS += -O2

 12.4. For portability reasons, Linux drivers use dedicated macros and routines
       to access registers of peripheral devices. By default DOC driver
       adheres to this policy. However, in many cases it is possible to 
       substantially increase  performance of DOC driver by instructing it
       to use general purpose memory routines (such as memcpy()) to transfer
       blocks of data to and from mDOC device. To do so, use driver's
       "tffs_memcpy=1" command line option:
       
           insmod tffs.ko tffs_memcpy=1 
       
       ===> NOTE. The "tffs_memcpy=1" command line option might not work
                  with some boards. 
 
 12.5. If you are using any of the following reference boards:

           - Texas Instruments's OMAP2420 ("H4")
           - Intel PXA27x ("Mainstone")

       you can substantially improve DOC driver's 'read' performance by
       telling it to use DMA to transfer data between mDOC and main memory.
       See Chapter 6 for more details on "tffs_dma_mode=<mode>" command
       line option.

       If you are using different board, consider adding support for your
       specific DMA implementation to DOC driver. 

 12.6. By default, DOC driver attempts to internally combine few 'write'
       requests into single 'write' operation on mDOC device (this process is
       usually referred to as "gathering" of I/O requests). Similarly, DOC
       driver attempts to internally combine few 'read' requests into single
       'read' operation on mDOC device (this process is usually referred to as
       "scattering" of I/O requests). 

       While this behavior improves DOC driver's performance for many
       systems, it might actually reduce it in case of systems with slow
       access to DRAM (such as Intel PXA27x "Mainstone"). For this kind of
       systems, it is possible to improve DOC driver's performance by
       instructing driver not to perform any scattering/gathering of I/O
       requests. 

       To tell DOC driver not to combine (gather) 'write' requests, use
       command line option "tffs_sg_write=0":

           insmod tffs.ko tffs_sg_write=0

       To tell DOC driver not to combine (scatter) 'read' requests, use
       command line option "tffs_sg_read=0":

           insmod tffs.ko tffs_sg_read=0

       Use both of these command line options to tell DOC driver not to do
       any scattering/gathering of I/O requests:

           insmod tffs.ko tffs_sg_write=0 tffs_sg_read=0

 12.7. By default, DOC driver uses polled I/O mode, and transfers single
       sector (512 bytes) at a time. It is possible to improve driver's
       I/O performance by instructing it to transfer multiple sectors a time.
       This could be done by using "tffs_pio=<num>" command line option, where
       <num> is either 2 (for two-sector transfers) or 4  (for four-sector
       transfers). For example:

           insmod tffs.ko tffs_pio=4 
       
 12.8. It is possible to substantially improve DOC driver's 'write' performance
       by increasing file system's block size. In case of EXT2 file systems,
       file system's block size is determined by 'mke2fs' utility when it
       initializes file system on the disk partitions (see Section 10.3), and
       is set to 1024, 2048 or 4096 bytes depending on the size of this disk
       partition. Passing '-b 4096' command line option to 'mke2fs' utility
       forces it to use 4096-byte blocks (the largest possible file system
       block size) regardless of the actual size of the disk partition,
       therefore improving DOC driver's 'write' performance.


 13. Reducing DOC driver's load on CPU
 =====================================

 13.1. During 'write' operations DOC driver normally polls mDOC device in
       order to detect completion of the operation. While this approach allows
       DOC driver to maximize mDOC's 'write' performance, it also ties up CPU
       for extensive periods of time, reducing amount of CPU time available to
       all other processes in the Linux system. 

       The alternatve approach for DOC driver would be to yield CPU right
       after starting 'write' operation on mDOC device, and sleep until
       completion of this operation. While this approach is optimal in terms
       of minimizing DOC driver's load on CPU, it is only possible if
       DOC driver supports mDOC interrupt generation on your particular
       system.

       See Chapter 7 for more details regarding mDOC interrupts.

 13.2. If mDOC interrupt isn't supported for your particular board, it is still
       possible to reduce DOC driver's load on CPU by using the command line
       option "tffs_skip_sleeps=<num>", where <num> values depend on the type of
       mDOC device. You should specify <num> values equal to or greater then
       100. Greater <num> values will improve DOC driver's 'write'
       performance, but will also increase it's load on CPU. The optimal <num>
       value depends on the desired tradeoff between 'write' performance and 
       load on CPU. You can start by trying <num> set to 5000:

             insmod tffs.ko tffs_skip_sleeps=5000

       and measure DOC driver's 'write' performance, and it's load on CPU.
       If DOC driver's load on CPU will be acceptable but it's 'write'