DMAPI Function Verification Test Bucket I. Test Bucket Introduction This test bucket tests the interfaces and events defined in the CAE Specification entitled "Systems Management: Data Storage Management (XDSM) API," which was copyrighted in February, 1997 by The Open Group. The test bucket consists of 20 executables containing 1097 variations which test 59 of 67 published DMAPIs and all JFS-supported events except DM_EVENT_NOSPACE on a functional level. II. Test Bucket Contents These files provide the test harness: dm_test.h : Defines macros and constants common to all DMAPI test cases; some of the constants may be platform-dependent and should be reviewed prior to running the test bucket on a new platform dm_vars.h : Defines variation number bases for all DMAPI test cases; theoretically these could all be zero, but the author believes that giving every variation a unique number makes it much easier when discussing successes/failures dm_impl.h : Define implementation-dependent functions and variables common to all DMAPI test cases; these must be modified prior to running the test bucket on a new platform (note: although this is a .h file, it is really a .c file that is included by dm_test.c and is separated to make it easier to port to new platforms) dm_test.c : Define functions and variables common to all DMAPI test cases These files provide the test scenarios: attr.c : Tests dm_set_dmattr, dm_get_dmattr, dm_remove_dmattr, dm_getall_dmattr, dm_set_fileattr, dm_get_fileattr, dm_get_dirattrs, dm_set_inherit, dm_clear_inherit and dm_getall_inherit config.c : Tests dm_get_config disp.c : Tests dm_get_config_events, dm_set_disp, dm_getall_disp, dm_set_eventlist and dm_get_eventlist event.c : Tests dm_get_events, dm_respond_event, dm_move_event and dm_pending event_am.c : Tests DM_EVENT_ATTRIBUTE, DM_EVENT_CLOSE, DM_EVENT_DESTROY and dm_set_return_on_destroy event_an.c : Tests DM_EVENT_POSTCREATE, DM_EVENT_POSTREMOVE, DM_EVENT_POSTRENAME, DM_EVENT_POSTSYMLINK and DM_EVENT_POSTLINK event_sd.c : Tests DM_EVENT_READ, DM_EVENT_WRITE and DM_EVENT_TRUNCATE event_sn.c : Tests DM_EVENT_CREATE, DM_EVENT_REMOVE, DM_EVENT_RENAME, DM_EVENT_SYMLINK and DM_EVENT_LINK event_us.c : Tests DM_EVENT_USER, dm_create_userevent, dm_send_msg and dm_find_eventmsg handle.c : Tests dm_path_to_handle, dm_fd_to_handle, dm_path_to_fshandle, dm_handle_to_fshandle, dm_handle_cmp, dm_handle_free, dm_handle_is_valid, dm_handle_hash, dm_handle_to_fsid, dm_handle_to_igen, dm_handle_to_ino, dm_make_handle, dm_make_fshandle, dm_handle_to_path and dm_sync_by_handle hole.c : Tests dm_get_allocinfo, dm_probe_hole and dm_punch_hole invis.c : Tests dm_read_invis and dm_write_invis mmap.c : Tests DM_EVENT_READ and DM_EVENT_WRITE mmapfile.c : Helper for mmap, invokes mmap() from a different process mount.c : Tests dm_get_mountinfo objref.c : Tests dm_obj_ref_hold, dm_obj_ref_rele and dm_obj_ref_query pmr_pre.c : Tests dm_set_region pmr_post.c : Tests dm_get_region right.c : Tests dm_request_right, dm_release_right, dm_query_right, dm_upgrade_right and dm_downgrade_right session.c : Tests dm_create_session, dm_destroy_session, dm_getall_sessions and dm_query_session token.c : Tests dm_getall_tokens These scripts execute the test scenarios: runtest_off.sh : Executes test scenarios that must be run off the DM-enabled file system (any directory is fine) runtest_on.sh : Executes test scenarios that must be run from the root directory of the DM-enabled file system Other file(s): README : You're looking at it Makefile : Builds the test harness and scenario; the platform must be defined (i.e. JFS) to build the proper stuff in dm_impl.c, and other constants as necessary to build the proper support (i.e. MULTIPLE_REGIONS) III. Test Bucket Omissions This test bucket does not test the following DMAPIs because they are not supported by the originating platform (JFS): dm_create_by_handle dm_get_bulkall dm_get_bulkattr dm_mkdir_by_handle dm_symlink_by_handle This test bucket does not fully test the following DMAPIs because they are not fully supported by the originating platform (JFS); in other words, these tests will probably need further variations to fully test their functionality as the current variations only test the skeleton support provided by JFS: dm_clear_inherit dm_downgrade_right dm_getall_inherit dm_query_right dm_release_right dm_request_right dm_set_inherit dm_upgrade_right IV. Test Bucket Execution To run this test bucket against a DMAPI-enabled partition, make sure the DMAPI implementation (kernel and user space code) is installed on the system (see Implementation-dependent Notes below) and follow these steps: 1) Untar the tarball in a directory NOT on a DMAPI-enabled partition: tar -xvf dm_test.tar 2) Make the test bucket: make NOTE: Modify dmapi_lib in Makefile to point to the user space library for the DMAPI implementation to be tested 3) If the file system is compiled as a module, make sure it is installed first: modprobe blah 4) Run the test cases that require NOT being on a DMAPI-enabled partition: ./runtest_off.sh 5) Check the results of these test cases: grep status *.log 6) Mount the DMAPI-enabled partition: mount -t blah -o blah /dev/hdablah /dmapidir 7) Copy the test bucket to the root of the DMAPI-enabled partition: cp * /dmapidir 8) Make the root of the DMAPI-enabled partition the current directory: cd /dmapidir 9) Remove the copies of the log files just generated: rm -f *.log 10) Run the test cases that require being on a DMAPI-enabled partition: ./runtest_on.sh 11) Check the results of these test cases: grep status *.log V. Test Case Format The general format of a test case using the supplied test harness should be: if (DMVAR_EXEC(variation number)) { set up variation; if (set up variation failed) DMVAR_SKIP(); else { execute variation; if (variation successful) DMVAR_PASS(); else DMVAR_FAIL(); clean up variation; } } VI. Test Case Options Following this format will allow the tester to be able to run a variation individually as the variation both initializes and terminates itself. Current options supported by the test harness are: -runfrom n : Defines the starting variation to begin executing from; sets a variation range to execute when used along with -runto, or runs all variations greater than or equal to n if -runto is not specified -runto n : Defines the stopping variation to end executing at; sets a variation range to execute when used along with -runfrom, or runs all variations less than or equal to n if -runfrom is not specified -runonly n : Executes only variation n -loglevel n : Write all messages less than or equal to n to the log file -termlevel n : Write all messages less than or equal to n to the terminal -logname s : Write all messages defined by -loglevel to the log file named s; if not defined, the default log file name is dm_logfile Options and corresponding option values MUST be separated by whitespace. Any unrecognized option (that is, one starting with a dash such as -devname) and its option value can be obtained by using the DMOPT_GET macro (such as DMOPT_GET("devname")). VII. Test Case Output Each line of output generated by the DMLOG_PRINT macro is prefixed with: [prog pid level] where: prog is the name of the test program pid is the decimal process identifier level is the decimal logging level VIII. Test Case Notes The test bucket contains several multithreaded test cases where one thread is responsible for generating DMAPI events while the other is responsible for receiving said events and communicating back to the generating thread what was or was not received. At first semaphores were used to control thread execution but this lead to several deadlocks when expected events did not arrive, so delays (EVENT_DELIVERY_DELAY macro) were used. This could lead to timing issues on some platforms, so if a variation fails make sure to check the log to see if the event arrived after the generating thread checked for its arrival. IX. Implementation-dependent Notes 1) JFS a) Instructions for installing DMAPI for IBM JFS can be found at http://oss.software.ibm.com/jfs/. b) The test case and user space library must match the architecture of the kernel. In other words, the test case and library must be compiled as 32-bit if running on a 32-bit kernel, and must be compiled as 64-bit if running on a 64-bit kernel. Currently, JFS DMAPI does not support a 32-bit DM app running on a 64-bit kernel.