*******************************************************************************
* *
* DOC Driver for Linux 2.6 *
* Source Code Edition *
* *
* *
* INSTALLATION MANUAL *
* *
* *
* Version 1.0.85-beta, released on February 06 2008 *
* Based on DOC Driver Block Device SDK version 1.1.0 EQA9 *
* *
* Copyright SanDisk IL Ltd. (C) 2008 *
* Please note that effective January 1, 2007, the name msystems Ltd. was *
* changed to SanDisk IL Ltd. *
* *
* Email questions to: oemsupport@sandisk.com *
* *
*******************************************************************************
* *
* This program is free software; you can redistribute it and/or modify it *
* under the terms of the GNU General Public License as published by the Free *
* Software Foundation; either version 2 of the License, or any later version. *
* This program is distributed in the hope that it will be useful, but WITHOUT *
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or *
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for *
* more details, which is set forth in the readme.txt file. *
* You should have received a copy of the GNU General Public License along *
* with this program; if not, write to the Free Software Foundation, Inc., 51 *
* Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA *
* *
* This License does not grant you any right to use the trademarks, service *
* marks or logos of SanDisk IL Ltd. or SanDisk Corporation. *
* Subject to the foregoing, SanDisk IL Ltd., for itself and on behalf of its *
* licensors, hereby reserves all intellectual property rights in the program, *
* except for the rights expressly granted in this License. *
* *
*******************************************************************************
Contents
========
1. Introduction
2. Supported types of mDOC devices
3. Conventions used in this document
4. DOC driver's general configuration options
5. Board specific configuration options
6. Configuring DOC driver to use Direct Memory Access (DMA)
7. Configuring DOC driver to use mDOC READY interrupt
8. Compiling DOC driver
9. Installing DOC driver
10. Using DOC driver
11. Configuring DOC driver to reduce power consumption
12. Improving DOC driver's I/O performance
13. Reducing DOC driver's load on CPU
14. Access to DOC driver's Extended Functions
15. Formatting mDOC
16. Updating firmware in mDOC devices
17. Memory footprint
18. Known limitations
19. Disclaimer of Liability
20. Contact information
1. Introduction
===============
1.1. This document explains how to install DOC driver, and use mDOC device
with Linux operating system. The information in this document applies
to 2.6.x versions of the Linux kernel.
1.2. The mDOC devices are high performance, low cost data storage products
based on the latest flash technology. The mDOC devices serve two
purposes under Linux:
(1) Main data storage device
In this role, mDOC devices serve the same purpose that
conventional hard disks serve in Linux servers or workstations -
they store various Linux kernel componenets (such as device
drivers, Linux libraries and configuration files), user
applications etc.
(2) System's boot device
All mDOC devices feature ROM area which can be programmed via
IOCTL calls to DOC driver. Boards developers usually arrange
for this ROM area to appear at CPU's reset vector, and software
developers program board-specific bootstrap code into it. When
CPU is reset, it executes this bootstrap code, and boots Linux
system entirely from mDOC device. Dedicated boot devices such as
separate ROM or NOR flash chips are no longer needed.
This document describes only the data storage function of mDOC devices.
1.3. Although mDOC devices use multi-level cell NAND flash technology
internally, DOC driver completely hides this fact from the user, and
implements traditional block device interface. This allow mDOC devices
to works with all standard disk-oriented Linux file systems (such as
EXT2, EXT3 etc.). In that respect DOC driver is similar to ATA hard
disks and CompactFlash cards, and is different from other NAND or NOR
flash devices (which must be managed by flash-specific file systems such
as JFFS2). All standard disk oriented Linux utilities (such as 'fdisk',
'du' etc.) work with mDOC devices.
1.4. DOC driver is distributed in the source code form, and is expected to
be compiled at customer's site. Instructions on how to configure and
compile DOC driver are provided in later chapters in this document.
2. Supported types of mDOC devices
==================================
2.1. This version of DOC driver supports the following types of mDOC
devices:
- mDOC H3 family
===> NOTE. This version of DOC driver will NOT work with the
following types of mDOC devices:
G3/P3 family
G4 family
H1 family
You will need to use TrueFFS driver version 7.1.0 (or higher)
with these types of mDOC devices.
3. Conventions used in this document
====================================
3.1. Term "host" is used in this document to refer to computer where DOC
driver's source code is located, and where DOC driver is compiled and
linked. Typically "hosts" are engineering workstations running RedHat
or SUSE Linux, or Windows operating systems.
Term "target" is used in this document to refer to computer where DOC
driver's executable runs, and where mDOC devices are installed. Typical
targets are mobile devices powered by ARM or XScale microprocessors,
specialized communication equipment powered by PowerPC microprocessors,
and various other embedded systems.
===> NOTE. Although usually host and target are different systems, in
some cases "host" and "target" could actually refer to the
same system. For example, it is possible to plug mDOC into
the PCI slot of PC workstation running Linux. If this
workstation contains kernel's source tree installed on it,
then it is possible to compile DOC driver, and run it on
this workstation. In this case PC workstation serves both
as host and target system.
All instructions provided by this document refer to the case when
"host" and "target" are separate systems.
3.2. Installation instructions in this document assume that user is logged
into the system as "root".
4. DOC driver's general configuration options
=============================================
4.1. Linux kernel requires that every device driver use unique major device
number. By default, DOC driver uses major device number '100'. If
you would like DOC driver to use different major device number, you
can do so by passing "tffs_major=<number>" command line option when
starting the driver. For example, to tell DOC driver to use major
device number '120':
insmod tffs.ko tffs_major=120
==> NOTE. File Documentation/devices.txt in Linux kernel's directory
list all major device numbers that had been reserved for the
various types of block devices. When specifying major device
number for DOC driver, it is essential to pick the number that
isn't listed in that file as already reserved for some other
block device. Consider using block device numbers that are
allocated for "local/experimental use" (for example, major
block device numbers in 120..127 range).
5. Board specific configuration options
=======================================
5.1. As shipped, the DOC driver should work with the following boards:
- Texas Instruments OMAP 2420 ("H4")
- Intel PXA27x Development Platform ("Mainstone")
If you are using one of these boards, you can skip remaining Sections
in Chapter 5. For all other boards, you will need to configure DOC
driver as appropriate for your system. Instructions below explain how
to do this.
5.2. User must tell DOC driver where to look for mDOC. This can be
accomplished by using "tffs_addr=<physical_address>" command line
option, where <physical_address> specifies physical address of the mDOC.
For example, if in your particular board mDOC resides at physical
address 0xc0000000, you would start DOC driver as follows:
insmod tffs.ko tffs_addr=0x00000000
Alternatively, you can set macro TFFS_PHYS_ADDR in DOC driver's header
tffsarch.h to the physical address of the mDOC, and recompile the
driver. For example, if mDOC device resides at physical address
0xc0000000, macro TFFS_PHYS_ADDR should be #defined as follows:
#define TFFS_PHYS_ADDR 0xc0000000
In this case you DOC driver by default would look for mDOC at the
specified address, so you can omit "tffs_addr=<physical_address>"
command line parameter, and start DOC driver simply as:
insmod tffs.ko
5.3. When DOC driver starts up, it calls routine tffsarch_init() to do any
board-specific hardware initialization (such as configuring Chip Select
that mDOC is connected to, allocating and configuring DMA channels and
interrupt request lines to be used by DOC driver etc.). The DOC
driver's file tffsarch.c contains example implementations of this
routine for a number of reference boards.
Users are required to implement this routine as appropriate for their
particular boards.
5.4. When DOC driver shuts down, it calls routine TffsHWRelease() to do any
board-specific hardware cleanup (such as releasing previously allocated
DMA channels and interrupt request lines etc.). The DOC driver's file
tffsarch.c contains example implementations of this routine for number
of reference boards.
Users are required to implement this routine as appropriate for their
particular boards.
6. Configuring DOC driver to use Direct Memory Access (DMA)
===========================================================
6.1. By default, DOC driver uses software loops to transfer blocks of data
to and from mDOC. In many cases it is possible to substantially improve
mDOC's 'read' performance by using DMA controler to do these data
transfers.
Current version of DOC driver includes example implementations of DMA
support for the following reference boards:
- Texas Instruments OMAP2420 ("H4")
- Intel PXA27x ("Mainstone")
These example implementations are found in DOC driver's files
tffsarch.h and tffsarch.c, and consists of the following items:
macro flReadEvenNumberOfBytes defined in tffsarch.h
macro flWriteEvenNumberOfBytes defined in tffsarch.h
routine tffs_dma_init() defined in tffsarch.c
routine tffs_dma_release() defined in tffsarch.c
routine __dmasw_bread() defined in tffsarch.c
routine __dmasw_bwrite() defined in tffsarch.c
You can use these example implementation as the starting point for DMA
implementation for your own system.
===> NOTE. Most likely you will be able to use the definitions of all
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 mDOC'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.5 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. If you are using multiple cascaded mDOC devices, edit
<top>/drivers/tffs/flcustom.h file, and uncomment the following
line there:
#define ATA_MAX_NUM_OF_DEVICES 2 /* only when using casacded devices */
8.2.3. 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.4. 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.5. 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.5 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. If you are using multiple cascaded mDOC devices, edit
<top>/drivers/tffs/flcustom.h file, and uncomment the following
line there:
#define ATA_MAX_NUM_OF_DEVICES 2 /* only when using casacded devices */
8.3.3. 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.4. Make sure that compiler (as specified by macro CC in Section 8.3.3)
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.5. 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
# 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 alternative 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'
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.
- Burst Mode with DMA is supported in the following mDoc H3 products:
SDEDX-aaab-ccc (X 5 or 7, a,b,c arbitrary numbers)
- 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.
- IPL in virtual ram mode in cascaded configuration is not supported.
- Fast area is supported on the following products:
SDEDX-aaab-ccc (X 5 or 7, a,b,c arbitrary numbers)
- IPL in paged ram mode is not supported in the following devices:
SDED5-aaab-ccc devices (a,b,c arbitrary numbers)
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 oemsupport@sandisk.com.
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.
