USB stream. More...

#include <dxd_usb_stream.h>

Inheritance diagram for dxd::usb_stream::stream:

Collaboration diagram for dxd::usb_stream::stream:

Public Member Functions
void	free ()
	frees circular backing store and frame buffers More...

os_result	initialize (const void *data, size_t size)
	IOKit memory initializer. More...

os_result	initialize (const void *data, size_t size)
	IOKit memory initializer. More...

os_result	initialize (const ::MDL *mdl)

os_result	initialize (const ::MDL *mdl)

os_result	initialize (void *data, size_t size)
	IOKit memory initializer. More...

os_result	initialize (void *data, size_t size)
	IOKit memory initializer. More...

os_result	initialize (const ::MDL *mdl, size_t offset, size_t size)

os_result	initialize (const ::MDL *mdl, size_t offset, size_t size)

os_result	initialize (::IOMemoryDescriptor *iokit_memory_descriptor)
	IOKit memory initializer. More...

os_result	initialize (::IOMemoryDescriptor *iokit_memory_descriptor)
	IOKit memory initializer. More...

os_result	initialize (::IOMemoryDescriptor *iokit_memory_descriptor, size_t offset, size_t size)
	IOKit memory initializer. More...

os_result	initialize (::IOMemoryDescriptor *iokit_memory_descriptor, size_t offset, size_t size)
	IOKit memory initializer. More...

os_result	initialize (::IOMemoryDescriptor *iokit_memory_descriptor, size_t offset=0)
	IOKit kernel map initializer. More...

os_result	initialize (size_t size, unsigned int limit=limit_t, unsigned int alignment=alignment_t, bool contigous=contigous_t)
	IOKit buffer initializer. More...

os_result	initialize (unsigned int line_size, unsigned int cycles, unsigned int sample_rate)
	creates circular backing store and frame buffers for isoc streaming More...

os_result	initialize (unsigned int buffers)
	creates circular backing store and frame buffers for non-isoc streaming More...

os_result	line_size (unsigned int line_size)
	sets the line_size More...

	operator const ::IOMemoryDescriptor * () const
	IOKit IOMemoryDescriptor* implicit cast. More...

	operator const ::IOMemoryDescriptor * () const
	IOKit IOMemoryDescriptor* implicit cast. More...

	operator const ::IOMemoryMap * () const

	operator const dx::circular * () const

	operator dx::circular * () const

	operator uint64_t () const
	IOKit physical address (only relevant for contigous memory) More...

	operator uint64_t () const
	IOKit physical address (only relevant for contigous memory) More...

const dx::circular *	operator-> () const
	operator to use mapping like pointer More...

dx::circular *	operator-> ()

	operator::IOMemoryDescriptor * ()

	operator::IOMemoryDescriptor * ()

	operator::IOMemoryMap * ()

	operator::MDL * () const

	operator::MDL * () const

template<typename reference_t >
int	release (reference_t &reference)

void	retain ()

os_result	sample_rate (dx::uint24 sample_rate)
	sets the sampling rate More...

dx::uint24	sample_rate () const

size_t	size () const
	IOKit memory size. More...

size_t	size () const
	IOKit memory size. More...

size_t	size () const
	kernel mapping size More...

os_result	start (bool force=false) override
	starts the USB streaming More...

os_result	stop (bool force=false) override

	stream (class usb_device &usb_device, const dx::stream::open< dx::usb::isoc > &open, int id)
	USB isoc endpoint constructor. More...

	stream (class usb_device &usb_device, const dx::stream::open< dx::usb::bulk > &open, int idx)
	USB bulk/IRQ endpoint constructor. More...

os_result	synchronize ()
	synchronizes to isoc device cycles More...

virtual	~stream ()
	stream destructor More...

Public Attributes
event	data
	data available event More...

event	gap
	gap (space) available event More...

os_result	status =not_initialized

Protected Attributes
dx::circular *	_vm
	kernel virtual address mapping More...

