Storage Device Block Driver API Test for USB Device (Compact 2013)
3/26/2014
The Storage Device Block Driver Application Programming Interface (API) Test assesses the functionality of mass storage block drivers. It includes test cases that verify that a block driver is working correctly so that you can mount a file system on the disk. This test also examines whether a block driver can read from and write to a disk, verifies data located on that disk, and then tests all disk boundary conditions. To work correctly, a mass storage block driver is not required to pass all test cases in the Storage Device Block Driver API Test.
The USB storage devices include any commercially available devices that are able to connect over USB. These USB devices include: pen drives, hard drives, card readers.
Test Prerequisites
Your device must meet the following requirements before you run this test.
The following tables show the hardware requirements for the Storage Device Block Driver API Test.
Requirements |
Description |
|---|---|
A mass storage device |
A mass storage device that works with the block driver being tested, for example, a USB drive. |
The following tables show the software requirements for the Storage Device Block Driver API Test.
Requirements |
Description |
|---|---|
Tux.exe |
Tux test harness, required for test execution |
Kato.dll |
Kato logging engine, required for logging test data |
Disktest.dll |
Library containing the test |
Mass storage block driver |
In the OS design, you must include a mass storage block driver that supports the mass storage device. |
Subtests
The table below lists the subtests included in this test.
SubTest ID |
Description |
|---|---|
4002 |
Format mass storage disk. Tests the functionality of the IOCTL_DISK_FORMAT_MEDIA IOCTL. If the disk supports only previous IOCTLs, use the /oldioctls command-line parameter to test the DISK_IOCTL_FORMAT_MEDIA IOCTL instead. This test case fails if the block driver does not support the IOCTL. If the storage device does not require or support low-level formatting, the driver should immediately report success. |
4003 |
Write, Read, Verify 1 sector at a time. Verifies that data written one sector at a time to any sector of the disk can be read back correctly. This test case fails if data is corrupted while reading or writing. It also fails if the boundary of a read or write buffer is overwritten. |
4004 |
Write, Read, Verify 8 sectors at a time. Verifies that data written eight sectors at a time to any sector of the disk can be read back correctly. This test case fails if data is corrupted while reading or writing. It also fails if the boundary of a read or write buffer is overwritten. |
4005 |
Write, Read, Verify 32 sectors at a time. Verifies that data written 32 sectors at a time to any sector of the disk can be read back correctly. This test case fails if data is corrupted while reading or writing. It also fails if the boundary of a read or write buffer is overwritten or if the storage device does not support large reads or writes. |
4006 |
Write, Read, Verify 256 sectors at a time. Verifies that data written 256 sectors at a time to any sector of the disk can be read back correctly. This test case fails if data is corrupted while reading or writing. It also fails if the boundary of a read or write buffer is overwritten or if the storage device does not support large reads or writes. |
4007 |
Write, Read, Verify 65536 sectors at a time. Verifies that data written 65536 sectors at a time to any sector of the disk can be read back correctly. This test case fails if data is corrupted while reading or writing. It also fails if the boundary of a read or write buffer is overwritten or if the storage device does not support large reads or writes. |
4008 |
Write, Read, Verify increasing buffer sizes. Reads and writes onto the sectors in increasing buffer sizes. Also compares the read and written data on each sector buffer size. |
4009 |
Write, read multi-SG 2 sectors at a time. Verifies that reading scatter-gather (SG) buffers two sectors at a time behaves correctly. This test case fails if the driver for the storage device does not support reading multiple SG buffers. It also fails if data is corrupted while reading or writing or if the boundary of a read or write buffer is overwritten. |
4010 |
Write, read multi-SG 8 sectors at a time. Verifies that reading SG buffers eight sectors at a time behaves correctly. This test fails if the driver for the storage device does not support reading multiple SG buffers. It also fails if data is corrupted while reading or writing or if the boundary of a read or write buffer is overwritten. |
4011 |
Write, read multi-SG 32 sectors at a time. Verifies that reading SG buffers 32 sectors at a time behaves correctly. This test fails if the driver for the storage device does not support reading multiple SG buffers. It also fails if data is corrupted while reading or writing or if the boundary of a read or write buffer is overwritten. |
4012 |
Write, read multi-SG 256 sectors at a time. Verifies that reading SG buffers 256 sectors at a time behaves correctly. This test fails if the driver for the storage device does not support reading multiple SG buffers. It also fails if data is corrupted while reading or writing or if the boundary of a read or write buffer is overwritten. |
4013 |
Write, read multi-SG 65536 sectors at a time. Verifies that reading SG buffers 65536 sectors at a time behaves correctly. This test fails if the driver for the storage device does not support reading multiple SG buffers. It also fails if data is corrupted while reading or writing or if the boundary of a read or write buffer is overwritten. |
4014 |
Write using 2-8 SG buffers, read + verify. Verifies that writing to multiple SG buffers behaves correctly. First, this test case writes data to between 2 and 8 SG buffers of random size. Then, it reads back the same range of sectors by using a single SG buffer and compares the data read to the data written. This test case fails if the driver for the storage device does not support multiple SG buffer writes. It also fails if the driver requires individual SG buffers to be sector aligned or if data is corrupted while reading or writing. |
4015 |
Write, read using 2-8 SG buffers + verify. Verifies that reading multiple SG buffers behaves correctly. First, this test case writes data by using a single SG buffer. Then, it reads data by using between 2 and 8 SG buffers of random size and compares the data written to the data read. This test case fails if the driver for the storage device does not support reading multiple SG buffers. It also fails if the driver requires individual SG buffers to be sector aligned or if data is corrupted while reading or writing. |
4016 |
Read and write with 2 SG buffers, varying size. Verifies that SG buffers of any size work correctly. This test case fails if the driver for the storage device does not support multiple SG buffer reads or writes. It also fails if the driver requires individual SG buffers to be sector aligned. |
4017 |
Read buffer extends past last sector. Verifies the behavior of reading from a disk when the request extends past the last sector on the disk. This test case fails if reading succeeds. A failure of the test case does not necessarily indicate a problem with the driver. |
4018 |
Read starts past final sector. Verifies the behavior of reading from a disk when the request starts past the last sector on the disk. This test case fails if reading succeeds. A failure of the test case does not necessarily indicate a problem with the driver. |
4019 |
Write buffer extends past last sector. Verifies the behavior of writing to a disk when the request extends past the last sector on the disk. This test case fails if writing succeeds. A failure of the test case does not necessarily indicate a problem with the driver. |
4020 |
Write starts past final sector. Verifies the behavior of writing to a disk when the request starts past the last sector on the disk. This test case fails if writing succeeds. A failure of the test case does not necessarily indicate a problem with the driver. |
4021 |
Delete sector test cases. Verifies the functionality of the IOCTL_DISK_DELETE_SECTORS IOCTL when it is given parameters that are not valid. It is not required that a driver support this IOCTL. If the driver does not support this IOCTL, the test case is skipped. This test case fails if the IOCTL_DISK_DELETE_SECTORS IOCTL does not handle bounds cases correctly. |
4022 |
Write using various buffer types. Verifies the ability of the driver to write from the following types of buffers: * Heap allocated * Stack allocated * Read only * DWORD aligned * Word aligned * Byte aligned. This test case fails if the driver cannot read from one of the buffer types or if the driver does not appropriately handle unaligned buffers when aligned buffers are required, for example with direct memory access (DMA) transfer. |
4023 |
Read using various buffer types. Verifies the ability of the driver to read into the following types of buffers: * Heap allocated * Stack allocated * DWORD aligned * Word aligned * Byte aligned. This test case fails if the driver cannot read into one of the buffer types or if the driver does not appropriately handle unaligned buffers when aligned buffers are required, for example with DMA transfer. |
4024 |
Write, Read single invalid buffer. Verifies by writing and reading data from invalid and NULL buffers. This test is expected to fail when writing or reading. |
4025 |
Write, Read multi-SG sectors with exceed # SG. Verifies by writing out of the boundary size of the buffer. This test is expected to fail when written out the buffer size. |
4026 |
Write, Read multi-SG invalid sectors. Verifies by writing or reading from a NULL buffer. This test is expected to fail. |
4027 |
Write, Read test with invalid Ioctl. Reads or writes into the buffer with size 0. |
Setting Up the Test
The removable USB storage card must be formatted so that it will be enumerated when plugged in. There are two ways to format the USB storage card:
1. The storage device can be partitioned and formatted using the Storage Manager Control Panel Applet. This applet can be added to the image using SYSGEN_STOREMGR_CPL. After the image has been built, the storage manager applet can be accessed by My Device->Control Panel->Storage Manager.
2. The storage device can be formatted using a Windows based desktop machines' built-in formatting application. This assumes the use of one partition.
The image must be built with SYSGEN_USB=1 and SYSGEN_USB_STORAGE=1 in order to enable detection and enumeration of USB storage device.
Running the Test
COMMAND LINE PARAMETERS:
You can modify the test by editing the command line. To specify one or more of the following optional command line parameters for this test, use the -c command line parameter, which forces Tux to pass the specified string into the test module. If your USB storage device uses a different storage profile name other than "USBHDProfile", please use that name in the command line.
SYNTAX:
tux -o -d disktest -c "-zorch [-disk DSKX:] [-profile <profile>] [-oldioctls] [-sectors <count>] [-store]"
Command Line Parameters |
Description |
|---|---|
-disk DSKx: |
Specifies the device name of the disk to be tested. If you do not specify this parameter, the test probes for a mass storage disk on devices DSK1-DSK9. Specifying this parameter overrides the automatic detection process and forces the test to use the disk that you specify. |
-profile <profile> |
Specifies the storage profile and limits testing to the devices with the specified storage profile. The default storage profile is "all profiles". |
-oldioctls |
Forces the test to use the previous disk I/O control codes (IOCTLs) instead of the current set of IOCTLs. The previous IOCTLs are prefixed with "DISK_IOCTL_" and are not Windows Embedded CE IOCTLs. The current set of IOCTLs are prefixed with "IOCTL_DISK_". Many block drivers support both previous and current IOCTLs. You can use this parameter to verify that current and previous IOCTLs work correctly. |
-sectors <count> |
Sets the maximum number of sectors per read/write transaction. You can use this parameter for a storage device to set the physical limit on the number of sectors that are transferred by the storage device at one time. The default value is 128 sectors. |
-store |
Specifies that the test opens a handle to the disk by using the OpenStore function instead of the CreateFile function. Notice that you are not required to open a handle by using OpenStore to test block driver functionality. However, it is useful for testing a storage device that Filesys.exe loads automatically if you cannot open the storage device. For example, you can open a handle to a flash driver for ROM by using the OpenStore function. |
-zorch |
Enables the functionality of the test. Without this parameter, the test will fail. With this parameter, the test will run and destroy all data on the storage device. |
Note:
During the test, all information on the storage device is destroyed. The test writes to and reads from sectors on the storage device without preserving the contents of the sectors. Microsoft recommends that you back up data on all cards and disks that are attached to the tested device before running the test.
Verifying the Test
When the test completes running, verify that "PASS" appears in the test log for all sub-tests.
Troubleshooting the Test
* The USB storage devices on a Windows Embedded Compact device typically use the USBHDProfile profile. If your device uses a different profile name, you can specify that in the command line. Alternatively, you can provide the device name of the file system via the "disk" option.
* Some USB devices may not function properly or be enumerated when plugged in to the Windows Embedded Compact device. Make sure you have enabled USB functionality in your image configuration.
* Some devices may work when connected to a desktop PC, but not work when connected to a Windows Embedded Compact device. This may be due to the USB device not meeting USB electrical or signal specification. Another reason might be due to firmware not meeting protocol.