xref: /test/ontest-stc2/src/tools/tet/contrib/ctitools/README

#
# Copyright 2007 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#
# ident	"@(#)README	1.5	07/08/15 SMI"
#

#
# This is free software; you can redistribute it and/or modify it
# under the terms of the "Artistic License" which is located in 
# the file named "Artistic" which is included with this software.
#

===============================================================================

Common Test Infrastructure (CTI) for Test Environment Toolkit (TET)

CTI for TET is a common set of tools, utilities and application interfaces
which support TET test development and execution.

===============================================================================

CTI Directory Structure 

Makefiles - contains the standard Makefiles that can be used with test suites
to define most of the building process when using make.

bin - compiled binary and shell standalone executable utilities.

examples - example test suites provided to show the use of the CTI interfaces
and CTI command line execution.

include - CTI header files that are to be included in code.

lib - compiled and shell script libraries that are linked or sourced into test
scripts to gain access to the CTI API.

src/defines - Solaris define files used to identify newer versions of Solaris.

src/lib - source code for the libraries that are built into the above lib
directory.

src/utils - the CTI command line utility and it's associated tools.  As well
as the build, clean and exec tools, the kmodtool interface and setuid programs
for root and user test suite execution.

src/scripts - tools to assist in the building and packaging of CTI for TET.

===============================================================================

bin/run_test.ksh (src/utils/run_test.ksh)

The run_test wrapper is used to execute test suites and passes the 
configuration program the following arguments:

        -F  : Configuration parameter file (name=value pairs)
	-S  : Do the setup only
	-E  : Do the execute only using the prior setup
	-C  : Do the cleanup only for the prior setup
	-L  : Log directory
	-R  : List of remote machines (only for distributed test)
	-I  : Ignore html/sorted_result creation
	-j  : Journal file (-j - goes to stdout)
	-s  : scenario file (tcc option)
	-x  : execute mode config file (tcc option)

	Following tcc options are passed directly to the 'tcc' command
	without being processed by run_test :
		b, c, e, i, f , g, I, l, n, t, v, y

===============================================================================

src/scripts/build_tet.ksh

The build_tet.ksh script will build the TET-Lite and Distributed TET versions
of TET along with the CTI software under $TET_ROOT. If the $CODEMGR_WS 
environment variable is set, the built code will also be copied to 
$CODEMGR_WS/proto and be ready for package generation. The 
/src/scripts/solpatch.ksh script is used by build_tet.ksh to patch TET so 
newer versions of Solaris are identified during the build process.

	Usage: build_tet.ksh <mode>

	Where <mode> is one of the following arguments :
		lite - to build TET Lite
		inet - to build Distributed TET

/src/scripts/build_tet_pkg.pl

The build_tet_pkg.pl script creates TET-Lite or Distributed TET packages from
the built code in $CODEMGR_WS/proto and stores the packages (SUNWstc-tetlite or
SUNWstc-dtet) in the $CODEMGR_WS/packages directory.

	Usage: build_tet_pkg.pl [-p <pkgdef_dir>] [-P <proto_dir>]
		[-s pkg_spool_dir] mode

	Where mode is one of the following arguments :
		lite - to build the lite packages (SUNWtetlite)
		inet - to build the distributed tet packages (SUNWdtet)

Example:

% setenv CODEMGR_WS /test/ws
% setenv TET_ROOT $CODEMGR_WS/src/tools/tet
% cd $TET_ROOT/contrib/ctitools/src/scripts
% build_tet.ksh inet
% build_tet_pkg.pl inet

The build and package scripts need to be run on sparc and i386 build servers
to produce sparc and i386 packages.  32-bit sparc, 64-bit sparcv9, 32-bit i386
and 64-bit amd64 binaries are produced. Four runs are required to produce all
combinations of sparc, i386, TET-Lite and Distributed TET packages.

===============================================================================