::IOMemoryMap *	iokit_memory_map

Private Types
enum	priority { priority::low =LOW_PRIORITY, priority::realtime =LOW_REALTIME_PRIORITY, priority::high =HIGH_PRIORITY }

Private Member Functions
os_result	prio (priority priority)

os_result	run ()
	IOKit process thread start. More...

os_result	run ()

Static Private Member Functions
static unsigned int	prio ()

static unsigned int	prio ()

Friends
struct	dx::circular

Detailed Description

USB stream.

Handling of high speed/low latency/high performance streams:

3 requests with dedicated buffers are circulating: (a) actually handled - (p) to be prepared - (w) request waiting for device 0:(p) (a) (w) 1:(w) (p) (a) 2:(a) (w) (p) This way there is always at least one request scheduled(w). When data ready is signalled a new request is first scheduled(p) and the (a) actual data is handled. The cycle starts by scheduling (p) and (w).

Exceptions

os_result an error returned by the underlaying KPIs is reflected by the methods return value. The object status can be retrieved by the status member.

Constructor & Destructor Documentation

dxd::usb_stream::stream::stream	(	class usb_device &	usb_device,
		const dx::stream::open< dx::usb::isoc > &	open,
		int	id
	)

inline

USB isoc endpoint constructor.

Checks the underlaying pipe construction state,

Todo:: default sample rate from clock description

Parameters

usb_device	USB device
open	stream metrics
id	stream ID

Here is the call graph for this function:

dxd::usb_stream::stream::stream	(	class usb_device &	usb_device,
		const dx::stream::open< dx::usb::bulk > &	open,
		int	idx
	)

inline

USB bulk/IRQ endpoint constructor.

Checks the underlaying pipe construction state,

check process creation status

Parameters

usb_device	USB device
open	stream metrics
idx	stream ID

Here is the call graph for this function:

virtual dxd::usb_stream::stream::~stream ( )

inline

stream destructor

Here is the call graph for this function:

Member Function Documentation

void dxd::usb_stream::stream::free ( )

inline

frees circular backing store and frame buffers

stops any outstanding requests,

releases intermittent device frame buffer,

unmaps kernel mapping to backing store

and release backing store.

Here is the call graph for this function:

Here is the caller graph for this function:

os_result dxd::memory< scope_t >::initialize	(	const void *	data,
		size_t	size
	)

inherited

IOKit memory initializer.

Parameters

data	virtual base address of range to create memory descriptor from
size	size of range to create memory descriptor from

os_result dxd::memory< scope_t >::initialize	(	const void *	data,
		size_t	size
	)

inherited

IOKit memory initializer.

Parameters

data	virtual base address of range to create memory descriptor from
size	size of range to create memory descriptor from

os_result dxd::memory< scope_t >::initialize ( const ::MDL * mdl )

inlineinherited

in contrast to an IOKit MemoryDescriptor MDLs do not support reference counting. take care when creating a dxd::memory from a dxd::buffer: although the dxd::memory holds an MDL to the buffer the buffer itself is not retained after the dxd::buffer is released!

Here is the call graph for this function:

os_result dxd::memory< scope_t >::initialize ( const ::MDL * mdl )

inlineinherited

in contrast to an IOKit MemoryDescriptor MDLs do not support reference counting. take care when creating a dxd::memory from a dxd::buffer: although the dxd::memory holds an MDL to the buffer the buffer itself is not retained after the dxd::buffer is released!

os_result dxd::memory< scope_t >::initialize	(	void *	data,
		size_t	size
	)

inherited

IOKit memory initializer.

Parameters

data	virtual base address of range to create memory descriptor from
size	size of range to create memory descriptor from

os_result dxd::memory< scope_t >::initialize	(	void *	data,
		size_t	size
	)

inherited

IOKit memory initializer.

Parameters

data	virtual base address of range to create memory descriptor from
size	size of range to create memory descriptor from

