This is pounder30 as of 2011-08-09. Copyright (C) 2003-2011 IBM. (Do not delete top line. It is used for version checking.) It would be a good idea to read this README file and the SCHEDULER and CONFIGURATION files (in the doc/ directory) prior to dabbling with pounder! Licensing ========= All files in this tarball are licensed under the GPL. Please see the file COPYING for more details. Contents ======== 1. Overview 2. Getting Started 3. Files and Directories 4. The Install Script 5. Configuration 6. The Pounder Script 7. Credits Overview ======== Pounder provides a framework for building, running, and logging results for user-defined sets of tests. Almost any test or test suite may be run as a subtest from within this framework, including the LTP test suite. (For more guidelines on building, scheduling, and running user-defined subtests, see doc/SCHEDULER) Getting Started =============== Some sample test "schedules" comprised of various publically available tests, including LTP, are provided. The default test schedule illustrates how one might use pounder and is also a useful general purpose stress test. The following steps describe how to build and run the default schedule: 0. Install your operating system. gcc and related development packages are required to build pounder. Missing dependencies will be identified at build time. X development packages are needed for the included video test. 1. Download and unpack the LTP tarball. You've already done this. 2. cd tools/pounder21/. You've already done this too. 3. (optional) Set up a NFS server to export "/pounder21" (unless you wish to skip nfs tests). 4. (optional) Modify any variables in "config" (see doc/CONFIGURATION for details). 5. Run "make install" to build tests for your machine The Install script will attempt to build all the subtests in the build_scripts folder. It will prompt you for the test scheduler you want to unpack. Go ahead of type "default" or simply press enter. It will then ask if you want to automate skipping of failed subtests. If you enter "y", the script will automatically delete any subtests from the test scheduler that fail to build. If you enter "n", the script will prompt you each time a test fails to build on whether or not to skip the failed test. 6. Run "./pounder" to start the tests (run "./pounder -h" for usage options). 7. Press ^C or run "./pounder -k" to stop the tests The default scheduler runs tests for 48 hours, but you can set a new duration in seconds by modifying config (see doc/CONFIGURATION for details) or by using the -d option when starting pounder (./pounder -d ) 8. Run "make mrclean" to restore everything to the state before the tarball was unpacked (running this command will of course require you to rebuild with "make install" for the next pounder run) See doc/SCHEDULER for details on defining the order in which tests are run, and whether they are run serially or in parallel. A few of the sample subtests have prerequisites: - ide_cdrom_copy: Requires a CD with some data on it to be put in the drive. - nfs, ping_nfs: Make sure you can mount an NFS server. Specify NFS in config or run "./pounder -n ipaddr" - xterm_stress: Make sure you can start X sessions. Enable X testing by setting the DO_X_TESTS flag in config or run "./pounder -x" These tests can be skipped during the build phase if reqs aren't met though. Files and Directories ===================== Below are brief descriptions of the files and directories found under the pounder/ directory. Files: CHANGELOG - A log of changes made to pounder COPYING - GNU general public license info Install - The script used to build pounder Makefile - Makefile for pounder debug.c - Debugging routines used for logging pounder results infinite_loop.c, timed_loop.c, fancy_timed_loop.c - Procedures used to run tests repeatedly (see doc/SCHEDULER for more information) config - Environment variables used for customizing pounder run are defined here (see doc/CONFIGURATION for details) libpounder.sh - More environment variables defined here. Unlike the ones in config, these are not meant to be modified by the user. (see doc/CONFIGURATION for details) nfs_logging - Script that sets up user-defined NFS server for logging pounder output. This script is executed when pounder is run with $NFS_LOGGING enabled in config (see doc/CONFIGURATION) or when "pounder -r" is used. Normally when running pounder, test output will be directly logged to $POUNDER_LOGLOCAL, but with NFS logging enabled, output will instead be logged to user-specified remote directory of an NFS server, $NFS_LOGSERVER:$NFS_LOGDIR. See doc/CONFIGURATION for more information on these variables. pounder - Script used to run pounder. (see "The Pounder Script" section below for details) proclist.c - Manages list of processes during pounder run. README - This file, which gives an overview of pounder's structure and how to build and start pounder. run.c - Program to run the tests in the test scheduler. Directories: build_scripts/ - Scripts to build your subtests go here. (see doc/SCHEDULER for details) doc/ - Contains the SCHEDULER file, which describes how to create, build, schedule, and run your own tests with pounder. - Contains the CONFIGURATION file, which describes pounder's environment variables. schedulers/ - Test scheduler tarballs are in here. (see doc/SCHEDULER for details) src/ - Sources packaged with pounder are in here. test_repo/ - This directory is a copy of the default test scheduler. It provides an example of what an test scheduler should look like after unpacking. test_scripts/ - Scripts to run your subtests go here. (see doc/SCHEDULER for details) tests/ - Symlinks to run the tests in a particular order. (see doc/SCHEDULER for details) After running "make install," you will see three additional directories: opt/ - Third party packages (LTP, kernel, etc) go here. tmp/ - Temporary directory to hold files that a test needs. log/ - Logs of output from pounder runs go here. Note that for the provided tests, third party test packages (bonnie, kernel, etc) aren't packaged with pounder. The build scripts should download them to opt/ (stored in $POUNDER_OPTDIR) and build them as necessary. The use of a cache might come in handy here (see doc/CONFIGURATION for details regarding the $POUNDER_CACHE variable). The Install Script ================== The Install script has no options. Run it to build whatever tests have been imported into the pounder package. Configuration ============= See doc/CONFIGURATION documentation file for details. The Pounder Script ================== The pounder script has the following syntax: Usage: ./pounder [-g logdir] [-x] [-d duration] [-n ipaddr] [-m max_failures] [-f] [-h|-u|-r|-k|-l|-e subtests|-i subtests|-c scheduler] [-s] -h Brings up this menu -c scheduler Creates a new test scheduler called scheduler-tests.tar.gz in the pounder/schedulers folder. All subtests to be packaged with this scheduler must first be placed in the pounder/tests folder. -x Enable X stress tests. -d duration Run pounder for duration seconds. -n ipaddr Use ipaddr for NFS tests. -f Remove pounder pid file before running. -u Unmount NFS log storage. -r Remount NFS log storage. -g logdir Use logdir as the log directory. (You probably want -s too.) -s Store logs locally. -l List (both included and excluded) subtests that came with the test scheduler -e subtests Exclude subtests from next pounder run -i subtests Include previously excluded subtests in the next pounder run -k Kill pounder. run "./pounder" to run all subtests run "./pounder subtest" to run just one particular subtest (example: ./pounder tests/T90ramp/D02build_kernel) Credits ======= o Inspired by Sammy Benjamin (sammy@us.ibm.com). None of his code remains in this version of pounder today. o Modifications and additions by members of the LTC xSeries Kernel Team: Darrick Wong (djwong@us.ibm.com) Chris McDermott (lcm@us.ibm.com) Jack Vogel (jfv@us.ibm.com) Keith Mannthey (kmannth@us.ibm.com) James Cleverdon (jamesclv@us.ibm.com) Pat Gaughen (gone@us.ibm.com) John Stultz (jstultz@us.ibm.com) Roger Mach (bigmach@us.ibm.com) Sarunya Jimenez Alexis Bruemmer (alexisb@us.ibm.com) James Takahashi (jmtt@us.ibm.com) Pradeep Kumar (pradeepkumars@in.ibm.com) Bhaskar Rangaswamy (bharanga@in.ibm.com) Manikandan Chidambaram (cmanikandan@in.ibm.com) Lucy Liang (lgliang@us.ibm.com) o Other contributers: Also utilizes: o memxfer5b, from IBM DeveloperWorks o Linux kernel's build system. http://www.kernel.org o bonnie++ o The Linux Test Project o Doug Ledford's (of RH) memtest script o lame, for MMX/SSE/SSE2/3dnow testing o nasm, to build lame o schedutils, to test CPU affinity (with lame) (note that the above packages are not distributed with pounder and are simply installed by the installer script)