
INSTRUCTIONS FOR ENDURANCE MEASUREMENTS
=======================================

Collecting the endurance measurements
-------------------------------------

- pre-requirement:
  - Kernel with SMAPS enabled and normal POSIX tools
    (like Maemo and about all normal Linux distributions)
  - sp-endurance package and its dependencies installed

1. Clean syslog (as root), e.g. with:
   * If you have normal syslog:
     echo "" > /var/log/syslog.old
     echo "" > /var/log/syslog
2. Reboot the device
3. If DISPLAY is not set, set it (needed for xmeminfo run by the script):
     export DISPLAY=:0
4. Then run the following before first test round:
     save-incremental-endurance-stats usecase
  -> This will save data files under "usecase/XXX/" directory.
     Each time it's called, XXX increases (it starts from 100)
5. Repeat step 4) after each test round.
   Note: if you're going to do this many times for use-cases which
   write a lot of data to syslog, you might clean the syslog also
   after step 4)

With the "endurance-mem-overview" script one can quickly check from
the collected data whether there were (already) large differencies
in the whole system memory usage.  This way only individual process
leakage and the leakage of other (less frequently leaked) resources
needs to be investigated with the full post-processing tools.


Post-processing / visualizing the endurance data
------------------------------------------------

- Pre-requirements:
  - sp-endurance-postproc package and its dependencies isntalled
  - the contents of the "usecase" directory (collected endurance data)

1. Run:
     parse-endurance-measurements --report use-case-name usecase/[0-9]*

This will produce:
- the "use-case-name.html" file
- reports about errors extracted from the syslog

If you want also details memory usage information from the
applications, give additional --parse-smaps argument to the script.
This will require sp-smaps-visualize package. Or just read the
smaps.cap.gz files directly (extract-endurance-process-smaps
extracts just the given process information from all rounds).


Files coming from the source package
------------------------------------

Files for the endurance data collection:
- measure/save-incremental-endurance-stats
  - saves all the measurement data under the given directory
    using the tools below, date, df, sp_smaps_snapshot etc
- measure/proc2csv
  - binary required by save-incremental-endurance-stats script
  - outputs contents of /proc/ files as CSV data
- measure/xmeminfo
  - binary required by save-incremental-endurance-stats script
  - outputs X clients resource usage from the X server as CSV data
- endurance-mem-overview
  - show ASCII chart of system memory usage from the already
    collected endurance data

Files for the data post-processing:
- postproc/parse-endurance-measurements
  - runs endurance_report.py with suitable options
- postproc/endurance_report.py
  - post-processes data files saved by save-incremental-endurance-stats script
- postproc/syslog_parse.py
  - used by endurance_report.py
  - script for digging out known types of problems from syslogs
- postproc/split-endurance-measurements
  - script for making several reports out of given data files
    (e.g. if device has booted in middle of testing, that invalidates
    the memory changes, so you want a separate report after that)
- postproc/extract-endurance-process-smaps
  - script for extracting just the given process SMAPS information
    from all the endurance rounds for comparising (diff -u ...)

Other files:
- README
  - this file
- src/proc2csv.c
  - source code for proc2csv
- src/xmeminfo.c
  - source code for xmeminfo
- Makefile
  - compiles the above source files and installs them
- man/
  - manual pages for all binaries and scripts
