MacAddAdapter

MacAddAdapter

NDIS_STATUS
MacAddAdapter(
IN NDIS_HANDLE MacMacContext,
IN NDIS_HANDLE WrapperConfigurationContext,
IN PNDIS_STRING AdapterName
);

MacAddAdapter is called to add support for each network interface card on the network.

Parameters

MacMacContext

Points to a context area in which NDIS maintains state about the NIC.

WrapperConfigurationContext

Specifies the context that the NDIS library associates with registry information for the NIC. The DriverEntry function obtained this handle from its call to NdisInitializeWrapper.

AdapterName

Points to a string in the OS-default character set naming the NIC. For Windows NT drivers, this string is a counted, zero-terminated Unicode string. The NIC driver passes this name to NdisRegisterAdapter.

Return Value

MacAddAdapter can return the value returned by NdisRegisterAdapter or possibly one of the following status codes:

NDIS_STATUS_ADAPTER_NOT_FOUND
NDIS_STATUS_RESOURCES
NDIS_STATUS_SUCCESS only if NdisRegisterAdapter returned this value

Comments

Using calls to NdisXxx configuration functions, such as NdisOpenConfiguration, NdisReadConfiguration, and NdisReadEisaSlotInformation, the NIC driver reads the hardware configuration information from the registry or from the I/O bus to determine the correct NIC parameters.

When it has collected the NIC configuration data it needs, MacAddAdapter calls NdisRegisterAdapter for the associated NIC, including the name of the logical adapter representing the NIC. This name allows NDIS to recognize the NIC when a protocol driver binds to the NIC using NdisOpenAdapter.

Other initialization functions the MacAddAdapter function calls can include NdisAllocateDmaChannel or NdisAllocateSharedMemory, NdisAllocateMemory, NdisInitializeInterrupt, and NdisMapIoSpace.

A successful call to NdisInitializeInterrupt enables calls to the NIC driver's MacInterruptServiceRoutine. Unless MacAddAdapter disables interrupts on the NIC before it calls NdisInitializeInterrupt or its NIC cannot generate interrupts in its current state, the driver must be prepared to handle a device interrupt during initialization.

MacAddAdapter should register the driver's MacShutdown function with NdisRegisterAdapterShutdownHandler.

MacAddAdapter also can initialize a filter library database with a call to EthCreateFilter, FddiCreateFilter, or TrCreateFilter, as appropriate to the medium type it supports.

If MacAddAdapter's call to NdisRegisterAdapter succeeds but it subsequently fails to initialize its NIC or to allocate necessary resources to support its NIC, MacAddAdapter must release any resources it has already allocated, such as by calling NdisFreeDmaChannel or NdisFreeSharedMemory, NdisRemoveInterrupt, NdisUnmapIoSpace, NdisCloseConfiguration, NdisDeregisterAdapterShutdownHandler, and so forth. It also must call NdisDeregisterAdapter before it returns control with an error status.

If MacAddAdapter cannot recognize, configure, and initialize at least one NIC in the machine, the NIC driver will not remain loaded. If MacAddAdapter does not returns NDIS_STATUS_SUCCESS for at least one adapter, the NDIS library interprets this as a failure and the driver will not remain loaded.

MacAddAdapter runs at IRQL PASSIVE_LEVEL in the context of a system thread.