common/rc: factor out _scratch_xfs_[get|set]_sb_field
[xfstests-dev.git] / dmapi / src / suite2 / README
1 #
2 # Copyright (c) 2000-2001 Silicon Graphics, Inc.  All Rights Reserved.
3 #
4
5                            DMAPI Test Suite 
6                           Informational File
7                           ------------------
8
9 I) Getting Started
10
11    A) Extracting from DMAPI_test.cpio
12
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.
16
17       2) Move the archive file DMAPI_test.cpio to the base directory
18          and execute the following command to extract from the archive:
19  
20              cpio -icvd < DMAPI_test.cpio 
21
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.
27
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. 
32
33    B) Checking the Existence and Version of DMAPI
34  
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):
38  
39       bindir/check_dmapi
40  
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.
44
45    C) Configuration
46
47       1) Creating the Test Directories
48
49          a) The Test Filesystem
50  
51             Mount a DMAPI filesystem, or use an existing one.
52             This filesystem's mount info MUST be listed in /etc/fstab.
53  
54             Write down the path to this filesystem's mountpoint, and label
55             it as "m_main" for future use.
56  
57          b) The Main Test Directory
58             
59             Create a new directory in the "m_main" filesystem. 
60  
61             Write down the path to this directory.  Note ONLY the part
62             that comes AFTER "m_main".  Label this as "d_name".
63  
64             EXAMPLE: You have a DMAPI filesystem /dmi_main  
65                      You name the test directory /dmi_main/test_dir
66             "m_main" is /dmi_main 
67             "d_name" is /test_dir
68  
69          c) The Cross-NFS Test Directories 
70  
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 
73             DMAPI filesystem.  
74  
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:
79  
80             mount -t nfs2 localhost:/dmi_main /dmi_nfs2
81  
82             Write down the paths to these nfs2 and nfs3 test directories.
83             Label them "m_nfs2" and "m_nfs3" respectively.
84  
85          c) The Realtime Test Filesystem and Directory
86  
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
89             filesystem.  
90  
91             Label the path to the filesystem mountpoint as "m_rt".
92             Label the path to the test directory as "d_rt".
93  
94       2) Configuring menu_test
95  
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.  
100          
101          Open menu_test in any text editor and change the following
102          variable assignments in the configuration section:
103  
104          a) base_dir:
105             Set this to the pathname of your "base" directory 
106             (where you un-archived "DMAPI_test.cpio").
107  
108          b) p_user:
109             Tests that do not run as root will run as this "primary" user.
110             Set this to any username. 
111  
112          c) m_main:
113             The mountpoint of the main test filesystem.
114             Set this to the value of "m_main" that you wrote down above.  
115   
116          d) d_name:  
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.
119  
120          e) m_nfs2:  
121             The mountpoint of the nfs2 test filesystem.
122             Set this to the value of "m_nfs2" that you wrote down above.
123  
124          f) m_nfs2:   
125             The mountpoint of the nfs3 test filesystem.
126             Set this to the value of "m_nfs3" that you wrote down above.
127  
128          g) m_rt:   
129             The mountpoint of the realtime test filesystem.
130             Set this to the value of "m_rt" that you wrote down above.
131  
132          h) d_rt:   
133             The path to the realtime test directory.
134             Set this to the value of "d_rt" that you wrote down above.
135  
136       3) Configuring "DMAPI_aliases"
137  
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
141          command line.
142  
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. 
146  
147 II) Running the Tests
148
149    A) Using "menu_test" to run tests
150
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.
154
155       2) menu_test is (surprise!) menu based.  Choose options by entering
156          their numbers.    
157  
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.
161
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.  
164
165    B) Using "DMAPI_aliases" to run tests   
166
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.]
171       
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.
175
176       3) DMAPI_aliases should be invoked as a Korn shell "dot" script:
177
178          . ./DMAPI_aliases 
179
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 
183
184       4) "Verbose mode"
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).
189
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.
195
196    C) Running tests directly
197
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)
202          testfiles.
203
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.)
208
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.
213
214 III) DMAPI Function tests:
215      
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. 
221   
222    A) check_dmapi
223       Written in: C 
224       Test of: presence (and correct version) of DMAPI library and kernel.  
225       Options: [-v] flag for verbose output.
226  
227    B) test_dmattr
228       Written in: C 
229       Test of: dm_get_dmattr, dm_set_dmattr, dm_remove_dmattr.
230
231    C) test_efault
232       Written in: C 
233       Test of: various bad function calls that should generate EFAULT,
234                according to the DMAPI specification.
235
236    D) test_eventlist
237       Written in: C 
238       Test of: dm_get_eventlist, dm_set_eventlist.
239
240    E) test_fileattr
241       Written in: C 
242       Test of: dm_get_fileattr, dm_set_fileattr,
243                dm_get_dirattrs, dm_get_bulkattr.
244
245    F) test_hole
246       Written in: C 
247       Test of: dm_probe_hole, dm_punch_hole.
248
249    G) test_invis
250       Written in: C 
251       Test of: dm_read_invis, dm_write_invis.
252
253    H) test_region
254       Written in:  C 
255       Test of: dm_get_region, dm_set,region.
256
257    I) test_rights
258       Written in: C 
259       Test of: various bad function calls that should generate EACCES,
260                and other conditions pertaining to DMAPI rights.
261
262    J) test_allocinfo_1
263       Written in: ksh
264       Test of: dm_get_allocinfo.  
265
266    K) test_allocinfo_2
267       Written in: ksh
268       Test of: dm_get_allocinfo.
269
270 IV) DMAPI Event tests and the "run_test" ksh script
271
272    A) How to use the "run_test" script
273
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.
280
281       2) You must be superuser, using the Korn shell, to execute run_test.
282
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.      
286
287    B) The existing .dat testfiles
288
289       1) fail.dat
290          Tests the events from: a user trying to access files owned
291          by someone else (in this case, root). 
292
293       2) main.dat
294          Tests the events from: events getting DM_RESP_ABORT, dm_send_msg(),
295          invisible i/o, and direct i/o.
296
297       3) nfs.dat
298          Tests the events from: events getting DM_RESP_ABORT over nfs,
299          EAGAIN over nfs.
300
301       4) pending.dat
302          Tests the events from: running dm_pending() while trying to 
303          do standard i/o.
304
305       5) pending_nfs.dat
306          Tests the events from: running dm_pending() while trying to
307          do standard i/o over NFS
308
309       6) realtime.dat
310          Tests the events from: Invisible, direct, and standard i/o
311          on realtime files in a realtime filesystem.
312
313       7) smallq.dat
314          Tests the events from: Slow i/o due to a small event queue.
315
316       8) standard.dat
317          Tests the events from: various kinds of standard i/o, 
318          memory-mapped i/o and remounting the filesystem.
319
320       9) standard_nfs.dat
321          Tests the events from: various kinds of standard i/o, over NFS.
322
323    C) How to write new ".dat" testfiles
324       
325       1) Overview
326
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.
331
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.
335
336       2) Event information variables
337          
338          a) From the daemon, "run_test" gets information about DMAPI events.
339             This information is stored in event information variables.  
340
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.
345
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.
350
351          d) "event_count" is a special variable.  It holds the number of
352             events that were generated by the most recent command.   
353
354          e) These are all the event information variables:
355
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
361
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.)
365
366       3) Testfile section 1:  List of required files
367
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 
371             files are missing.  
372          
373          b) Each line of this section may contain ANY NUMBER of filenames.
374
375          c) Lines beginning with // will be treated as comments.  The
376             entirety of such lines will be ignored.
377           
378          d) The last line of this section should begin with three hyphens
379             ---  Other characters on that line will be ignored. 
380
381       4) Testfile section 2:  Initialization commands
382          
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 
386             here. 
387
388          b) Each line of this section should be ONE shell command.
389
390          c) Lines beginning with // will be treated as comments.  
391             The entirety of such lines will be ignored.
392           
393          d) The last line of this section should begin with three hyphens
394             "---"  Other characters on that line will be ignored.
395
396       5) Testfile sections 3 and on:  Individual tests
397
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.  
401             
402          b) Comments
403
404             1) Comments are valid ONLY before the command. 
405
406             2) Lines beginning with // will be treated as comments.  
407                The entirety of such lines will be ignored.
408
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.
413
414          c) Valid grammar for the command itself
415
416             1) Standard command syntax: 
417                This should be ONE shell command, on a line by itself.  
418                
419             2) Alternate command syntax:
420                A) run_as_root:  
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.
425
426                B) run_without_test:
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. 
435
436          d) Valid grammar for the "expected events" lines
437
438             1) [variable_name] [value]
439                This specifies that the variable [variable_name] should be
440                set to [value].  
441
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
445
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.
451    
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]" 
458
459             4) failure
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.
463             
464          e) The last line of these sections should begin with three
465             hyphens "---".  Other characters on that line will be ignored.
466  
467       6) Sending messages to the DMAPI daemon
468
469          a) Overview
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:
476             
477          b) unfriendly_X
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.
483
484          c) friendly
485             This returns the test_daemon to normal operation after it
486             was set to be "unfriendly".  
487
488          d) countdown_X_Y
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.
494
495          e) pending_X
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.
501
502          f) reset_fs
503             This message MUST be sent after remounting the test filesystem.
504             It causes the daemon to re-register for all events.
505
506          g) over
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.
513
514       7) Other "helper functions" for testfiles
515
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.
519             written in: ksh
520
521          b) crttf  (create realtime test files)
522             purpose: creates 10 realtime files.
523             parameters: location of "bindir", location of target directory.
524             written in: ksh
525
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.
529             written in: ksh
530
531          d) fcntl 
532             purpose: do fcntl() syscall
533             parameters: see "usage" by running without parameters.
534             written in: C (source not included)
535
536          e) open_test 
537             purpose: do open() syscall 
538             parameters: see "usage" by running without parameters.
539             written in: C 
540
541          f) rd  
542             purpose: do read() syscall 
543             parameters: see "usage" by running without parameters.
544             written in: C (source not included)
545
546          g) new_wf 
547             purpose: do write() syscall  (new version of wf)
548             parameters: see "usage" by running without parameters.
549             written in: C (source not included)
550
551          h) wf 
552             purpose: do write() syscall
553             parameters: see "usage" by running without parameters.
554             written in: C (source not included)
555
556          i) truncate 
557             purpose: truncate a file
558             parameters: see "usage" by running without parameters.
559             written in: C (source not included)
560
561          j) read_invis
562             purpose: do dm_read_invis()
563             parameters: see "usage" by running without parameters.
564             written in: C
565
566          k) write_invis
567             purpose: do dm_write_invis(). 
568             parameters: see "usage" by running without parameters.
569             written in: C
570
571          l) set_region
572             purpose: do dm_set_region()
573             parameters: see "usage" by running without parameters.
574             written in: C
575
576          m) set_return_on_destroy
577             purpose: do dm_set_return_on_destroy()
578             parameters: see "usage" by running without parameters.
579             written in: C 
580
581          n) ctest.c
582             purpose: test memory mapping used by cc during compilation 
583                      (really a helper file, not a helper function)
584
585          o) mmap_cp
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)
589
590          p) dump_allocinfo
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
594             written in: C 
595
596          q) mm_fill
597             purpose: fill a filesystem, using memory-mapped i/o
598             parameters: pathname of target file
599             written in: C 
600
601          r) make_holey
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
605             written in: ksh