1 2 DMAPI Function Verification Test Bucket 3 4 I. Test Bucket Introduction 5 6 This test bucket tests the interfaces and events defined in the CAE 7 Specification entitled "Systems Management: Data Storage Management (XDSM) 8 API," which was copyrighted in February, 1997 by The Open Group. The test 9 bucket consists of 20 executables containing 1097 variations which test 59 of 10 67 published DMAPIs and all JFS-supported events except DM_EVENT_NOSPACE on a 11 functional level. 12 13 II. Test Bucket Contents 14 15 These files provide the test harness: 16 17 dm_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 20 dm_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 24 dm_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) 30 dm_test.c : Define functions and variables common to all DMAPI test cases 31 32 These files provide the test scenarios: 33 34 attr.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 38 config.c : Tests dm_get_config 39 disp.c : Tests dm_get_config_events, dm_set_disp, dm_getall_disp, 40 dm_set_eventlist and dm_get_eventlist 41 event.c : Tests dm_get_events, dm_respond_event, dm_move_event and 42 dm_pending 43 event_am.c : Tests DM_EVENT_ATTRIBUTE, DM_EVENT_CLOSE, DM_EVENT_DESTROY 44 and dm_set_return_on_destroy 45 event_an.c : Tests DM_EVENT_POSTCREATE, DM_EVENT_POSTREMOVE, 46 DM_EVENT_POSTRENAME, DM_EVENT_POSTSYMLINK and 47 DM_EVENT_POSTLINK 48 event_sd.c : Tests DM_EVENT_READ, DM_EVENT_WRITE and DM_EVENT_TRUNCATE 49 event_sn.c : Tests DM_EVENT_CREATE, DM_EVENT_REMOVE, DM_EVENT_RENAME, 50 DM_EVENT_SYMLINK and DM_EVENT_LINK 51 event_us.c : Tests DM_EVENT_USER, dm_create_userevent, dm_send_msg and 52 dm_find_eventmsg 53 handle.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 59 hole.c : Tests dm_get_allocinfo, dm_probe_hole and dm_punch_hole 60 invis.c : Tests dm_read_invis and dm_write_invis 61 mmap.c : Tests DM_EVENT_READ and DM_EVENT_WRITE 62 mmapfile.c : Helper for mmap, invokes mmap() from a different process 63 mount.c : Tests dm_get_mountinfo 64 objref.c : Tests dm_obj_ref_hold, dm_obj_ref_rele and dm_obj_ref_query 65 pmr_pre.c : Tests dm_set_region 66 pmr_post.c : Tests dm_get_region 67 right.c : Tests dm_request_right, dm_release_right, dm_query_right, 68 dm_upgrade_right and dm_downgrade_right 69 session.c : Tests dm_create_session, dm_destroy_session, 70 dm_getall_sessions and dm_query_session 71 token.c : Tests dm_getall_tokens 72 73 These scripts execute the test scenarios: 74 75 runtest_off.sh : Executes test scenarios that must be run off the DM-enabled 76 file system (any directory is fine) 77 runtest_on.sh : Executes test scenarios that must be run from the root 78 directory of the DM-enabled file system 79 80 Other file(s): 81 82 README : You're looking at it 83 Makefile : 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 88 III. Test Bucket Omissions 89 90 This test bucket does not test the following DMAPIs because they are not 91 supported 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 99 This test bucket does not fully test the following DMAPIs because they are not 100 fully supported by the originating platform (JFS); in other words, these tests 101 will probably need further variations to fully test their functionality as the 102 current 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 113 IV. Test Bucket Execution 114 115 To run this test bucket against a DMAPI-enabled partition, make sure the 116 DMAPI 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 168 V. Test Case Format 169 170 The 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 186 VI. Test Case Options 187 188 Following this format will allow the tester to be able to run a variation 189 individually as the variation both initializes and terminates itself. Current 190 options 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 206 Options and corresponding option values MUST be separated by whitespace. Any 207 unrecognized option (that is, one starting with a dash such as -devname) and 208 its option value can be obtained by using the DMOPT_GET macro (such as 209 DMOPT_GET("devname")). 210 211 VII. Test Case Output 212 213 Each line of output generated by the DMLOG_PRINT macro is prefixed with: 214 215 [prog pid level] 216 217 where: 218 prog is the name of the test program 219 pid is the decimal process identifier 220 level is the decimal logging level 221 222 VIII. Test Case Notes 223 224 The test bucket contains several multithreaded test cases where one thread is 225 responsible for generating DMAPI events while the other is responsible for 226 receiving said events and communicating back to the generating thread what was 227 or was not received. At first semaphores were used to control thread execution 228 but this lead to several deadlocks when expected events did not arrive, so 229 delays (EVENT_DELIVERY_DELAY macro) were used. This could lead to timing 230 issues on some platforms, so if a variation fails make sure to check the log 231 to see if the event arrived after the generating thread checked for its 232 arrival. 233 234 IX. Implementation-dependent Notes 235 236 1) 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
