1 2 DMAPI Function Verification Test Bucket 3 4I. Test Bucket Introduction 5 6This test bucket tests the interfaces and events defined in the CAE 7Specification entitled "Systems Management: Data Storage Management (XDSM) 8API," which was copyrighted in February, 1997 by The Open Group. The test 9bucket consists of 20 executables containing 1097 variations which test 59 of 1067 published DMAPIs and all JFS-supported events except DM_EVENT_NOSPACE on a 11functional level. 12 13II. Test Bucket Contents 14 15These files provide the test harness: 16 17dm_test.h : Defines macros and constants common to all DMAPI test cases; 18 some of the constants may be platform-dependent and should be 19 reviewed prior to running the test bucket on a new platform 20dm_vars.h : Defines variation number bases for all DMAPI test cases; 21 theoretically these could all be zero, but the author 22 believes that giving every variation a unique number makes 23 it much easier when discussing successes/failures 24dm_impl.h : Define implementation-dependent functions and variables 25 common to all DMAPI test cases; these must be modified prior 26 to running the test bucket on a new platform (note: although 27 this is a .h file, it is really a .c file that is included by 28 dm_test.c and is separated to make it easier to port to new 29 platforms) 30dm_test.c : Define functions and variables common to all DMAPI test cases 31 32These files provide the test scenarios: 33 34attr.c : Tests dm_set_dmattr, dm_get_dmattr, dm_remove_dmattr, 35 dm_getall_dmattr, dm_set_fileattr, dm_get_fileattr, 36 dm_get_dirattrs, dm_set_inherit, dm_clear_inherit and 37 dm_getall_inherit 38config.c : Tests dm_get_config 39disp.c : Tests dm_get_config_events, dm_set_disp, dm_getall_disp, 40 dm_set_eventlist and dm_get_eventlist 41event.c : Tests dm_get_events, dm_respond_event, dm_move_event and 42 dm_pending 43event_am.c : Tests DM_EVENT_ATTRIBUTE, DM_EVENT_CLOSE, DM_EVENT_DESTROY 44 and dm_set_return_on_destroy 45event_an.c : Tests DM_EVENT_POSTCREATE, DM_EVENT_POSTREMOVE, 46 DM_EVENT_POSTRENAME, DM_EVENT_POSTSYMLINK and 47 DM_EVENT_POSTLINK 48event_sd.c : Tests DM_EVENT_READ, DM_EVENT_WRITE and DM_EVENT_TRUNCATE 49event_sn.c : Tests DM_EVENT_CREATE, DM_EVENT_REMOVE, DM_EVENT_RENAME, 50 DM_EVENT_SYMLINK and DM_EVENT_LINK 51event_us.c : Tests DM_EVENT_USER, dm_create_userevent, dm_send_msg and 52 dm_find_eventmsg 53handle.c : Tests dm_path_to_handle, dm_fd_to_handle, 54 dm_path_to_fshandle, dm_handle_to_fshandle, dm_handle_cmp, 55 dm_handle_free, dm_handle_is_valid, dm_handle_hash, 56 dm_handle_to_fsid, dm_handle_to_igen, dm_handle_to_ino, 57 dm_make_handle, dm_make_fshandle, dm_handle_to_path and 58 dm_sync_by_handle 59hole.c : Tests dm_get_allocinfo, dm_probe_hole and dm_punch_hole 60invis.c : Tests dm_read_invis and dm_write_invis 61mmap.c : Tests DM_EVENT_READ and DM_EVENT_WRITE 62mmapfile.c : Helper for mmap, invokes mmap() from a different process 63mount.c : Tests dm_get_mountinfo 64objref.c : Tests dm_obj_ref_hold, dm_obj_ref_rele and dm_obj_ref_query 65pmr_pre.c : Tests dm_set_region 66pmr_post.c : Tests dm_get_region 67right.c : Tests dm_request_right, dm_release_right, dm_query_right, 68 dm_upgrade_right and dm_downgrade_right 69session.c : Tests dm_create_session, dm_destroy_session, 70 dm_getall_sessions and dm_query_session 71token.c : Tests dm_getall_tokens 72 73These scripts execute the test scenarios: 74 75runtest_off.sh : Executes test scenarios that must be run off the DM-enabled 76 file system (any directory is fine) 77runtest_on.sh : Executes test scenarios that must be run from the root 78 directory of the DM-enabled file system 79 80Other file(s): 81 82README : You're looking at it 83Makefile : Builds the test harness and scenario; the platform must be 84 defined (i.e. JFS) to build the proper stuff in dm_impl.c, 85 and other constants as necessary to build the proper support 86 (i.e. MULTIPLE_REGIONS) 87 88III. Test Bucket Omissions 89 90This test bucket does not test the following DMAPIs because they are not 91supported by the originating platform (JFS): 92 93 dm_create_by_handle 94 dm_get_bulkall 95 dm_get_bulkattr 96 dm_mkdir_by_handle 97 dm_symlink_by_handle 98 99This test bucket does not fully test the following DMAPIs because they are not 100fully supported by the originating platform (JFS); in other words, these tests 101will probably need further variations to fully test their functionality as the 102current variations only test the skeleton support provided by JFS: 103 104 dm_clear_inherit 105 dm_downgrade_right 106 dm_getall_inherit 107 dm_query_right 108 dm_release_right 109 dm_request_right 110 dm_set_inherit 111 dm_upgrade_right 112 113IV. Test Bucket Execution 114 115To run this test bucket against a DMAPI-enabled partition, make sure the 116DMAPI implementation (kernel and user space code) is installed on the system 117(see Implementation-dependent Notes below) and follow these steps: 118 119 1) Untar the tarball in a directory NOT on a DMAPI-enabled partition: 120 121 tar -xvf dm_test.tar 122 123 2) Make the test bucket: 124 125 make 126 127 NOTE: Modify dmapi_lib in Makefile to point to the user space 128 library for the DMAPI implementation to be tested 129 130 3) If the file system is compiled as a module, make sure it is 131 installed first: 132 133 modprobe blah 134 135 4) Run the test cases that require NOT being on a DMAPI-enabled 136 partition: 137 138 ./runtest_off.sh 139 140 5) Check the results of these test cases: 141 142 grep status *.log 143 144 6) Mount the DMAPI-enabled partition: 145 146 mount -t blah -o blah /dev/hdablah /dmapidir 147 148 7) Copy the test bucket to the root of the DMAPI-enabled partition: 149 150 cp * /dmapidir 151 152 8) Make the root of the DMAPI-enabled partition the current directory: 153 154 cd /dmapidir 155 156 9) Remove the copies of the log files just generated: 157 158 rm -f *.log 159 160 10) Run the test cases that require being on a DMAPI-enabled partition: 161 162 ./runtest_on.sh 163 164 11) Check the results of these test cases: 165 166 grep status *.log 167 168V. Test Case Format 169 170The general format of a test case using the supplied test harness should be: 171 172 if (DMVAR_EXEC(variation number)) { 173 set up variation; 174 if (set up variation failed) 175 DMVAR_SKIP(); 176 else { 177 execute variation; 178 if (variation successful) 179 DMVAR_PASS(); 180 else 181 DMVAR_FAIL(); 182 clean up variation; 183 } 184 } 185 186VI. Test Case Options 187 188Following this format will allow the tester to be able to run a variation 189individually as the variation both initializes and terminates itself. Current 190options supported by the test harness are: 191 192-runfrom n : Defines the starting variation to begin executing from; sets 193 a variation range to execute when used along with -runto, or 194 runs all variations greater than or equal to n if -runto is 195 not specified 196-runto n : Defines the stopping variation to end executing at; sets 197 a variation range to execute when used along with -runfrom, 198 or runs all variations less than or equal to n if -runfrom is 199 not specified 200-runonly n : Executes only variation n 201-loglevel n : Write all messages less than or equal to n to the log file 202-termlevel n : Write all messages less than or equal to n to the terminal 203-logname s : Write all messages defined by -loglevel to the log file named 204 s; if not defined, the default log file name is dm_logfile 205 206Options and corresponding option values MUST be separated by whitespace. Any 207unrecognized option (that is, one starting with a dash such as -devname) and 208its option value can be obtained by using the DMOPT_GET macro (such as 209DMOPT_GET("devname")). 210 211VII. Test Case Output 212 213Each line of output generated by the DMLOG_PRINT macro is prefixed with: 214 215 [prog pid level] 216 217where: 218 prog is the name of the test program 219 pid is the decimal process identifier 220 level is the decimal logging level 221 222VIII. Test Case Notes 223 224The test bucket contains several multithreaded test cases where one thread is 225responsible for generating DMAPI events while the other is responsible for 226receiving said events and communicating back to the generating thread what was 227or was not received. At first semaphores were used to control thread execution 228but this lead to several deadlocks when expected events did not arrive, so 229delays (EVENT_DELIVERY_DELAY macro) were used. This could lead to timing 230issues on some platforms, so if a variation fails make sure to check the log 231to see if the event arrived after the generating thread checked for its 232arrival. 233 234IX. Implementation-dependent Notes 235 2361) JFS 237 a) Instructions for installing DMAPI for IBM JFS can be found at 238 http://oss.software.ibm.com/jfs/. 239 b) The test case and user space library must match the architecture 240 of the kernel. In other words, the test case and library must be 241 compiled as 32-bit if running on a 32-bit kernel, and must be compiled 242 as 64-bit if running on a 64-bit kernel. Currently, JFS DMAPI does 243 not support a 32-bit DM app running on a 64-bit kernel. 244