IPortWavePci::NewMasterDmaChannel method (portcls.h)

Article
07/25/2023

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

Syntax

NTSTATUS NewMasterDmaChannel(
                 PDMACHANNEL   *OutDmaChannel,
  [in, optional] PUNKNOWN      OuterUnknown,
  [in]           POOL_TYPE     PoolType,
  [in, optional] PRESOURCELIST ResourceList,
  [in]           BOOLEAN       ScatterGather,
  [in]           BOOLEAN       Dma32BitAddresses,
  [in]           BOOLEAN       Dma64BitAddresses,
  [in]           BOOLEAN       IgnoreCount,
  [in]           DMA_WIDTH     DmaWidth,
  [in]           DMA_SPEED     DmaSpeed,
  [in]           ULONG         MaximumLength,
  [in]           ULONG         DmaPort
);

Parameters

OutDmaChannel

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

Specifies the type of storage pool from which the object is to be allocated. This is a POOL_TYPE enumeration value. Specify a nonpaged pool type for this parameter.

[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] ScatterGather

Requests that the DMA channel support scatter/gather DMA. Always set this parameter to TRUE.

[in] Dma32BitAddresses

Specifies the use of 32-bit addresses for DMA operations.

[in] Dma64BitAddresses

Specifies the use of 64-bit addresses for DMA operations.

[in] IgnoreCount

Indicates whether to ignore the DMA controller's transfer counter. Set to TRUE if the DMA controller in this platform does not maintain an accurate transfer counter, and therefore requires a workaround.

[in] DmaWidth

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

[in] DmaSpeed

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

[in] MaximumLength

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

[in] DmaPort

Not used. Set to 0.

Return value

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

Remarks

The definitions of the call parameters for the NewMasterDmaChannel method are similar to those for the members of the DEVICE_DESCRIPTION structure with the same names.

Specify the PoolType parameter to be one of the nonpaged pool types defined in the POOL_TYPE enumeration. The DMA-channel object must not reside in paged memory because several of the methods in the IDmaChannel interface can be called from IRQL DISPATCH_LEVEL.

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

Requirements

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