1 #
   2 # CDDL HEADER START
   3 #
   4 # The contents of this file are subject to the terms of the
   5 # Common Development and Distribution License (the "License").
   6 # You may not use this file except in compliance with the License.
   7 #
   8 # You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9 # or http://www.opensolaris.org/os/licensing.
  10 # See the License for the specific language governing permissions
  11 # and limitations under the License.
  12 #
  13 # When distributing Covered Code, include this CDDL HEADER in each
  14 # file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15 # If applicable, add the following below this CDDL HEADER, with the
  16 # fields enclosed by brackets "[]" replaced with your own identifying
  17 # information: Portions Copyright [yyyy] [name of copyright owner]
  18 #
  19 # CDDL HEADER END
  20 #
  21 
  22 #
  23 # Copyright 2008 Sun Microsystems, Inc.  All rights reserved.
  24 # Use is subject to license terms.
  25 #
  26 # ident "@(#)README     1.3     08/12/19 SMI"
  27 #
  28 
  29 DESCRIPTION:
  30 ============
  31 
  32 This test suite is designed to test the loopback file (lofi) driver.
  33 The suite was primarily written to test lofi's compression/decompression
  34 functionality, so the bulk of the test assertions are in that area.
  35 However, since there was no pre-existing lofi test suite to add the
  36 compression tests to, this suite also provides some degree of general
  37 lofi coverage that does not involve compression.
  38 
  39 The suite auto-detects the presence or absence of lofi compression
  40 functionality.  If missing, the compression-related tests will not be
  41 run.  The lofi compression functionality was put back in snv_80, so when
  42 run against snv_80 or later the compression portion of the tests will be
  43 run; for snv_79 and before, as well as any s10 build, only those tests
  44 not involving compression will be executed.
  45 
  46 
  47 PREREQUISITES:
  48 ==============
  49 
  50 1. The SUNWstc-tetlite test harness package is required to be installed,
  51    or be accessible via nfs.
  52 
  53 2. A scratch directory with 1.1GB or more of free space.
  54 
  55 3. No pre-existing lofi devices may be configured on the system.  If
  56    the suite detects pre-existing lofi devices, it will not run.
  57 
  58 
  59 CTI-TET PACKAGE INSTALLATION:
  60 =============================
  61 
  62 The CTI-TET package is called SUNWstc-tetlite and installs into "/opt"
  63 by default.  Installation is via the standard Solaris package
  64 installation tool pkgadd(1m).  To install SUNWstc-tetlite simply enter
  65 the following command line as root (or having adopted the root role):
  66 
  67 # pkgadd -d <package location>  SUNWstc-tetlite
  68 
  69 Where <package location> refers to the path containing the SUNWstc-tetlite
  70 package directory.
  71 
  72 o It is recommended that you install the packages from scratch, rather
  73   than on top of an existing installation.  Thus, if an old version of
  74   the tests is installed, remove it:
  75 
  76 # pkgrm SUNWstc-tetlite
  77 
  78 It is also acceptable to use an nfs accessible version of SUNWstc-tetlite.
  79 
  80 
  81 TEST SUITE INSTALLATION :
  82 =======================
  83 
  84 In the majority of cases, the test suite can be installed from
  85 packages. The package is called SUNWstc-os-lofi and installs into "/opt" by
  86 default.  Installation is via the standard Solaris package installation
  87 tool pkgadd(1m).  To install SUNWstc-os-lofi simply enter the following
  88 command line as root (or having adopted the root role):
  89 
  90 # pkgadd -d <package location>  SUNWstc-os-lofi
  91 
  92 Where <package location> refers to the path containing the SUNWstc-os-lofi
  93 package directory.
  94 
  95  o It is recommended that you install the packages from scratch, rather
  96    than on top of an existing installation.  Thus, if an old version of
  97    the tests is installed:
  98 
  99 # pkgrm SUNWstc-os-lofi
 100 
 101 It is also acceptable to use an nfs accessible version of SUNWstc-os-lofi.
 102 
 103 Optionally, the test suite source can be installed locally, built in the
 104 source tree and run from that location.
 105 
 106 As any user do the following after installing the test suite source :
 107 
 108 1. TET_ROOT=/opt/SUNWstc-tetlite
 109 2. export TET_ROOT
 110 3. CTI_ROOT=$TET_ROOT/contrib/ctitools
 111 4. export CTI_ROOT
 112 5. TET_SUITE_ROOT=/export/home/cti_lofi/usr/src/suites/os (e.g location)
 113 6. export TET_SUITE_ROOT
 114 7. cd $TET_SUITE_ROOT/lofi
 115 8. /usr/bin/make
 116 
 117 The build can also install into a proto directory below the workspace
 118 root directory.  The workspace root is the directory under which the
 119 usr/src or usr/closed directory is located (so, in the example location
 120 used in step 5 above, the workspace root is "/export/home/cti_lofi").
 121 In addition, test suite packages can be built using the proto directory
 122 and stored in the packages directory below the defined workspace root
 123 directory.  To install the binaries into the proto area, do:
 124 
 125 9. /usr/ccs/bin/make install
 126 
 127 To create the test suite package, do
 128 
 129 10. /usr/ccs/bin/make package
 130 
 131 
 132 TEST SUITE CONFIGURATION:
 133 =========================
 134 
 135 The only configuration necessary is to define the mandatory SCRATCH_DIR
 136 variable for the test suite.  This must point to a directory that has
 137 slightly over 1GB of free space and in which root has write permissions.
 138 SCRATCH_DIR can be specified in the file:
 139 
 140 $TET_SUITE_ROOT/lofi/config/test_config
 141 
 142 or they can be specified on the command line when executing the tests
 143 (see TEST SUITE EXECUTION below).  Other variables can also be set
 144 to place limits on varying test parameters that get run.  See the 
 145 comments in $TET_SUITE_ROOT/lofi/config/test_config for details.
 146 
 147 
 148 TEST SUITE EXECUTION:
 149 =====================
 150 
 151 The test suite execution is required to be done as root.
 152 
 153 Set up the environment variables:
 154 
 155 export TET_ROOT=/opt/SUNWstc-tetlite
 156 export CTI_ROOT=$TET_ROOT/contrib/ctitools
 157 export TET_SUITE_ROOT=/opt/SUNWstc-os-lofi (installation path of suite)
 158 PATH=$PATH:$CTI_ROOT/bin
 159 export PATH
 160 
 161 To run the entire test suite do the following:
 162 
 163 # run_test lofi
 164 
 165 if you have defined SCRATCH_DIR in the test_config file (see TEST SUITE
 166 CONFIGURATION above).  If not, specify a value for SCRATCH_DIR on the
 167 command line:
 168 
 169 # run_test -v SCRATCH_DIR=/export/home lofi
 170 
 171 The following usage of the run_test command is supported:
 172 
 173 # run_test lofi [<scenario>|tc_dir:[tp_list]]
 174 
 175 For example:
 176 
 177     # run_test lofi compression_dynamic
 178     (run the compression_dynamic test scenario only)
 179 
 180     # run_test lofi compression_dynamic:10
 181     (only run test purpose 10 of the compression_dynamic scenario)
 182 
 183 
 184 EVALUATING TEST SUITE RESULTS:
 185 ==============================
 186 
 187 At the completion of a test run, a summary of test results will be
 188 displayed on the terminal where the test suite was invoked.  If 0 tests
 189 were run, this typically indicates a problem was encountered in setup
 190 before any test cases were attempted.  Details on any issues can be
 191 found by viewing the journal file, the location of which will be
 192 reported by TET at the end of the test run.
 193 
 194 The STATUS.LIST file at the top level of the test suite lists any expected
 195 failures for the suite.  The following test status values can be reported:
 196 
 197         PASS - Test ran to completion with no issues
 198         FAIL - Test ran to completion, but failed to prove the assertion
 199         UNRESOLVED - Unable to execute test assertion because of an issue
 200             in prerequisite steps.
 201         UNTESTED - Test skipped, either because support for feature missing
 202             on test system (e.g. compression tests skipped on OS without
 203             compression support) or because of user configuration choices
 204             (e.g. RUNMODE set to 'short' so the more time-consuming tests
 205             are skipped)
 206 
 207 TEST SUITE UNCONFIGURE:
 208 =======================
 209 
 210 No test suite unconfiguration step is necessary.  So long as none of
 211 the tests terminated abnormally, the suite will leave the test system
 212 in the same shape that it found it.
 213 
 214 Should the test suite exit abnormally (system goes down during testing,
 215 etc.) then the tests may leave behind configured lofi devices (execute
 216 'lofiadm' to check for them) or files in SCRATCH_DIR that the user will
 217 need to clean up before attempting to run the test suite again.