KsDeviceRegisterAdapterObject function (ks.h)

The KsDeviceRegisterAdapterObject function registers a DMA adapter object with AVStream for performing scatter/gather DMA on the specified device. All drivers compiled for Win64 should use IKsDeviceFunctions::RegisterAdapterObjectEx instead.

Syntax

void KsDeviceRegisterAdapterObject(
  [in] PKSDEVICE       Device,
  [in] PADAPTER_OBJECT AdapterObject,
  [in] ULONG           MaxMappingsByteCount,
  [in] ULONG           MappingTableStride
);

Parameters

[in] Device

A pointer to the KSDEVICE structure representing the AVStream device for which to register an adapter object.

[in] AdapterObject

A pointer to the DMA_ADAPTER structure returned by IoGetDmaAdapter that represents the DMA controller..

[in] MaxMappingsByteCount

This parameter specifies the maximum number of bytes that the device can handle for a single mapping. Allows AVStream to automatically break up large chunks of contiguous physical memory into multiple scatter/gather elements for devices that impose a size limit on individual mappings in DMA transfers. Breaks are not guaranteed to occur on page boundaries.

[in] MappingTableStride

This parameter specifies how many bytes each entry in the mapping table requires. This must be at least sizeof (KSMAPPING) and can be as large as necessary.

Additional space can be used by the minidriver as context information.

Return value

None

Remarks

A minidriver that calls KsDeviceRegisterAdapterObject is responsible for previously acquiring the adapter object through IoGetDmaAdapter.

Also note that if the minidriver specifies the KSPIN_FLAG_GENERATE_MAPPINGS flag for any pin on any filter on the device, the minidriver must call KsDeviceRegisterAdapterObject before processing any data. More information about this flag can be found in the reference page for KSPIN_DESCRIPTOR_EX. Also see AVStream DMA Services.

If you set MaxMappingByteCount to one physical page in length, mappings are not guaranteed to reside on a single physical page. In addition, as noted in the member description above, setting MaxMappingsByteCount does not guarantee that breaks will occur on page boundaries. If you require breaks on page boundaries, consider not specifying a limit on mapping sizes; instead, break the returned scatter/gather mappings into page-aligned chunks manually.

Also see Supporting DMA in 64-Bit AVStream Drivers.

Requirements

See also

IoGetDmaAdapter

KSFILTER_DESCRIPTOR

KSMAPPING

KSPIN_DESCRIPTOR_EX