flashbench: add README file
This adds a little introductory file describing
how to use flashbench. Needs more text still.
Signed-off-by: Arnd Bergmann <arnd@arndb.de>
diff --git a/README b/README
new file mode 100644
index 0000000..775f03d
--- /dev/null
+++ b/README
@@ -0,0 +1,86 @@
+= flashbench -- identify characteristics of flash media =
+
+This is the tool used to identify the properties of
+SD cards and other media for the Linaro flash memory
+survey at [1]. The latest version should be available
+at [2]. Please also check out the article on lwn.net [3].
+
+A short introduction to the most useful commands follows.
+
+== Guess erase block and page sizes ==
+
+''flashbench -a <device>''
+
+This is a simple read-only test doing small reads
+across boundaries of various sizes. Example:
+
+$ sudo ./flashbench -a /dev/mmcblk0 --blocksize=1024
+align 134217728 pre 735µs on 1.08ms post 780µs diff 324µs
+align 67108864 pre 736µs on 1.05ms post 763µs diff 300µs
+align 33554432 pre 722µs on 1.04ms post 763µs diff 294µs
+align 16777216 pre 727µs on 1.05ms post 772µs diff 302µs
+align 8388608 pre 724µs on 1.04ms post 768µs diff 299µs
+align 4194304 pre 741µs on 1.08ms post 788µs diff 317µs
+align 2097152 pre 745µs on 950µs post 811µs diff 171µs
+align 1048576 pre 745µs on 945µs post 807µs diff 169µs
+align 524288 pre 743µs on 936µs post 799µs diff 165µs
+align 262144 pre 746µs on 948µs post 809µs diff 171µs
+align 131072 pre 737µs on 935µs post 804µs diff 165µs
+align 65536 pre 735µs on 925µs post 796µs diff 159µs
+align 32768 pre 735µs on 925µs post 800µs diff 157µs
+align 16384 pre 745µs on 911µs post 781µs diff 148µs
+align 8192 pre 785µs on 808µs post 725µs diff 53.3µs
+align 4096 pre 784µs on 788µs post 779µs diff 5.85µs
+align 2048 pre 787µs on 793µs post 789µs diff 4.65µs
+
+This shows the access times to do two 1024 byte reads around
+the boundaries of power-of-two aligned blocks. Reading at
+the end of a 128 MB unit takes around 735 microseconds, reading x
+the last block of this unit together with the first block of
+the next one takes about 1080 microseconds and reading the first
+two blocks in a 128 MB unit takes around 780 microseconds.
+
+The most interesting number here is the last one, the difference
+between the second number and the average of the first and the third
+is 324 microseconds. These numbers all stay roughly the same for
+all units between 4 MB and 128 MB.
+
+However, from 2 MB down to 16 KB, the last column has a much lower
+value. This indicates that whatever the memory card does on a 4 MB
+boundary does not happen at other boundaries. The educated guess
+here is that 4 MB is the erase block size, also called the segment
+or allocation unit size. This erase blocksize will need to be
+used in other tests following this one.
+
+Similarly, both 16 KB and 8 KB boundaries are special. The logical
+explanation for this is that the card has 8 KB pages, but can use
+multi-plane accesses to read two 8 KB pages simultaneously.
+
+Some cards only show a clear pattern using accesses with certain
+block sizes, other cards do not show any pattern, which means
+that the numbers need to be determined differently.
+
+Also, cards that were never fully written may show a different
+behaviour because access times on pre-erased segments are different
+from those that have been written.
+
+== Create a scatter plot of access times ==
+
+''flashbench -s <device> --scatter-order=<n> --scatter-span=<m> -o <file>''
+
+Writes a scatter plot into a file that can be used as input
+for a ''gnuplot -p -e 'plot "file"' ''
+
+== References ==
+
+[1] https://wiki.linaro.org/WorkingGroups/KernelConsolidation/Projects/FlashCardSurvey
+[2] git clone git://git.linaro.org/people/arnd/flashbench.git
+[3] http://lwn.net/Articles/428XXX FIXME
+
+Feel free to reach the author by email for any questions
+about the latest version, Arnd Bergmann <arnd.bergmann@linaro.org>,
+or use the linaro-dev@lists.linaro.org mailing list for discussions.
+
+If you use this tool to measure memory cards, USB sticks
+or SSDs and get useful results, please share them
+at flashbench-results@lists.linaro.org.
