Chris Cant - Writing Windows WDM Device Drivers

Listing 15.3 Stored write byte commands

BYTE WriteByte[] = {

PHDIO_WRITE, PARPORT_CONTROL, 0xDC, // Ensure STROBE off

PHDIO_WRITE_NEXT, PARPORT_DATA, // Write next byte

PHDIO_DELAY, 1, // Delay 1us

PHDIO_WRITE, PARPORT_CONTROL., 0xDD, // STROBE on

PHDIO_DELAY, 1, // Delay 1us

PHDIO_WRITE, PARPORT_C0NTROL. 0xDC, // STROBE off

PHDIO_DELAY, 1, // Delay 1us

PHDIO_READ, PARPORT_STATUS, // Read status

};

The PHDIO_WRITE_NEXT command is crucial to these data transfer commands. The WdmIo driver keeps track of the current position in the output buffer passed by WriteFile . WdmIo correctly runs the WriteByte commands until all the bytes have been transferred.

Writing Data

The WdmIoTest program is finally ready to output a message to the printer. The following code snippet shows that WriteFile is used in the normal way to output data.

char* Msg = "Hello from WdmIo example\r\nChris Cant, PHD Computer Consultants Ltd\r\n";

DWORD Ten = strlen(Msg);

if (!WriteFile(hWdmIo, Msg, Ten, &BytesReturned, NULL)) printf("XXX Could not write message %d\n", GetLastError());

else if (BytesReturned==len) printf(" Write succeeded\n");

else printf("XXX Wrong number of bytes written: %d\n", BytesReturned);

The WdmIo driver uses the WriteByte commands to output the first byte, H. It then expects an interrupt when each byte has been printed. The WriteByte commands are run again by the interrupt handler to output each following byte. Assuming all goes well, when an interrupt is received after the last byte has been sent, WdmIo completes the WriteFile call successfully.

If there is a problem, WriteFile returns an error. The most likely error is ERROR_NOT_READY, which is returned if the write times out. If there is a problem running the write byte commands, ERROR_GEN_FAILURE is returned. Retrieve the WriteFile results to find the source of the problem.

Getting WriteFile Results

Each time the write commands are run, WdmIo gives its command processor a 5-byte output buffer. The first two words (4 bytes) are used for the error code and location. The fifth byte is filled with any output data that the commands produce. In WdmIoTest, the WriteByte commands read the Status register just after each byte is output. If the write commands attempt to output more than one byte, the command run will be aborted with error code PHDIO_NO_OUTPUT_ROOM.

However, what is really wanted is the value of the Status register after each byte is processed by the printer. At this point, the Status register contains some useful information, such as whether the printer is off-line or has run out of paper.

While WdmIoTest can just issue the ReadStatus commands again, it is more convenient if the Status register value is returned along with the command output data. Therefore, the register that the interrupt handler read is stored as a sixth byte in the WriteFile results buffer.

IOCTL_PHDIO_GET_RW_RESULTS is used to obtain the write (and read) results. Table 15.5 recaps the contents of the 6-byte buffer that is returned. Listing 15.4 shows how DeviceIoControl is used to read and display the results. When WdmIoTest is run successfully, the cmd status is 0x5F and the int status is 0xDF. This is expected. When a byte has just been output to the printer, BUSY# (the top bit of the Status register) goes low. When it has been printed, BUSY# goes high and an interrupt is generated.

Note that the command output buffer and the last interrupt register value locations are reused each time an interrupt occurs and the commands are run. This is not a problem. As soon as any fault occurs, processing stops with the most useful information in the results buffer.

Table 15.5 Read/Write results

Listing 15.4 Getting Write/Read command results

if (DeviceIoControl(hWdmIo, IOCTL_PHDIO_GET_RW_RESULTS,

NULL, 0, // Input

rv, sizeof(rv), // Output

&BytesReturned, NULL)) {

printf(" Get RW Results OK. rv=%d at %d\n", rv[0], rv[l]);

BYTE* pbuf = (BYTE*)(&rv[2]);

printf(" cmd status=%02x\n", pbuf[0]);

printf(" int status=%02x\n", pbuf[l]);

}

WdmIoTest finally disables interrupts by running the DisableInterrupts commands and closes its handle to the WdmIo device.

Reading data is a process similar to writing data. This time, two sets of commands need to be passed to WdmIo before the actual ReadFile is issued. The first set of commands starts the read process. The second set is used to process interrupts. Two sets are needed, as it is highly likely that different commands will be needed.

Use IOCTL_PHDIO_CMDS_FOR_READ_START to tell WdmIo which commands to use to start the read process. Typically, these commands might simply enable input interrupts from the device. IOCTL_PHDIO_CMDS_FOR_READ passes WdmIo the commands used to process each interrupt.

The ReadFile call passes the read buffer. The WdmIo driver can only handle fixed length transfers. However, a time-out of only one or two seconds could be used to ensure that errors are caught reasonably quickly.

As before, IOCTL_PHDIO_GET_RW_RESULTS is used to get the read results.

Reading data is not illustrated in WdmIoTest.

Installing a WdmIo device for a parallel port is a bit trickier than all the previous drivers. This is because Windows should already have installed its own driver to service the port. It is possible to run WdmIo for a parallel port in Windows 98. However, I found it was not possible in Windows 2000. The PHDIo driver can be forced to run in W2000 to talk to a parallel port.

The WdmIoLpt1Checked.inf and WdmIoLpt1Free.inf installation files are designed for a parallel port that, by default, lives at address 0x0378 and generates ISA interrupt IRQ7. Other configurations are made available for the user to select.

The best way to install WdmIo in Windows 98 is to use Hardware profiles. A Hardware profile is the combination of drivers that Windows loads. The trick is to have one profile in which the standard Windows parallel port driver is available. Another Hardware profile loads the WdmIo driver. When Windows starts, select the profile that you want to use.

In the Control Panel System applet, select the Hardware profiles tab. Copy the "Original Configuration" profile into a new profile called "WdmIo". Reboot into this new profile. In the Device Manager, select the Parallel port (LPT1) driver. First, remember which resources the LPT1 driver uses. Now remove the Parallel port driver from this profile. Simply disabling the driver is not good enough, as a disabled driver still keeps its resource assignments. Do not restart yet.

Now install a WdmIo device in the Other devices category as usual. You will have to reboot for the WdmIo device to be activated. I found that removing the Parallel port driver may mean that the parallel port was disabled in the BIOS setup. As you do the last reboot, you should go into your BIOS setup and reenable the LPT1 port again.