libtests/block08/block08.doc

0001 bdbuf tests
0002 ~~~~~~~~~~~
0003
0004 Test 1
0005 ~~~~~~
0006
0007 Tests of this group check the behaviour of rtems_bdbuf_read() function
0008 in different situations.
0009
0010 Test 1.1
0011 ~~~~~~~~
0012
0013 Check the behaviour of rtems_bdbuf_read function with different
0014 reports from disk device driver.
0015
0016 1. Call rtems_bdbuf_read() function and disk device driver ioctl()
0017    function returns 0, and the result of asynchronous read complete
0018    notification is successful.
0019    Check that rtems_bdbuf_read() returns RTEMS_SUCCESSFUL and
0020    provides buffer descriptor.
0021 2. Call rtems_bdbuf_read() function and disk device driver ioctl()
0022    function returns -1 (there will be no asynchronous read complete
0023    notification).
0024    Check that rtems_bdbuf_read() returns RTEMS_IO_ERROR.
0025 3. Call rtems_bdbuf_read() function and disk device driver ioctl()
0026    function returns 0, but the result of asynchronous read complete
0027    notification is faulty (with some erroneous status).
0028    Check that rtems_bdbuf_read() returns that status and does not
0029    return buffer descriptor.
0030
0031 Test 1.2
0032 ~~~~~~~~
0033
0034 Check how rtems_bdbuf_read() handles two readers waiting for a buffer
0035 for the same block number in cases when disk device driver reports
0036 failure in read complete notification.
0037
0038 1. Call rtems_bdbuf_read() function in thread #1 and block on
0039    waiting for read complete notification.
0040 2. Call rtems_bdbuf_read() function in thread #2 for the same block
0041    number. As the result it blocks on this read as well (but it will
0042    block on transfer semaphore).
0043 3. Disk device reports an error in read complete notification.
0044    As the result an error is returned from rtems_bdbuf_read() in
0045    thread #1.
0046 4. rtems_bdbuf_read() called in thread #2 should try to re-read data
0047    again so disk device ioctl() function is called again for this
0048    block number.
0049 5. Disk device reports an error in read complete notification.
0050    As the result an error is returned from rtems_bdbuf_read() in
0051    thread #2.
0052
0053 Test 1.3
0054 ~~~~~~~~
0055
0056 Check how rtems_bdbuf_read() handles two readers waiting for a buffer
0057 for the same block number in cases when disk device driver reports
0058 failure in read complete notification.
0059
0060 1. Call rtems_bdbuf_read() function in thread #1 and block on
0061    waiting for read complete notification.
0062 2. Call rtems_bdbuf_read() function in thread #2 for the same block
0063    number. As the result it blocks on this read as well (but it will
0064    block on transfer semaphore).
0065 3. Disk device reports an error in read complete notification.
0066    As the result an error is returned from rtems_bdbuf_read() in
0067    thread #1.
0068 4. rtems_bdbuf_read() called in thread #2 should try to re-read data
0069    again so disk device ioctl() function is called again for this
0070    block number.
0071 5. This time disk device reports success in read complete notification.
0072    As the result rtems_bdbuf_read() in thread #2 shall return RTEMS_SUCCESSFUL
0073    and provide buffer descriptor.
0074 6. Call rtems_bdbuf_release() function in thread #2.
0075
0076 Test 1.4
0077 ~~~~~~~~
0078
0079 Check how rtems_bdbuf_read() handles two readers waiting for a buffer
0080 for the same block number in cases when disk device driver reports
0081 success in read complete notification.
0082
0083 1. Call rtems_bdbuf_read() function in thread #1 and block on
0084    waiting for read complete notification.
0085 2. Call rtems_bdbuf_read() function in thread #2 for the same block
0086    number. As the result it blocks on this read as well (but it will
0087    block on transfer semaphore).
0088 3. Disk device reports success in read complete notification.
0089    As the result rtems_bdbuf_read() function retuens RTEMS_SUCCESSFUL
0090    in thread #1.
0091 4. Thread #1 releases buffer with rtems_bdbuf_release() function.
0092 5. rtems_bdbuf_read() function in thread #2 unlocks and returns
0093    RTEMS_SUCCESSFUL.
0094 6. Call rtems_bdbuf_release() function in thread #2.
0095
0096 ISSUE (A)
0097 Due to implementation constrains of bdbuf library there is no way to
0098 handle such a situation according to task priority, but it is
0099 coded in such a way that task requested this buffer first will get it
0100 first (even though it is less priority task).
0101
0102 Test 1.5
0103 ~~~~~~~~
0104
0105 Check how rtems_bdbuf_read() handles read request for a buffer that
0106 is owned by an application.
0107
0108 1. Call rtems_bdbuf_read() function in thread #1 and provide successful
0109    read complete notification for this operation.
0110    As the result rtems_bdbuf_read() returns RTEMS_SUCCESSFUL in thread #1.
0111 2. In thread #2 call rtems_bdbuf_read() function for the same block number.
0112    A buffer for this block is owned by an application and as the result
0113    thread #2 block on this function.
0114 3. Call rtems_bdbuf_release() function in thread #1 in order to give
0115    it back under control of bdbuf library.
0116 4. Buffer now is ready to be returned for another application and as
0117    the result rtems_bdbuf_read() unblocks and returns RTEMS_SUCCESSFUL
0118    in thread #2.
0119 5. Call rtems_bdbuf_release() function in thread #2.
0120
0121
0122 Test 2.1
0123 ~~~~~~~~
0124
0125 Check how rtems_bdbuf_read() and rtems_bdbuf_release_modified() coexist.
0126 rtems_bdbuf_read() is blocked when required buffer is being transferred.
0127
0128 1. Call rtems_bdbuf_read() function in thread #1 and block on
0129    waiting for read complete notification.
0130 2. Call rtems_bdbuf_read() function in thread #2 for the same block
0131    number. As the result it blocks on this read as well (but it will
0132    block on transfer semaphore).
0133 3. Disk device reports success in read complete notification.
0134    As the result rtems_bdbuf_read() function retuens RTEMS_SUCCESSFUL
0135    in thread #1.
0136 4. Thread #1 releases buffer with rtems_bdbuf_release_modified() function.
0137 5. rtems_bdbuf_read() function in thread #2 unlocks and returns
0138    RTEMS_SUCCESSFUL.
0139 6. Wait swapout period and check that the buffer is not requested to be
0140    flushed to a disk.
0141 7. Call rtems_bdbuf_release() function in thread #2.
0142 8. Check that this block number is requested for a flush in swapout period.
0143
0144 ISSUE (A)
0145
0146 Test 2.2
0147 ~~~~~~~~
0148
0149 The same as Test 2.1, but on step 7 thread #2 calls
0150 rtems_bdbuf_release_modified().
0151 Check how rtems_bdbuf_read() and rtems_bdbuf_release_modified() coexist.
0152 rtems_bdbuf_read() is blocked when required buffer is being transferred.
0153
0154 1. Call rtems_bdbuf_read() function in thread #1 and block on
0155    waiting for read complete notification.
0156 2. Call rtems_bdbuf_read() function in thread #2 for the same block
0157    number. As the result it blocks on this read as well (but it will
0158    block on transfer semaphore).
0159 3. Disk device reports success in read complete notification.
0160    As the result rtems_bdbuf_read() function retuens RTEMS_SUCCESSFUL
0161    in thread #1.
0162 4. Thread #1 releases buffer with rtems_bdbuf_release_modified() function.
0163 5. rtems_bdbuf_read() function in thread #2 unlocks and returns
0164    RTEMS_SUCCESSFUL.
0165 6. Wait swapout period and check that the buffer is not requested to be
0166    flushed to a disk.
0167 7. Call rtems_bdbuf_release_modified() function in thread #2.
0168 8. Check that this block number is requested for a flush in swapout period.
0169
0170 Test 2.3
0171 ~~~~~~~~
0172
0173 Check how rtems_bdbuf_read() and rtems_bdbuf_release_modified() coexist.
0174 rtems_bdbuf_read() is blocked when required buffer is owned by another
0175 application.
0176
0177 1. Call rtems_bdbuf_read() function in thread #1 and provide successful
0178    read complete notification for this operation.
0179    As the result rtems_bdbuf_read() returns RTEMS_SUCCESSFUL in thread #1.
0180 2. In thread #2 call rtems_bdbuf_read() function for the same block number.
0181    A buffer for this block is owned by an application and as the result
0182    thread #2 block on this function.
0183 3. Call rtems_bdbuf_release_modified() function in thread #1 in order
0184    to give it back under control of bdbuf library.
0185 4. Buffer now is ready to be returned for another application and as
0186    the result rtems_bdbuf_read() unblocks and returns RTEMS_SUCCESSFUL
0187    in thread #2.
0188 5. Wait swapout period and check that the buffer is not requested to be
0189    flushed to a disk.
0190 6. Call rtems_bdbuf_release() function in thread #2.
0191 7. Check that this block number is requested for a flush in swapout period.
0192
0193 Test 2.4
0194 ~~~~~~~~
0195
0196 Check how rtems_bdbuf_read() and rtems_bdbuf_release_modified() coexist.
0197 rtems_bdbuf_read() is blocked when required buffer is owned by another
0198 application.
0199 The same as Test 2.3 but thread #2 releases buffer with
0200 rtems_bdbuf_release_modified() function.
0201
0202 1. Call rtems_bdbuf_read() function in thread #1 and provide successful
0203    read complete notification for this operation.
0204    As the result rtems_bdbuf_read() returns RTEMS_SUCCESSFUL in thread #1.
0205 2. In thread #2 call rtems_bdbuf_read() function for the same block number.
0206    A buffer for this block is owned by an application and as the result
0207    thread #2 block on this function.
0208 3. Call rtems_bdbuf_release_modified() function in thread #1 in order
0209    to give it back under control of bdbuf library.
0210 4. Buffer now is ready to be returned for another application and as
0211    the result rtems_bdbuf_read() unblocks and returns RTEMS_SUCCESSFUL
0212    in thread #2.
0213 5. Wait swapout period and check that the buffer is not requested to be
0214    flushed to a disk.
0215 6. Call rtems_bdbuf_release_modified() function in thread #2.
0216 7. Check that this block number is requested for a flush in swapout period.
0217
0218
0219
0220 Test 3
0221 ~~~~~~
0222
0223 Tests of this group check the behaviour of concurent reads from
0224 different tasks. Reads are done for different block numbers.
0225
0226 Test 3.1
0227 ~~~~~~~~
0228
0229 Check how read/release work in case of only one buffer in ready list.
0230
0231 1. In thread #1 call rtems_bdbuf_get(#N) to get an empty block #N.
0232 2. In thread #1 call rtems_bdbuf_release_modified() for previously got buffer.
0233 3. In thread #1 call rtems_bdbuf_read(#N) to get the same buffer
0234    (after this call a buffer is in AVL tree with ACCESS_MODIFIED state).
0235 4. In thread #2 call rtems_bdbuf_read/get(#M).
0236 5. In thread #1 call rtems_bdbuf_release(#N).
0237 6. Check that in thread #2 a buffer is obtained.
0238
0239 Test 3.2
0240 ~~~~~~~~
0241
0242 Check that when there are some tasks waiting for an available buffer only
0243 one of them get a buffer after some other task releases one.
0244
0245 1. Call rtems_bdbuf_read(#N1) in thread #1.
0246 2. Call rtems_bdbuf_get(#N2) in thread #2.
0247    This thread blocks because we have no buffers available.
0248 3. Call rtems_bdbuf_get(#N3) in thread #3.
0249    This thread also blocks because we have no buffers available.
0250 4. Call rtems_bdbuf_release_modified(#N1) in thread #1.
0251 5. Check that only one thread (thread #2 or thread #3) got a buffer.
0252    Another thread shall still be blocked.
0253
0254 Test 3.3
0255 ~~~~~~~~
0256
0257 The same as Test 3.2, but instead of calling rtems_bdbuf_get() in
0258 threads #1 and #2, it calls rtems_bdbuf_read().
0259
0260 1. Call rtems_bdbuf_read(#N1) in thread #1.
0261 2. Call rtems_bdbuf_read(#N2) in thread #2.
0262    This thread blocks because we have no buffers available.
0263 3. Call rtems_bdbuf_read(#N3) in thread #3.
0264    This thread also blocks because we have no buffers available.
0265 4. Call rtems_bdbuf_release(#N1) in thread #1.
0266 5. Check that only one thread (thread #2 or thread #3) got a buffer.
0267    Another thread shall still be blocked.
0268 6. Call rtems_bdbuf_release(#N2) in thread #2 and check that thread #3
0269    got a buffer as the result.
0270
0271 Test 4
0272 ~~~~~~
0273
0274 Group of tests for sync buffer functionality.
0275
0276 Test 4.1
0277 ~~~~~~~~
0278
0279 1. Call rtems_bdbuf_read(#N) in thread #1.
0280 2. Call rtems_bdbuf_read(#N) from thread #2.
0281    Thread #2 blocks on this call.
0282 3. Call rtems_bdbuf_sync(#N) in thread #1.
0283 4. After a while disk driver gets write request for block #N.
0284    Notify bdbuf library about write complete event.
0285 5. Check that thread #1 unlocked after this.
0286 6. Check that thread #2 unblocks and get buffer #N.
0287 7. Release buffer in thread #2.
0288
0289 Test 4.2
0290 ~~~~~~~~
0291
0292 1. Call rtems_bdbuf_read(#N) in thread #1.
0293 2. Call rtems_bdbuf_sync(#N) in thread #1.
0294 3. After a while disk driver gets write request for block #N.
0295 4. Call rtems_bdbuf_read(#N) from thread #2 (before reply from the driver).
0296    Thread #2 blocks on this call.
0297 5. Notify bdbuf library about write complete event.
0298 6. Check that rtems_bdbuf_sync(#N) in thread #1 unlocked after this.
0299    (in fact a thread to unlock might be any).
0300 7. Check that thread #2 unblocks and get buffer #N.
0301 8. Release buffer in thread #2.
0302
0303 Test 4.3
0304 ~~~~~~~~
0305
0306 1. Call rtems_bdbuf_read(#N) in thread #1.
0307 2. Call rtems_bdbuf_sync(#N) in thread #1.
0308 3. After a while disk driver gets write request for block #N.
0309    Notify bdbuf about write complete event.
0310 4. Check that rtems_bdbuf_sync(#N) in thread #1 unlocked after this.
0311 5. Call rtems_bdbuf_read(#N) in thread #2.
0312 6. Check that buffer is successfully obtained in thread #2.
0313 7. Call rtems_bdbuf_release(#N) in thread #2.
0314
0315
0316 Test 4.4
0317 ~~~~~~~~
0318
0319 TODO: Two brances in sync() function should be tested.