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/
39 A) Extracting from DMAPI_test.cpio
41 1) Create a new directory for storing the tests. We will refer to
42 this as the "base" directory. The base directory can be
43 located anywhere; it does NOT need to be in a DMAPI filesystem.
45 2) Move the archive file DMAPI_test.cpio to the base directory
46 and execute the following command to extract from the archive:
48 cpio -icvd < DMAPI_test.cpio
50 3) There should now be several files and subdirectories in the base
51 directory, including the file "file_list". Read this file for a
52 complete listing of which files should be present in which
53 directories. Compare "file_list" with the output of "ls -Rpl"
54 to be sure that you have the necessary files.
56 4) The base directory contains the files and programs that are of
57 immediate use for testing. The "bindir" subdirectory contains
58 the test programs and datafiles. The "lib" and "src" subdirectories
59 contain C libraries and source code for the C programs.
61 B) Checking the Existence and Version of DMAPI
63 The program check_dmapi can verify that you have the correct
64 version of DMAPI installed. NOTE: it can only be run as root.
65 Execute this command (from the "base" directory):
69 It should report that you have a current version of DMAPI. If it
70 does not, it will also suggest which components of your DMAPI are
71 not current, and where to find a patch to update them.
75 1) Creating the Test Directories
77 a) The Test Filesystem
79 Mount a DMAPI filesystem, or use an existing one.
80 This filesystem's mount info MUST be listed in /etc/fstab.
82 Write down the path to this filesystem's mountpoint, and label
83 it as "m_main" for future use.
85 b) The Main Test Directory
87 Create a new directory in the "m_main" filesystem.
89 Write down the path to this directory. Note ONLY the part
90 that comes AFTER "m_main". Label this as "d_name".
92 EXAMPLE: You have a DMAPI filesystem /dmi_main
93 You name the test directory /dmi_main/test_dir
97 c) The Cross-NFS Test Directories
99 For NFS tests, all you must do is create two empty directories
100 (one for nfs2, one for nfs3). They do NOT need to be in a
103 Your main test directory will be mounted across NFS, into these
104 two directories. Normally, the tests will do this automatically.
105 However, if you need to do this mount manually, the command
106 would look like this example:
108 mount -t nfs2 localhost:/dmi_main /dmi_nfs2
110 Write down the paths to these nfs2 and nfs3 test directories.
111 Label them "m_nfs2" and "m_nfs3" respectively.
113 c) The Realtime Test Filesystem and Directory
115 If you wish to test realtime i/o, you'll need a filesystem
116 mounted with a realtime partition, and a directory in that
119 Label the path to the filesystem mountpoint as "m_rt".
120 Label the path to the test directory as "d_rt".
122 2) Configuring menu_test
124 The Korn-shell script named menu_test is an interface to the
125 other test programs. At the beginning of the script, there
126 is a "configuration section", in which is sets several variables
127 for use in the rest of the script.
129 Open menu_test in any text editor and change the following
130 variable assignments in the configuration section:
133 Set this to the pathname of your "base" directory
134 (where you un-archived "DMAPI_test.cpio").
137 Tests that do not run as root will run as this "primary" user.
138 Set this to any username.
141 The mountpoint of the main test filesystem.
142 Set this to the value of "m_main" that you wrote down above.
145 m_main concatenated with d_name is the main test directory path.
146 Set this to the value for "d_name" that you wrote down above.
149 The mountpoint of the nfs2 test filesystem.
150 Set this to the value of "m_nfs2" that you wrote down above.
153 The mountpoint of the nfs3 test filesystem.
154 Set this to the value of "m_nfs3" that you wrote down above.
157 The mountpoint of the realtime test filesystem.
158 Set this to the value of "m_rt" that you wrote down above.
161 The path to the realtime test directory.
162 Set this to the value of "d_rt" that you wrote down above.
164 3) Configuring "DMAPI_aliases"
166 This is an optional alternative to the menu interface. It runs
167 as a Korn shell "dot" script and creates an alias to each test.
168 It was made for those who wish to run tests directly from the
171 DMAPI_aliases has exactly the same configuration section as
172 menu_test. If you wish to use DMAPI_aliases, make the same
173 changes to its configuration section.
175 II) Running the Tests
177 A) Using "menu_test" to run tests
179 1) You must be superuser, using the Korn shell, to run menu_test.
180 You also must have adjusted the variables in menu_test's
181 "configuration section", as was explained above.
183 2) menu_test is (surprise!) menu based. Choose options by entering
186 3) The names of the menu options explain which DMAPI functions
187 or DMAPI events are being tested. Some of the options, labeled
188 accordingly, run more than one test programs.
190 4) See section SECTION# for a list of the test scripts and programs,
191 and a brief explanation of each script or program's function.
193 B) Using "DMAPI_aliases" to run tests
195 1) NOTE: The aliases in DMAPI_aliases are meant to be used by
196 those who are familiar with the test programs and wish to run
197 them more directly. [Designer's note: I included the alias
198 file more out of nostalgia than necessity.]
200 2) You should be superuser, using the Korn shell, to run DMAPI_aliases.
201 You also must have adjusted the variables in DMAPI_aliases's
202 "configuration section", as was explained above.
204 3) DMAPI_aliases should be invoked as a Korn shell "dot" script:
208 It sets an alias for each test program; each alias begins with
209 the characters "do_" and is followed by some appropriate name.
210 Read DMAPI_aliases, or execute "alias | grep do", to
213 In the menu of function tests, one of the options is an on/off
214 toggle of "verbose mode". When verbose mode is on, the function
215 tests will print semi-explanatory output. Verbose mode affects
216 only the function tests (this does include check_dmapi).
218 5) "Pausing after each command"
219 In the menu of event tests, one of the options is a toggle of
220 "pausing after each command". When this is on, the event tests
221 will pause for a carriage return after running each command.
222 This affects only the event tests.
224 C) Running tests directly
226 1) For the VERY adventurous, all the tests in the "bindir" directory
227 can be run directly from the command line. Only some of the files
228 in "bindir" are test scripts/programs. Read section III for a list
229 of function tests and section IV for a list of run_test (.dat)
232 2) Running a test program without parameters will produce a list of
233 correct options. (The exception to this is check_dmapi, which
234 normally has no parameters. check_dmapi takes only one option,
235 [-v] for verbose output.)
237 3) It is suggested that you read a program's source before running
238 it directly. (The source of the C programs is included in the
239 "src" directory.) Specifically, in each source file, an initial
240 comment explains the program's options/parameters in detail.
242 III) DMAPI Function tests:
244 This section offers a terse description of the DMAPI function tests.
245 For those tests written in C, the source code is given in the "src"
246 directory. The ksh scripts can, of course, be read directly.
247 In all cases except check_dmapi, running the program without
248 parameters will produce a list of correct options.
252 Test of: presence (and correct version) of DMAPI library and kernel.
253 Options: [-v] flag for verbose output.
257 Test of: dm_get_dmattr, dm_set_dmattr, dm_remove_dmattr.
261 Test of: various bad function calls that should generate EFAULT,
262 according to the DMAPI specification.
266 Test of: dm_get_eventlist, dm_set_eventlist.
270 Test of: dm_get_fileattr, dm_set_fileattr,
271 dm_get_dirattrs, dm_get_bulkattr.
275 Test of: dm_probe_hole, dm_punch_hole.
279 Test of: dm_read_invis, dm_write_invis.
283 Test of: dm_get_region, dm_set,region.
287 Test of: various bad function calls that should generate EACCES,
288 and other conditions pertaining to DMAPI rights.
292 Test of: dm_get_allocinfo.
296 Test of: dm_get_allocinfo.
298 IV) DMAPI Event tests and the "run_test" ksh script
300 A) How to use the "run_test" script
302 1) A quick description of run_test's behavior:
303 run_test invokes a DMAPI daemon (as a ksh coprocess). It then
304 proceeds in a loop, in which it reads a command from a "testfile",
305 executes that command, reads a description of expected events from
306 the testfile, and compares the expected events with the actual
307 events, as returned by the DMAPI daemon.
309 2) You must be superuser, using the Korn shell, to execute run_test.
311 3) Executing run_test without parameters will produce a list of
312 correct options. For a much more in-depth explanation of the
313 options to run_test, read its own initial comment.
315 B) The existing .dat testfiles
318 Tests the events from: a user trying to access files owned
319 by someone else (in this case, root).
322 Tests the events from: events getting DM_RESP_ABORT, dm_send_msg(),
323 invisible i/o, and direct i/o.
326 Tests the events from: events getting DM_RESP_ABORT over nfs,
330 Tests the events from: running dm_pending() while trying to
334 Tests the events from: running dm_pending() while trying to
335 do standard i/o over NFS
338 Tests the events from: Invisible, direct, and standard i/o
339 on realtime files in a realtime filesystem.
342 Tests the events from: Slow i/o due to a small event queue.
345 Tests the events from: various kinds of standard i/o,
346 memory-mapped i/o and remounting the filesystem.
349 Tests the events from: various kinds of standard i/o, over NFS.
351 C) How to write new ".dat" testfiles
355 A testfile contains a complete description of a DMAPI event test.
356 Testfiles are divided into sections: the first two contain
357 test initialization, while the remaining sections each contain ONE
358 command, followed by a list of expected events.
360 The following is a description of testfile syntax. If you wish to
361 fully understand testfile syntax, PLEASE examine the existing
362 testfiles and the "run_test" script.
364 2) Event information variables
366 a) From the daemon, "run_test" gets information about DMAPI events.
367 This information is stored in event information variables.
369 b) NOTE: event information variables are not persistent.
370 After "run_test" has compared the expected and actual events
371 for a command, and before it executes the next command, it
372 unsets the values of all these variables.
374 c) Most of these variables are arrays, indexed by the number of
375 the event (starting with 0). For example, if the initial event
376 is a read event, then we have "event[0]" set to "read", and
377 "file_handle[0]" set to the handle of whatever file was read.
379 d) "event_count" is a special variable. It holds the number of
380 events that were generated by the most recent command.
382 e) These are all the event information variables:
384 contents event event_count fs_handle handle length
385 offset media_designator mode mountpoint_handle
386 mountpoint_path msg_str name new_name new_parent
387 parent_handle ret_code root_handle sequence token
388 tries_left unmount_mode
390 f) PLEASE examine the run_test script to see which variables
391 are set by which events. (The scheme corresponds, roughly,
392 to the "Event Types" section of the DMAPI specification.)
394 3) Testfile section 1: List of required files
396 a) A testfile's first section is a list of the files it requires.
397 If these files are not present in the "bindir" directory,
398 "run_test" will abort the test and inform the user of which
401 b) Each line of this section may contain ANY NUMBER of filenames.
403 c) Lines beginning with // will be treated as comments. The
404 entirety of such lines will be ignored.
406 d) The last line of this section should begin with three hyphens
407 --- Other characters on that line will be ignored.
409 4) Testfile section 2: Initialization commands
411 a) A testfile's second section consists of a list of commands.
412 "run_test" will execute these commands before starting the
413 DMAPI daemon. Any necessary initialization should be done
416 b) Each line of this section should be ONE shell command.
418 c) Lines beginning with // will be treated as comments.
419 The entirety of such lines will be ignored.
421 d) The last line of this section should begin with three hyphens
422 "---" Other characters on that line will be ignored.
424 5) Testfile sections 3 and on: Individual tests
426 a) The remaining sections of a testfile consist of a single
427 shell command, followed by descriptions of events that should
428 be generated by the command.
432 1) Comments are valid ONLY before the command.
434 2) Lines beginning with // will be treated as comments.
435 The entirety of such lines will be ignored.
437 3) Lines beginning with @@ will be treated as "print" comments.
438 Such lines will not be parsed, but they will be printed to
439 standard output during the test. This is useful for
440 describing what each test does.
442 c) Valid grammar for the command itself
444 1) Standard command syntax:
445 This should be ONE shell command, on a line by itself.
447 2) Alternate command syntax:
449 If the test is preceded by the metacommand "run_as_root"
450 (on a line by itself) then the command will be run as
451 root rather than as "p_user". The command should still
452 be one command on a line by itself.
455 If the test is preceded by the metacommand
456 "run_without_test" (on a line by itself), then ALL
457 subsequent lines in the section will be executed as
458 commands, and NO testing will be performed. Note that
459 the commands will be executed as root. This is useful
460 for re-initialization sections during a test.
461 NOTE: A testfile cannot end with a "run_without_test"
462 section. The last section must contain a test.
464 d) Valid grammar for the "expected events" lines
466 1) [variable_name] [value]
467 This specifies that the variable [variable_name] should be
470 2) [variable_name_1] matches [variable_name_2]
471 This specifies that both variables should be set to
472 the same value. A list of valid variables
474 3) [variable_name] store_in [string]
475 This specifies that the contents of [variable_name]
476 should be stored in a variable named [string].
477 The variable [string] can then be referenced as a
478 variable in later tests.
480 EXAMPLE: if two commands deal with the file "foobar",
481 you might want to check that they both use the same handle.
482 In the first section, write
483 "handle[0] store_in old_handle_0"
484 In the second section, write
485 "old_handle_0 matches handle[0]"
488 This specifies that the command is expected to fail
489 (return some non-zero exit status). If "failure"
490 is not specified, the command is expected to succeed.
492 e) The last line of these sections should begin with three
493 hyphens "---". Other characters on that line will be ignored.
495 6) Sending messages to the DMAPI daemon
498 Normally, run_test only reads from the DMAPI daemon, and never
499 sends messages back. However, sometimes we need the daemon to
500 execute some function or change its behavior in some way. This
501 is accomplished by calling "send_msg" as a command in the
502 testfile. The test daemon has been coded to respond to the
503 following user events generated by send_msg:
506 Replace X here with an integer, as in "send_msg unfriendly_6".
507 This causes the daemon to respond to all messages (other than
508 user events) with DM_RESP_ABORT instead of DM_RESP_CONTINUE,
509 and with errno X. If the message is just "unfriendly", the
510 default errno is EBADMSG.
513 This returns the test_daemon to normal operation after it
514 was set to be "unfriendly".
517 Replace X and Y with integers, as in "send_msg countdown_6_8".
518 This causes the daemon to respond to the next X messages (other
519 than user events) with DM_RESP_ABORT instead of DM_RESP_CONTINUE,
520 and with errno Y. If the message is just "countdown", the
521 default count is 5 and the default errno is EAGAIN.
524 Replace X here with an integer, as in "send_msg pending_4".
525 This causes the daemon to call dm_pending() rather than
526 responding to the next X messages. If the message is just
527 "pending", the default count is 1. After the count reaches
528 zero, the messages will be responded to.
531 This message MUST be sent after remounting the test filesystem.
532 It causes the daemon to re-register for all events.
535 This message is sent by run_test itself, and should not be
536 sent in a testfile. "send_msg over" is called after each
537 command is executed, as an indicator that the batch of events
538 from that command is complete. When run_test sees a user
539 event with the data "over", it knows to stop reading events
540 and move on to the next command.
542 7) Other "helper functions" for testfiles
544 a) ctf (create test files)
545 purpose: creates 20 copies of "bindir/ls_to_copy".
546 parameters: location of "bindir", location of target directory.
549 b) crttf (create realtime test files)
550 purpose: creates 10 realtime files.
551 parameters: location of "bindir", location of target directory.
554 c) stf (setup test files)
555 purpose: set dm attributes and managed regions on target files.
556 parameters: location of "bindir", pathnames of target files.
560 purpose: do fcntl() syscall
561 parameters: see "usage" by running without parameters.
562 written in: C (source not included)
565 purpose: do open() syscall
566 parameters: see "usage" by running without parameters.
570 purpose: do read() syscall
571 parameters: see "usage" by running without parameters.
572 written in: C (source not included)
575 purpose: do write() syscall (new version of wf)
576 parameters: see "usage" by running without parameters.
577 written in: C (source not included)
580 purpose: do write() syscall
581 parameters: see "usage" by running without parameters.
582 written in: C (source not included)
585 purpose: truncate a file
586 parameters: see "usage" by running without parameters.
587 written in: C (source not included)
590 purpose: do dm_read_invis()
591 parameters: see "usage" by running without parameters.
595 purpose: do dm_write_invis().
596 parameters: see "usage" by running without parameters.
600 purpose: do dm_set_region()
601 parameters: see "usage" by running without parameters.
604 m) set_return_on_destroy
605 purpose: do dm_set_return_on_destroy()
606 parameters: see "usage" by running without parameters.
610 purpose: test memory mapping used by cc during compilation
611 (really a helper file, not a helper function)
614 purpose: test memory mapping by using it to copy a file
615 parameters: source pathname, destination pathname
616 written in: C (source not included)
619 purpose: test dm_get_allocinfo by using it to dump
620 a list of file extents, much like to xfs_bmap.
621 parameters: see "usage" by running without parameters
625 purpose: fill a filesystem, using memory-mapped i/o
626 parameters: pathname of target file
630 purpose: create a hole-filled file, using wf
631 parameters: path to "bindir", pathname of target file,
632 count of how many holes should be created