dmapi/src/suite2/dist/README

   1 #
   2 # Copyright (c) 2000-2001 Silicon Graphics, Inc.  All Rights Reserved.
   3 #
   4                            DMAPI Test Suite
   5                           Informational File
   6                           ------------------
   7
   8 I) Getting Started
   9
  10    A) Extracting from DMAPI_test.cpio
  11
  12       1) Create a new directory for storing the tests.  We will refer to
  13          this as the "base" directory.  The base directory can be
  14          located anywhere; it does NOT need to be in a DMAPI filesystem.
  15
  16       2) Move the archive file DMAPI_test.cpio to the base directory
  17          and execute the following command to extract from the archive:
  18
  19             cat DMAPI_test.cpio | cpio -icd
  20
  21       3) There should now be several files and subdirectories in the base
  22          directory, including the file "file_list".  Read this file for a
  23          complete listing of which files should be present in which
  24          directories.  Compare "file_list" with the output of "ls -Rpl"
  25          to be sure that you have the necessary files.
  26
  27       4) The base directory contains the files and programs that are of
  28          immediate use for testing.  The "bindir" subdirectory contains
  29          the test programs and datafiles.  The "lib" and "src" subdirectories
  30          contain C libraries and source code for the C programs.
  31
  32    B) Checking the Existence and Version of DMAPI
  33
  34       The program check_dmapi can verify that you have the correct
  35       version of DMAPI installed.  Note: it can only be run as root.
  36       Execute this command (from the "base" directory):
  37
  38       bindir/check_dmapi
  39
  40       It should report that you have a current version of DMAPI.  If it
  41       does not, it will also suggest which components of your DMAPI are
  42       not current, and where to find a patch to update them.
  43
  44    C) Configuration
  45
  46       1) Creating the Test Directories
  47
  48          a) The Test Filesystem
  49
  50             Mount a DMAPI filesystem, or use an existing one.
  51             This filesystem's mount info MUST be listed in /etc/fstab.
  52
  53             Write down the path to this filesystem's mountpoint, and label
  54             it as "m_main" for future use.
  55
  56          b) The Main Test Directory
  57
  58             Create a new directory in the "m_main" filesystem.
  59
  60             Write down the path to this directory.  Note ONLY the part
  61             that comes AFTER "m_main".  Label this as "d_name".
  62
  63             EXAMPLE: You have a DMAPI filesystem /dmi_main
  64                      You name the test directory /dmi_main/test_dir
  65             "m_main" is /dmi_main
  66             "d_name" is /test_dir
  67
  68          c) The Cross-NFS Test Directories
  69
  70             For NFS tests, all you must do is create two empty directories
  71             (one for nfs2, one for nfs3). They do NOT need to be in a
  72             DMAPI filesystem.
  73
  74             Your main test directory will be mounted across NFS, into these
  75             two directories.  Normally, the tests will do this automatically.
  76             However, if you need to do this mount manually, the command
  77             would look like this example:
  78
  79             mount -t nfs2 localhost:/dmi_main /dmi_nfs2
  80
  81             Write down the paths to these nfs2 and nfs3 test directories.
  82             Label them "m_nfs2" and "m_nfs3" respectively.
  83
  84          c) The Realtime Test Filesystem and Directory
  85
  86             If you wish to test realtime i/o, you'll need a filesystem
  87             mounted with a realtime partition, and a directory in that
  88             filesystem.
  89
  90             Label the path to the filesystem mountpoint as "m_rt".
  91             Label the path to the test directory as "d_rt".
  92
  93       2) Configuring menu_test
  94
  95          The Korn-shell script named menu_test is an interface to the
  96          other test programs.  At the beginning of the script, there
  97          is a "configuration section", in which is sets several variables
  98          for use in the rest of the script.
  99
 100          Open menu_test in any text editor and change the following
 101          variable assignments in the configuration section:
 102
 103          a) base_dir:
 104             Set this to the pathname of your "base" directory
 105             (where you un-archived "DMAPI_test.cpio").
 106
 107          b) p_user:
 108             Tests that do not run as root will run as this "primary" user.
 109             Set this to any username.
 110
 111          c) m_main:
 112             The mountpoint of the main test filesystem.
 113             Set this to the value of "m_main" that you wrote down above.
 114
 115          d) d_name:
 116             m_main concatenated with d_name is the main test directory path.
 117             Set this to the value for "d_name" that you wrote down above.
 118
 119          e) m_nfs2:
 120             The mountpoint of the nfs2 test filesystem.
 121             Set this to the value of "m_nfs2" that you wrote down above.
 122
 123          f) m_nfs2:
 124             The mountpoint of the nfs3 test filesystem.
 125             Set this to the value of "m_nfs3" that you wrote down above.
 126
 127          g) m_rt:
 128             The mountpoint of the realtime test filesystem.
 129             Set this to the value of "m_rt" that you wrote down above.
 130
 131          h) d_rt:
 132             The path to the realtime test directory.
 133             Set this to the value of "d_rt" that you wrote down above.
 134
 135       3) Configuring "DMAPI_aliases"
 136
 137          This is an optional alternative to the menu interface. It runs
 138          as a Korn shell "dot" script and creates an alias to each test.
 139          It was made for those who wish to run tests directly from the
 140          command line.
 141
 142          DMAPI_aliases has exactly the same configuration section as
 143          menu_test.  If you wish to use DMAPI_aliases, make the same
 144          changes to its configuration section.
 145
 146 II) Running the Tests
 147
 148    A) Using "menu_test" to run tests
 149
 150       1) You must be superuser, using the Korn shell, to run menu_test.
 151          You also must have adjusted the variables in menu_test's
 152          "configuration section", as was explained above.
 153
 154       2) menu_test is (surprise!) menu based.  Choose options by entering
 155          their numbers.
 156
 157       3) The names of the menu options explain which DMAPI functions
 158          or DMAPI events are being tested.  Some of the options, labeled
 159          accordingly, run more than one test programs.
 160
 161       4) See section SECTION# for a list of the test scripts and programs,
 162          and a brief explanation of each script or program's function.
 163
 164    B) Using "DMAPI_aliases" to run tests
 165
 166       1) NOTE: The aliases in DMAPI_aliases are meant to be used by
 167          those who are familiar with the test programs and wish to run
 168          them more directly.  [Designer's note: I included the alias
 169          file more out of nostalgia than necessity.]
 170
 171       2) You should be superuser, using the Korn shell, to run DMAPI_aliases.
 172          You also must have adjusted the variables in DMAPI_aliases's
 173          "configuration section", as was explained above.
 174
 175       3) DMAPI_aliases should be invoked as a Korn shell "dot" script:
 176
 177          . ./DMAPI_aliases
 178
 179          It sets an alias for each test program; each alias begins with
 180          the characters "do_" and is followed by some appropriate name.
 181          Read DMAPI_aliases, or execute "alias | grep do", to
 182
 183    C) Running tests directly
 184
 185       1) For the VERY adventurous, all the tests in the "bindir" directory
 186          can be run directly from the command line.  Only some of the files
 187          in "bindir" are test scripts/programs.  Read section III for a list
 188          of function tests and section IV for a list of run_test (.dat)
 189          testfiles.
 190
 191       2) Running a test program without parameters will produce a list of
 192          correct options.  (The exception to this is check_dmapi, which
 193          normally has no parameters.  check_dmapi takes only one option,
 194          [-v] for verbose output.)
 195
 196       3) It is suggested that you read a program's source before running
 197          it directly.  (The source of the C programs is included in the
 198          "src" directory.)  Specificually, in each source file, an initial
 199          comment explains the program's options/parameters in detail.
 200
 201 III) DMAPI Function tests:
 202
 203      This section offers a terse description of the DMAPI function tests.
 204      For those tests written in C, the source code is given in the "src"
 205      directory.  The ksh scripts can, of course, be read directly.
 206      In all cases except check_dmapi, running the program without
 207      parameters will produce a list of correct options.
 208
 209    A) check_dmapi
 210       Written in: C
 211       Test of: presence (and correct version) of DMAPI library and kernel.
 212       Options: [-v] flag for verbose output.
 213
 214    B) test_dmattr
 215       Written in: C
 216       Test of: dm_get_dmattr, dm_set_dmattr, dm_remove_dmattr.
 217
 218    C) test_efault
 219       Written in: C
 220       Test of: various bad function calls that should generate EFAULT,
 221                according to the DMAPI specification.
 222
 223    D) test_eventlist
 224       Written in: C
 225       Test of: dm_get_eventlist, dm_set_eventlist.
 226
 227    E) test_fileattr
 228       Written in: C
 229       Test of: dm_get_fileattr, dm_set_fileattr,
 230                dm_get_dirattrs, dm_get_bulkattr.
 231
 232    F) test_hole
 233       Written in: C
 234       Test of: dm_probe_hole, dm_punch_hole.
 235
 236    G) test_invis
 237       Written in: C
 238       Test of: dm_read_invis, dm_write_invis.
 239
 240    H) test_region
 241       Written in:  C
 242       Test of: dm_get_region, dm_set,region.
 243
 244    I) test_rights
 245       Written in: C
 246       Test of: various bad function calls that should generate EACCES,
 247                and other conditions pertaining to DMAPI rights.
 248
 249    J) test_allocinfo_1
 250       Written in: ksh
 251       Test of: dm_get_allocinfo.
 252
 253    K) test_allocinfo_2
 254       Written in: ksh
 255       Test of: dm_get_allocinfo.
 256
 257 IV) DMAPI Event tests and the "run_test" ksh script
 258
 259    A) How to use the "run_test" script
 260
 261       1) A quick description of run_test's behavior:
 262          run_test invokes a DMAPI daemon (as a ksh coprocess).  It then
 263          reads a "testfile", which contains a description of the test.
 264
 265       2) You must be superuser, using the Korn shell, to execute run_test.
 266
 267       3) Executing run_test without parameters will produce a list of
 268          correct options.  For a much more in-depth explanation of the
 269          options to run_test, read its own initial comment.
 270
 271    B) The existing .dat testfiles
 272
 273      1) fail.dat
 274       2) main.dat
 275       3) nfs.dat
 276       4) old_nfs3.dat
 277       5) pending.dat
 278       6) pending_nfs.dat
 279       7) realtime.dat
 280       8) smallq.dat
 281       9) standard.dat
 282      10) standard_nfs.dat
 283
 284    C) How to write ".dat" testfiles
 285
 286       1) Overview
 287
 288          A testfile contains a complete description of a DMAPI event test.
 289          Testfiles are divided into sections: the first two contain
 290          test initialization, while the remaining sections each contain ONE
 291          command, followed by a list of expected events.
 292
 293          The following is a description of testfile syntax.  If you wish to
 294          fully understand testfile syntax, PLEASE examine the existing
 295          testfiles and the "run_test" script.
 296
 297       2) Event information variables
 298
 299          a) From the daemon, "run_test" gets information about DMAPI events.
 300             This information is stored in event information variables.
 301
 302          b) NOTE: event information variables are not persistant.
 303             After "run_test" has compared the expected and actual events
 304             for a command, and before it executes the next command, it
 305             unsets the values of all these variables.
 306
 307          c) Most of these variables are arrays, indexed by the number of
 308             the event (starting with 0). For example, if the initial event
 309             is a read event, then we have "event[0]" set to "read", and
 310             "file_handle[0]" set to the handle of whatever file was read.
 311
 312          d) "event_count" is a special variable.  It holds the number of
 313             events that were generated by the most recent command.
 314
 315          e) These are all the event information variables:
 316
 317             contents event event_count fs_handle handle length
 318             offset media_designator mode mountpoint_handle
 319             mountpoint_path msg_str name new_name new_parent
 320             parent_handle ret_code root_handle sequence token
 321             tries_left unmount_mode
 322
 323          f) PLEASE examine the run_test script to see which variables
 324             are set by which events.  (The scheme corresponds, roughly,
 325             to the "Event Types" section of the DMAPI specification.)
 326
 327       3) Testfile section 1:  List of required files
 328
 329          a) A testfile's first section is a list of the files it requires.
 330             If these files are not present in the "bindir" directory,
 331             "run_test" will abort the test and inform the user of which
 332             files are missing.
 333
 334          b) Each line of this section may contain ANY NUMBER of filenames.
 335
 336          c) Lines beginning with // will be treated as comments.  The
 337             entirety of such lines will be ignored.
 338
 339          d) The last line of this section should begin with three hyphens
 340             ---  Other characters on that line will be ignored.
 341
 342       4) Testfile section 2:  Initialization commands
 343
 344          a) A testfile's second section consists of a list of commands.
 345             "run_test" will execute these commands before starting the
 346             DMAPI daemon.  Any necessary initialization should be done
 347             here.
 348
 349          b) Each line of this section should be ONE shell command.
 350
 351          c) Lines beginning with // will be treated as comments.
 352             The entirety of such lines will be ignored.
 353
 354          d) The last line of this section should begin with three hyphens
 355             "---"  Other characters on that line will be ignored.
 356
 357       5) Testfile sections 3 and on:  Individual tests
 358
 359          a) The remaining sections of a testfile consist of a single
 360             shell command, followed by descriptions of events that should
 361             be generated by the command.
 362
 363          b) Comments
 364
 365             1) Comments are valid ONLY before the command.
 366
 367             2) Lines beginning with // will be treated as comments.
 368                The entirety of such lines will be ignored.
 369
 370             3) Lines beginning with @@ will be treated as "print" comments.
 371                Such lines will not be parsed, but they will be printed to
 372                standard output during the test.  This is useful for
 373                describing what each test does.
 374
 375          c) Valid grammar for the command itself
 376
 377             1) Standard command syntax:
 378                This should be ONE shell command, on a line by itself.
 379
 380             2) Alternate command syntax:
 381
 382                A) run_as_root:
 383                   If the test is preceeded by the metacommand "run_as_root"
 384                   (on a line by itself) then the command will be run as
 385                   root rather than as "p_user".  The command should still
 386                   be one command on a line by itself.
 387
 388                B) run_without_test:
 389                   If the test is preceeded by the metacommand
 390                   "run_without_test" (on a line by itself), then ALL
 391                   subsequent lines in the section will be executed as
 392                   commands, and NO testing will be performed.  Note that
 393                   the commands will be executed as root.  This is useful
 394                   for re-initialization sections during a test.
 395
 396          d) Valid grammar for the "expected events" lines
 397
 398             1) [variable_name] [value]
 399                This specifies that the variable [variable_name] should be
 400                set to [value].
 401
 402             2) [variable_name_1] matches [variable_name_2]
 403                This specifies that both variables should be set to
 404                the same value.  A list of valid variables
 405
 406             3) [variable_name] store_in [string]
 407                This specifies that the contents of [variable_name]
 408                should be stored in a variable named [string].
 409                The variable [string] can then be referenced as a
 410                variable in later tests.
 411
 412                EXAMPLE: if two commands deal with the file "foobar",
 413                you might want to check that they both use the same handle.
 414                In the first section, write
 415                 "handle[0] store_in old_handle_0"
 416                In the second section, write
 417                 "old_handle_0 matches handle[0]"
 418
 419             4) failure
 420                This specifies that the command is expected to fail
 421                (return some non-zero exit status).  If "failure"
 422                is not specified, the command is expected to succeed.
 423
 424          e) The last line of these sections should begin with three
 425             hyphens "---".  Other characters on that line will be ignored.
 426
 427       6) Sending messages to the DMAPI daemon
 428
 429
 430       7) Other "helper functions" for testfiles
 431
 432
 433
 434
 435