2 # Copyright (c) 2000 Silicon Graphics, Inc. All Rights Reserved.
4 # This program is free software; you can redistribute it and/or modify it
5 # under the terms of version 2 of the GNU General Public License as
6 # published by the Free Software Foundation.
8 # This program is distributed in the hope that it would be useful, but
9 # WITHOUT ANY WARRANTY; without even the implied warranty of
10 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
12 # Further, this software is distributed without any warranty that it is
13 # free of the rightful claim of any third person regarding infringement
14 # or the like. Any license provided herein, whether implied or
15 # otherwise, applies only to this software file. Patent licenses, if
16 # any, provided herein do not apply to combinations of this program with
17 # other software, or any other product whatsoever.
19 # You should have received a copy of the GNU General Public License along
20 # with this program; if not, write the Free Software Foundation, Inc., 59
21 # Temple Place - Suite 330, Boston MA 02111-1307, USA.
23 # Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
24 # Mountain View, CA 94043, or:
28 # For further information regarding this notice, see:
30 # http://oss.sgi.com/projects/GenInfo/SGIGPLNoticeExplan/
38 A) Extracting from DMAPI_test.cpio
40 1) Create a new directory for storing the tests. We will refer to
41 this as the "base" directory. The base directory can be
42 located anywhere; it does NOT need to be in a DMAPI filesystem.
44 2) Move the archive file DMAPI_test.cpio to the base directory
45 and execute the following command to extract from the archive:
47 cat DMAPI_test.cpio | cpio -icd
49 3) There should now be several files and subdirectories in the base
50 directory, including the file "file_list". Read this file for a
51 complete listing of which files should be present in which
52 directories. Compare "file_list" with the output of "ls -Rpl"
53 to be sure that you have the necessary files.
55 4) The base directory contains the files and programs that are of
56 immediate use for testing. The "bindir" subdirectory contains
57 the test programs and datafiles. The "lib" and "src" subdirectories
58 contain C libraries and source code for the C programs.
60 B) Checking the Existence and Version of DMAPI
62 The program check_dmapi can verify that you have the correct
63 version of DMAPI installed. Note: it can only be run as root.
64 Execute this command (from the "base" directory):
68 It should report that you have a current version of DMAPI. If it
69 does not, it will also suggest which components of your DMAPI are
70 not current, and where to find a patch to update them.
74 1) Creating the Test Directories
76 a) The Test Filesystem
78 Mount a DMAPI filesystem, or use an existing one.
79 This filesystem's mount info MUST be listed in /etc/fstab.
81 Write down the path to this filesystem's mountpoint, and label
82 it as "m_main" for future use.
84 b) The Main Test Directory
86 Create a new directory in the "m_main" filesystem.
88 Write down the path to this directory. Note ONLY the part
89 that comes AFTER "m_main". Label this as "d_name".
91 EXAMPLE: You have a DMAPI filesystem /dmi_main
92 You name the test directory /dmi_main/test_dir
96 c) The Cross-NFS Test Directories
98 For NFS tests, all you must do is create two empty directories
99 (one for nfs2, one for nfs3). They do NOT need to be in a
102 Your main test directory will be mounted across NFS, into these
103 two directories. Normally, the tests will do this automatically.
104 However, if you need to do this mount manually, the command
105 would look like this example:
107 mount -t nfs2 localhost:/dmi_main /dmi_nfs2
109 Write down the paths to these nfs2 and nfs3 test directories.
110 Label them "m_nfs2" and "m_nfs3" respectively.
112 c) The Realtime Test Filesystem and Directory
114 If you wish to test realtime i/o, you'll need a filesystem
115 mounted with a realtime partition, and a directory in that
118 Label the path to the filesystem mountpoint as "m_rt".
119 Label the path to the test directory as "d_rt".
121 2) Configuring menu_test
123 The Korn-shell script named menu_test is an interface to the
124 other test programs. At the beginning of the script, there
125 is a "configuration section", in which is sets several variables
126 for use in the rest of the script.
128 Open menu_test in any text editor and change the following
129 variable assignments in the configuration section:
132 Set this to the pathname of your "base" directory
133 (where you un-archived "DMAPI_test.cpio").
136 Tests that do not run as root will run as this "primary" user.
137 Set this to any username.
140 The mountpoint of the main test filesystem.
141 Set this to the value of "m_main" that you wrote down above.
144 m_main concatenated with d_name is the main test directory path.
145 Set this to the value for "d_name" that you wrote down above.
148 The mountpoint of the nfs2 test filesystem.
149 Set this to the value of "m_nfs2" that you wrote down above.
152 The mountpoint of the nfs3 test filesystem.
153 Set this to the value of "m_nfs3" that you wrote down above.
156 The mountpoint of the realtime test filesystem.
157 Set this to the value of "m_rt" that you wrote down above.
160 The path to the realtime test directory.
161 Set this to the value of "d_rt" that you wrote down above.
163 3) Configuring "DMAPI_aliases"
165 This is an optional alternative to the menu interface. It runs
166 as a Korn shell "dot" script and creates an alias to each test.
167 It was made for those who wish to run tests directly from the
170 DMAPI_aliases has exactly the same configuration section as
171 menu_test. If you wish to use DMAPI_aliases, make the same
172 changes to its configuration section.
174 II) Running the Tests
176 A) Using "menu_test" to run tests
178 1) You must be superuser, using the Korn shell, to run menu_test.
179 You also must have adjusted the variables in menu_test's
180 "configuration section", as was explained above.
182 2) menu_test is (surprise!) menu based. Choose options by entering
185 3) The names of the menu options explain which DMAPI functions
186 or DMAPI events are being tested. Some of the options, labeled
187 accordingly, run more than one test programs.
189 4) See section SECTION# for a list of the test scripts and programs,
190 and a brief explanation of each script or program's function.
192 B) Using "DMAPI_aliases" to run tests
194 1) NOTE: The aliases in DMAPI_aliases are meant to be used by
195 those who are familiar with the test programs and wish to run
196 them more directly. [Designer's note: I included the alias
197 file more out of nostalgia than necessity.]
199 2) You should be superuser, using the Korn shell, to run DMAPI_aliases.
200 You also must have adjusted the variables in DMAPI_aliases's
201 "configuration section", as was explained above.
203 3) DMAPI_aliases should be invoked as a Korn shell "dot" script:
207 It sets an alias for each test program; each alias begins with
208 the characters "do_" and is followed by some appropriate name.
209 Read DMAPI_aliases, or execute "alias | grep do", to
211 C) Running tests directly
213 1) For the VERY adventurous, all the tests in the "bindir" directory
214 can be run directly from the command line. Only some of the files
215 in "bindir" are test scripts/programs. Read section III for a list
216 of function tests and section IV for a list of run_test (.dat)
219 2) Running a test program without parameters will produce a list of
220 correct options. (The exception to this is check_dmapi, which
221 normally has no parameters. check_dmapi takes only one option,
222 [-v] for verbose output.)
224 3) It is suggested that you read a program's source before running
225 it directly. (The source of the C programs is included in the
226 "src" directory.) Specificually, in each source file, an initial
227 comment explains the program's options/parameters in detail.
229 III) DMAPI Function tests:
231 This section offers a terse description of the DMAPI function tests.
232 For those tests written in C, the source code is given in the "src"
233 directory. The ksh scripts can, of course, be read directly.
234 In all cases except check_dmapi, running the program without
235 parameters will produce a list of correct options.
239 Test of: presence (and correct version) of DMAPI library and kernel.
240 Options: [-v] flag for verbose output.
244 Test of: dm_get_dmattr, dm_set_dmattr, dm_remove_dmattr.
248 Test of: various bad function calls that should generate EFAULT,
249 according to the DMAPI specification.
253 Test of: dm_get_eventlist, dm_set_eventlist.
257 Test of: dm_get_fileattr, dm_set_fileattr,
258 dm_get_dirattrs, dm_get_bulkattr.
262 Test of: dm_probe_hole, dm_punch_hole.
266 Test of: dm_read_invis, dm_write_invis.
270 Test of: dm_get_region, dm_set,region.
274 Test of: various bad function calls that should generate EACCES,
275 and other conditions pertaining to DMAPI rights.
279 Test of: dm_get_allocinfo.
283 Test of: dm_get_allocinfo.
285 IV) DMAPI Event tests and the "run_test" ksh script
287 A) How to use the "run_test" script
289 1) A quick description of run_test's behavior:
290 run_test invokes a DMAPI daemon (as a ksh coprocess). It then
291 reads a "testfile", which contains a description of the test.
293 2) You must be superuser, using the Korn shell, to execute run_test.
295 3) Executing run_test without parameters will produce a list of
296 correct options. For a much more in-depth explanation of the
297 options to run_test, read its own initial comment.
299 B) The existing .dat testfiles
312 C) How to write ".dat" testfiles
316 A testfile contains a complete description of a DMAPI event test.
317 Testfiles are divided into sections: the first two contain
318 test initialization, while the remaining sections each contain ONE
319 command, followed by a list of expected events.
321 The following is a description of testfile syntax. If you wish to
322 fully understand testfile syntax, PLEASE examine the existing
323 testfiles and the "run_test" script.
325 2) Event information variables
327 a) From the daemon, "run_test" gets information about DMAPI events.
328 This information is stored in event information variables.
330 b) NOTE: event information variables are not persistant.
331 After "run_test" has compared the expected and actual events
332 for a command, and before it executes the next command, it
333 unsets the values of all these variables.
335 c) Most of these variables are arrays, indexed by the number of
336 the event (starting with 0). For example, if the initial event
337 is a read event, then we have "event[0]" set to "read", and
338 "file_handle[0]" set to the handle of whatever file was read.
340 d) "event_count" is a special variable. It holds the number of
341 events that were generated by the most recent command.
343 e) These are all the event information variables:
345 contents event event_count fs_handle handle length
346 offset media_designator mode mountpoint_handle
347 mountpoint_path msg_str name new_name new_parent
348 parent_handle ret_code root_handle sequence token
349 tries_left unmount_mode
351 f) PLEASE examine the run_test script to see which variables
352 are set by which events. (The scheme corresponds, roughly,
353 to the "Event Types" section of the DMAPI specification.)
355 3) Testfile section 1: List of required files
357 a) A testfile's first section is a list of the files it requires.
358 If these files are not present in the "bindir" directory,
359 "run_test" will abort the test and inform the user of which
362 b) Each line of this section may contain ANY NUMBER of filenames.
364 c) Lines beginning with // will be treated as comments. The
365 entirety of such lines will be ignored.
367 d) The last line of this section should begin with three hyphens
368 --- Other characters on that line will be ignored.
370 4) Testfile section 2: Initialization commands
372 a) A testfile's second section consists of a list of commands.
373 "run_test" will execute these commands before starting the
374 DMAPI daemon. Any necessary initialization should be done
377 b) Each line of this section should be ONE shell command.
379 c) Lines beginning with // will be treated as comments.
380 The entirety of such lines will be ignored.
382 d) The last line of this section should begin with three hyphens
383 "---" Other characters on that line will be ignored.
385 5) Testfile sections 3 and on: Individual tests
387 a) The remaining sections of a testfile consist of a single
388 shell command, followed by descriptions of events that should
389 be generated by the command.
393 1) Comments are valid ONLY before the command.
395 2) Lines beginning with // will be treated as comments.
396 The entirety of such lines will be ignored.
398 3) Lines beginning with @@ will be treated as "print" comments.
399 Such lines will not be parsed, but they will be printed to
400 standard output during the test. This is useful for
401 describing what each test does.
403 c) Valid grammar for the command itself
405 1) Standard command syntax:
406 This should be ONE shell command, on a line by itself.
408 2) Alternate command syntax:
411 If the test is preceeded by the metacommand "run_as_root"
412 (on a line by itself) then the command will be run as
413 root rather than as "p_user". The command should still
414 be one command on a line by itself.
417 If the test is preceeded by the metacommand
418 "run_without_test" (on a line by itself), then ALL
419 subsequent lines in the section will be executed as
420 commands, and NO testing will be performed. Note that
421 the commands will be executed as root. This is useful
422 for re-initialization sections during a test.
424 d) Valid grammar for the "expected events" lines
426 1) [variable_name] [value]
427 This specifies that the variable [variable_name] should be
430 2) [variable_name_1] matches [variable_name_2]
431 This specifies that both variables should be set to
432 the same value. A list of valid variables
434 3) [variable_name] store_in [string]
435 This specifies that the contents of [variable_name]
436 should be stored in a variable named [string].
437 The variable [string] can then be referenced as a
438 variable in later tests.
440 EXAMPLE: if two commands deal with the file "foobar",
441 you might want to check that they both use the same handle.
442 In the first section, write
443 "handle[0] store_in old_handle_0"
444 In the second section, write
445 "old_handle_0 matches handle[0]"
448 This specifies that the command is expected to fail
449 (return some non-zero exit status). If "failure"
450 is not specified, the command is expected to succeed.
452 e) The last line of these sections should begin with three
453 hyphens "---". Other characters on that line will be ignored.
455 6) Sending messages to the DMAPI daemon
458 7) Other "helper functions" for testfiles