NdisMRegisterMiniport

NdisMRegisterMiniport registers a miniport's MiniportXxx entry points with the NDIS library as the first step in NIC driver initialization.

NDIS_STATUS 
  NdisMRegisterMiniport(
    IN NDIS_HANDLE  NdisWrapperHandle,
    IN PNDIS_MINIPORT_CHARACTERISTICS  MiniportCharacteristics,
    IN UINT  CharacteristicsLength
    );

Parameters

NdisWrapperHandle

Specifies the handle returned by NdisMInitializeWrapper.

MiniportCharacteristics

Pointer to an NDIS_MINIPORT_CHARACTERISTICS structure set up by the caller. The structure at MiniportCharacteristics is defined as follows:

typedef struct _NDIS_MINIPORT_CHARACTERISTICS {
    UCHAR MajorNdisVersion;
    UCHAR MinorNdisVersion;
    UINT Reserved;
    W_CHECK_FOR_HANG_HANDLER CheckForHangHandler;
    W_DISABLE_INTERRUPT_HANDLER DisableInterruptHandler;
    W_ENABLE_INTERRUPT_HANDLER  EnableInterruptHandler;
    W_HALT_HANDLER HaltHandler;
    W_HANDLE_INTERRUPT_HANDLER  HandleInterruptHandler;
    W_INITIALIZE_HANDLER InitializeHandler;
    W_ISR_HANDLER ISRHandler;
    W_QUERY_INFORMATION_HANDLER QueryInformationHandler;
    W_RECONFIGURE_HANDLER ReconfigureHandler;
    W_RESET_HANDLER ResetHandler;
    W_SEND_HANDLER SendHandler; 
    W_SET_INFORMATION_HANDLER SetInformationHandler;
    W_TRANSFER_DATA_HANDLER TransferDataHandler;
//
// Version used is V4.0 or V5.0
// with following members
//
    W_RETURN_PACKET_HANDLER ReturnPacketHandler;
    W_SEND_PACKETS_HANDLER SendPacketsHandler;
    W_ALLOCATE_COMPLETE_HANDLER AllocateCompleteHandler;
//
// Version used is V5.0 with the following members
//
    W_CO_CREATE_VC_HANDLER CoCreateVcHandler;
    W_CO_DELETE_VC_HANDLER CoDeleteVcHandler;
    W_CO_ACTIVATE_VC_HANDLER CoActivateVcHandler;
    W_CO_DEACTIVATE_VC_HANDLER CoDeactivateVcHandler;
    W_CO_SEND_PACKETS_HANDLER CoSendPacketsHandler;
    W_CO_REQUEST_HANDLER CoRequestHandler;
//
// Version used is V5.1 with the following members
//
    W_CANCEL_SEND_PACKETS_HANDLER CancelSendPacketsHandler;
    W_PNP_EVENT_NOTIFY_HANDLER PnPEventNotifyHandler;
    W_MINIPORT_SHUTDOWN_HANDLER AdapterShutdownHandler;
} NDIS_MINIPORT_CHARACTERISTICS, *PNDIS_MINIPORT_CHARACTERISTICS;The driver should initialize this structure with zeros before setting up any of the following members:

