IPortWaveCyclic::NewSlaveDmaChannel

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

NTSTATUS
  NewSlaveDmaChannel(
    OUT PDMACHANNELSLAVE  *DmaChannel,
    IN PUNKNOWN  OuterUnknown,
    IN PRESOURCELIST  ResourceList  OPTIONAL,
    IN ULONG  DmaIndex,
    IN ULONG  MaximumLength,
    IN BOOL  DemandMode,
    IN 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.

Headers

Declared in portcls.h. Include portcls.h.

Comments

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 slave device. In contrast, a master device has built-in bus-mastering DMA hardware. A slave 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 slave device. To create a DMA-channel object for a master device, call the IPortWaveCyclic::NewMasterDmaChannel method instead. The sb16 sample driver in the Windows DDK is an example of a WaveCyclic miniport driver for a slave device. 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 NewSlaveDmaChannel must run at IRQL PASSIVE_LEVEL.

See Also

IPortWaveCyclic::NewMasterDmaChannel, IDmaChannel, IDmaChannelSlave, IResourceList, DEVICE_DESCRIPTION