X-Git-Url: https://sigrok.org/gitweb/?p=libsigrokdecode.git;a=blobdiff_plain;f=controller.c;h=9f9b7b1820481c8e82e4c5992299b6a8cf370c24;hp=7987ea172b8d2270d9fc221246b57e84ab71f0fc;hb=0169f19c53e195df2f96c4df731ad3214c59e20a;hpb=b88e336b86493ee3d893f563d1d847d901f8ce07

diff --git a/controller.c b/controller.c
index 7987ea1..9f9b7b1 100644
--- a/controller.c
+++ b/controller.c
@@ -24,6 +24,7 @@
 #include <glib.h>
 #include <inttypes.h>
 #include <stdlib.h>
+#include <stdint.h>
 
 /**
  * @mainpage libsigrokdecode API
@@ -86,19 +87,17 @@
  * @{
  */
 
-/* List of decoder instances. */
-static GSList *di_list = NULL;
+/** @cond PRIVATE */
 
-/* List of frontend callbacks to receive decoder output. */
-static GSList *callbacks = NULL;
+SRD_PRIV GSList *sessions = NULL;
+static int max_session_id = -1;
 
-/** @cond PRIVATE */
+static int session_is_valid(struct srd_session *sess);
 
 /* decoder.c */
 extern SRD_PRIV GSList *pd_list;
 
 /* module_sigrokdecode.c */
-/* FIXME: SRD_PRIV causes issues on MinGW. Investigate. */
 extern PyMODINIT_FUNC PyInit_sigrokdecode(void);
 
 /* type_logic.c */
@@ -138,6 +137,11 @@ SRD_API int srd_init(const char *path)
 	int ret;
 	char *env_path;
 
+	if (max_session_id != -1) {
+		srd_err("libsigrokdecode is already initialized.");
+		return SRD_ERR;
+	}
+
 	srd_dbg("Initializing libsigrokdecode.");
 
 	/* Add our own module to the list of built-in modules. */
@@ -168,6 +172,8 @@ SRD_API int srd_init(const char *path)
 		}
 	}
 
+	max_session_id = 0;
+
 	return SRD_OK;
 }
 
@@ -187,8 +193,13 @@ SRD_API int srd_init(const char *path)
  */
 SRD_API int srd_exit(void)
 {
+	GSList *l;
+
 	srd_dbg("Exiting libsigrokdecode.");
 
+	for (l = sessions; l; l = l->next)
+		srd_session_destroy((struct srd_session *)l->data);
+
 	srd_decoder_unload_all();
 	g_slist_free(pd_list);
 	pd_list = NULL;
@@ -196,6 +207,8 @@ SRD_API int srd_exit(void)
 	/* Py_Finalize() returns void, any finalization errors are ignored. */
 	Py_Finalize();
 
+	max_session_id = -1;
+
 	return SRD_OK;
 }
 
@@ -254,21 +267,6 @@ SRD_PRIV int srd_decoder_searchpath_add(const char *path)
 	g_string_free(new_path, TRUE);
 	g_free(wc_new_path);
 
-//#ifdef _WIN32
-//	gchar **splitted;
-//
-//	/*
-//	 * On Windows/MinGW, Python's sys.path needs entries of the form
-//	 * 'C:\\foo\\bar' instead of '/foo/bar'.
-//	 */
-//
-//	splitted = g_strsplit(DECODERS_DIR, "/", 0);
-//	path = g_build_pathv("\\\\", splitted);
-//	g_strfreev(splitted);
-//#else
-//	path = g_strdup(DECODERS_DIR);
-//#endif
-
 	return SRD_OK;
 }
 
