Bus-master DMA Considerations

DMA typically includes system DMA and Bus-master DMA. The difference is that system DMA is dependent on systems, and the device itself does not have the ability to control the transmission of DMA, whereas the Bus-master device has the ability to control transmission with DMA. It is often more common to see the Bus-master DMA mode.

The use of DMA, first obtains the Dma_adapter in the start device, through the Dma_adapter provides the call back to realize the DMA transmission.

To get the Dma_adapter function:

Iogetdmaadapter The Iogetdmaadapter routine returns a pointer to the DMA adapter structure for a physical device object. Pdma_adapter Iogetdmaadapter (in Pdevice_object physicaldeviceobject, in Pdevice_description DeviceDescriptio


N, out Pulong numberofmapregisters); Parameters Physicaldeviceobject Pointer to the physical device object for the device requesting the DMA adapter structure 
. 
Devicedescription Pointer to a device_description structure, which describes the attributes of the physical DEVICE. Numberofmapregisters A pointer to, on output, the maximum number of map registers then the driver can allocate for any DM 
A transfer operation. Return Value Iogetdmaadapter Returns a pointer to a dma_adapter structure, which contains pointers to functions that Suppo RT system-defined DMA Operations. 

IF The structure cannot be allocated, the routine returns NULL. Comments before calling this routine, a driver must zero-initialize the structure passed at DeviceDescription and then supply the relevant information for its device. On success, the Dmaoperations member of the routine ' s return value points to a dma_operations structure, which is a table of pointers to functions so the driver can use to perform subsequent DMA operations. If the driver passes device_description_version or Device_description_version1 in the VERSION member of the Devicedescript Ion parameter, Iogetdmaadapter returns a pointer to version 1 of the dma_operations structure. If the driver passes Device_description_version2, Iogetdmaadapter returns version 2 of the table if version 2 is supported ; Otherwise, it returns NULL.

Drivers must check to see if version 2 was supported before attempting to use any version 2 function. A PNP driver calls Iogetdmaadapter when its AddDevice routine was called or when it handles a PnP irp_mn_start_device reque St for a device. This IRP is includes information about the device's hardware resources, the driver must supply in the DevicedeScription structure. The caller uses the MaximumLength member in the devicedescription structure to indicate the optimal number of the map register s it can use. The I/O Manager would attempt to allocate enough map registers to accommodate a DMA transfer operation of this maximum size . On output, the I/O manager returns, in the Numberofmapregisters parameter, the number of map registers that it allocates. Drivers should check the returned value;

There is no guarantee a driver would receive the same number of map registers it requested. The adapter object, the driver should call Putdmaadapter through the pointer returned in the DMA_ADAPTER structure

. Note as previously described, Iogetdmaadapter returns NULL if it does not support the version of the Dma_adapter Structur E that's specified by Devicedescription->version. Callers should rely on this behavior to determine whether the routine returns a pointer to the requested version of the DM A_adapter structure. When IogetdmaadapteR returns a pointer to version 1 or version 2 of the Dma_adapter structure, the version member of this structure are always Set to 1.  Thus, the caller cannot use the Version member of the returned Dma_adapter structure to distinguish between versions 1 and 


2 of this structure. 

Requirements versions:available in Windows and later Versions of Windows. 

Irql:passive_level headers:declared in Wdm.h. Include Wdm.h, Ntddk.h, or Ntifs.h. 
 Library:contained in Ntoskrnl.lib.

These APIs require special attention to several of these parameters:

Devicedescription-corresponds to the properties of the desired dma_adapter, this setting will have a direct effect on subsequent references. Device_descroption is defined as follows

typedef struct _DEVICE_DESCRIPTION {
  ULONG  Version;		*
  BOOLEAN  Master;		Bus-master or System
  BOOLEAN  Scattergather;	Support Scattergather or not
  BOOLEAN  Demandmode;		System DMA only	
  BOOLEAN  autoinitialize;	System DMA only
  BOOLEAN  dma32bitaddresses;	Use 32bit address or not
  BOOLEAN  ignorecount;		Related to version
  BOOLEAN  Reserved1;
  BOOLEAN  dma64bitaddresses;	Use 64bit address or not
  ULONG  busnumber; 
  ULONG  DmaChannel;		For system DMA only
  Interface_type  InterfaceType;
  Dma_width  dmawidth;		System DMA only
  dma_speed  dmaspeed;		System DMA only	
  ULONG  maximumlength;		*
  ULONG  dmaport;
} Device_description, *pdevice_description;

