NdisMRegisterIoPortRange

NdisMRegisterIoPortRange

NDIS_STATUS
NdisMRegisterIoPortRange(
OUT PVOID *PortOffset,
IN NDIS_HANDLE MiniportAdapterHandle,
IN UINT InitialPort,
IN UINT NumberOfPorts
);

NdisMRegisterIoPortRange sets up driver access to device I/O ports with the NdisRawReadPortXxx and NdisRawWritePortXxx functions and claims the range of I/O port addresses in the registry for that driver's NIC.

Parameters

PortOffset

Specifies a caller-supplied variable in which this function returns the mapped base virtual address for the given bus-relative I/O port range specified by InitialPort and NumberOfPorts.

MiniportAdapterHandle

Specifies the handle input to MiniportInitialize.

InitialPort

Specifies the bus-relative base port address for a range of ports to be mapped.

NumberOfPorts

Specifies the number of ports in the range to be mapped.

Return Value

NdisMRegisterIoPortRange can return one of the following:

NDIS_STATUS_SUCCESS

The given range of I/O ports was mapped successfully so the value at PortOffset is valid and the mapped range has been claimed in the registry for the NIC.

NDIS_STATUS_RESOURCE_CONFLICT

An attempt to claim the I/O port range in the registry has failed, possibly because another driver already claimed the range for its device. NdisMRegisterIoPortRange logs an error if this occurs.

NDIS_STATUS_RESOURCES

The port range could not be mapped or NDIS could not allocate resources to check the registry for hardware-resource conflicts.

NDIS_STATUS_FAILURE

Either the bus type or bus number is out of range or the given InitialPort and NumberOfPorts were invalid (possibly not within the I/O port space of the current platform).

Comments

A NIC driver calls NdisMRegisterIoPortRange from its MiniportInitialize function. MiniportInitialize must call NdisMSetAttributes or NdisMSetAttributesEx before calling NdisMRegisterIoPortRange.

NdisMRegisterIoPortRange maps a bus-relative device address range that the miniport can use subsequently to access an I/O port range on its NIC by calling the NdisRawXxx functions. A successful call claims the specified range of I/O ports in the registry for the caller's NIC.

Because the parameters passed to the NdisRawXxx have been mapped, these functions run significantly faster than the corresponding NdisImmediate..PortXxx. After a successful call to NdisMRegisterIoPortRange, a miniport cannot call any of the NdisImmediate..PortXxx functions with either bus-relative addresses or mapped virtual addresses within such an I/O port range.

If its call to NdisMRegisterIoPortRange fails, MiniportInitialize should release all resources it already allocated for its NIC and, then, fail initialization for that NIC.

Drivers of NICs with device registers in the host memory space call NdisMMapIoSpace and, subsequently, the NdisRead/WriteRegisterXxx functions to access the NIC registers.

Callers of NdisMRegisterIoPortRange run at IRQL PASSIVE_LEVEL.