NdisStartBufferPhysicalMapping

VOID
NdisStartBufferPhysicalMapping(
IN NDIS_HANDLE NdisAdapterHandle,
IN PNDIS_BUFFER Buffer,
IN ULONG PhysicalMapRegister,
IN BOOLEAN WriteToDevice,
OUT PNDIS_PHYSICAL_ADDRESS_UNIT PhysicalAddressArray,
OUT PUINT ArraySize
);

NdisStartBufferPhysicalMapping is called by a busmaster NIC driver to start a mapping the NDIS interface library uses to associate the virtual address of a buffer with the addresses of the physical segments that comprise the buffer.

Parameters

NdisAdapterHandle: Specifies the handle that the NDIS interface library associates with the network interface card.
Buffer: Points to the buffer descriptor.
PhysicalMapRegister: Specifies the index of the map register that the NDIS interface library uses to manage physical buffer addresses.
WriteToDevice: Specifies TRUE if the NIC driver uses the mapping for a download operation, or FALSE if it uses the mapping for an upload.
PhysicalAddressArray: Points to the caller-supplied location in which this function writes an array of NDIS_PHYSICAL_ADDRESS_UNIT structures. Before calling this function, the NIC driver must ensure the array is large enough by calling NdisGetBufferPhysicalArraySize.
ArraySize: Points to the caller-supplied location in which this function writes the number of physical segments comprising the buffer. This number is a zero-based value.

Comments

Before calling NdisStartBufferPhysicalMapping, the NIC driver must call NdisGetBufferPhysicalArraySize to determine the number of physical segments comprising the buffer. Then the driver allocates an array large enough to contain a mapping and calls NdisStartBufferPhysicalMapping. The mapping (array) that this function returns remains valid until the NIC driver calls NdisCompleteBufferPhysicalMapping.

To upload data to the host, the driver uses the following steps:

Sets up the mapping using NdisStartBufferPhysicalMapping.
Informs the network interface card of the physical buffer addresses that the function writes, and programs it to perform the upload operation.
When the upload is complete, cancels the mapping by calling NdisCompleteBufferPhysicalMapping.
Reads the data from host memory.

To download data to the network interface card, the driver must:

Copy the data into host memory.
Set up the mapping using NdisStartBufferPhysicalMapping.
Inform the network interface card of the physical buffer addresses the function writes, and program it to perform the download operation.
When the download is complete, cancel the mapping by calling NdisCompleteBufferPhysicalMapping.

Callers of NdisStartBufferPhysicalMapping run at IRQL <= DISPATCH_LEVEL.