1, version the difference between the different version here is that the dmaoperations in Dma_adapter is different, version3>version2>version1

Version3 is the latest support in Win8, can refer to the definition of dmaoperations

The dma_operations structure provides a table of pointers to functions the control the operation of a DMA controller.
  Syntax C + + Copy typedef struct _DMA_OPERATIONS {ULONG Size;
  Pput_dma_adapter Putdmaadapter;
  Pallocate_common_buffer Allocatecommonbuffer;
  Pfree_common_buffer Freecommonbuffer;
  Pallocate_adapter_channel Allocateadapterchannel;
  Pflush_adapter_buffers flushadapterbuffers;
  Pfree_adapter_channel Freeadapterchannel;
  Pfree_map_registers freemapregisters;
  Pmap_transfer Maptransfer;
  Pget_dma_alignment getdmaalignment;
  Pread_dma_counter Readdmacounter;
  Pget_scatter_gather_list getscattergatherlist;
  Pput_scatter_gather_list putscattergatherlist;
  Pcalculate_scatter_gather_list_size calculatescattergatherlist;       Pbuild_scatter_gather_list   Buildscattergatherlist;
  Pbuild_mdl_from_scatter_gather_list buildmdlfromscattergatherlist;
  Pget_dma_adapter_info Getdmaadapterinfo;
  Pget_dma_transfer_info Getdmatransferinfo;
  Pinitialize_dma_transfer_context Initializedmatransfercontext;
  PALLOCATE_COMMON_BUFFER_EX Allocatecommonbufferex;
  PALLOCATE_ADAPTER_CHANNEL_EX Allocateadapterchannelex;
  Pconfigure_adapter_channel Configureadapterchannel;
  Pcancel_adapter_channel Canceladapterchannel;
  PMAP_TRANSFER_EX Maptransferex;
  PGET_SCATTER_GATHER_LIST_EX Getscattergatherlistex;
  PBUILD_SCATTER_GATHER_LIST_EX Buildscattergatherlistex;
  PFLUSH_ADAPTER_BUFFERS_EX Flushadapterbuffersex;
  Pfree_adapter_object Freeadapterobject;
Pcancel_mapped_transfer Cancelmappedtransfer;


} dma_operations, *pdma_operations;

Members size the size, in bytes, of this dma_operations structure. PutdmaadApter A pointer to a system-defined routine to free a dma_adapter structure.

For more information, see Putdmaadapter. Allocatecommonbuffer a pointer to a system-defined routine to allocate A physically contiguous DMA buffer.

For more information, see Allocatecommonbuffer.  Freecommonbuffer a pointer to a system-defined routine to free A physically contiguous DMA buffer previously allocated by Allocatecommonbuffer.

For more information, see Freecommonbuffer. Allocateadapterchannel a pointer to a system-defined routine to allocate A channel for DMA operations.

For more information, see Allocateadapterchannel. Flushadapterbuffers a pointer to a system-defined routine to flush data from the system or Bus-master adapter ' s internal Cache after a DMA operation.

For more information, see Flushadapterbuffers. Freeadapterchannel a pointer to a system-defined routine to free A channel previously allocated for DMA operations by all Ocateadapterchannel. For more information, see FREEADAPTERchannel. Freemapregisters a pointer to a system-defined routine to free maps registers allocated for DMA operations.

For more information, see Freemapregisters. Maptransfer a pointer to a system-defined routine to begin A DMA operation.

For more information, see Maptransfer. Getdmaalignment a pointer to a system-defined routine to obtain the DMA alignment requirements of the controller.

For more information, see getdmaalignment. Readdmacounter a pointer to a system-defined routine to obtain the current transfer count for A DMA operation.

For more information, see Readdmacounter.  Getscattergatherlist a pointer to a system-defined routine that allocates map registers and creates a scatter/gather list For DMA.

For more information, see Getscattergatherlist.  Putscattergatherlist a pointer to a system-defined routine this frees map registers and A scatter/gather list after A DMA Operation is complete.

For more information, see Putscattergatherlist. Calculatescattergatherlist A Pointer to a system-defined routine this determines the buffer size needed to the Scatter/gather list that describes An I/O data buffer. This member are available only in versions 2 and later of Dma_operations.

For more information, see Calculatescattergatherlist. Buildscattergatherlist a pointer to a system-defined routine that allocates map registers and creates a Scatter/gather Li St for DMA in a driver-supplied buffer. This member are available only in versions 2 and later of Dma_operations.

