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