README
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