MajorNdisVersion: Specifies the major version of the NDIS library the driver is using. The current value is 0x05, although the NDIS library continues to support existing NIC drivers developed for NDIS 4.0 and NDIS 3.0.
This member must be set to 0x05 or 0x04 if the caller sets entry points in any members following TransferDataHandler; it must be set to 0x05 if the caller sets entry points in any members following AllocateCompleteHandler.
MinorNdisVersion: Specifies the minor version of the NDIS library the driver is using. The current value is 0x00.
Reserved: This member is reserved for system use.
CheckForHangHandler: Specifies the entry point of the caller’s MiniportCheckForHang function, if any, or NULL.
DisableInterruptHandler: Specifies the entry point of the caller’s MiniportDisableInterrupt function, if any.
EnableInterruptHandler: Specifies the entry point of the caller’s MiniportEnableInterrupt function, if any.
HaltHandler: Specifies the entry point of the caller’s MiniportHalt function.
HandleInterruptHandler: Specifies the entry point of the caller’s MiniportHandleInterrupt function, if any.
InitializeHandler: Specifies the entry point of the caller’s MiniportInitialize function.
ISRHandler: Specifies the entry point of the caller’s MiniportISR function, if any. This miniport driver function is required if the driver later calls NdisMRegisterInterrupt from its MiniportInitialize function.
QueryInformationHandler: Specifies the entry point of the caller’s MiniportQueryInformation function, which is optional if the caller supplies a MiniportCoRequest function.
ReconfigureHandler: Specifies the entry point of the caller’s MiniportReconfigure function, or NULL.
ResetHandler: Specifies the entry point of the caller’s MiniportReset function.
SendHandler: Specifies the entry point of the caller’s MiniportSend function, MiniportWanSend function, or NULL if the caller supplies a MiniportSendPackets or MiniportCoSendPackets function.
If the miniport driver supports multipacket sends or controls a connection-oriented NIC, it sets the SendPacketsHandler or CoSendPacketsHandler member, respectively, and sets this member to NULL.
SetInformationHandler: Specifies the entry point of the caller’s MiniportSetInformation function, which is optional if the caller supplies a MiniportCoRequest function.
TransferDataHandler: Specifies the entry point of the caller’s MiniportTransferData function, if any. This miniport driver function is required unless the caller is the driver of a WAN NIC or the caller supports multipacket receives and, therefore, supplies the entry point of its MiniportReturnPacket function at ReturnPacketHandler. Drivers of connection-oriented NICs must support multipacket receives.
ReturnPacketHandler: Specifies the entry point of the caller’s MiniportReturnPacket function, if any.
SendPacketsHandler: Specifies the entry point of the caller’s MiniportSendPackets function, if any. If the driver of a connectionless NIC also sets an entry point in the SendHandler member, NDIS always calls its MiniportSendPackets function. The driver of a connection-oriented NIC must set the CoSendPacketsHandler member instead of this member.
AllocateCompleteHandler: Specifies the entry point of the caller’s MiniportAllocateComplete function, if any. MiniportCoCreateVc function. If the caller is an integrated call manager and connection-oriented NIC (MCM) driver, this member is set to NULL, because such a driver subsequently registers its ProtocolCoCreateVc function as a call manager with NdisMCmRegisterAddressFamily.
CoDeleteVcHandler: Specifies the entry point of the caller's MiniportCoDeleteVc function. If the caller is an integrated call manager and connection-oriented NIC (MCM) driver, this member is set to NULL, because such a driver subsequently registers its ProtocolCoDeleteVc function as a call manager with NdisMCmRegisterAddressFamily.
CoActivateVcHandler: Specifies the entry point of the caller's MiniportCoActivateVc function.
CoDeactivateVcHandler: Specifies the entry point of the caller's MiniportCoDeactivateVc function.
CoSendPacketsHandler: Specifies the entry point of the caller's MiniportCoSendPackets function. The SendHandler and SendPacketsHandler members should be NULL if the driver supplies a MiniportCoSendPackets function.
CoRequestHandler: Specifies the entry point of the caller's MiniportCoRequest function. If the driver also supplies MiniportQueryInformation and MiniportSetInformation functions, its MiniportCoRequest function handles only OID_GEN_CO_XXX and connection-oriented medium-specific OID_XXX requests. If such a driver sets the QueryInformationHandler and SetInformationHandler members to NULL, its MiniportCoRequest function must respond to all possible OID requests, including the OID_GEN_XXX that all NDIS miniports must handle.
CancelSendPacketsHandler: Specifies the entry point of the caller’s MiniportCancelSendPackets function, if any, or NULL. Miniport drivers that queue send packets for more than one second should register a MiniportCancelSendPackets function.
PnPEventNotifyHandler: Specifies the entry point of the caller’s MiniportPnPEventNotify function. NDIS 5.1 miniport drivers must register a MiniportPnPEventNotify function. Miniport drivers that have a WDM lower edge should register a MiniportPnPEventNotify function.
AdapterShutdownHandler: Specifies the entry point of the caller’s MiniportShutdown function, if any, or NULL. NDIS 5.1 miniports must register a MiniportShutdown function. NDIS 5.1 miniports should register a MiniportShutdown function by calling NdisMRegisterMiniport—not by calling NdisMRegisterAdapterShutdownHandler.

