DSI Stream API

Functions operating on DSI streams. More...


Functions
int	dsi_stream_create (dsi_component_t sender, dsi_component_t receiver, l4dm_dataspace_t ctrl, l4dm_dataspace_t data, dsi_stream_t **stream)
	Create application stream and connect send/receive component.
int	dsi_stream_start (dsi_stream_t *stream)
	Send start messages to send/receive components.
int	dsi_stream_stop (dsi_stream_t *stream)
	stop the transfer on a stream This function calls the stop-functions provided on dsi_stream_create() to stop the data transfer. It is up to the two components to react in a reasonable way, dsi does not check anything, it just calls the functions, first sender, receiver then.
int	dsi_stream_close (dsi_stream_t *stream)
	Close stream.
int	dsi_stream_select (dsi_select_socket_t sockets, const int num_sockets, dsi_select_socket_t events, int *num_events)
	Wait for component events.

Detailed Description

Functions operating on DSI streams.

Streams connect a send and a receive socket. Usually, they are created by in-the-middle client applications.

Function Documentation

int dsi_stream_close ( dsi_stream_t * stream )

Close stream.

Parameters:

stream

Stream descriptor

Returns:

0 on success (stream closed), error code otherwise:

-L4_EINVAL invalid socket descriptor
-DSI_ECOMPONENT component operation failed

We need two steps to close a stream: 1. Stop the send and receive component. After the stop function returned we can be sure that a component stopped its processing and does not access stream data anymore. 2. Close the sockets and the stream. These two steps are required to ensure that no resource are released in a component while the other component still uses them.

Definition at line 335 of file app.c.

References dsi_component::close, dsi_is_valid_stream(), dsi_stream::flags, dsi_stream::receiver, dsi_stream::sender, dsi_component::socketref, dsi_component::stop, and dsi_socket_ref::work_th.

int dsi_stream_create	(	dsi_component_t *	sender,
		dsi_component_t *	receiver,
		l4dm_dataspace_t	ctrl,
		l4dm_dataspace_t	data,
		dsi_stream_t **	stream
	)

Create application stream and connect send/receive component.

Parameters:

	sender	description of send component
	receiver	description od receive component
	ctrl	control area
	data	data area

Return values:

	0	success, created stream, `stream` contains stream descriptor
	-L4_EINVAL	invalid component / dataspace descriptors
	-DSI_ECONNECT	connect call to sender or receiver failed
	-DSI_ENOSTREAM	no stream descriptor available

Definition at line 132 of file app.c.

References __allocate_stream(), dsi_stream::__private, dsi_component::connect, dsi_stream::ctrl, dsi_stream::data, dsi_is_valid_component(), dsi_stream::flags, dsi_stream::receiver, dsi_stream::sender, and dsi_component::socketref.

int dsi_stream_select	(	dsi_select_socket_t *	sockets,
		const int	num_sockets,
		dsi_select_socket_t *	events,
		int *	num_events
	)

Wait for component events.

Parameters:

	sockets	Socket list, the struct must contain: `stream` Stream descriptor `component` Component (either `DSI_SEND_COMPONENT` or `DSI_RECEIVE_COMPONENT`) `event` Event mask
	num_sockets	Number of sockets

Return values:

	events	Event list, it contains all sockets for which an event was received, the elements are: `stream` Stream descriptor `component` Component `mask` Event mask set by the component
	num_events	Number of sockets for which an event was received.

Returns:

0 if one of the events was set by the component, error code otherwise:

-L4_EINVAL invalid stream descriptor
-L4_ENOTHREAD create select thread failed
-L4_EBUSY someone else already waiting for one of the events
-L4_EIPC IPC error calling component

Wait for component events. sockets contains a list of sockets and events masks. For each of these sockets a thread is created with dsi_create_select_thread(), which calls the components event signalling thread to wait for an event notification. If the first notification is received (it can be immediately if one of the events is already set by the component), the event is marked in the socket list, all threads are destroyed and the function returns.

Definition at line 126 of file select.c.

References __select_thread(), dsi_select_socket::component, dsi_create_select_thread(), dsi_event_reset(), dsi_is_valid_stream(), DSI_SEND_COMPONENT, dsi_shutdown_select_thread(), dsi_select_thread_arg::error, dsi_select_socket::events, dsi_select_thread_arg::events, dsi_select_thread_arg::mask, dsi_stream::receiver, dsi_select_thread_arg::sem, dsi_stream::sender, dsi_socket_ref::socket, dsi_select_thread_arg::socket, dsi_component::socketref, and dsi_select_socket::stream.

int dsi_stream_start ( dsi_stream_t * stream )

Send start messages to send/receive components.

Parameters:

stream

stream descriptor

Return values:

	0	success
	-L4_EINVAL	invalid stream descriptor

Conceptionally, this function starts the data transmission on a stream. Technically, this function just calls the start-functions of the send and receive component of the stream. They should be implemented in a way that data transmission is started this way. It is perfectly legal for a send component to already start its send operation after dsi_stream_create() to achieve its preload needed for real-time guarantees. But the send component may stop generating packets after it achieved its preload until dsi_stream_start() is called.

Definition at line 224 of file app.c.

References dsi_is_valid_stream(), dsi_stream::receiver, dsi_stream::sender, and dsi_component::start.

int dsi_stream_stop ( dsi_stream_t * stream )

stop the transfer on a stream

This function calls the stop-functions provided on dsi_stream_create() to stop the data transfer. It is up to the two components to react in a reasonable way, dsi does not check anything, it just calls the functions, first sender, receiver then.

Parameters:

stream

stream descriptor

Return values:

	0	on success
	-L4_EINVAL	invalid stream descriptor

Definition at line 274 of file app.c.

References dsi_is_valid_stream(), dsi_stream::receiver, dsi_stream::sender, dsi_component::socketref, dsi_component::stop, and dsi_socket_ref::work_th.