For more information, see Buildscattergatherlist. Buildmdlfromscattergatherlist a pointer to a system-defined routine the builds an MDL corresponding to a scatter/gather List. This member are available only in versions 2 and later of Dma_operations.

For more information, see Buildmdlfromscattergatherlist. Getdmaadapterinfo a pointer to a system-defined routine that describes the capabilities of a Bus-master DMA device or A s Ystem DMA Controller. Getdmaadapterinfo is available only in VErsion 3 of Dma_operations.

For more information, see Getdmaadapterinfo. Getdmatransferinfo a pointer to a system-defined routine it describes the allocation requirements for A Scatter/gather List. This routine replaces Calculatescattergatherlist. Getdmatransferinfo is available only in version 3 of Dma_operations.

For more information, see Getdmatransferinfo. Initializedmatransfercontext a pointer to a system-defined routine the initializes an opaque DMA transfer context. The operating system stores the internal status of a DMA transfer in this context. Initializedmatransfercontext is available only in version 3 of Dma_operations.

For more information, see Initializedmatransfercontext. Allocatecommonbufferex a pointer to a system-defined routine the allocates memory for A common buffer and maps this memo Ry so, it can accessed both by the processor and by a DMA device. Allocatecommonbufferex is available only in version 3 of Dma_operations. For more information, see AllocAtecommonbufferex. Allocateadapterchannelex a pointer to a system-defined routine this allocates the resources required for A DMA transfer A nd then calls the driver-supplied Adaptercontrol routine to initiate the DMA transfer. Allocateadapterchannelex is available only in version 3 of Dma_operations.

For more information, see Allocateadapterchannelex. Configureadapterchannel a pointer to a system-defined routine enables a custom function that's implemented by the DMA Co Ntroller. Configureadapterchannel is available only in version 3 of Dma_operations.

For more information, see Configureadapterchannel. Canceladapterchannel a pointer to a system-defined routine this tries to cancel a pending request to allocate a DMA Chann El Canceladapterchannel is available only in version 3 of Dma_operations.

For more information, see Canceladapterchannel. Maptransferex a pointer to a system-defined routine this sets up map registers to map the physical addresses in A scatter /gather list to THe logical addresses that is required to do a DMA transfer. Maptransferex is available only in version 3 of Dma_operations.

For more information, see Maptransferex.  Getscattergatherlistex a pointer to a system-defined routine this allocates resources required for A DMA transfer, builds A scatter/gather list, and then calls the driver-supplied Adapterlistcontrol routine to initiate the DMA transfer. Getscattergatherlistex is available only in version 3 of Dma_operations. For more information, see Getscattergatherlistex.

This routine is a wrapper of Allocateadapterchannelex and Maptransferex. Buildscattergatherlistex a pointer to a system-defined routine this builds a scatter/gather list in a caller-allocated bu Ffer, and then calls the driver-supplied Adapterlistcontrol routine to initiate the DMA transfer. Buildscattergatherlistex is available only in version 3 of Dma_operations.

For more information, see Buildscattergatherlistex. Flushadapterbuffersex a pointer to a System-definEd routine that flushes any data this remains in the system DMA controller ' s internal cache or in a bus-master adapter ' s I Nternal cache at the end of a DMA transfer. For a device which uses a system DMA controller, this routine cancels the current DMA transfer on the controller if the TRA Nsfer is isn't complete. Flushadapterbuffersex is available only in version 3 of Dma_operations.

For more information, see Flushadapterbuffersex. Freeadapterobject a pointer to a system-defined routine so releases the specified adapter object after A driver have com pleted all DMA operations. Freeadapterobject is available only in version 3 of Dma_operations.

For more information, see Freeadapterobject. Cancelmappedtransfer a pointer to a system-defined routine that cancels A mapped transfer. Cancelmappedtransfer is available only in version 3 of Dma_operations.
 For more information, see Cancelmappedtransfer.

2,maximumlength refers to the maximum length that a single DMA can operate. It needs to be specified at Iogetdmaadapter, where the length determines the single maximum transmission length, and the maximum map regs.

Iogetdmaadapter will return a maximum length based on maximunlength, if maxmumlength within the allowable range, the number of map regs returned = (A map regs + 1 that can describe this length). If the maximunlength exceeds the maximum length, it returns a map regs that corresponds to the maximum length allowed. For storage Such a device, the maximum transmission length is usually 1M, corresponding to 256 map Reg. If the length here is set to 64k, the maximum length of a single storage can be transferred from 1M to 64k.