Cross Reference: /test/stcnv/usr/src/suites/os/cpu-caps/README

#
# CDDL HEADER START
#
# The contents of this file are subject to the terms of the
# Common Development and Distribution License (the "License").
# You may not use this file except in compliance with the License.
#
# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
# or http://www.opensolaris.org/os/licensing.
# See the License for the specific language governing permissions
# and limitations under the License.
#
# When distributing Covered Code, include this CDDL HEADER in each
# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
# If applicable, add the following below this CDDL HEADER, with the
# fields enclosed by brackets "[]" replaced with your own identifying
# information: Portions Copyright [yyyy] [name of copyright owner]
#
# CDDL HEADER END
#

#
# Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#
# ident	"@(#)README	1.2	09/01/29 SMI"
#

DESCRIPTION
===========

This suite verifies the functionality of the CPU caps resource control
technology.  CPU caps enable the administrator to restrict the amount of CPU
consumption at the zone or project level and are made effective via prctl(1),
zonecfg(1M), or via the project(4) file.  CPU caps will work for all scheduling
classes with the exception of the realtime class.  Process running in the RT
class are not subject to CPU caps. CPU caps may be used in conjunction with
the cpu-shares resource control, but caps will take precedence.  Also, zone caps
will take precedence over any project cap in the zone.

Some of the tests examine the behavior of processes under a zone cap.  As a
result, any CPU activity in the zone (global or non-global) counts against the
zone cap.   Measures have been made to mitigate this as much as possible, but
clearly the test suite and its processes can't run in a vaccuum. The stress
tests require some human intelligence when interpreting the ouptut so they must
be run manually.  In short, failures may occur due to the statistical nature of
these tests.  The stress tests have been omitted from the "all" category and
won't be in run in ONPIT as they have this higher propensity for false failure.
Typically, a false failure can be seen in a verbose journal file and is
is characterized by temporary drops in CPU usage which leads to either a high
standard deviation or an artificially low mean CPU usage for the given process.
If this takes place, it's recommended to verify no CPU-intesive processes exist
in the zone, via prstat -m, and re-run the test.

As a final note, the fewer CPUs a system has, the higher the likelihood of
failure for those tests in the stress category.  This is due to the increased
competition for CPU cycles.


SYSTEM REQUIREMENTS
===================

Due to the statistical nature of the bulk of these tests, a processor set is
required.  Therefore, this test will only run a system with at least two CPUs.

This test should be run on a system with at least snv_61 or S10U5 installed.
For local zones testing, the system should also be able to support zones.
This suite should not be executed in a local zone as the suite creates its own
local zone for non-global zone testing.  The local zone installed will use
/export/test_zone as its root directory and upon test suite completion, should
clean up after itself.  Any changes to /etc/project should also be removed.


TEST SUITE INSTALLATION
=======================

As root user perform the following to install the tetlite and cpu-caps test
suite packages in /opt:

	# pkgadd -d <package location> SUNWstc-dtet
	# pkgadd -d <package location> SUNWstc-os-cpu-caps


TEST SUITE EXECUTION
====================

The test suite makes use of the TET test harness.  The following steps will
execute the test suite and provide a log in /var/tmp/results.<tet PID>.  The
summary provided at the end of the suite execution will provide the actual
logfile location.

1.  Switch to root user and clear the environment variables:

	$ su -

2.  Export the following environment variables:

	$ export TET_ROOT=/opt/SUNWstc-tetlite
	$ export CTI_ROOT=${TET_ROOT}/contrib/ctitools
	$ export TET_SUITE_ROOT=/opt/SUNWstc-os-cpu-caps
	$ export PATH=$TET_ROOT/bin:$CTI_ROOT/bin:$PATH

3.  Change directory to the cpu-caps root directory:

	$ cd $TET_SUITE_ROOT

4.  The following execution options are available:

	$ run_test cpu-caps all			[ all functional tests ]
	$ run_test cpu-caps global_zn		[ global zone tests ]
	$ run_test cpu-caps real_time		[ real-time tests ]
	$ run_test cpu-caps non_global_zn	[ non-global zone tests ]
	$ run_test cpu-caps kstats		[ kstat tests ]
	$ run_test cpu-caps stress		[ stress tests ]
	$ run_test cpu-caps wad			[ all tests ]

run_test may also be executed with "-v verbose=true" for more verbose output.
If it's desired to redirect the output of the logfile to standard out, execute
run_test with the "-j -" option. For example:

	$ run_test -v verbose=true cpu-caps all
	$ run_test -j - cpu-caps global_zn
	$ run_test -v verbose=true cpu-caps kstats

The lowest level entity that can be executed is the "invocable component" as
defined in each test case file ("tc_*").  For example, if it is desired to
only run test purposes 1 and 3 (tp_001 and tp_003) in the global tests, use
the following command:

	$ run_test cpu-caps global_zn:1,3


TEST SUITE BUILDING
===================

The test suite build should not be done as root user.

1.  Export the following environment variables:
    (Note. TET_SUITE_ROOT is set to the source path)

	$ export TET_ROOT=/opt/SUNWstc-tetlite
	$ export CTI_ROOT=${TET_ROOT}/contrib/ctitools
	$ export TET_SUITE_ROOT=<local directory>/usr/src/suites/os
	$ export PATH=$TET_ROOT/bin:$CTI_ROOT/bin:$PATH

2.  Change directory to the cpu-caps root directory:

	$ cd $TET_SUITE_ROOT/cpu-caps

3.  Clear out any old bits and build new package:

	$ /usr/ccs/bin/make clobber
	$ /usr/ccs/bin/make package