Handle Scatter/Gather DMA in NDIS 6.0 (Compact 2013)

3/26/2014

In NDIS 6.0, scatter/gather lists (SGL) for direct memory access (DMA) are associated with NET_BUFFER structures. NDIS 6.0 provides several new functions for handling SGLs and for allocating shared memory for DMA.

To support scatter/gather DMA in NDIS 6.0

1. Register for NDIS 6.0 scatter/gather DMA support by calling the NDIS 6.0 NdisMRegisterScatterGatherDma function.

   Initialize an NDIS_SG_DMA_DESCRIPTION structure and pass this structure to the NdisMRegisterScatterGatherDma function. NdisMRegisterScatterGatherDma returns a handle and your miniport driver subsequently passes this handle to NDIS scatter/gather DMA run-time functions. The following code example illustrates how to initialize an NDIS_SG_DMA_DESCRIPTION and call NdisMRegisterScatterGatherDma.

   Important

   For readability, the following code example does not contain security checking or error handling. Do not use the following code in a production environment.

   NDIS_SG_DMA_DESCRIPTION DmaDescription;
   
   // Initialize the DMA description with packet size and handlers:
   DmaDescription.Header.Type = NDIS_OBJECT_TYPE_SG_DMA_DESCRIPTION;
   DmaDescription.Header.Revision = NDIS_SG_DMA_DESCRIPTION_REVISION_1;
   DmaDescription.Header.Size = sizeof(NDIS_SG_DMA_DESCRIPTION);
   DmaDescription.Flags = 0;
   DmaDescription.MaximumPhysicalMapping = NIC_MAX_PACKET_SIZE;
   DmaDescription.ProcessSGListHandler = MyMiniportProcessSGList;
   
   // Register for scatter/gather DMA support:
   Status = NdisMRegisterScatterGatherDma(
                       pMyAdapter->AdapterHandle,
                       &DmaDescription,
                       &pMyAdapter->NdisMiniportDmaHandle);
   

   In the preceding example, the object header is initialized to standard values for NDIS 6.0, the Flags member is set to 0 (zero) to indicate that 32-bit addressing is used, and MaximumPhysicalMapping is set to the maximum number of bytes that the network adapter can transfer in a single DMA operation (NIC_MAX_PACKET_SIZE). NdisMRegisterScatterGatherDma saves the resulting DMA handle in pMyAdapter->NdisMiniportDmaHandle.

   Register the miniport driver MyMiniportProcessSGList function so that NDIS can call this function when the OS is finished building the SGL. You define this function in your miniport driver to assist NDIS with scatter/gather DMA operations.

2. While processing send requests, call the NdisMAllocateNetBufferSGList function to obtain a SGL for a NET_BUFFER structure.

   When your driver calls NdisMAllocateNetBufferSGList, NDIS calls the OS to build the SGL. After the OS builds the SGL, NDIS calls the MiniportProcessSGList function. When NDIS calls MiniportProcessSGList, your driver can send the NET_BUFFER structure to the network adapter. Your miniport driver must call the NdisMFreeNetBufferSGList function to free an SGL.

3. Release scatter/gather DMA resources by the calling the NdisMDeregisterScatterGatherDma function.

   Pass NdisMDeregisterScatterGatherDma the handle returned by NdisMRegisterScatterGatherDma. Your driver normally calls NdisMDeregisterScatterGatherDma in the context of its MiniportHaltEx function.

   Continuing with the previous example, the following code releases the handle saved in pMyAdapter->NdisMiniportDmaHandle.

   Important

   For readability, the following code example does not contain security checking or error handling. Do not use the following code in a production environment.

   NdisMDeregisterScatterGatherDma(pMyAdapter->NdisMiniportDmaHandle);
   

Note that, unlike desktop Windows, the Windows Embedded Compact NDIS implementation does not support the use of a shared memory allocation completion handler (this handler is normally registered in the SharedMemAllocateCompleteHandler member of NDIS_SG_DMA_DESCRIPTION). In addition, Windows Embedded Compact does not support the NdisMAllocateSharedMemoryAsyncEx function.

For more information about scatter/gather DMA, see Scatter/Gather DMA Reference.

See Also

Concepts

Update Miniport Driver DMA Functionality for NDIS 6.0