bin/build_suite_pkg (utils/build_suite_pkg.pl)

The build_suite_pkg.pl script uses the standard Makefiles with the package
directive to build a package of the current test suite. Script execution can
be modified by supplying custom packaging files and information. This script
can also remove the package with -R suitename.

	Usage:	build_suite_pkg.pl [ -p <pkgdef_dir>] [ -P <proto_dir>]
		[ -s <pkg_spool_dir> ] <-R | -S> suitedir

		suitedir - The location of the compiled test suite.

	This compilation is done with the standard makefiles by using
	the 'package' directive, e.g :
	
		$ /usr/ccs/bin/make package

	To remove the package, e.g :

		$ /usr/ccs/bin/make unpackage

===============================================================================

Supported development CTI libraries (languages) :

CTI support libraries are written for ksh, C, Perl and java.

The ksh files to be sourced in are :

	lib/ctiutils.ksh - Common tetlite CTI API interfaces.
	lib/ctidutils.ksh - Distributed CTI API interfaces.

The C libraries are :

	lib/libCommonTest.so - Common tetlite and distributed interfaces
		depending on packages installed.
	lib/libCommonTest_s.so - Provides a modified cti_delete() and 
		cti_deleteall() functions that use shared variables
		with the TET libraries.
	lib/libCommonTest_script.so - Shell script like helpers for C
	lib/libCommonTest_thr.so - Threaded CTI interfaces.

The Perl files to be soureced in are:

	lib/ctiutils.pl - Common tetlite CTI API interfaces.

The jave library :

	lib/CommonTest.jar - Common tetlite and distributed interfaces
		depending on packages installed.

===============================================================================

bin/build_tool  (Source - src/utils/build_tool.ksh)
bin/clean_tool  (Source - src/utils/clean_tool.ksh)

The build_tool and clean_tool scripts can be used as TCC build and clean tools 
(respectively) to support options in scenario test case names. Both scripts
perform shell variable expansion.

bin/exec_tool	(Source - src/utils/exec_tool.ksh)

The exec_tool supports two options: su and kmod.  The "su" option allows a test
case to be run with an arbitary UID, for example:

        /foo/bar/tc1:su=root{3-5}
        /foo/bar/tc2:su=uucp

The "kmod" or "kernel" option specifies that the test case is a kernel module.
This enhancement provides facilities for TET test cases to be written and run 
directly in the kernel, for example:

        /foo/bar/tc3:kmod{1,4-7,10}

The build and clean tools are simple scripts that basically strip out the above
options from scenario test case names such that the usual TCC build and clean
tools such as make can still be used.

For more detailed information, please read the comments at the top of each
script.

NOTE: these scripts are available in the $CTI_ROOT/bin directory.

===============================================================================

lib/[amd64|sparcv9]/libkmodapi.a	(Source - src/lib/C/kmodapi.c)
bin/kmodtool				(Source - src/utils/kmodtool.c)

Include Files

include/kmod_support.h
include/tet_kmodapi.h

The kmodtool and libkmodapi.a library provide support for TET kernel test 
cases.
Kernel test cases look very similar to TET user-level test cases.  They can 
call (some) TET APIs and thus use facilities provided by TET.  These test 
cases are kernel modules which run directly in the kernel, and they can be 
specified in the same scenarios as user-level test cases.

The file src/lib/kmodapi.c contains the source for some TET APIs available in
the kernel.  Not all TET C routines are available in the kernel.  Some of them
like tet_fork() are not provided simply because they don't make sense in the 
kernel.

Kernel test cases must include the header file <tet_kmodapi.h> (as opposed to
the standard <tet_api.h>) which is available in $CTI_ROOT/include directory.
They must also be linked with the archive library likmodapi.a (as opposed to
the standard libapi.a) located in $CTI_ROOT/lib.

