Generic session class. More...

#include <libsmu.hpp>

Public Member Functions
int	scan ()
	Scan system for all supported devices. Updates the list of available, supported devices for the session (m_available_devices). More...

int	add (Device *device)
	Add a device to the session. This method may not be called while the session is active. More...

int	add_all ()
	Shim to scan and add all available devices to a session. This method may not be called while the session is active. More...

int	remove (Device *device, bool detached=false)
	Remove a device from the session. More...

int	destroy (Device *device)
	Remove a device from the list of available devices. More...

int	configure (uint32_t sampleRate=0)
	Configure the session's sample rate. More...

int	run (uint64_t samples)
	Run the currently configured capture and wait for it to complete. More...

int	start (uint64_t samples)
	Start the currently configured capture, but do not wait for it to complete. More...

int	cancel ()
	Cancel capture and block waiting for it to complete. More...

bool	cancelled ()
	Determine the cancellation status of a session. More...

void	flush ()
	Flush the read and write queues for all devices in a session.

int	scan_samba_devs (std::vector< libusb_device * > &samba_devs)
	Scan system for devices in SAM-BA mode. More...

int	flash_firmware (std::string file, std::vector< Device * > devices={})
	Update firmware for the target device(s). More...

void	completion ()
	internal: Called by devices on the USB thread when they are complete.

void	handle_error (int status, const char *tag)
	internal: Called by devices on the USB thread when a device encounters an error.

void	attached (libusb_device *usb_dev)
	internal: Called by device attach events on the USB thread.

void	detached (libusb_device *usb_dev)
	internal: Called by device detach events on the USB thread.

int	end ()
	For noncontinuous sessions, block until all devices have completed, then turn off the devices. Continuous sessions don't wait for completion and instead proceed with turning off the devices after canceling the session. More...

Public Attributes
std::vector< Device * >	m_available_devices
	Devices that are present on the system. Note that these devices consist of all supported devices currently recognized on the system; however, the devices aren't necessarily bound to a session. In order to add devices to a session, add() must be used.

std::set< Device * >	m_devices
	Devices that are part of this session. These devices will be started when start() is called. Use `add()` and `remove()` to manipulate this set.

unsigned	m_active_devices
	Number of devices currently streaming samples.

std::map< libusb_device , libusb_device_handle >	m_deviceHandles
	Map for the workaround described in session.cpp -> probe_device().

unsigned	m_queue_size = 100000
	Size of input/output sample queues for every device. Alter this if necessary to make continuous data flow work for the target usage. The default is approximately 100ms worth of samples at the maximum sampling rate. Note that must be changed before devices are added to a session otherwise they'll use the default.

std::function< void(unsigned)>	m_completion_callback
	Callback run via the USB thread on session completion. Called with the current value of m_cancellation as an argument, i.e. if the parameter is non-zero we are waiting to complete a cancelled session.

uint64_t	m_sample_rate = 0
	Session sample rate.

bool	m_continuous = false
	Flag used to determine if a session is in continuous mode or not.

Protected Member Functions
Device *	probe_device (libusb_device *usb_dev)
	Identify devices supported by libsmu. More...

Device *	find_existing_device (libusb_device *usb_dev)
	Find an existing, available device. More...

Protected Attributes
unsigned	m_cancellation = 0
	Flag used to cancel all pending USB transactions for devices in a session.

std::atomic< bool >	m_usb_thread_loop
	Flag for controlling USB event handling. USB event handling loop will be run while m_usb_thread_loop is true.

std::thread	m_usb_thread
	USB thread handling pending events in blocking mode.

std::mutex	m_lock
	Lock for session completion.

std::mutex	m_lock_devlist
	Lock for the available device list. All code that references m_available_devices needs to acquire this lock before accessing it.

std::condition_variable	m_completion
	Blocks on m_lock until session completion is finished.

libusb_context *	m_usb_ctx
	libusb context related with a session. This allows for segregating libusb usage so external users can also use libusb without interfering with internal usage.

libusb_hotplug_callback_handle	m_usb_cb
	libusb hotplug callback handle.

std::vector< std::function< void(Device *device)> >	m_hotplug_attach_callbacks
	Callbacks called on the USB thread when a device is removed from the system.

std::vector< std::function< void(Device *device)> >	m_hotplug_detach_callbacks
	Callbacks called on the USB thread when a device is plugged into the system.

Detailed Description

Generic session class.

Member Function Documentation

◆ add()

int smu::Session::add ( Device * device )

Add a device to the session. This method may not be called while the session is active.

Parameters

device The device to be added to the session.

Returns: On success, 0 is returned.; On error, a negative errno code is returned.

◆ add_all()

int smu::Session::add_all ( )

Shim to scan and add all available devices to a session. This method may not be called while the session is active.