@@ -307,6 +305,16 @@ SRD_API int srd_inst_option_set(struct srd_decoder_inst *di,
 	const char *val_str;
 	char *dbg, *key;
 
+	if (!di) {
+		srd_err("Invalid decoder instance.");
+		return SRD_ERR_ARG;
+	}
+
+	if (!options) {
+		srd_err("Invalid options GHashTable.");
+		return SRD_ERR_ARG;
+	}
+
 	if (!PyObject_HasAttrString(di->decoder->py_dec, "options")) {
 		/* Decoder has no options. */
 		if (g_hash_table_size(options) == 0) {
@@ -328,8 +336,18 @@ SRD_API int srd_inst_option_set(struct srd_decoder_inst *di,
 	/* All of these are synthesized objects, so they're good. */
 	py_dec_optkeys = PyDict_Keys(py_dec_options);
 	num_optkeys = PyList_Size(py_dec_optkeys);
+
+	/*
+	 * The 'options' dictionary is a class variable, but we need to
+	 * change it. Changing it directly will affect the entire class,
+	 * so we need to create a new object for it, and populate that
+	 * instead.
+	 */
 	if (!(py_di_options = PyObject_GetAttrString(di->py_inst, "options")))
 		goto err_out;
+	Py_DECREF(py_di_options);
+	py_di_options = PyDict_New();
+	PyObject_SetAttrString(di->py_inst, "options", py_di_options);
 	for (i = 0; i < num_optkeys; i++) {
 		/* Get the default class value for this option. */
 		py_str_as_str(PyList_GetItem(py_dec_optkeys, i), &key);
@@ -409,13 +427,14 @@ SRD_API int srd_inst_option_set(struct srd_decoder_inst *di,
 	ret = SRD_OK;
 
 err_out:
-	Py_XDECREF(py_optlist);
 	Py_XDECREF(py_di_options);
 	Py_XDECREF(py_dec_optkeys);
 	Py_XDECREF(py_dec_options);
 	g_free(key);
-	if (PyErr_Occurred())
+	if (PyErr_Occurred()) {
 		srd_exception_catch("Stray exception in srd_inst_option_set().");
+		ret = SRD_ERR_PYTHON;
+	}
 
 	return ret;
 }
@@ -448,9 +467,8 @@ SRD_API int srd_inst_probe_set_all(struct srd_decoder_inst *di,
 	GList *l;
 	GSList *sl;
 	struct srd_probe *p;
-	int *new_probemap, new_probenum;
+	int *new_probemap, new_probenum, num_required_probes, num_probes, i;
 	char *probe_id;
-	int i, num_required_probes;
 
 	srd_dbg("set probes called for instance %s with list of %d probes",
 		di->inst_id, g_hash_table_size(new_probes));
@@ -480,9 +498,10 @@ SRD_API int srd_inst_probe_set_all(struct srd_decoder_inst *di,
 	for (i = 0; i < di->dec_num_probes; i++)
 		new_probemap[i] = -1;
 
+	num_probes = 0;
 	for (l = g_hash_table_get_keys(new_probes); l; l = l->next) {
 		probe_id = l->data;
-		probe_val= g_hash_table_lookup(new_probes, probe_id);
+		probe_val = g_hash_table_lookup(new_probes, probe_id);
 		if (!g_variant_is_of_type(probe_val, G_VARIANT_TYPE_INT32)) {
 			/* Probe name was specified without a value. */
 			srd_err("No probe number was specified for %s.",
@@ -506,7 +525,9 @@ SRD_API int srd_inst_probe_set_all(struct srd_decoder_inst *di,
 		new_probemap[p->order] = new_probenum;
 		srd_dbg("Setting probe mapping: %s (index %d) = probe %d.",
 			p->id, p->order, new_probenum);
+		num_probes++;
 	}
+	di->data_unitsize = (num_probes + 7) / 8;
 
 	srd_dbg("Final probe map:");
 	num_required_probes = g_slist_length(di->decoder->probes);
@@ -524,6 +545,7 @@ SRD_API int srd_inst_probe_set_all(struct srd_decoder_inst *di,
 /**
  * Create a new protocol decoder instance.
  *
+ * @param sess The session holding the protocol decoder instance.
  * @param decoder_id Decoder 'id' field.
  * @param options GHashtable of options which override the defaults set in
  *                the decoder class. May be NULL.
@@ -531,10 +553,10 @@ SRD_API int srd_inst_probe_set_all(struct srd_decoder_inst *di,
  * @return Pointer to a newly allocated struct srd_decoder_inst, or
  *         NULL in case of failure.
  *
- * @since 0.1.0
+ * @since 0.3.0
  */
-SRD_API struct srd_decoder_inst *srd_inst_new(const char *decoder_id,
-		GHashTable *options)
+SRD_API struct srd_decoder_inst *srd_inst_new(struct srd_session *sess,
+		const char *decoder_id, GHashTable *options)
 {
 	int i;
 	struct srd_decoder *dec;
@@ -543,6 +565,11 @@ SRD_API struct srd_decoder_inst *srd_inst_new(const char *decoder_id,
 
 	srd_dbg("Creating new %s instance.", decoder_id);
 
+	if (session_is_valid(sess) != SRD_OK) {
+		srd_err("Invalid session.");
+		return NULL;
+	}
+
 	if (!(dec = srd_decoder_get_by_id(decoder_id))) {
 		srd_err("Protocol decoder %s not found.", decoder_id);
 		return NULL;
@@ -554,6 +581,7 @@ SRD_API struct srd_decoder_inst *srd_inst_new(const char *decoder_id,
 	}
 
 	di->decoder = dec;
+	di->sess = sess;
 	if (options) {
 		inst_id = g_hash_table_lookup(options, "id");
 		di->inst_id = g_strdup(inst_id ? inst_id : decoder_id);
@@ -566,10 +594,10 @@ SRD_API struct srd_decoder_inst *srd_inst_new(const char *decoder_id,
 	 * order in which the decoder class defined them.
 	 */
 	di->dec_num_probes = g_slist_length(di->decoder->probes) +
-			     g_slist_length(di->decoder->opt_probes);
+			g_slist_length(di->decoder->opt_probes);
 	if (di->dec_num_probes) {
 		if (!(di->dec_probemap =
-		     g_try_malloc(sizeof(int) * di->dec_num_probes))) {
+				g_try_malloc(sizeof(int) * di->dec_num_probes))) {
 			srd_err("Failed to g_malloc() probe map.");
 			g_free(di);
 			return NULL;
@@ -577,12 +605,13 @@ SRD_API struct srd_decoder_inst *srd_inst_new(const char *decoder_id,
 		for (i = 0; i < di->dec_num_probes; i++)
 			di->dec_probemap[i] = i;
 	}
+	di->data_unitsize = (di->dec_num_probes + 7) / 8;
 
 	/* Create a new instance of this decoder class. */
 	if (!(di->py_inst = PyObject_CallObject(dec->py_dec, NULL))) {
 		if (PyErr_Occurred())
 			srd_exception_catch("failed to create %s instance: ",
-					    decoder_id);
+					decoder_id);
 		g_free(di->dec_probemap);
 		g_free(di);
 		return NULL;
@@ -595,7 +624,7 @@ SRD_API struct srd_decoder_inst *srd_inst_new(const char *decoder_id,
 	}
 
 	/* Instance takes input from a frontend by default. */
-	di_list = g_slist_append(di_list, di);
+	sess->di_list = g_slist_append(sess->di_list, di);
 
 	return di;
 }
@@ -603,24 +632,31 @@ SRD_API struct srd_decoder_inst *srd_inst_new(const char *decoder_id,
 /**
  * Stack a decoder instance on top of another.
  *
+ * @param sess The session holding the protocol decoder instances.
  * @param di_from The instance to move.
  * @param di_to The instance on top of which di_from will be stacked.
  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
  *
- * @since 0.1.0
+ * @since 0.3.0
  */
-SRD_API int srd_inst_stack(struct srd_decoder_inst *di_from,
-		struct srd_decoder_inst *di_to)
+SRD_API int srd_inst_stack(struct srd_session *sess,
+		struct srd_decoder_inst *di_from, struct srd_decoder_inst *di_to)
 {
+
+	if (session_is_valid(sess) != SRD_OK) {
+		srd_err("Invalid session.");
+		return SRD_ERR_ARG;
+	}
+
 	if (!di_from || !di_to) {
 		srd_err("Invalid from/to instance pair.");
 		return SRD_ERR_ARG;
 	}
 
-	if (g_slist_find(di_list, di_to)) {
+	if (g_slist_find(sess->di_list, di_to)) {
 		/* Remove from the unstacked list. */
-		di_list = g_slist_remove(di_list, di_to);
+		sess->di_list = g_slist_remove(sess->di_list, di_to);
 	}
 
 	/* Stack on top of source di. */
@@ -635,19 +671,26 @@ SRD_API int srd_inst_stack(struct srd_decoder_inst *di_from,
  * Only the bottom level of instances are searched -- instances already stacked
  * on top of another one will not be found.
  *
+ * @param sess The session holding the protocol decoder instance.
  * @param inst_id The instance ID to be found.
  *
  * @return Pointer to struct srd_decoder_inst, or NULL if not found.
  *
- * @since 0.1.0
+ * @since 0.3.0
  */
-SRD_API struct srd_decoder_inst *srd_inst_find_by_id(const char *inst_id)
+SRD_API struct srd_decoder_inst *srd_inst_find_by_id(struct srd_session *sess,
+		const char *inst_id)
 {
 	GSList *l;
 	struct srd_decoder_inst *tmp, *di;
 
+	if (session_is_valid(sess) != SRD_OK) {
+		srd_err("Invalid session.");
+		return NULL;
+	}
+
 	di = NULL;
-	for (l = di_list; l; l = l->next) {
+	for (l = sess->di_list; l; l = l->next) {
 		tmp = l->data;
 		if (!strcmp(tmp->inst_id, inst_id)) {
 			di = tmp;
@@ -658,11 +701,36 @@ SRD_API struct srd_decoder_inst *srd_inst_find_by_id(const char *inst_id)
 	return di;
 }
 
+static struct srd_decoder_inst *srd_sess_inst_find_by_obj(
+		struct srd_session *sess, const GSList *stack,
+		const PyObject *obj)
+{
+	const GSList *l;
+	struct srd_decoder_inst *tmp, *di;
+
+	if (session_is_valid(sess) != SRD_OK) {
+		srd_err("Invalid session.");
+		return NULL;
+	}
+
+	di = NULL;
+	for (l = stack ? stack : sess->di_list; di == NULL && l != NULL; l = l->next) {
+		tmp = l->data;
+		if (tmp->py_inst == obj)
+			di = tmp;
+		else if (tmp->next_di)
+			di = srd_sess_inst_find_by_obj(sess, tmp->next_di, obj);
+	}
+
+	return di;
+}
+
 /**
  * Find a decoder instance by its Python object.
  *
  * I.e. find that instance's instantiation of the sigrokdecode.Decoder class.
- * This will recurse to find the instance anywhere in the stack tree.
+ * This will recurse to find the instance anywhere in the stack tree of all
+ * sessions.
  *
  * @param stack Pointer to a GSList of struct srd_decoder_inst, indicating the
  *              stack to search. To start searching at the bottom level of
@@ -678,56 +746,42 @@ SRD_API struct srd_decoder_inst *srd_inst_find_by_id(const char *inst_id)
 SRD_PRIV struct srd_decoder_inst *srd_inst_find_by_obj(const GSList *stack,
 		const PyObject *obj)
 {
-	const GSList *l;
-	struct srd_decoder_inst *tmp, *di;
+	struct srd_decoder_inst *di;
+	struct srd_session *sess;
+	GSList *l;
 
 	di = NULL;
-	for (l = stack ? stack : di_list; di == NULL && l != NULL; l = l->next) {
-		tmp = l->data;
-		if (tmp->py_inst == obj)
-			di = tmp;
-		else if (tmp->next_di)
-			di = srd_inst_find_by_obj(tmp->next_di, obj);
+	for (l = sessions; di == NULL && l != NULL; l = l->next) {
+		sess = l->data;
+		di = srd_sess_inst_find_by_obj(sess, stack, obj);
 	}
 
 	return di;
 }
 
 /** @private */
-SRD_PRIV int srd_inst_start(struct srd_decoder_inst *di, PyObject *args)
+SRD_PRIV int srd_inst_start(struct srd_decoder_inst *di)
 {
-	PyObject *py_name, *py_res;
+	PyObject *py_res;
 	GSList *l;
 	struct srd_decoder_inst *next_di;
+	int ret;
 
 	srd_dbg("Calling start() method on protocol decoder instance %s.",
-		di->inst_id);
+			di->inst_id);
 
-	if (!(py_name = PyUnicode_FromString("start"))) {
-		srd_err("Unable to build Python object for 'start'.");
+	if (!(py_res = PyObject_CallMethod(di->py_inst, "start", NULL))) {
 		srd_exception_catch("Protocol decoder instance %s: ",
-				    di->inst_id);
+				di->inst_id);
 		return SRD_ERR_PYTHON;
 	}
-
-	if (!(py_res = PyObject_CallMethodObjArgs(di->py_inst,
-						  py_name, args, NULL))) {
-		srd_exception_catch("Protocol decoder instance %s: ",
-				    di->inst_id);
-		return SRD_ERR_PYTHON;
-	}
-
 	Py_DecRef(py_res);
-	Py_DecRef(py_name);
 
-	/*
-	 * Start all the PDs stacked on top of this one. Pass along the
-	 * metadata all the way from the bottom PD, even though it's only
-	 * applicable to logic data for now.
-	 */
+	/* Start all the PDs stacked on top of this one. */
 	for (l = di->next_di; l; l = l->next) {
 		next_di = l->data;
-		srd_inst_start(next_di, args);
+		if ((ret = srd_inst_start(next_di)) != SRD_OK)
+			return ret;
 	}
 
 	return SRD_OK;
@@ -736,9 +790,11 @@ SRD_PRIV int srd_inst_start(struct srd_decoder_inst *di, PyObject *args)
 /**
  * Run the specified decoder function.
  *
+ * @param di The decoder instance to call. Must not be NULL.
  * @param start_samplenum The starting sample number for the buffer's sample
  * 			  set, relative to the start of capture.
- * @param di The decoder instance to call. Must not be NULL.
+ * @param end_samplenum The ending sample number for the buffer's sample
+ * 			  set, relative to the start of capture.
  * @param inbuf The buffer to decode. Must not be NULL.
  * @param inbuflen Length of the buffer. Must be > 0.
  *
@@ -748,16 +804,16 @@ SRD_PRIV int srd_inst_start(struct srd_decoder_inst *di, PyObject *args)
  *
  * @since 0.1.0
  */
-SRD_PRIV int srd_inst_decode(uint64_t start_samplenum,
-		const struct srd_decoder_inst *di, const uint8_t *inbuf,
-		uint64_t inbuflen)
+SRD_PRIV int srd_inst_decode(const struct srd_decoder_inst *di,
+		uint64_t start_samplenum, uint64_t end_samplenum,
+		const uint8_t *inbuf, uint64_t inbuflen)
 {
 	PyObject *py_res;
 	srd_logic *logic;
-	uint64_t end_samplenum;
 
-	srd_dbg("Calling decode() on instance %s with %d bytes starting "
-		"at sample %d.", di->inst_id, inbuflen, start_samplenum);
+	srd_dbg("Calling decode() on instance %s with %" PRIu64 " bytes "
+		"starting at sample %" PRIu64 ".", di->inst_id, inbuflen,
+		start_samplenum);
 
 	/* Return an error upon unusable input. */
 	if (!di) {
@@ -788,12 +844,9 @@ SRD_PRIV int srd_inst_decode(uint64_t start_samplenum,
 	Py_INCREF(logic->sample);
 
 	Py_IncRef(di->py_inst);
-	end_samplenum = start_samplenum + inbuflen / di->data_unitsize;
 	if (!(py_res = PyObject_CallMethod(di->py_inst, "decode",
-					   "KKO", logic->start_samplenum,
-					   end_samplenum, logic))) {
-		srd_exception_catch("Protocol decoder instance %s: ",
-				    di->inst_id);
+			"KKO", start_samplenum, end_samplenum, logic))) {
+		srd_exception_catch("Protocol decoder instance %s: ", di->inst_id);
 		return SRD_ERR_PYTHON;
 	}
 	Py_DecRef(py_res);
@@ -823,21 +876,26 @@ SRD_PRIV void srd_inst_free(struct srd_decoder_inst *di)
 }
 
 /** @private */
-SRD_PRIV void srd_inst_free_all(GSList *stack)
+SRD_PRIV void srd_inst_free_all(struct srd_session *sess, GSList *stack)
 {
 	GSList *l;
 	struct srd_decoder_inst *di;
 
+	if (session_is_valid(sess) != SRD_OK) {
+		srd_err("Invalid session.");
+		return;
+	}
+
 	di = NULL;
-	for (l = stack ? stack : di_list; di == NULL && l != NULL; l = l->next) {
+	for (l = stack ? stack : sess->di_list; di == NULL && l != NULL; l = l->next) {
 		di = l->data;
 		if (di->next_di)
-			srd_inst_free_all(di->next_di);
+			srd_inst_free_all(sess, di->next_di);
 		srd_inst_free(di);
 	}
 	if (!stack) {
-		g_slist_free(di_list);
-		di_list = NULL;
+		g_slist_free(sess->di_list);
+		sess->di_list = NULL;
 	}
 }
 
@@ -851,51 +909,145 @@ SRD_PRIV void srd_inst_free_all(GSList *stack)
  * @{
  */
 
+static int session_is_valid(struct srd_session *sess)
+{
+
+	if (!sess || sess->session_id < 1)
+		return SRD_ERR;
+
+	return SRD_OK;
+}
+
+/**
+ * Create a decoding session.
+ *
+ * A session holds all decoder instances, their stack relationships and
+ * output callbacks.
+ *
+ * @param sess A pointer which will hold a pointer to a newly
+ *             initialized session on return.
+ *
+ * @return SRD_OK upon success, a (negative) error code otherwise.
+ *
+ * @since 0.3.0
+ */
+SRD_API int srd_session_new(struct srd_session **sess)
+{
+
+	if (!sess) {
+		srd_err("Invalid session pointer.");
+		return SRD_ERR_ARG;
+	}
+
+	if (!(*sess = g_try_malloc(sizeof(struct srd_session))))
+		return SRD_ERR_MALLOC;
+	(*sess)->session_id = ++max_session_id;
+	(*sess)->di_list = (*sess)->callbacks = NULL;
+
+	/* Keep a list of all sessions, so we can clean up as needed. */
+	sessions = g_slist_append(sessions, *sess);
+
+	srd_dbg("Created session %d.", (*sess)->session_id);
+
+	return SRD_OK;
+}
+
 /**
  * Start a decoding session.
  *
- * Decoders, instances and stack must have been prepared beforehand.
+ * Decoders, instances and stack must have been prepared beforehand,
+ * and all SRD_CONF parameters set.
  *
- * @param num_probes The number of probes which the incoming feed will contain.
- * @param unitsize The number of bytes per sample in the incoming feed.
- * @param samplerate The samplerate of the incoming feed.
+ * @param sess The session to start.
  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
  *
- * @since 0.1.0
+ * @since 0.3.0
  */
-SRD_API int srd_session_start(int num_probes, int unitsize, uint64_t samplerate)
+SRD_API int srd_session_start(struct srd_session *sess)
 {
-	PyObject *args;
 	GSList *d;
 	struct srd_decoder_inst *di;
 	int ret;
 
+	if (session_is_valid(sess) != SRD_OK) {
+		srd_err("Invalid session pointer.");
+		return SRD_ERR;
+	}
+
+	srd_dbg("Calling start() on all instances in session %d.", sess->session_id);
+
+	/* Run the start() method on all decoders receiving frontend data. */
 	ret = SRD_OK;
+	for (d = sess->di_list; d; d = d->next) {
+		di = d->data;
+		if ((ret = srd_inst_start(di)) != SRD_OK)
+			break;
+	}
 
-	srd_dbg("Calling start() on all instances with %d probes, "
-		"unitsize %d samplerate %d.", num_probes, unitsize, samplerate);
+	return ret;
+}
 
-	/*
-	 * Currently only one item of metadata is passed along to decoders,
-	 * samplerate. This can be extended as needed.
-	 */
-	if (!(args = Py_BuildValue("{s:l}", "samplerate", (long)samplerate))) {
-		srd_err("Unable to build Python object for metadata.");
-		return SRD_ERR_PYTHON;
+SRD_PRIV int srd_inst_send_meta(struct srd_decoder_inst *di, int key,
+		GVariant *data)
+{
+	PyObject *py_ret;
+
+	if (key != SRD_CONF_SAMPLERATE)
+		/* This is the only key we pass on to the decoder for now. */
+		return SRD_OK;
+
+	if (!PyObject_HasAttrString(di->py_inst, "metadata"))
+		/* This decoder doesn't want metadata, that's fine. */
+		return SRD_OK;
+
+	py_ret = PyObject_CallMethod(di->py_inst, "metadata", "lK",
+			(long)SRD_CONF_SAMPLERATE,
+			(unsigned long long)g_variant_get_uint64(data));
+	Py_XDECREF(py_ret);
+
+	return SRD_OK;
+}
+
+/**
+ * Set a metadata configuration key in a session.
+ *
+ * @param sess The session to configure.
+ * @param key The configuration key (SRD_CONF_*).
+ * @param 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.
+ *
+ * @return SRD_OK upon success, a (negative) error code otherwise.
+ *
+ * @since 0.3.0
+ */
+SRD_API int srd_session_metadata_set(struct srd_session *sess, int key,
+		GVariant *data)
+{
+	GSList *l;
+	int ret;
+
+	if (session_is_valid(sess) != SRD_OK) {
+		srd_err("Invalid session.");
+		return SRD_ERR_ARG;
 	}
 
-	/* Run the start() method on all decoders receiving frontend data. */
-	for (d = di_list; d; d = d->next) {
-		di = d->data;
-		di->data_num_probes = num_probes;
-		di->data_unitsize = unitsize;
-		di->data_samplerate = samplerate;
-		if ((ret = srd_inst_start(di, args)) != SRD_OK)
+	if (key != SRD_CONF_SAMPLERATE) {
+		srd_err("Unknown config key %d.", key);
+		return SRD_ERR_ARG;
+	}
+
+	srd_dbg("Setting session %d samplerate to %"PRIu64".",
+			sess->session_id, g_variant_get_uint64(data));
+
+	ret = SRD_OK;
+	for (l = sess->di_list; l; l = l->next) {
+		if ((ret = srd_inst_send_meta(l->data, key, data)) != SRD_OK)
 			break;
 	}
 
-	Py_DecRef(args);
+	g_variant_unref(data);
 
 	return ret;
 }
@@ -903,33 +1055,81 @@ SRD_API int srd_session_start(int num_probes, int unitsize, uint64_t samplerate)
 /**
  * Send a chunk of logic sample data to a running decoder session.
  *
+ * The logic samples must be arranged in probe order, in the least
+ * amount of space possible. If no probes were configured, the default
+ * probe set consists of all required probes + all optional probes.
+ *
+ * The size of a sample in inbuf is the minimum number of bytes needed
+ * to store the configured (or default) probes.
+ *
+ * @param sess The session to use.
  * @param start_samplenum The sample number of the first sample in this chunk.
+ * @param end_samplenum The sample number of the last sample in this chunk.
  * @param inbuf Pointer to sample data.
  * @param inbuflen Length in bytes of the buffer.
  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
  *
- * @since 0.1.0
+ * @since 0.3.0
  */
-SRD_API int srd_session_send(uint64_t start_samplenum, const uint8_t *inbuf,
-		uint64_t inbuflen)
+SRD_API int srd_session_send(struct srd_session *sess,
+		uint64_t start_samplenum, uint64_t end_samplenum,
+		const uint8_t *inbuf, uint64_t inbuflen)
 {
 	GSList *d;
 	int ret;
 
+	if (session_is_valid(sess) != SRD_OK) {
+		srd_err("Invalid session.");
+		return SRD_ERR_ARG;
+	}
+
 	srd_dbg("Calling decode() on all instances with starting sample "
-		"number %" PRIu64 ", %" PRIu64 " bytes at 0x%p",
-		start_samplenum, inbuflen, inbuf);
+			"number %" PRIu64 ", %" PRIu64 " bytes at 0x%p",
+			start_samplenum, inbuflen, inbuf);
 
-	for (d = di_list; d; d = d->next) {
-		if ((ret = srd_inst_decode(start_samplenum, d->data, inbuf,
-					   inbuflen)) != SRD_OK)
+	for (d = sess->di_list; d; d = d->next) {
+		if ((ret = srd_inst_decode(d->data, start_samplenum,
+				end_samplenum, inbuf, inbuflen)) != SRD_OK)
 			return ret;
 	}
 
 	return SRD_OK;
 }
 
+/**
+ * Destroy a decoding session.
+ *
+ * All decoder instances and output callbacks are properly released.
+ *
+ * @param sess The session to be destroyed.
+ *
+ * @return SRD_OK upon success, a (negative) error code otherwise.
+ *
+ * @since 0.3.0
+ */
+SRD_API int srd_session_destroy(struct srd_session *sess)
+{
+	int session_id;
+
+	if (!sess) {
+		srd_err("Invalid session.");
+		return SRD_ERR_ARG;
+	}
+
+	session_id = sess->session_id;
+	if (sess->di_list)
+		srd_inst_free_all(sess, NULL);
+	if (sess->callbacks)
+		g_slist_free_full(sess->callbacks, g_free);
+	sessions = g_slist_remove(sessions, sess);
+	g_free(sess);
+
+	srd_dbg("Destroyed session %d.", session_id);
+
+	return SRD_OK;
+}
+
 /**
  * Register/add a decoder output callback function.
  *
@@ -937,18 +1137,24 @@ SRD_API int srd_session_send(uint64_t start_samplenum, const uint8_t *inbuf,
  * to the PD controller (except for Python objects, which only go up the
  * stack).
  *
+ * @param sess The output session in which to register the callback.
  * @param output_type The output type this callback will receive. Only one
  *                    callback per output type can be registered.
  * @param cb The function to call. Must not be NULL.
  * @param cb_data Private data for the callback function. Can be NULL.
  *
- * @since 0.1.0
+ * @since 0.3.0
  */
-SRD_API int srd_pd_output_callback_add(int output_type,
-		srd_pd_output_callback_t cb, void *cb_data)
+SRD_API int srd_pd_output_callback_add(struct srd_session *sess,
+		int output_type, srd_pd_output_callback_t cb, void *cb_data)
 {
 	struct srd_pd_callback *pd_cb;
 
+	if (session_is_valid(sess) != SRD_OK) {
+		srd_err("Invalid session.");
+		return SRD_ERR_ARG;
+	}
+
 	srd_dbg("Registering new callback for output type %d.", output_type);
 
 	if (!(pd_cb = g_try_malloc(sizeof(struct srd_pd_callback)))) {
@@ -959,53 +1165,33 @@ SRD_API int srd_pd_output_callback_add(int output_type,
 	pd_cb->output_type = output_type;
 	pd_cb->cb = cb;
 	pd_cb->cb_data = cb_data;
-	callbacks = g_slist_append(callbacks, pd_cb);
+	sess->callbacks = g_slist_append(sess->callbacks, pd_cb);
 
 	return SRD_OK;
 }
 
 /** @private */
-SRD_PRIV void *srd_pd_output_callback_find(int output_type)
+SRD_PRIV struct srd_pd_callback *srd_pd_output_callback_find(
+		struct srd_session *sess, int output_type)
 {
 	GSList *l;
-	struct srd_pd_callback *pd_cb;
-	void *(cb);
+	struct srd_pd_callback *tmp, *pd_cb;
 
-	cb = NULL;
-	for (l = callbacks; l; l = l->next) {
-		pd_cb = l->data;
-		if (pd_cb->output_type == output_type) {
-			cb = pd_cb->cb;
-			break;
-		}
+	if (session_is_valid(sess) != SRD_OK) {
+		srd_err("Invalid session.");
+		return NULL;
 	}
 
-	return cb;
-}
-
-/* This is the backend function to Python sigrokdecode.add() call. */
-/** @private */
-SRD_PRIV int srd_inst_pd_output_add(struct srd_decoder_inst *di,
-				    int output_type, const char *proto_id)
-{
-	struct srd_pd_output *pdo;
-
-	srd_dbg("Instance %s creating new output type %d for %s.",
-		di->inst_id, output_type, proto_id);
-
-	if (!(pdo = g_try_malloc(sizeof(struct srd_pd_output)))) {
-		srd_err("Failed to g_malloc() struct srd_pd_output.");
-		return -1;
+	pd_cb = NULL;
+	for (l = sess->callbacks; l; l = l->next) {
+		tmp = l->data;
+		if (tmp->output_type == output_type) {
+			pd_cb = tmp;
+			break;
+		}
 	}
 
-	/* pdo_id is just a simple index, nothing is deleted from this list anyway. */
-	pdo->pdo_id = g_slist_length(di->pd_output);
-	pdo->output_type = output_type;
-	pdo->di = di;
-	pdo->proto_id = g_strdup(proto_id);
-	di->pd_output = g_slist_append(di->pd_output, pdo);
-
-	return pdo->pdo_id;
+	return pd_cb;
 }
 
 /** @} */