NdisMRegisterMiniport

NdisMRegisterMiniport

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

NdisMRegisterMiniport registers a NIC or intermediate driver's MiniportXxx entry points and name with the NDIS library when the driver initializes.

Parameters

NdisWrapperHandle

Specifies the handle returned by NdisMInitializeWrapper.

MiniportCharacteristics

Points 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;

//

// MajorNdisVersion must be set to 0x04 with following members

//

W_RETURN_PACKET_HANDLER ReturnPacketHandler;

W_SEND_PACKETS_HANDLER SendPacketsHandler;

W_ALLOCATE_COMPLETE_HANDLER AllocateCompleteHandler;

} 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 0x04, although the NDIS library continues to support existing NIC drivers developed for NDIS V3.0.

This member must be set to 0x04 if the caller sets entry points in any members following Name.

MinorNdisVersion

Specifies the minor version of the NDIS library the driver is using. The current value is 0x00, although NDIS continues to support existing drivers.

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 function is required if the NIC shares an interrupt vector.

QueryInformationHandler

Specifies the entry point of the caller's MiniportQueryInformation 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 function.

If the miniport supports multipacket sends, it sets the SendPacketsHandler member instead and sets this member to NULL.

SetInformationHandler

Specifies the entry point of the caller's MiniportSetInformation function.

TransferDataHandler

Specifies the entry point of the caller's MiniportTransferData function, if any. This miniport 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.

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 caller also sets an entry point in the SendHandler member, NDIS always calls MiniportSendPackets.

AllocateCompleteHandler

Specifies the entry point of the caller's MiniportAllocateComplete function, if any.

CharacteristicsLength

Specifies the length in bytes of the caller-supplied characteristics buffer. Depending on the value of MajorNdisVersion, this parameter must be either sizeof(NDIS40_MINIPORT_CHARACTERISTICS) or sizeof(NDIS30_MINIPORT_CHARACTERISTICS).

If the driver includes the build instruction NDIS40_MINIPORT (or NDIS30_MINIPORT, as appropriate) in its sources or if the driver writer uses the -DNDIS40_MINIPORT (or ..30..) compiler switch, this parameter is set when the driver is built.

Return Value

NdisMRegisterMiniport returns NDIS_STATUS_SUCCESS if it registered the miniport, 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. For example, if the NDIS library cannot load the driver's image and lock it into system memory, it returns this error.

Comments

A NIC driver calls NdisMRegisterMiniport from its DriverEntry function after DriverEntry calls NdisMInitializeWrapper.

Every NIC driver exports only MiniportXxx functions must set up a characteristics structure and call 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 handler functions.

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

After the driver has called NdisMRegisterMiniport, it should be prepared to be called back at the MiniportInitialize entry point specified in the characteristics structure.

NDIS intermediate drivers, which export both MiniportXxx and ProtocolXxx functions, usually call NdisIMRegisterLayeredMiniport instead of NdisMRegisterMiniport. Intermediate drivers that export only a set of MiniportXxx usually call NdisMRegisterMiniport.

Callers of NdisMRegisterMiniport run at IRQL PASSIVE_LEVEL.