os_result dxd::memory< scope_t >::initialize	(	const ::MDL *	mdl,
		size_t	offset,
		size_t	size
	)

inlineinherited

os_result dxd::memory< scope_t >::initialize	(	const ::MDL *	mdl,
		size_t	offset,
		size_t	size
	)

inlineinherited

Here is the call graph for this function:

os_result dxd::memory< scope_t >::initialize ( ::IOMemoryDescriptor * iokit_memory_descriptor )

inlineinherited

IOKit memory initializer.

Here is the call graph for this function:

os_result dxd::memory< scope_t >::initialize ( ::IOMemoryDescriptor * iokit_memory_descriptor )

inlineinherited

IOKit memory initializer.

os_result dxd::memory< scope_t >::initialize	(	::IOMemoryDescriptor *	iokit_memory_descriptor,
		size_t	offset,
		size_t	size
	)

inlineinherited

IOKit memory initializer.

Here is the call graph for this function:

os_result dxd::memory< scope_t >::initialize	(	::IOMemoryDescriptor *	iokit_memory_descriptor,
		size_t	offset,
		size_t	size
	)

inlineinherited

IOKit memory initializer.

os_result dxd::map< scope_t, dx::circular >::initialize	(	::IOMemoryDescriptor *	iokit_memory_descriptor,
		size_t	offset = `0`
	)

inlineinherited

IOKit kernel map initializer.

map<kernel> maps an IOMemoryDescriptor (typically cast of a dxd::memory or buffer class) into the kernel address space.

https://developer.apple.com/library/content/qa/qa1197/_index.html

Allows re-initialization.

Checks buffer object,

maps the buffer into the kernel (will fail if offset is given)

and obtains a kernel virtual address (apply offset here instead).

Parameters

iokit_memory_descriptor	IOMemoryDescriptor to be mapped into the kernel address space
offset	offset into memory descriptor to create mapping

os_result dxd::buffer< scope_t, limit_t, alignment_t, contigous_t >::initialize	(	size_t	size,
		unsigned int	limit = `limit_t`,
		unsigned int	alignment = `alignment_t`,
		bool	contigous = `contigous_t`
	)

inlineinherited

IOKit buffer initializer.

Allows re-initialization.

Creates a buffer and associated memory descriptor.

Wires down the backing store memory.

Parameters

size	size to be alloced by buffer object
limit	limit physical memory address space
alignment	enforce physical memory alignment
contigous	enforce contiguos physical memory

os_result dxd::usb_stream::stream::initialize	(	unsigned int	line_size,
		unsigned int	cycles,
		unsigned int	sample_rate
	)

inline

creates circular backing store and frame buffers for isoc streaming

Todo:: initialize also RX isoc when no extralines are required

generates isoc cycle metrics from sample rate,

update max frame size

Todo:: reset max frame size when pipe is closed

create backing store memory,

map it

initializes circular buffer

Here is the call graph for this function:

Here is the caller graph for this function:

os_result dxd::usb_stream::stream::initialize ( unsigned int buffers )

inline

creates circular backing store and frame buffers for non-isoc streaming

create streaming backing store (twice the required size to accomodate single request wrap arounds)

map it

initializes circular buffer

creates frames inside backing store for continously overlapped streaming requests

creates intermittent device frame buffer

Here is the call graph for this function:

os_result dxd::usb_stream::stream::line_size ( unsigned int line_size )

inline

sets the line_size

may reinitialize streaming (different buffering!)

Here is the call graph for this function:

Here is the caller graph for this function:

dxd::memory< scope_t >::operator const ::IOMemoryDescriptor * ( ) const

inlineinherited

IOKit IOMemoryDescriptor* implicit cast.

dxd::memory< scope_t >::operator const ::IOMemoryDescriptor * ( ) const

inlineinherited

IOKit IOMemoryDescriptor* implicit cast.

