ProtocolBindAdapter

ProtocolBindAdapter

VOID
   ProtocolBindAdapter(
       OUT PNDIS_STATUS Status,
       IN NDIS_HANDLE BindContext,
       IN PNDIS_STRING DeviceName,
       IN PVOID SystemSpecific1,
       IN PVOID SystemSpecific2
       );

ProtocolBindAdapter is usually implemented in an NDIS intermediate driver, both to make the driver Plug-and-Play-ready and to defer setting up its virtual NIC(s) until the underlying NIC driver(s) have initialized. Currently, it is an optional function in other NDIS protocols so that legacy protocols remain viable.

Parameters

Status

Points to a variable in which ProtocolBindAdapter returns the status of its operation(s), as one of the following:

NDIS_STATUS_SUCCESS

The driver completed initialization successfully if it was deferred from DriverEntry. The driver bound itself to the given NIC driver specified at DeviceName.

NDIS_STATUS_PENDING

The protocol will complete the bind operation asynchronously with a call to NdisCompleteBindAdapter when it is ready to accept receives from the underlying driver and to send transmit, query, and set requests down to the underlying driver.

NDIS_STATUS_XXX or NTSTATUS_XXX

The protocol’s attempt to set up a binding failed or the protocol could not allocate the resources it needed to carry out network I/O operations. Usually, such an error status is propagated from an NdisXxx function or a kernel-mode support routine.

BindContext

Specifies a handle, supplied by NDIS, that the protocol passes subsequently to NdisCompleteBindAdapter.

DeviceName

Points to a counted, zero-terminated Unicode string naming an underlying NIC driver or virtual NIC driver to which ProtocolBindAdapter should bind.

SystemSpecific1

Specifies a registry path pointer that is a required parameter to NdisOpenProtocolConfiguration.

SystemSpecific2

Reserved for system use.

Comments

ProtocolBindAdapter performs dynamic binding operations whenever an underlying NIC to which the protocol can bind itself becomes available. In addition, ProtocolBindAdapter continues driver initialization operations deferred from the DriverEntry function. ProtocolBindAdapter allocates sufficient memory to maintain per-binding runtime state and calls NdisOpenAdapter with the given BindContext and DeviceName to bind itself to the underlying driver.

If NdisOpenAdapter returns NDIS_STATUS_PENDING, the driver’s ProtocolOpenAdapterComplete function will be called subsequently when the binding operation has completed. ProtocolBindAdapter should store the input BindContext handle in the area it allocated for per-binding state; the ProtocolBindContext handle it supplied to NdisOpenAdapter is an input parameter to the driver’s ProtocolOpenAdapterComplete function, which must pass the BindContext handle to NdisCompleteBindAdapter subsequently. The underlying NIC driver returns NDIS_STATUS_ADAPTER_NOT_READY for any requests it receives while the open operation is pending. Consequently, ProtocolBindAdapter cannot call NdisRequest to query the underlying driver if NdisOpenAdapter returns NDIS_STATUS_PENDING.

In these circumstances, ProtocolBindAdapter simply sets Status to NDIS_STATUS_PENDING and returns control, thereby deferring whatever actions the protocol takes to set up binding-specific state and to allocate binding-specific resources to ProtocolOpenAdapterComplete if this function is called with an input Status of NDIS_STATUS_SUCCESS.

Similarly, if NdisOpenAdapter returns an error status, ProtocolBindAdapter sets Status to the returned value, releases any per-binding resources the driver has allocated, and returns control immediately. Otherwise, a successful binding has been established and the protocol can receive indications from the underlying driver to its ProtocolStatus, ProtocolReceivePacket, and/or ProtocolReceive functions.

Consequently, when NdisOpenAdapter returns NDIS_STATUS_SUCCESS, ProtocolBindAdapter allocates the resources the driver needs to carry out network I/O on the binding and sets up whatever binding-specific runtime state the protocol uses to track network I/O operations. If the driver’s installation script installed adapter-specific configuration information in the protocol section of the registry, ProtocolBindAdapter calls NdisOpenProtocolConfiguration and NdisReadConfiguration to retrieve this information. For more information about driver installation scripts, see the Programmer’s Guide.

ProtocolBindAdapter also can call NdisRequest to query the underlying driver (or NDIS) about the underlying driver’s NIC-specific limits, such as its maximum frame size, transmit/receive buffer space, and so forth, to set up appropriate state for the binding.

A protocol can determine whether the underlying driver indicates full-packet receives by comparing the values that driver returns for the OID_GEN_CURRENT_LOOKAHEAD and OID_GEN_RECEIVE_BLOCK_SIZE queries it passes to NdisRequest. If they are identical, the protocol will make no calls to NdisTransferData on this binding. A protocol can determine whether the underlying driver supports multipacket sends with the OID_GEN_MAXIMUM_SEND_PACKETS query. However, even if the underlying driver returns one, indicating that it does not have a MiniportSendPackets function, the protocol can still call NdisSendPackets on the binding, as long as the protocol does not supply out-of-band information with the packet descriptors it allocates for sends. NDIS handles the submission of packet arrays to such an underlying driver transparently to bound protocols. The protocol is responsible for ensuring that the underlying driver is capable of handling protocol-supplied out-of-band data, if any.

For more information about general and medium-specific OID requests, see Chapter 5.

A driver’s ProtocolReceivePacket or ProtocolReceive function can be called as soon as the protocol sets up a packet filter with OID_GEN_CURRENT_PACKET_FILTER for the binding. For the NULL filter, receive indications are enabled on return from a successfull call to NdisOpenAdapter.

Every NDIS protocol driver should allocate sufficient packet pool and buffer pool from which to allocate packet descriptors and buffer descriptors for subsequent network transmits and, possibly, for subsequent transfer-data requests, depending on whether the underlying driver indicates full-packet receives with NdisMIndicateReceivePacket.

The ProtocolBindAdapter function of an NDIS intermediate driver is responsible for prompting the initialization of the driver’s virtual NIC by calling NdisIMInitializeDeviceInstance, which, in turn, calls the driver’s MiniportInitialize function. Such a driver must initialize its virtual NIC after ProtocolBindAdapter (or ProtocolBindAdapterComplete) establishes a binding to the underlying driver specified at DeviceName. Still higher level protocols cannot bind to such an intermediate driver until its virtual NIC has been initialized.

If ProtocolBindAdapter cannot allocate the resources it needs to carry out subsequent network I/O operations, it should free all resources it has already allocated, set Status to an appropriate error value, and return control.

If the driver is ready to carry out network I/O on the established binding, ProtocolBindAdapter calls NdisCompleteBindAdapter with NDIS_STATUS_SUCCESS for the Status and OpenStatus arguments.

By default, ProtocolBindAdapter runs at IRQL PASSIVE_LEVEL in the context of a system thread.