CharacteristicsLength

Specifies the size in bytes of the caller-supplied characteristics buffer, which is sizeof(NDIS_MINIPORT_CHARACTERISTICS). The exact buffer size allocated depends on the compiler or build directives set for the miniport driver.

For example, the following shows the appropriate compiler directives to embed at the start of a miniport driver's source code if the driver uses an NDIS 5.0 NDIS_MINIPORT_CHARACTERISTICS structure:

#define NDIS_MINIPORT_DRIVER
#define NDIS50_MINIPORT   1 
#include <Ndis.h>  // AFTER preceding directives

The inclusion of ndis.h must occur after the NDIS_MINIPORT_DRIVER and NDISXX_MINIPORT directives, where XX can be 40, as well as the 50 shown here. If the NDISXX_MINIPORT directive is omitted, the NDIS_MINIPORT_CHARACTERISTICS structure size defaults to version 3.0.

As an alternative, the same driver could set the following build directive in its sources file, instead of using the preceding compiler directives:

... 
C_FLAGS=$(C_FLAGS) -DNDIS_MINIPORT_DRIVER -DNDIS50_MINIPORT_DRIVER
...

As for the corresponding compiler directive, the driver writer can specify a -DNDISXX_MINIPORT_DRIVER directive, where XX can be 40, as well as the 50 shown here.

Setting the appropriate compiler/build directives sets the CharacteristicsLength automatically. The values set in the MajorNdisVersion and MinorNdisVersion members of the characteristics structure must be consistent with the compiler/build directives set for the miniport driver.

Return Value

NdisMRegisterMiniport returns NDIS_STATUS_SUCCESS if it registered the miniport driver, or it can return one of the following status values:

NDIS_STATUS_BAD_CHARACTERISTICS: The CharacteristicsLength is too small for the MajorNdisVersion specified in the buffer at MiniportCharacteristics.
NDIS_STATUS_BAD_VERSION: The MajorNdisVersion or MinorNdisVersion specified in the characteristics structure is invalid.
NDIS_STATUS_RESOURCES: A shortage of resources, possibly memory, prevented the NDIS library from registering the caller.
NDIS_STATUS_FAILURE: This is a default error status, returned when none of the preceding errors caused the registration to fail.

Headers

Declared in Ndis.h. Include Ndis.h.

Comments

A NIC driver calls NdisMRegisterMiniport from its DriverEntry function, following its call to NdisMInitializeWrapper.

Every NIC driver exports a set of standard MiniportXxx functions by setting up the characteristics structure and calling NdisMRegisterMiniport. This structure is copied in the NdisMRegisterMiniport request to the NDIS library’s internal storage. Thus, once it has registered, a miniport driver cannot change its MiniportXxx functions.

After the driver has called NdisMRegisterMiniport and after its DriverEntry function returns control, it should be prepared to be called back at the MiniportInitialize entry point specified in the characteristics structure. In the PnP environment, a NIC driver's call to NdisMRegisterMiniport simply registers the miniport driver's entry points with NDIS, which defers calling the driver's MiniportInitialize function until the PnP Manager sends NDIS a request to start the NIC. For more information about PnP, see Driver Setup, Plug and Play, & Power Management.

The NDIS library currently does not call MiniportReconfigure functions, so such a function in an existing miniport driver is dead code unless the miniport driver makes internal calls to its MiniportReconfigure function from MiniportInitialize.

NDIS intermediate drivers, which export both MiniportXxx and ProtocolXxx functions, must call NdisIMRegisterLayeredMiniport instead of NdisMRegisterMiniport. Connection-oriented MCM drivers, however, which export MiniportXxx and ProtocolCmXxx functions, call NdisMRegisterMiniport.

Callers of NdisMRegisterMiniport run at IRQL = PASSIVE_LEVEL.

NdisMRegisterMiniport

Parameters

Return Value

Headers

Comments

See Also