readme.txt

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

                  macros in file tffsarch.h "as is". You do have to implement
                  routines in file tffsarch.c as appropriate for your own
                  system.
       
  6.2. To instruct DOC driver to use DMA during 'read' and/or 'write
       operations, use 'tffs_dma_mode=<mode>' command line option. Possible
       <mode> values are described below:

           tffs_dma_mode      Description

                1             DMA is used during 'read' operations. 
                              Data is transferred in two steps: first, it is
                              read (using DMA) from mDOC device into driver's
                              internal non-cachable DMA buffer; secondly, data
                              is copied (using memcpy()) from the internal DMA
                              buffer to destination buffer.

                2             DMA is used during 'write' operations. 
                              Data is transferred in two steps: first, it is
                              copied (using memcpy()) from source buffer into
                              driver's internal non-cacheable DMA buffer;
                              secondly, data is written (using DMA) from DMA
                              buffer to mDOC device.

                3             This is the combination of modes '1' and '2'.

                5             DMA is used during 'read' operations. 
                              Data is transferred (using DMA) directly from mDOC
                              device to the destination buffer, without using
                              intermediate non-cachable DMA buffer.

                6             DMA is used during 'write' operations. 
                              Data is transferred (using DMA) directly from 
                              the source buffer to mDOC device, without using
                              intermediate non-cachable DMA buffer.  

                7             This is the combination of modes '5' and '6'.

       ===> NOTE. Systems with fast CPU-to-external-RAM interfaces would benefit
                  most from the DMA modes 1..3. Systems with slow 
                  CPU-to-external-RAM interfaces (such as PXA27x Mainstone)
                  would benefit most from the DMA modes 5..7. We advice that you
                  try various DMA modes with your particular system, and pick
                  the one with the best I/O performance.

       For example, to instruct DOC driver to use DMA mode '1' during
      'read' operations only, and don't use it during 'write' operations, you
       would start the driver as follows:

           insmod tffs.ko tffs_dma_mode=1



  7. Configuring DOC driver to use mDOC READY interrupt
  =====================================================

  7.1. The 'write' operations in modern flash devices (such as mDOC) might
       take hundreeds of microseconds. Often it is possible to improve overall
       system's responsiveness and throughput by configuring DOC driver to
       yield CPU during these periods of time.

       ===> NOTE. This option could negatively impact mDOC's  "write"
                  performance, especially when workload on the system
                  increases.

  7.2. By default, DOC driver enables mDOC READY interrupt for Intel PXA27x
       board ("Mainstone"), and disables it for all other boards.

       To override this default, use 'tffs_irq=<irq>' command line option.
       The <irq> argument specifies board's interrupt request line that mDOC's
       IREQ signal is connected to. 

       Current version of DOC driver support mDOC interrupts for the following
       reference boards:

             +------------------------------------+--------------------+
             | Board                              | Interrupt          |
             +------------------------------------+--------------------+
             | Texas Instruments OMAP2420 ("H4")  |   190              |
             +------------------------------------+--------------------+
             | Intel PXA27x ("Mainstone")         |   167              |
             +------------------------------------+--------------------+

       For example, in case of Texas Instruments's OMAP2420 board ("H4"),
       mDOC's IRQ signal is connected to board's GPIO_94 line (which generates
       interrupt 190), so you would start DOC driver as follows:

           insmod tffs.ko tffs_irq=190

       To disable DikOnChip's READY interrupt, specify <irq> as '-1'. For
       example:

           insmod tffs.ko tffs_irq=-1

                 

  8. Compiling DOC driver
  =======================

  8.1. This Chapter contains instructions for compiling DOC driver.

       The DOC driver can be placed into the Linux kernel's source code tree,
       and compiled as part of the Linux kernel compilation. Section 8.2
       provides instructions of how to do that.

       The DOC driver can also be placed in the separate directory outside of
       Linux kernel's source code tree, and compiled separately from the Linux
       kernel. Section 8.3 explains how to do that.
       
       Instructions below refer to the top directory of Linux kernel's source
       code tree (where .config kernel configuration file resides) as <top>.

  8.2. Sections 8.2.1 - 8.2.4 describe how to add DOC driver to Linux kernel's
       source code tree, and build it as part of Linux kernel compilation. 

  8.2.1. Create new directory <top>/drivers/tffs, copy DOC driver's archive
         to this directory, and unpack it there.

  8.2.2. Edit <top>/drivers/Makefile, and add the following statement at the
         end of this file:

             obj-y += tffs/ 

         This will cause 'make' utility to descend into <top>/drivers/tffs
         directory during Linux kernel compilation, build DOC driver, and
         statically link it into Linux kernel.

         If you don't want to statically link DOC driver into Linux kernel,
         and instead prefer to build it as dynamically loadable kernel module,
         you should change this statement as shown below:

             obj-m += tffs/ 

         This will cause 'make' utility to descend into <top>/drivers/tffs
         directory when building Linux kernel modules, and compile DOC driver
         as dynamically loadble Linux kernel.
 
  8.2.3. Create <top>/drivers/tffs/Makefile with the following contents:

             obj-y += tffs.o

             tffs-objs := trace32.o
             tffs-objs += defs.o
             tffs-objs += docdrv.o
             tffs-objs += doch_api.o
             tffs-objs += doch_ata.o
             tffs-objs += dochstub.o
             tffs-objs += dochtl.o
             tffs-objs += docsys.o
             tffs-objs += extfiltr.o
             tffs-objs += fatfilt.o
             tffs-objs += flbase.o
             tffs-objs += flcustom.o
             tffs-objs += flioctl.o
             tffs-objs += flsystem.o
             tffs-objs += hal_nor.o
             tffs-objs += tffs2lnx.o
             tffs-objs += tffs_api.o
             tffs-objs += tffsarch.o
             tffs-objs += tffs-pm26.o
             tffs-objs += tffsdrv26.o

         This Makefile instructs 'make' utility to build DOC driver, and
         statically link it into Linux kernel.

         If you don't want to statically link DOC driver into Linux kernel,
         and instead prefer to build it as dynamically loadable kernel module,
         you should change the first line of this Makefile as shown below:

             obj-m += tffs.o
             
  8.2.4. If you now build Linux kernel (if you have choosen to statically link
         DOC driver into Linux kernel) or kernel modules (if you have choosen
         to build DOC driver as loadable kernel module), you should see DOC
         driver being built as part of this process.

         You are done; skip the rest of Chapter 8.

  8.3. Sections 8.3.1 - 8.3.4 describe how to build DOC driver in the separate
       directory outside of Linux kernel's source code tree, separately from
       the Linux kernel. In this case DOC driver will be built as loadable
       kernel module tffs.ko.

  8.3.1. Place DOC driver's archive into the private directory outside of
         kernel's source tree, and unpack it there.

  8.3.2. DOC driver directory includes example Makefiles for the following 
         reference boards:

             +------------------------------------+--------------------+
             | Board                              | Makefile-<board>   |
             +------------------------------------+--------------------+
             | Texas Instruments OMAP2420 ("H4")  | Makefile-omap2420  |
             +------------------------------------+--------------------+
             | Intel PXA27x ("Mainstone")         | Makefile-pxa27x    |
             +------------------------------------+--------------------+

       If you are using one of these boards, then copy the respective file
       Makefile-<board> to Makefile. For example, if you are using Texas
       Instruments' OMAP2420 board:

             cp Makefile-omap2420 Makefile

       If you are using board other then listed above, you will need to write
       your own Makefile. The simplest way to do this is to take any of the 
       provided reference Makefile-<board>, and change the following macros
       as appropriate to your development setup:

           KERNEL_DIR
           CC
           CFLAGS
           LD
           LDFLAGS

       The KERNEL_DIR macro should be set to point to top directory of your
       kernel's source code tree.

       Macros CC and CFLAGS specify which compiler to use to build DOC driver,
       and which compiler flags to use for that. Similarly, macros LD and
       LDFLAGS specify which linker to use to link DOC driver's binary, and
       which linker flags to use for that. 

       ===> NOTE. The easy way to figure out appropriate settings for CC,
                  CFLAGS, LD and LDFLAGS macros is to execute:

                      make V=1 modules

                  in the kernel's top directory, and observe the values that
                  this this command is using to compile and link all Linux
                  loadable kernel modules.

                  The 'V=1' command line option instructs 'make' utility to
                  issue verbose output (which includes compiler's command line
                  parameters) rather then terse messages that it produces by
                  default.

  8.3.3. Make sure that compiler (as specified by macro CC in Section 8.3.2)
         is in the PATH, and build DOC driver by executing:

             make
 
         in DOC driver's directory. This command should generate tffs.ko
         loadable kernel module.
 
  8.3.4. You will need to create directory

             lib/modules/<kernel-version>/kernel/drivers/tffs

         on your target system's root file system, and copy loadable kernel
         module tffs.ko to that directory.



  9. Installing DOC driver
  ========================

  9.1. Add the following line to /lib/modules/<kernel-version>/modules.dep
       file on target's root file system:

           /lib/modules/<kernel-version>/kernel/drivers/tffs/tffs.ko:

  9.2. Create mDOC entries for mDOC devices under /dev directory. 

       Since current version of DOC driver supports up to 12 "disks" on mDOC
       device, with up to 15 file system partition on each of such "disks",
       you will need to create up to 192 mDOC entries under /dev (one "raw
       disk" entry is required for each of 16 "disk"). You can use script
       make_tffs_nodes.sh to create all these /dev entries, or you can do
       that manually using Linux 'mknod' utility. For example:

            # mknod /dev/tffsa  b 100 0 
            # mknod /dev/tffsa1 b 100 1