dxd::map< scope_t, dx::circular >::operator const ::IOMemoryMap * ( ) const

inlineinherited

dxd::map< scope_t, dx::circular >::operator const dx::circular * ( ) const

inlineinherited

dxd::map< scope_t, dx::circular >::operator dx::circular * ( ) const

inlineinherited

dxd::memory< scope_t >::operator uint64_t ( ) const

inlineinherited

IOKit physical address (only relevant for contigous memory)

dxd::memory< scope_t >::operator uint64_t ( ) const

inlineinherited

IOKit physical address (only relevant for contigous memory)

const dx::circular * dxd::map< scope_t, dx::circular >::operator-> ( ) const

inlineinherited

operator to use mapping like pointer

dx::circular * dxd::map< scope_t, dx::circular >::operator-> ( )

inlineinherited

dxd::memory< scope_t >::operator::IOMemoryDescriptor * ( )

inlineinherited

dxd::memory< scope_t >::operator::IOMemoryDescriptor * ( )

inlineinherited

dxd::map< scope_t, dx::circular >::operator::IOMemoryMap * ( )

inlineinherited

dxd::memory< scope_t >::operator::MDL * ( ) const

inlineinherited

dxd::memory< scope_t >::operator::MDL * ( ) const

inlineinherited

template<typename reference_t >

int dxd::referenced::release ( reference_t & reference )

inlineinherited

void dxd::referenced::retain ( )

inlineinherited

Here is the caller graph for this function:

os_result dxd::usb_stream::stream::sample_rate ( dx::uint24 sample_rate )

inline

sets the sampling rate

may reinitialize streaming (different buffering!)

Here is the call graph for this function:

dx::uint24 dxd::usb_stream::stream::sample_rate ( ) const

inline

Here is the call graph for this function:

Here is the caller graph for this function:

size_t dxd::memory< scope_t >::size ( ) const

inlineinherited

IOKit memory size.

size_t dxd::memory< scope_t >::size ( ) const

inlineinherited

IOKit memory size.

size_t dxd::map< scope_t, dx::circular >::size ( ) const

inlineinherited

kernel mapping size

Here is the caller graph for this function:

os_result dxd::usb_stream::stream::start ( bool force = false )

inlineoverridevirtual

starts the USB streaming

initializes/resets circular buffer

synchronizes to isoc device cycles,

estimate upcoming timestamp

Todo:: compute timestamp in ticks (not nsec)!

scheduling all but one isoc requests at least 1 sequence ahead; aligned to whole cycles,

if stream is sync master

it starts the sync master thread

else starts the USB stream listener

initiates new async cycle: issue requests

Implements dxd::stream.

Here is the call graph for this function:

os_result dxd::usb_stream::stream::stop ( bool force = false )

inlineoverridevirtual

If stream is sync master on bulk/irq pipe

it signals the sync master mode thread,

and waits for thread to finish

todo: move abort before master wait to avoid blocking if device doesn't handle transaction

Implements dxd::stream.

Here is the caller graph for this function:

os_result dxd::usb_stream::stream::synchronize ( )

inline

synchronizes to isoc device cycles

scheduling isoc sync request at least 1 complete cycles ahead; aligned to whole cycles,

correcting invalid frames

Here is the call graph for this function:

Friends And Related Function Documentation

friend struct dx::circular

friend

Member Data Documentation

dx::circular * dxd::map< scope_t, dx::circular >::_vm

protectedinherited

kernel virtual address mapping

event dxd::usb_stream::stream::data

data available event

event dxd::usb_stream::stream::gap

gap (space) available event

::IOMemoryMap* dxd::map< scope_t, dx::circular >::iokit_memory_map

protectedinherited

os_result dxd::usb_stream::stream::status =not_initialized

The documentation for this class was generated from the following file:

dxd_usb_stream.h

Public Member Functions

Public Attributes

Protected Attributes

Private Types

Private Member Functions

Static Private Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation