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.