The file kmodtool.c is a "fake" user-level test case which acts as a
proxy agent for kernel test case.  To run a kernel test case, you must use
the $CTI_ROOT/bin/exec_tool script as the TCC exec tool.  This can be done 
by adding an entry such as :

	TET_EXEC_TOOL=${TET_ROOT}/contrib/ctitools/bin/exec_tool

in tetexec.cfg.  You must also specify the TET_SU_TOOL and TET_KMOD_TOOL
configuration variables, e.g.:

	TET_SU_TOOL=${TET_ROOT}/contrib/ctitools/bin/sutool
	TET_KMOD_TOOL=${TET_ROOT}/contrib/ctitools/bin/kmodtool

The sutool utility is needed because kmodtool needs to run as root to modload 
the kernel test case.

When the exec_tool encounters a scenario test case name such as

	/foo/bar/mytestcase:kmod

which has the "kmod" or "kernel" option set, it calls on the sutool utility
to start the user-level kmodtool test case as root, passing in the path
to the kernel test case as argument.  In turn, kmodtool creates a Solaris door
server and then modloads the kernel test case.  During the initialization
phase, the kernel test case sets up a kernel door server and then contacts
kmodtool via kmodtool's door.  Thus these two doors provide a two-way
communication channel between the kernel test case and kmodtool.

kmodtool acts as proxy agent for the kernel test case because to the TET Test
Case Manager (TCM) the user-level kmodtool is the test case that it is actually
running.  When the TCM executes a test purpose function inside kmodtool, this
function then forwards the request, via the door, to the test case in the 
kernel.
When the call reaches the kernel door server, it in turn calls the actual test
purpose routine in the kernel test case. Conversely, when the kernel test case
calls a kernel TET API (kmodapi.c), the routine forwards the request up to
kmodtool's door server in userland. kmodtool's door server in turn calls the
actual TET API on behalf of the kernel test case.

This allows you to write test cases that run directly in the kernel and yet
still use many of TET's facilities, such as calling tet_getvar() from
inside the kernel to get configuration variables specified in tetexec.cfg,
or running a distributed kernel test on several remote machines with remote
parts doing synchronization and communication among each other.  And the
same scenario processing facility also applies to kernel tests.  For example,
it's possible to do this

	:parallel,20:
	/foo/bar/tc1:kernel
	:endparallel:

which runs 20 instances of the tc1 kernel test case in parallel (this of course
means that all 20 instances of tc1 run within the same address space, which
means tc1 has to be written in such a way that these instances don't interfere
with each other when accessing global kernel resources).  And kernel test cases
can be mixed and matched with userland test cases, for example:

	:timed_loop,3600:
	  :distributed,1-4,7:
	    :random:
	      /foo/bar/user-tc{3,5,7}
	      /foo/bar/kernel-tc:kmod{1-3}
	    :endrandom:
	  :enddistributed:
	:endtimed_loop:

As mentioned previously, not all TET functions are available in the kernel.
Some like tet_fork() are not provided because they don't make sense in the
kernel.  While some have slightly different interfaces from the actual TET
version.  In particular those that return an allocated buffer such as
tet_getvar() and tet_remgetlist().  For these routines, you must pass a
buffer that you allocate yourself prior to the call.  This requirement was made
to help remind callers to deallocate those buffers when they are done and
to minimize the chance they forget, which would cause a kernel memory leak.
For a list of TET APIs available in the kernel see the the header file
$CTI_ROOT/include/tet_kmodapi.h.

===============================================================================

bin/sutool	(Source - src/utils/sutool.c)

sutool is a simple tool, akin to su or sudo, that allows an arbitrary command
to be executed as the specified user (including root).  Unlike su or sudo,
this program does NOT ask for any password.  It changes the UID, EUID,
saved-UID, GID, EGID, saved-GID, and supplementary group list of the process
to those of the specified user's prior to executing the command.

WARNING: This program is a major security risk.  Do not use if security is an
issue and/or remove the installed binary from the package installation.