Starting and handling decoding sessions. More...

Functions
int	srd_session_new (struct srd_session **sess)
	Create a decoding session. More...

int	srd_session_start (struct srd_session *sess)
	Start a decoding session. More...

int	srd_session_metadata_set (struct srd_session sess, int key, GVariant data)
	Set a metadata configuration key in a session. More...

int	srd_session_send (struct srd_session sess, uint64_t abs_start_samplenum, uint64_t abs_end_samplenum, const uint8_t inbuf, uint64_t inbuflen, uint64_t unitsize)
	Send a chunk of logic sample data to a running decoder session. More...

int	srd_session_send_eof (struct srd_session *sess)
	Communicate the end of the stream of sample data to the session. More...

int	srd_session_terminate_reset (struct srd_session *sess)
	Terminate currently executing decoders in a session, reset internal state. More...

int	srd_session_destroy (struct srd_session *sess)
	Destroy a decoding session. More...

int	srd_pd_output_callback_add (struct srd_session sess, int output_type, srd_pd_output_callback cb, void cb_data)
	Register/add a decoder output callback function. More...

Detailed Description

Starting and handling decoding sessions.

Function Documentation

int srd_pd_output_callback_add	(	struct srd_session *	sess,
		int	output_type,
		srd_pd_output_callback	cb,
		void *	cb_data
	)

Register/add a decoder output callback function.

The function will be called when a protocol decoder sends output back to the PD controller (except for Python objects, which only go up the stack).

Parameters

sess	The output session in which to register the callback. Must not be NULL.
output_type	The output type this callback will receive. Only one callback per output type can be registered.
cb	The function to call. Must not be NULL.
cb_data	Private data for the callback function. Can be NULL.

Since: 0.3.0

Definition at line 393 of file session.c.

References srd_pd_callback::cb, srd_pd_callback::cb_data, srd_pd_callback::output_type, SRD_ERR_ARG, SRD_OK, and SRD_PRIV.

int srd_session_destroy ( struct srd_session * sess )

Destroy a decoding session.

All decoder instances and output callbacks are properly released.

Parameters

sess	The session to be destroyed. Must not be NULL.

Returns: SRD_OK upon success, a (negative) error code otherwise.

Since: 0.3.0

Definition at line 357 of file session.c.

References SRD_ERR_ARG, and SRD_OK.

Referenced by srd_init().

Here is the caller graph for this function:

int srd_session_metadata_set	(	struct srd_session *	sess,
		int	key,
		GVariant *	data
	)

Set a metadata configuration key in a session.

Parameters

sess	The session to configure. Must not be NULL.
key	The configuration key (SRD_CONF_*).
data	The new value for the key, as a GVariant with GVariantType appropriate to that key. A floating reference can be passed in; its refcount will be sunk and unreferenced after use.

Returns: SRD_OK upon success, a (negative) error code otherwise.

Since: 0.3.0

Definition at line 159 of file session.c.

References SRD_CONF_SAMPLERATE, SRD_ERR_ARG, and SRD_OK.

int srd_session_new ( struct srd_session ** sess )

Create a decoding session.

A session holds all decoder instances, their stack relationships and output callbacks.

Parameters

sess	A pointer which will hold a pointer to a newly initialized session on return. Must not be NULL.

Returns: SRD_OK upon success, a (negative) error code otherwise.

Since: 0.3.0

Definition at line 61 of file session.c.

References SRD_ERR_ARG, and SRD_OK.

int srd_session_send	(	struct srd_session *	sess,
		uint64_t	abs_start_samplenum,
		uint64_t	abs_end_samplenum,
		const uint8_t *	inbuf,
		uint64_t	inbuflen,
		uint64_t	unitsize
	)

Send a chunk of logic sample data to a running decoder session.

If no channel map has been set up, the logic samples must be arranged in channel order, in the least amount of space possible. The default channel set consists of all required channels + all optional channels.

The size of a sample in inbuf is 'unitsize' bytes. If no channel map has been configured, it is the minimum number of bytes needed to store the default channels.

The calls to this function must provide the samples that shall be used by the protocol decoder

