IPortWaveCyclic::NewMasterDmaChannel method (portcls.h)

Article
10/21/2021

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

Syntax

NTSTATUS NewMasterDmaChannel(
  [out]          PDMACHANNEL   *DmaChannel,
  [in]           PUNKNOWN      OuterUnknown,
  [in, optional] PRESOURCELIST ResourceList,
  [in]           ULONG         MaximumLength,
  [in]           BOOLEAN       Dma32BitAddresses,
  [in]           BOOLEAN       Dma64BitAddresses,
  [in]           DMA_WIDTH     DmaWidth,
  [in]           DMA_SPEED     DmaSpeed
);

Parameters

[out] 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.

[in] 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.

[in, optional] 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.

[in] MaximumLength

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

[in] Dma32BitAddresses

Specifies the use of 32-bit addresses.

[in] Dma64BitAddresses

Specifies the use of 64-bit addresses.

[in] DmaWidth

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

[in] 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.

Remarks

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 subordinate 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 subordinate device, call the IPortWaveCyclic::NewSlaveDmaChannel method instead. 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.

Note

Microsoft supports a diverse and inclusive environment. This article contains references to terminology that the Microsoft style guide for bias-free communication recognizes as exclusionary. The word or phrase is used in this article for consistency because it currently appears in the software. When the software is updated to remove the language, this article will be updated to be in alignment.

Requirements

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