dxd - dynax driver framework  2675
cross platform open source driver development framework
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
dxd::usb_stream::stream Class Reference

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::circularoperator-> () const
 operator to use mapping like pointer More...
 
dx::circularoperator-> ()
 
 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_resultan 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_deviceUSB device
openstream metrics
idstream 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_deviceUSB device
openstream metrics
idxstream 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
datavirtual base address of range to create memory descriptor from
sizesize 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
datavirtual base address of range to create memory descriptor from
sizesize 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
datavirtual base address of range to create memory descriptor from
sizesize of range to create memory descriptor from
os_result dxd::memory< scope_t >::initialize ( void *  data,
size_t  size 
)
inherited

IOKit memory initializer.

Parameters
datavirtual base address of range to create memory descriptor from
sizesize 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_descriptorIOMemoryDescriptor to be mapped into the kernel address space
offsetoffset 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
sizesize to be alloced by buffer object
limitlimit physical memory address space
alignmentenforce physical memory alignment
contigousenforce 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:

(c) copyright 2009 dynamic acoustics e.U. generated on Tue Dec 4 2018

a closed source license may be obtained by requesting a written permission from dynamic acoustics e.U.
however - governmental use generally and military use especially is strictly prohibited though.