in the correct order ([...]5, 6, 4, 7, 8[...] is a bug),
starting from sample zero (2, 3, 4, 5, 6[...] is a bug),
consecutively, with no gaps (0, 1, 2, 4, 5[...] is a bug).

The start- and end-sample numbers are absolute sample numbers (relative to the start of the whole capture/file/stream), i.e. they are not relative sample numbers within the chunk specified by 'inbuf' and 'inbuflen'.

Correct example (4096 samples total, 4 chunks @ 1024 samples each): srd_session_send(s, 0, 1023, inbuf, 1024, 1); srd_session_send(s, 1024, 2047, inbuf, 1024, 1); srd_session_send(s, 2048, 3071, inbuf, 1024, 1); srd_session_send(s, 3072, 4095, inbuf, 1024, 1);

The chunk size ('inbuflen') can be arbitrary and can differ between calls.

Correct example (4096 samples total, 7 chunks @ various samples each): srd_session_send(s, 0, 1023, inbuf, 1024, 1); srd_session_send(s, 1024, 1123, inbuf, 100, 1); srd_session_send(s, 1124, 1423, inbuf, 300, 1); srd_session_send(s, 1424, 1642, inbuf, 219, 1); srd_session_send(s, 1643, 2047, inbuf, 405, 1); srd_session_send(s, 2048, 3071, inbuf, 1024, 1); srd_session_send(s, 3072, 4095, inbuf, 1024, 1);

INCORRECT example (4096 samples total, 4 chunks @ 1024 samples each, but the start- and end-samplenumbers are not absolute): srd_session_send(s, 0, 1023, inbuf, 1024, 1); srd_session_send(s, 0, 1023, inbuf, 1024, 1); srd_session_send(s, 0, 1023, inbuf, 1024, 1); srd_session_send(s, 0, 1023, inbuf, 1024, 1);

Parameters

sess	The session to use. Must not be NULL.
abs_start_samplenum	The absolute starting sample number for the buffer's sample set, relative to the start of capture.
abs_end_samplenum	The absolute ending sample number for the buffer's sample set, relative to the start of capture.
inbuf	Pointer to sample data. Must not be NULL.
inbuflen	Length in bytes of the buffer. Must be > 0.
unitsize	The number of bytes per sample. Must be > 0.

Returns: SRD_OK upon success, a (negative) error code otherwise.

Since: 0.4.0

Definition at line 262 of file session.c.

References SRD_ERR_ARG, and SRD_OK.

int srd_session_send_eof ( struct srd_session * sess )

Communicate the end of the stream of sample data to the session.

Parameters

[in] sess The session. Must not be NULL.

Returns: SRD_OK upon success. A (negative) error code otherwise.

Since: 0.6.0

Definition at line 290 of file session.c.

References SRD_ERR_ARG, and SRD_OK.

int srd_session_start ( struct srd_session * sess )

Start a decoding session.

Decoders, instances and stack must have been prepared beforehand, and all SRD_CONF parameters set.

Parameters

sess	The session to start. Must not be NULL.

Returns: SRD_OK upon success, a (negative) error code otherwise.

Since: 0.3.0

Definition at line 90 of file session.c.

References srd_decoder_inst::next_di, srd_decoder_inst::py_inst, SRD_CONF_SAMPLERATE, SRD_ERR_ARG, and SRD_OK.

int srd_session_terminate_reset ( struct srd_session * sess )

Terminate currently executing decoders in a session, reset internal state.

All decoder instances have their .wait() method terminated, which shall terminate .decode() as well. Afterwards the decoders' optional .reset() method gets executed.

This routine allows callers to abort pending expensive operations, when they are no longer interested in the decoders' results. Note that the decoder state is lost and aborted work cannot resume.

This routine also allows callers to re-use previously created decoder stacks to process new input data which is not related to previously processed input data. This avoids the necessity to re-construct the decoder stack.

Parameters

sess	The session in which to terminate decoders. Must not be NULL.

Returns: SRD_OK upon success, a (negative) error code otherwise.

Since: 0.5.1

Definition at line 329 of file session.c.

References SRD_ERR_ARG, and SRD_OK.

Functions

Detailed Description

Function Documentation