Returns: On success, the number of devices added to the session is returned.; On error, a negative errno code is returned.

◆ cancel()

int smu::Session::cancel ( )

Cancel capture and block waiting for it to complete.

Returns: On success, 0 is returned.; On error, -1 is returned. Note that the cancellation process will stop on the first device that fails to cancel its capture.

◆ cancelled()

bool smu::Session::cancelled ( )

inline

Determine the cancellation status of a session.

Returns: True, if the session has been cancelled (usually from explicitly calling cancel() or cancelled USB transactions).; False, if the session hasn't been started, is running, or has been stopped successfully.

◆ configure()

int smu::Session::configure ( uint32_t sampleRate = 0 )

Configure the session's sample rate.

Parameters

sampleRate The requested sample rate for the session. Requesting a sample rate of 0 (the default) causes the session to use the first device's default sample rate.

Returns: On success, the configured sample rate is returned.; On error, a negative errno code is returned. This method may not be called while the session is active.

◆ destroy()

int smu::Session::destroy ( Device * device )

Remove a device from the list of available devices.

Parameters

device A device to be removed from the available list. Devices are automatically added to this list on attach. Devices must be removed from this list on detach. This method may not be called while the session is active.

Returns: On success, 0 is returned.; On error, a negative errno code is returned.

◆ end()

int smu::Session::end ( )

For noncontinuous sessions, block until all devices have completed, then turn off the devices. Continuous sessions don't wait for completion and instead proceed with turning off the devices after canceling the session.

Returns: On success, 0 is returned.; On error, a negative errno code is returned.

◆ find_existing_device()

Device* smu::Session::find_existing_device ( libusb_device * usb_dev )

protected

Find an existing, available device.

Parameters

usb_dev libusb device

Returns: If the usb device relates to an existing, available device the Device is returned, otherwise NULL is returned.

◆ flash_firmware()

int smu::Session::flash_firmware	(	std::string	file,
		std::vector< Device * >	devices = `{}`
	)

Update firmware for the target device(s).

Parameters

file	Path to firmware file.
devices	The device(s) targeted for updating. If empty or unset, all the attached devices in SAM-BA mode are updated.

Returns: On success, the number of devices flashed is returned.

Exceptions

std::runtime_error for various USB failures causing aborted flashes.

◆ probe_device()

Device* smu::Session::probe_device ( libusb_device * usb_dev )

protected

Identify devices supported by libsmu.

Parameters

usb_dev libusb device

Returns: If the usb device relates to a supported device the Device is returned, otherwise NULL is returned.

◆ remove()

int smu::Session::remove	(	Device *	device,
		bool	detached = `false`
	)

Remove a device from the session.

Parameters

device	A device to be removed from the session.
detached	True if the device has already been detached from the system (defaults to false). This method may not be called while the session is active.

Returns: On success, 0 is returned.; On error, a negative errno code is returned.

◆ run()

int smu::Session::run ( uint64_t samples )

Run the currently configured capture and wait for it to complete.

Parameters

samples Number of samples to capture until we stop. If 0, run in continuous mode.

Returns: On success, 0 is returned.; On error, a negative errno code is returned.

Exceptions

std::system_error of EBUSY if sample underflows/overflows have occurred.

◆ scan()

int smu::Session::scan ( )

Scan system for all supported devices. Updates the list of available, supported devices for the session (m_available_devices).

Returns: On success, the number of devices found is returned.; On error, a negative errno code is returned.

◆ scan_samba_devs()

int smu::Session::scan_samba_devs ( std::vector< libusb_device * > & samba_devs )

Scan system for devices in SAM-BA mode.

Parameters

samba_devs Vector of libusb devices in SAM-BA mode.

Returns: On success, the number of devices found is returned.; On error, a negative errno code is returned.

◆ start()

int smu::Session::start ( uint64_t samples )

Start the currently configured capture, but do not wait for it to complete.

Parameters

samples Number of samples to capture until we stop. If 0, run in continuous mode.

Note that the number of samples actually captured will be the nearest multiple of the amount of samples per USB packet larger than the request amount of samples.

Once started, the only allowed Session methods are cancel() and end() until the session has stopped.

Returns: On success, 0 is returned.; On error, a negative errno code is returned.

Exceptions

std::system_error of EBUSY if sample underflows/overflows have occurred.

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

/home/vsts/work/1/s/include/libsmu/libsmu.hpp

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

◆ add()

◆ add_all()

◆ cancel()

◆ cancelled()

◆ configure()

◆ destroy()

◆ end()

◆ find_existing_device()

◆ flash_firmware()

◆ probe_device()

◆ remove()

◆ run()

◆ scan()

◆ scan_samba_devs()

◆ start()