1 files changed, 197 insertions, 0 deletions
diff --git a/tests/jittertest/README b/tests/jittertest/README
new file mode 100644
index 0000000..f411a2c
--- /dev/null
+++ b/tests/jittertest/README
@@ -0,0 +1,197 @@
+$Id: README,v 1.2 2001/08/10 19:23:11 vipin Exp $
+
+This is the README file for the JitterTest (and friends)
+program.
+
+This program is used to measure what the jitter of a
+real time task would be under "standard" Linux.
+
+More particularly, what is the effect of running
+a real time task under Linux with background
+JFFS file system activity.
+
+The jitter is measured in milli seconds (ms) from
+the expected time of arrival of a signal from a 
+periodic timer (set by the task) to when the
+task actually gets the signal.
+
+This jitter is then stored in a file specified
+(or the default output file "jitter.dat").
+
+The data  may also be sent out to the console by
+writing to /dev/console (See help options. This is
+highly desirable specially if you have redirected 
+your console to the serial port and are storing it
+as a minicom log on another computer for later analysis
+using some tools provided here).
+
+This is particularly useful if you have a serial
+console and are outputting "interesting" info
+from inside some kernel task or driver.
+(or something as simple as a "df" program running
+periodically and redirecting o/p to the console).
+
+One "interesting" thing that I have measured
+is the effect of FLASH chip erases on the jitter
+of a real time task.
+
+One can do that by putting a printk at the
+beginning of the flash erase routine in the MTD
+flash chip driver.
+
+Now you will get jitter data interspersed with
+flash sector erase events. Other printk's can also
+be placed at suspected jitter causing locations in
+the system.
+
+
+
+EXECUTING THE PROGRAM "JitterTest"
+
+You may specify a file to be read by the
+program every time it wakes up (every cycle).
+This file is created and filled with some junk
+data. The purpose of this is to test the jitter
+of the program if it were reading from- say
+a JFFS (Journaling Flash File System) file system.
+
+By specifying the complete paths of the read and write
+(o/p) files you can test the jitter a POSIX type
+real time task will experience under Linux, under
+various conditions.
+
+These can be as follows:
+
+1. O/P file on ram file system, no i/p file.
+
+ In this case you would presumably generate other
+"typical" background activity for your system and
+examine the worst case jitter experienced by
+a task that is neither reading nor writing to
+a file system.
+
+Other cases could be:
+
+2. O/P to ram fs, I/P from JFFS (type) fs:
+
+ This is specially useful to test the proper
+operation of erase suspend type of operation
+in JFFS file systems (with an MTD layer that
+supports it).
+
+  In this test you would generate some background
+write/erase type activity that would generate
+chip erases. Since this program is reading from
+the same file system, you contrast the latencies 
+with those obtained with writes going to the same
+fs.
+
+3. Both read and writes to (or just write to) JFFS
+file system:
+
+  Here you would test for latencies experienced by
+a program if it were writing (and optionally also 
+reading) from a JFFS fs.
+
+
+
+
+Grabing a kernel profile:
+
+This program can also conditionally grab a kernel profile.
+Specify --grab_kprofile on the cmd line as well as 
+a "threshold" parameter (see help options by -?).
+
+Any jitter greater than this "threshold" will cause the
+program to read the /proc/profile file and dump it in
+a local file with increasing file numbers. It will also
+output the filename at that time to the console file specified.
+This will allow you to corelate later in time the various profiles
+with data in your console file and what was going on at that time.
+
+These profile files may then be later examined by running them through
+ksymoops.
+
+Make sure you specify "profile=2" on the kernel command line
+when you boot the kernel if you want to use this functionality.
+
+
+
+Signalling the JFFS[2] GC task:
+
+You can also force this program to send a SIGSTOP/SIGCONT to the 
+JFFS (or JFFS2) gc task by specifing --siggc <pid> on the cmd line.
+
+This will let you investigate the effect of forcing the gc task to 
+wake up and do its thing when you are not writing to the fs and to
+force it to sleep when you want to write to the fs.
+
+These are just various tools to investigate the possibility of
+achieving minimal read/write latency when using JFFS[2].
+
+You need to manually do a "ps aux" and look up the PID of the gc
+thread and provide it to the program. 
+
+
+
+
+EXECUTING THE PROGRAM "plotJittervsFill"
+
+This program is a post processing tool that will extract the jitter
+times as printed by the JitterTest program in its console log file
+as well as the data printed by the "df" command.
+
+This "df" data happens to be in the console log because you will
+run the shell file fillJffs2.sh on a console when you are doing
+your jitter test.
+
+This shell script copies a specified file to another specified file
+every programmable seconds. It also does a "df" and redirects output
+to /dev/console where it is mixed with the output from JitterTest.
+
+All this console data is stored on another computer, as all this data
+is being outputted to the serial port as you have redirected the console
+to the serial port (that is the only guaranteed way to not loose any
+console log or printk data).
+
+You can then run this saved console log through this program and it
+will output a very nice text file with the %fill in one col and
+corrosponding jitter values in the second. gnuplot then does a 
+beautifull plot of this resulting file showing you graphically the
+jitters encountered at different fill % of your JFFS[2] fs.
+
+
+
+OTHER COMMENTS:
+
+Use the "-w BYTES" cmd line parameter to simulate your test case.
+Not everyone has the same requirements. Someone may want to measure
+the jitter of JFFS2 with 500 bytes being written every 500ms. Others
+may want to measure the system performance writing 2048 bytes every
+5 seconds.
+
+RUNNING MULTIPLE INSTANCES:
+
+Things get real interesting when you run multiple instances of this
+program *at the same time*.
+
+You could have one version running as a real time task (by specifing
+the priority with the -p cmd line parameter), not interacting with
+any fs or at the very least not reading and writing to JFFS[2].
+
+At the same time you could have another version running as a regular
+task (by not specifing any priority) but reading and writing to JFFS[2].
+
+This way you can easily measure the blocking performance of the real time
+task while another non-real time task interacts with JFFS[2] in the back ground.
+
+You get the idea.
+
+
+WATCH OUT!
+
+Be particularly careful of running this program as a real time task AND
+writing to JFFS[2]. Any blocks will cause your whole system to block till
+any garbage collect initiated by writes by this task complete. I have measured
+these blocks to be of the order of 40-50 seconds on a reasonably powerful
+32 bit embedded system.