IPortWaveCyclic::NewSlaveDmaChannel method

The NewSlaveDmaChannel method creates a new instance of a subordinate DMA channel.

Syntax

NTSTATUS NewSlaveDmaChannel(
  PDMACHANNELSLAVE *DmaChannel,
  PUNKNOWN         OuterUnknown,
  PRESOURCELIST    ResourceList,
  ULONG            DmaIndex,
  ULONG            MaximumLength,
  BOOLEAN          DemandMode,
  DMA_SPEED        DmaSpeed
);

Parameters

DmaChannel

Pointer to a caller-allocated pointer variable into which the method writes a pointer to the new DMA-channel object's IDmaChannelSlave interface. 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 an IResourceList object. This resource list contains the resource that describes the DMA channel.

DmaIndex

Index in the resource list of the DMA-channel descriptor. The function uses this value as a call parameter to the ResourceList object's IResourceList::FindxxxEntry method.

MaximumLength

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

DemandMode

Indicates whether the device associated with the DMA channel supports demand mode.

DmaSpeed

The DMA speed can be specified as one of the following DMA_SPEED enumeration values: Compatible, TypeA, TypeB, TypeC, or TypeF.

Return value

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

Remarks

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

A WaveCyclic device that lacks DMA-hardware capabilities is referred to as a subordinate device. In contrast, a master device has built-in bus-mastering DMA hardware. A subordinate device has to rely on the system DMA controller to perform any data transfers that it requires. The NewSlaveDmaChannel method creates a DMA-channel object for a subordinate device. To create a DMA-channel object for a master device, call the IPortWaveCyclic::NewMasterDmaChannel method instead. The sb16 sample audio driver in the Microsoft Windows Driver Kit (WDK) is an example of a WaveCyclic miniport driver for a subordinate device. For more information about master and subordinate devices, see IDmaChannel and IDmaChannelSlave.

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

Requirements

   
Target Platform Universal
Header portcls.h (include Portcls.h)
IRQL PASSIVE_LEVEL

See also

DEVICE_DESCRIPTION

IDmaChannel

IDmaChannelSlave

IPortWaveCyclic

IPortWaveCyclic::NewMasterDmaChannel

IResourceList