1This is pounder30 as of 2011-08-09.  Copyright (C) 2003-2011 IBM.
2(Do not delete top line. It is used for version checking.)
3
4It would be a good idea to read this README file and the SCHEDULER and
5CONFIGURATION files (in the doc/ directory) prior to dabbling with pounder!
6
7Licensing
8=========
9All files in this tarball are licensed under the GPL.  Please see
10the file COPYING for more details.
11
12Contents
13========
141. Overview
152. Getting Started
163. Files and Directories
174. The Install Script
185. Configuration
196. The Pounder Script
207. Credits
21
22Overview
23========
24Pounder provides a framework for building, running, and logging results
25for user-defined sets of tests.  Almost any test or test suite may be run
26as a subtest from within this framework, including the LTP test suite.
27(For more guidelines on building, scheduling, and running user-defined
28subtests, see doc/SCHEDULER)
29
30Getting Started
31===============
32
33Some sample test "schedules" comprised of various publically available
34tests, including LTP, are provided. The default test schedule illustrates
35how one might use pounder and is also a useful general purpose stress test.
36
37The following steps describe how to build and run the default schedule:
38
39	0. Install your operating system.  gcc and related development packages are
40		required to build pounder.  Missing dependencies will be identified at
41		build time. X development packages are needed for the included video test.
42
43	1. Download and unpack the LTP tarball.  You've already done this.
44
45	2. cd tools/pounder21/.  You've already done this too.
46
47	3. (optional) Set up a NFS server to export "/pounder21" (unless you wish
48		to skip nfs tests).
49
50	4. (optional) Modify any variables in "config" (see doc/CONFIGURATION for details).
51
52	5. Run "make install" to build tests for your machine
53		The Install script will attempt to build all the subtests in the
54		build_scripts folder. It will prompt you for the test scheduler
55		you want to unpack. Go ahead of type "default" or simply press
56		enter. It will then ask if you want to automate skipping of
57		failed subtests. If you enter "y", the script will automatically
58		delete any subtests from the test scheduler that fail to build.
59		If you enter "n", the script will prompt you each time a test
60		fails to build on whether or not to skip the failed test.
61
62	6. Run "./pounder" to start the tests (run "./pounder -h" for usage options).
63
64	7. Press ^C or run "./pounder -k" to stop the tests
65		The default scheduler runs tests for 48 hours, but you can set a new
66		duration in seconds by modifying config (see doc/CONFIGURATION for details)
67		or by using the -d option when starting pounder (./pounder -d <duration in seconds>)
68
69	8. Run "make mrclean" to restore everything to the state before the tarball
70		was unpacked (running this command will of course require you to
71		rebuild with "make install" for the next pounder run)
72
73See doc/SCHEDULER for details on defining the order in which tests are run, and whether they
74are run serially or in parallel.
75
76A few of the sample subtests have prerequisites:
77
78	- ide_cdrom_copy: Requires a CD with some data on it to be put in the drive.
79
80	- nfs, ping_nfs: Make sure you can mount an NFS server. Specify NFS in config
81		or run "./pounder -n ipaddr"
82
83	- xterm_stress: Make sure you can start X sessions. Enable X testing by setting
84		the DO_X_TESTS flag in config or run "./pounder -x"
85
86These tests can be skipped during the build phase if reqs aren't met though.
87
88Files and Directories
89=====================
90Below are brief descriptions of the files and directories found under the pounder/
91directory.
92
93Files:
94
95	CHANGELOG
96		- A log of changes made to pounder
97	COPYING
98		- GNU general public license info
99	Install
100		- The script used to build pounder
101	Makefile
102		- Makefile for pounder
103	debug.c
104		- Debugging routines used for logging pounder results
105	infinite_loop.c, timed_loop.c, fancy_timed_loop.c
106		- Procedures used to run tests repeatedly (see doc/SCHEDULER for more
107		information)
108	config
109		- Environment variables used for customizing pounder run are defined
110		here (see doc/CONFIGURATION for details)
111	libpounder.sh
112		- More environment variables defined here. Unlike the ones in config,
113		these are not meant to be modified by the user. (see doc/CONFIGURATION
114		for details)
115	nfs_logging
116		- Script that sets up user-defined NFS server for logging pounder output.
117		This script is executed when pounder is run with $NFS_LOGGING enabled in
118		config (see doc/CONFIGURATION) or when "pounder -r" is used. Normally when
119		running pounder, test output will be directly logged to $POUNDER_LOGLOCAL,
120		but with NFS logging enabled, output will instead be logged to user-specified
121		remote directory of an NFS server, $NFS_LOGSERVER:$NFS_LOGDIR.
122		See doc/CONFIGURATION for more information on these variables.
123	pounder
124		- Script used to run pounder. (see "The Pounder Script" section below
125		for details)
126	proclist.c
127		- Manages list of processes during pounder run.
128	README
129		- This file, which gives an overview of pounder's structure and how to
130		build and start pounder.
131	run.c
132		- Program to run the tests in the test scheduler.
133
134Directories:
135
136	build_scripts/
137		- Scripts to build your subtests go here. (see doc/SCHEDULER for details)
138	doc/
139		- Contains the SCHEDULER file, which describes how to create, build,
140		schedule, and run your own tests with pounder.
141		- Contains the CONFIGURATION file, which describes pounder's environment
142		variables.
143	schedulers/
144		- Test scheduler tarballs are in here. (see doc/SCHEDULER for details)
145	src/
146		- Sources packaged with pounder are in here.
147	test_repo/
148		- This directory is a copy of the default test scheduler. It provides an
149		example of what an test scheduler should look like after unpacking.
150	test_scripts/
151		- Scripts to run your subtests go here. (see doc/SCHEDULER for details)
152	tests/
153		- Symlinks to run the tests in a particular order. (see doc/SCHEDULER for
154		details)
155
156After running "make install," you will see three additional directories:
157
158	opt/
159		- Third party packages (LTP, kernel, etc) go here.
160	tmp/
161		- Temporary directory to hold files that a test needs.
162	log/
163		- Logs of output from pounder runs go here.
164
165Note that for the provided tests, third party test packages (bonnie, kernel, etc) aren't
166packaged with pounder. The build scripts should download them to opt/ (stored in
167$POUNDER_OPTDIR) and build them as necessary. The use of a cache might come in handy here
168(see doc/CONFIGURATION for details regarding the $POUNDER_CACHE variable).
169
170The Install Script
171==================
172The Install script has no options.  Run it to build whatever tests have been
173imported into the pounder package.
174
175Configuration
176=============
177See doc/CONFIGURATION documentation file for details.
178
179The Pounder Script
180==================
181The pounder script has the following syntax:
182
183Usage: ./pounder [-g logdir] [-x] [-d duration] [-n ipaddr] [-m max_failures] [-f] [-h|-u|-r|-k|-l|-e subtests|-i subtests|-c scheduler] [-s]
184
185-h              Brings up this menu
186-c scheduler    Creates a new test scheduler called scheduler-tests.tar.gz in the pounder/schedulers folder.
187                All subtests to be packaged with this scheduler must first be placed in the pounder/tests folder.
188-x              Enable X stress tests.
189-d duration     Run pounder for duration seconds.
190-n ipaddr       Use ipaddr for NFS tests.
191-f              Remove pounder pid file before running.
192-u              Unmount NFS log storage.
193-r              Remount NFS log storage.
194-g logdir       Use logdir as the log directory. (You probably want -s too.)
195-s              Store logs locally.
196-l              List (both included and excluded) subtests that came with the test scheduler
197-e subtests     Exclude subtests from next pounder run
198-i subtests     Include previously excluded subtests in the next pounder run
199-k              Kill pounder.
200
201run "./pounder" to run all subtests
202run "./pounder subtest" to run just one particular subtest
203        (example: ./pounder tests/T90ramp/D02build_kernel)
204
205Credits
206=======
207o Inspired by Sammy Benjamin (sammy@us.ibm.com).  None of his code remains
208  in this version of pounder today.
209o Modifications and additions by members of the LTC xSeries Kernel Team:
210    Darrick Wong (djwong@us.ibm.com)
211    Chris McDermott (lcm@us.ibm.com)
212    Jack Vogel (jfv@us.ibm.com)
213    Keith Mannthey (kmannth@us.ibm.com)
214    James Cleverdon (jamesclv@us.ibm.com)
215    Pat Gaughen (gone@us.ibm.com)
216    John Stultz (jstultz@us.ibm.com)
217    Roger Mach (bigmach@us.ibm.com)
218    Sarunya Jimenez
219    Alexis Bruemmer (alexisb@us.ibm.com)
220    James Takahashi (jmtt@us.ibm.com)
221    Pradeep Kumar (pradeepkumars@in.ibm.com)
222    Bhaskar Rangaswamy (bharanga@in.ibm.com)
223    Manikandan Chidambaram (cmanikandan@in.ibm.com)
224    Lucy Liang (lgliang@us.ibm.com)
225o Other contributers:
226
227Also utilizes:
228o memxfer5b, from IBM DeveloperWorks
229o Linux kernel's build system.
230    http://www.kernel.org
231o bonnie++
232o The Linux Test Project
233o Doug Ledford's (of RH) memtest script
234o lame, for MMX/SSE/SSE2/3dnow testing
235o nasm, to build lame
236o schedutils, to test CPU affinity (with lame)
237
238(note that the above packages are not distributed with pounder
239 and are simply installed by the installer script)
240