IPortWaveCyclic::NewMasterDmaChannel

The NewMasterDmaChannel method creates a new instance of a bus-master DMA channel.

NTSTATUS
  NewMasterDmaChannel(
    OUT PDMACHANNEL  *DmaChannel,
    IN PUNKNOWN  OuterUnknown,
    IN PRESOURCELIST  ResourceList  OPTIONAL,
    IN ULONG  MaximumLength,
    IN BOOL  Dma32BitAddresses,
    IN BOOL  Dma64BitAddresses,
    IN DMA_WIDTH  DmaWidth,
    IN DMA_SPEED  DmaSpeed
    ); 

Parameters

DmaChannel

Pointer to a caller-allocated pointer variable into which the method writes a pointer to the new IDmaChannel object. Specify a valid, non-NULL pointer value for this parameter.

OuterUnknown

Pointer to the IUnknown interface of an object that needs to aggregate the DMA-channel object. This parameter is optional. If aggregation is not required, specify this parameter as NULL.

ResourceList

Pointer to the miniport driver's resource list, which is an IResourceList object. This parameter is optional and can be specified as NULL. The NewMasterDmaChannel method currently makes no use of this parameter.

MaximumLength

Maximum length in bytes of the cyclic DMA buffer that will be associated with this channel.

Dma32BitAddresses

Specifies the use of 32-bit addresses.

Dma64BitAddresses

Specifies the use of 64-bit addresses.

DmaWidth

Not used. Set to (DMA_WIDTH)(-1).

DmaSpeed

Not used. Set to (DMA_SPEED)(-1).

Return Value

NewMasterDmaChannel returns STATUS_SUCCESS if the call was successful. Otherwise, the method returns an appropriate error code.

Headers

Declared in portcls.h. Include portcls.h.

Comments

Parameters MaximumLength, Dma32BitAddresses, Dma64BitAddresses, DmaWidth, and DmaSpeed are similar in meaning to the members of the DEVICE_DESCRIPTION structure with the same names.

A WaveCyclic device with built-in bus-mastering DMA hardware is referred to as a master device. In contrast, a slave device lacks DMA hardware and has to rely on the system DMA controller to perform any data transfers that it requires. The NewMasterDmaChannel method creates a DMA-channel object for a master device. To create a DMA-channel object for a slave device, call the IPortWaveCyclic::NewSlaveDmaChannel method instead. For more information about master and slave devices, see IDmaChannel and IDmaChannelSlave.

The DmaChannel, OuterUnknown, and ResourceList parameters follow the reference-counting conventions for COM objects.

Callers of NewMasterDmaChannel must run at IRQL PASSIVE_LEVEL.

See Also

IPortWaveCyclic::NewSlaveDmaChannel, IDmaChannel, IDmaChannelSlave, IResourceList, DEVICE_DESCRIPTION