NdisRegisterAdapter

NDIS_STATUS
NdisRegisterAdapter(
OUT PNDIS_HANDLE NdisAdapterHandle,
IN NDIS_HANDLE NdisMacHandle,
IN NDIS_HANDLE MacAdapterContext,
IN NDIS_HANDLE WrapperConfigurationContext,
IN PNDIS_STRING AdapterName,
IN PVOID AdapterInformation
);

NdisRegisterAdapter associates a name with the caller’s NIC so the NIC driver can receive NdisOpenAdapter requests that protocol drivers direct to that netcard.

Parameters

NdisAdapterHandle

Points to a caller-supplied variable in which this function returns the handle that the NDIS interface library associates with the NIC.

NdisMacHandle

Specifies the handle that the NDIS interface library associates with the NIC driver.

MacAdapterContext

Specifies the context that the NIC driver associates with the network interface card. This value is typically a pointer to storage that the driver maintains to describe the network interface card. This state information is sometimes called the logical adapter.

WrapperConfigurationContext

Specifies the context that the NDIS interface library associates with configuration registry information for the network interface card.

AdapterName

Points to a variable-length string specifying the name of the NIC in the OS-default character set. For Windows NT drivers, this is a counted Unicode string.

AdapterInformation

Points to an NDIS_ADAPTER_INFORMATION structure set up by the caller. The structure at AdapterInformation is defined as follows:

typedef struct _NDIS_ADAPTER_INFORMATION {
    ULONG DmaChannel;
    BOOLEAN Master;
    BOOLEAN Dma32BitAddresses;
    NDIS_INTERFACE_TYPE AdapterType;
    ULONG PhysicalMapRegistersNeeded;
    ULONG MaximumPhysicalMapping;
    ULONG NumberOfPortDescriptors;
    NDIS_PORT_DESCRIPTOR PortDescriptors[1];
} NDIS_ADAPTER_INFORMATION, *PNDIS_ADAPTER_INFORMATION;

The driver should initialize this structure with NdisZeroMemory before it sets values in the following members:

DmaChannel

Specifies the bus-relative number of the DMA channel that a slave DMA NIC uses. If the NIC is not a DMA device or is a busmaster, this member must be zero.

Master

Specifies TRUE if the NIC is a busmaster DMA device. If the NIC is not a DMA device or is a slave, this member must be FALSE.

Dma32BitAddresses

Specifies TRUE for a busmaster DMA NIC that has 32 address lines and that can access memory with physical addresses greater than 0x00FFFFFF.

AdapterType

Specifies the I/O bus or internal interface for the NIC as one of the following values:

NdisInterfaceInternal
NdisInterfaceIsa
NdisInterfaceEisa
NdisInterfaceMca (MicroChannel)
NdisInterfaceTurboChannel
NdisInterfacePci (PCI)
NdisInterfacePcMcia (PCMCIA)

PhysicalMapRegistersNeeded

Specifies the maximum number of map registers that a busmaster DMA NIC can use per transfer operation. If the NIC uses slave DMA or is not a DMA device, this member must be zero.

For more information about allocating map registers, see NdisStartBufferPhysicalMapping.

MaximumPhysicalMapping

Specifies the maximum number of bytes that a busmaster DMA NIC can transfer in a single DMA operation. If the NIC uses slave DMA or is not a DMA device, this member must be zero.

For a busmaster DMA NIC, this value is the length of the longest buffer the driver ever passes to NdisStartBufferPhysicalMapping.

NumberOfPortDescriptors

Specifies the number of elements in the PortDescriptors array.

PortDescriptors

Specifies a variable-sized array with elements of type NDIS_PORT_DESCRIPTOR, defined as follows:

typedef struct _NDIS_PORT_DESCRIPTOR {
    ULONG InitialPort;   // first port in range
    ULONG NumberOfPorts; // number of ports in range
    PVOID *PortOffset;   // bus-relative offset of NIC ports
} NDIS_PORT_DESCRIPTOR, *PNDIS_PORT_DESCRIPTOR;

If the call to NdisRegisterAdapter succeeds, all ranges described in the PortDescriptors array are mapped so the driver can call the high-performance NdisRawXxx functions to communicate with its NIC. After a successful call, the driver must not pass these mapped ports to the slower NdisImmediateXxx functions.

Return Value

NdisRegisterAdapter can return the following status codes:

NDIS_STATUS_CLOSING
NDIS_STATUS_DEVICE_FAILED
NDIS_STATUS_NOT_ACCEPTED
NDIS_STATUS_RESOURCES
NDIS_STATUS_SUCCESS

Comments

A NIC driver should call NdisRegisterAdapter only during its initialization from its DriverEntry or MacAddAdapter function.

A NIC driver calls NdisRegisterAdapter only after it has called the appropriate NdisXxx configuration functions. Calling these functions occurs during the addition of a network interface card to the network, usually in the driver’s MacAddAdapter function.

When a NIC driver supports more than one NIC, it must register each NIC separately. Each registration supplies a unique adapter name so that protocol drivers can bind themselves to each NIC such a multiNIC driver supports.

A NIC driver should initialize the entire NDIS_ADAPTER_INFORMATION structure with zeros before setting values in this structure. If the driver later maps device memory with NdisMapIoSpace, it must set zero in the PhysicalMapRegistersNeeded and MaximumPhysicalMapping members of this structure.

When a full-NIC driver unloads, it deregisters each of its NICs with call(s) to NdisDeregisterAdapter.

Callers of NdisRegisterAdapter run at IRQL PASSIVE_LEVEL.