2 # Copyright (c) 2000-2001 Silicon Graphics, Inc. All Rights Reserved.
11 A) Extracting from DMAPI_test.cpio
13 1) Create a new directory for storing the tests. We will refer to
14 this as the "base" directory. The base directory can be
15 located anywhere; it does NOT need to be in a DMAPI filesystem.
17 2) Move the archive file DMAPI_test.cpio to the base directory
18 and execute the following command to extract from the archive:
20 cpio -icvd < DMAPI_test.cpio
22 3) There should now be several files and subdirectories in the base
23 directory, including the file "file_list". Read this file for a
24 complete listing of which files should be present in which
25 directories. Compare "file_list" with the output of "ls -Rpl"
26 to be sure that you have the necessary files.
28 4) The base directory contains the files and programs that are of
29 immediate use for testing. The "bindir" subdirectory contains
30 the test programs and datafiles. The "lib" and "src" subdirectories
31 contain C libraries and source code for the C programs.
33 B) Checking the Existence and Version of DMAPI
35 The program check_dmapi can verify that you have the correct
36 version of DMAPI installed. NOTE: it can only be run as root.
37 Execute this command (from the "base" directory):
41 It should report that you have a current version of DMAPI. If it
42 does not, it will also suggest which components of your DMAPI are
43 not current, and where to find a patch to update them.
47 1) Creating the Test Directories
49 a) The Test Filesystem
51 Mount a DMAPI filesystem, or use an existing one.
52 This filesystem's mount info MUST be listed in /etc/fstab.
54 Write down the path to this filesystem's mountpoint, and label
55 it as "m_main" for future use.
57 b) The Main Test Directory
59 Create a new directory in the "m_main" filesystem.
61 Write down the path to this directory. Note ONLY the part
62 that comes AFTER "m_main". Label this as "d_name".
64 EXAMPLE: You have a DMAPI filesystem /dmi_main
65 You name the test directory /dmi_main/test_dir
69 c) The Cross-NFS Test Directories
71 For NFS tests, all you must do is create two empty directories
72 (one for nfs2, one for nfs3). They do NOT need to be in a
75 Your main test directory will be mounted across NFS, into these
76 two directories. Normally, the tests will do this automatically.
77 However, if you need to do this mount manually, the command
78 would look like this example:
80 mount -t nfs2 localhost:/dmi_main /dmi_nfs2
82 Write down the paths to these nfs2 and nfs3 test directories.
83 Label them "m_nfs2" and "m_nfs3" respectively.
85 c) The Realtime Test Filesystem and Directory
87 If you wish to test realtime i/o, you'll need a filesystem
88 mounted with a realtime partition, and a directory in that
91 Label the path to the filesystem mountpoint as "m_rt".
92 Label the path to the test directory as "d_rt".
94 2) Configuring menu_test
96 The Korn-shell script named menu_test is an interface to the
97 other test programs. At the beginning of the script, there
98 is a "configuration section", in which is sets several variables
99 for use in the rest of the script.
101 Open menu_test in any text editor and change the following
102 variable assignments in the configuration section:
105 Set this to the pathname of your "base" directory
106 (where you un-archived "DMAPI_test.cpio").
109 Tests that do not run as root will run as this "primary" user.
110 Set this to any username.
113 The mountpoint of the main test filesystem.
114 Set this to the value of "m_main" that you wrote down above.
117 m_main concatenated with d_name is the main test directory path.
118 Set this to the value for "d_name" that you wrote down above.
121 The mountpoint of the nfs2 test filesystem.
122 Set this to the value of "m_nfs2" that you wrote down above.
125 The mountpoint of the nfs3 test filesystem.
126 Set this to the value of "m_nfs3" that you wrote down above.
129 The mountpoint of the realtime test filesystem.
130 Set this to the value of "m_rt" that you wrote down above.
133 The path to the realtime test directory.
134 Set this to the value of "d_rt" that you wrote down above.
136 3) Configuring "DMAPI_aliases"
138 This is an optional alternative to the menu interface. It runs
139 as a Korn shell "dot" script and creates an alias to each test.
140 It was made for those who wish to run tests directly from the
143 DMAPI_aliases has exactly the same configuration section as
144 menu_test. If you wish to use DMAPI_aliases, make the same
145 changes to its configuration section.
147 II) Running the Tests
149 A) Using "menu_test" to run tests
151 1) You must be superuser, using the Korn shell, to run menu_test.
152 You also must have adjusted the variables in menu_test's
153 "configuration section", as was explained above.
155 2) menu_test is (surprise!) menu based. Choose options by entering
158 3) The names of the menu options explain which DMAPI functions
159 or DMAPI events are being tested. Some of the options, labeled
160 accordingly, run more than one test programs.
162 4) See section SECTION# for a list of the test scripts and programs,
163 and a brief explanation of each script or program's function.
165 B) Using "DMAPI_aliases" to run tests
167 1) NOTE: The aliases in DMAPI_aliases are meant to be used by
168 those who are familiar with the test programs and wish to run
169 them more directly. [Designer's note: I included the alias
170 file more out of nostalgia than necessity.]
172 2) You should be superuser, using the Korn shell, to run DMAPI_aliases.
173 You also must have adjusted the variables in DMAPI_aliases's
174 "configuration section", as was explained above.
176 3) DMAPI_aliases should be invoked as a Korn shell "dot" script:
180 It sets an alias for each test program; each alias begins with
181 the characters "do_" and is followed by some appropriate name.
182 Read DMAPI_aliases, or execute "alias | grep do", to
185 In the menu of function tests, one of the options is an on/off
186 toggle of "verbose mode". When verbose mode is on, the function
187 tests will print semi-explanatory output. Verbose mode affects
188 only the function tests (this does include check_dmapi).
190 5) "Pausing after each command"
191 In the menu of event tests, one of the options is a toggle of
192 "pausing after each command". When this is on, the event tests
193 will pause for a carriage return after running each command.
194 This affects only the event tests.
196 C) Running tests directly
198 1) For the VERY adventurous, all the tests in the "bindir" directory
199 can be run directly from the command line. Only some of the files
200 in "bindir" are test scripts/programs. Read section III for a list
201 of function tests and section IV for a list of run_test (.dat)
204 2) Running a test program without parameters will produce a list of
205 correct options. (The exception to this is check_dmapi, which
206 normally has no parameters. check_dmapi takes only one option,
207 [-v] for verbose output.)
209 3) It is suggested that you read a program's source before running
210 it directly. (The source of the C programs is included in the
211 "src" directory.) Specifically, in each source file, an initial
212 comment explains the program's options/parameters in detail.
214 III) DMAPI Function tests:
216 This section offers a terse description of the DMAPI function tests.
217 For those tests written in C, the source code is given in the "src"
218 directory. The ksh scripts can, of course, be read directly.
219 In all cases except check_dmapi, running the program without
220 parameters will produce a list of correct options.
224 Test of: presence (and correct version) of DMAPI library and kernel.
225 Options: [-v] flag for verbose output.
229 Test of: dm_get_dmattr, dm_set_dmattr, dm_remove_dmattr.
233 Test of: various bad function calls that should generate EFAULT,
234 according to the DMAPI specification.
238 Test of: dm_get_eventlist, dm_set_eventlist.
242 Test of: dm_get_fileattr, dm_set_fileattr,
243 dm_get_dirattrs, dm_get_bulkattr.
247 Test of: dm_probe_hole, dm_punch_hole.
251 Test of: dm_read_invis, dm_write_invis.
255 Test of: dm_get_region, dm_set,region.
259 Test of: various bad function calls that should generate EACCES,
260 and other conditions pertaining to DMAPI rights.
264 Test of: dm_get_allocinfo.
268 Test of: dm_get_allocinfo.
270 IV) DMAPI Event tests and the "run_test" ksh script
272 A) How to use the "run_test" script
274 1) A quick description of run_test's behavior:
275 run_test invokes a DMAPI daemon (as a ksh coprocess). It then
276 proceeds in a loop, in which it reads a command from a "testfile",
277 executes that command, reads a description of expected events from
278 the testfile, and compares the expected events with the actual
279 events, as returned by the DMAPI daemon.
281 2) You must be superuser, using the Korn shell, to execute run_test.
283 3) Executing run_test without parameters will produce a list of
284 correct options. For a much more in-depth explanation of the
285 options to run_test, read its own initial comment.
287 B) The existing .dat testfiles
290 Tests the events from: a user trying to access files owned
291 by someone else (in this case, root).
294 Tests the events from: events getting DM_RESP_ABORT, dm_send_msg(),
295 invisible i/o, and direct i/o.
298 Tests the events from: events getting DM_RESP_ABORT over nfs,
302 Tests the events from: running dm_pending() while trying to
306 Tests the events from: running dm_pending() while trying to
307 do standard i/o over NFS
310 Tests the events from: Invisible, direct, and standard i/o
311 on realtime files in a realtime filesystem.
314 Tests the events from: Slow i/o due to a small event queue.
317 Tests the events from: various kinds of standard i/o,
318 memory-mapped i/o and remounting the filesystem.
321 Tests the events from: various kinds of standard i/o, over NFS.
323 C) How to write new ".dat" testfiles
327 A testfile contains a complete description of a DMAPI event test.
328 Testfiles are divided into sections: the first two contain
329 test initialization, while the remaining sections each contain ONE
330 command, followed by a list of expected events.
332 The following is a description of testfile syntax. If you wish to
333 fully understand testfile syntax, PLEASE examine the existing
334 testfiles and the "run_test" script.
336 2) Event information variables
338 a) From the daemon, "run_test" gets information about DMAPI events.
339 This information is stored in event information variables.
341 b) NOTE: event information variables are not persistent.
342 After "run_test" has compared the expected and actual events
343 for a command, and before it executes the next command, it
344 unsets the values of all these variables.
346 c) Most of these variables are arrays, indexed by the number of
347 the event (starting with 0). For example, if the initial event
348 is a read event, then we have "event[0]" set to "read", and
349 "file_handle[0]" set to the handle of whatever file was read.
351 d) "event_count" is a special variable. It holds the number of
352 events that were generated by the most recent command.
354 e) These are all the event information variables:
356 contents event event_count fs_handle handle length
357 offset media_designator mode mountpoint_handle
358 mountpoint_path msg_str name new_name new_parent
359 parent_handle ret_code root_handle sequence token
360 tries_left unmount_mode
362 f) PLEASE examine the run_test script to see which variables
363 are set by which events. (The scheme corresponds, roughly,
364 to the "Event Types" section of the DMAPI specification.)
366 3) Testfile section 1: List of required files
368 a) A testfile's first section is a list of the files it requires.
369 If these files are not present in the "bindir" directory,
370 "run_test" will abort the test and inform the user of which
373 b) Each line of this section may contain ANY NUMBER of filenames.
375 c) Lines beginning with // will be treated as comments. The
376 entirety of such lines will be ignored.
378 d) The last line of this section should begin with three hyphens
379 --- Other characters on that line will be ignored.
381 4) Testfile section 2: Initialization commands
383 a) A testfile's second section consists of a list of commands.
384 "run_test" will execute these commands before starting the
385 DMAPI daemon. Any necessary initialization should be done
388 b) Each line of this section should be ONE shell command.
390 c) Lines beginning with // will be treated as comments.
391 The entirety of such lines will be ignored.
393 d) The last line of this section should begin with three hyphens
394 "---" Other characters on that line will be ignored.
396 5) Testfile sections 3 and on: Individual tests
398 a) The remaining sections of a testfile consist of a single
399 shell command, followed by descriptions of events that should
400 be generated by the command.
404 1) Comments are valid ONLY before the command.
406 2) Lines beginning with // will be treated as comments.
407 The entirety of such lines will be ignored.
409 3) Lines beginning with @@ will be treated as "print" comments.
410 Such lines will not be parsed, but they will be printed to
411 standard output during the test. This is useful for
412 describing what each test does.
414 c) Valid grammar for the command itself
416 1) Standard command syntax:
417 This should be ONE shell command, on a line by itself.
419 2) Alternate command syntax:
421 If the test is preceded by the metacommand "run_as_root"
422 (on a line by itself) then the command will be run as
423 root rather than as "p_user". The command should still
424 be one command on a line by itself.
427 If the test is preceded by the metacommand
428 "run_without_test" (on a line by itself), then ALL
429 subsequent lines in the section will be executed as
430 commands, and NO testing will be performed. Note that
431 the commands will be executed as root. This is useful
432 for re-initialization sections during a test.
433 NOTE: A testfile cannot end with a "run_without_test"
434 section. The last section must contain a test.
436 d) Valid grammar for the "expected events" lines
438 1) [variable_name] [value]
439 This specifies that the variable [variable_name] should be
442 2) [variable_name_1] matches [variable_name_2]
443 This specifies that both variables should be set to
444 the same value. A list of valid variables
446 3) [variable_name] store_in [string]
447 This specifies that the contents of [variable_name]
448 should be stored in a variable named [string].
449 The variable [string] can then be referenced as a
450 variable in later tests.
452 EXAMPLE: if two commands deal with the file "foobar",
453 you might want to check that they both use the same handle.
454 In the first section, write
455 "handle[0] store_in old_handle_0"
456 In the second section, write
457 "old_handle_0 matches handle[0]"
460 This specifies that the command is expected to fail
461 (return some non-zero exit status). If "failure"
462 is not specified, the command is expected to succeed.
464 e) The last line of these sections should begin with three
465 hyphens "---". Other characters on that line will be ignored.
467 6) Sending messages to the DMAPI daemon
470 Normally, run_test only reads from the DMAPI daemon, and never
471 sends messages back. However, sometimes we need the daemon to
472 execute some function or change its behavior in some way. This
473 is accomplished by calling "send_msg" as a command in the
474 testfile. The test daemon has been coded to respond to the
475 following user events generated by send_msg:
478 Replace X here with an integer, as in "send_msg unfriendly_6".
479 This causes the daemon to respond to all messages (other than
480 user events) with DM_RESP_ABORT instead of DM_RESP_CONTINUE,
481 and with errno X. If the message is just "unfriendly", the
482 default errno is EBADMSG.
485 This returns the test_daemon to normal operation after it
486 was set to be "unfriendly".
489 Replace X and Y with integers, as in "send_msg countdown_6_8".
490 This causes the daemon to respond to the next X messages (other
491 than user events) with DM_RESP_ABORT instead of DM_RESP_CONTINUE,
492 and with errno Y. If the message is just "countdown", the
493 default count is 5 and the default errno is EAGAIN.
496 Replace X here with an integer, as in "send_msg pending_4".
497 This causes the daemon to call dm_pending() rather than
498 responding to the next X messages. If the message is just
499 "pending", the default count is 1. After the count reaches
500 zero, the messages will be responded to.
503 This message MUST be sent after remounting the test filesystem.
504 It causes the daemon to re-register for all events.
507 This message is sent by run_test itself, and should not be
508 sent in a testfile. "send_msg over" is called after each
509 command is executed, as an indicator that the batch of events
510 from that command is complete. When run_test sees a user
511 event with the data "over", it knows to stop reading events
512 and move on to the next command.
514 7) Other "helper functions" for testfiles
516 a) ctf (create test files)
517 purpose: creates 20 copies of "bindir/ls_to_copy".
518 parameters: location of "bindir", location of target directory.
521 b) crttf (create realtime test files)
522 purpose: creates 10 realtime files.
523 parameters: location of "bindir", location of target directory.
526 c) stf (setup test files)
527 purpose: set dm attributes and managed regions on target files.
528 parameters: location of "bindir", pathnames of target files.
532 purpose: do fcntl() syscall
533 parameters: see "usage" by running without parameters.
534 written in: C (source not included)
537 purpose: do open() syscall
538 parameters: see "usage" by running without parameters.
542 purpose: do read() syscall
543 parameters: see "usage" by running without parameters.
544 written in: C (source not included)
547 purpose: do write() syscall (new version of wf)
548 parameters: see "usage" by running without parameters.
549 written in: C (source not included)
552 purpose: do write() syscall
553 parameters: see "usage" by running without parameters.
554 written in: C (source not included)
557 purpose: truncate a file
558 parameters: see "usage" by running without parameters.
559 written in: C (source not included)
562 purpose: do dm_read_invis()
563 parameters: see "usage" by running without parameters.
567 purpose: do dm_write_invis().
568 parameters: see "usage" by running without parameters.
572 purpose: do dm_set_region()
573 parameters: see "usage" by running without parameters.
576 m) set_return_on_destroy
577 purpose: do dm_set_return_on_destroy()
578 parameters: see "usage" by running without parameters.
582 purpose: test memory mapping used by cc during compilation
583 (really a helper file, not a helper function)
586 purpose: test memory mapping by using it to copy a file
587 parameters: source pathname, destination pathname
588 written in: C (source not included)
591 purpose: test dm_get_allocinfo by using it to dump
592 a list of file extents, much like to xfs_bmap.
593 parameters: see "usage" by running without parameters
597 purpose: fill a filesystem, using memory-mapped i/o
598 parameters: pathname of target file
602 purpose: create a hole-filled file, using wf
603 parameters: path to "bindir", pathname of target file,
604 count of how many holes should be created