Edit

AVStream Allocators

  • Article

The AVStream class driver uses an Allocator to allocate data buffers in units called frames. A frame is a chunk of continuous memory, the size of which is vendor-specified through the AllocatorFraming member of KSPIN_DESCRIPTOR_EX.

Minidrivers access these buffers through the Stream Pointers API; call KsPinGetLeadingEdgeStreamPointer to acquire a pointer into the stream.

AVStream clients can obtain information about the framing requirements of a pin by using the read-only property KSPROPERTY_CONNECTION_ALLOCATORFRAMING_EX. This property returns a structure of type KSALLOCATOR_FRAMING_EX that describe the framing requirements for the pin.

When data is no longer in use, AVStream uses the allocator to free the buffer.

AVStream provides a default allocator. The default allocator allocates pool memory based on the allocator requirements that the minidriver provides in the AllocatorFraming member of the KSPIN_DESCRIPTOR_EX structure.

A vendor with device-specific allocation requirements can write a minidriver that includes its own allocation routines. For example, you might provide an allocator if your driver allocates memory from a common DMA buffer.

To provide an allocator, supply a KSALLOCATOR_DISPATCH structure that contains pointers to the following vendor-supplied callback routines:

Provide a pointer to this allocator dispatch structure in the Allocator member of the KSPIN_DISPATCH structure describing the pin for which this allocator will instantiate frames.

Supply a pointer to this pin dispatch structure in the Dispatch member of the corresponding KSPIN_DESCRIPTOR_EX structure. To learn more about dispatch structures in AVStream, read AVStream Dispatch Tables.

At run time, the graph manager (for example, the Kernel Streaming Proxy module) handles allocator selection. A vendor-supplied allocator is not guaranteed to be selected by the graph manager.

A kernel-mode allocator is only chosen if the connection is in kernel mode. In addition, your allocator could be rejected if there is a mismatch in allocator requirements and your allocator's capabilities. If your allocator is not selected, your AVStrMiniInitializeAllocator callback routine is never called.

Also see AVStream DMA Services and Stream Pointers.