Chris Cant - Writing Windows WDM Device Drivers

A driver releases its claim on any resources by calling IoReportResourceUsage again; this time to report that it uses no resources. Listing 18.5 shows how UnclaimResources does this job. UnclaimResources is called when the file handle is closed.

Listing 18.5 UnclaimResources routine

void UnclaimResources(IN PDEVICE_OBJECT phddo) {

DebugPrintMsg("Freeing all allocated resources");

// Release all driver's resources by declaring we have none.

CM_RESOURCE_LIST ResourceList;

ResourceList.Count = 0;

BOOLEAN ConflictDetected;

IoReportResourceUsage(NULL,

phddo->DriverObject, &ResourceList, sizeof(ResourceList), // Driver

NULL, NULL, 0, // Device resources

FALSE, &ConflictDetected); // ignore return result

}

At this point, PHDIo has found its raw resource requirements and claimed them for itself. The final stage is to translate the raw resource information into a form that can be used by the driver. Listing 18.6 shows the TranslateAndMapResources routine that does this job.

HalTranslateBusAddress is used to translate a bus address. The bus type and number are passed as the first parameters, followed by the raw address. The AddressSpace parameter is used as both an input and an output. If set to 1, the address is in I/O space. If AddressSpace is 0 on output, the output address in memory space must be mapped using MmMapIoSpace . The PortStartAddress device extension field receives the translated address.

The raw interrupt information must be translated using HalGetInterruptVector. The bus type and number as passed as before. For the ISA bus, specifying the IRQ number for the raw interrupt level and raw vector parameters seems to work. The translated interrupt Vector, Irql, and Affinity are stored in the PHDIo device extension. Do not forget that PHDIo still needs to connect to the interrupt to install its interrupt service routine.

The final step in TranslateAndMapResources is to get a usable pointer to the I/O port. If the port needs mapping, MmMapIoSpace is called to obtain this pointer. Otherwise, PHDIo can just use the low part of the translated port address.

Listing 18.6 TranslateAndMapResources routine

NTSTATUS TranslateAndMapResources(IN PDEVICE_OBJECT phddo) {

PPHDIO_DEVICE_EXTENSION dx = (PPHDIO_DEVICE_EXTENSION)phddo->DeviceExtension;

// Translate IO port values

ULONG AddressSpace = 1; //IO space

if (!HalTranslateBusAddress(Isa, 0, dx->PortStartAddress, &AddressSpace, &dx->PortStartAddress)) {

DebugPrint("Create file: could not translate IO %x", dx->PortStartAddress.LowPart);

return STATUS_INVALID_PARAMETER;

}

DebugPrint("IO trans %x,%d", dx->PortStartAddress.LowPart, dx->PortLength);

dx->PortNeedsMapping = (AddressSpace==0);

dx->PortInIOSpace = (AddressSpace==1);

// Translate IRQ values

if (dx->GotInterrupt) {

ULONG irq = dx->Irql;

dx->Vector = HalGetInterruptVector(Isa, 0, irq, irq, &dx->Irql, &dx->Affinity);

if (dx->Vector==NULL) {

DebugPrint("Create filename: Could not get interrupt vector for IRQ %d", irq);

return STATUS_INVALID_PARAMETER;

}

DebugPrint("Interrupt vector %x IRQL %d Affinity %d Mode %d", dx->Vector, dx->Irql, dx->Affinity, dx->Mode);

}

// Map memory

if (dx->PortNeedsMapping) {

dx->PortBase = (PUCHAR)MmMapIoSpace(dx->PortStartAddress, dx->PortLength, MmNonCached);

if (dx->PortBase==NULL) DebugPrintMsg("Cannot map IO port");

return STATUS_NO_MEMORY;

} else dx->PortBase = (PUCHAR)dx->PortStartAddress.LowPart;

return STATUS_SUCCESS;

}

The FreeResources routine is used to unmap memory and disconnect from the interrupt, if necessary.

Well, that wraps up the discussion of PHDIo. The rest of its functionality is the same as WdmIo. The rest of the chapter backtracks to revisit the subject of finding the resources that a driver needs.

The PHDIo driver is told which resources to use in the filename passed with the Create IRP. However, most NT style drivers do not have this luxury. Instead, they must use one of the following techniques to find out what resources to use.

• Ask what resources the kernel has detected.

• Interrogate configurable buses.

• Save the resource requirements in the driver's registry key when it is installed.

• Poke around in memory to see if you can find your devices.

Calling IoGetConfigurationInformation returns a count of certain types of device.

NT and Windows 2000 attempt to identify all the hardware devices attached to the system when they boot. A driver can look for suitable devices using the IoQueryDeviceDescription kernel call. IoQueryDeviceDescription calls your configuration callback routine for each matching hardware element. I have not tried to find out if this call works in Windows 98.

The automatic detection process finds all the buses on the system, all recognized controllers on each bus, and. if possible, each peripheral attached to a controller. It starts by locating any standard serial and parallel ports and finds any attached mice or printers. Along the way, it finds any disk drivers, network cards, etc. The detected information is put in the registry in the HKLM\HARDWARE\DESCRIPTION key.

Table 18.2 shows the parameters for IoQueryDeviceDescription . You must supply a BusType parameter, and can optionally provide ControllerType and PeripheralType parameters. These parameters are pointers, so specifying NULL means that you do not want to find this type of hardware. You also pass a callback routine and a context to pass to it.

The possible bus, controller, and peripheral types are found in the INTERFACE_TYPE and CONFIGURATION_TYPE enumerations in NTDDK.H.

Table 18.2 IoQueryDeviceDescription function

Listing 18.7 shows some code that finds any parallel ports that have been detected (i.e., where the ControllerType is ParallelController). The code can be found in the book software file PHDIo\autodetect.cpp. Note carefully that the code will find parallel ports that are on all the available buses, not just the ISA bus. At the moment, this code just prints out the basic raw resource details using DebugPrint. If you use this code, you will eventually have to claim these resources and translate them into usable values. Do not forget that you need a separate Full Resource Descriptor for each bus type in the resource list passed to IoReportResourceUsage .