X-Git-Url: https://sigrok.org/gitweb/?p=libsigrokdecode.git;a=blobdiff_plain;f=session.c;h=4d794df4b97a5a1d44cf99e79f80b253cbfd3d2c;hp=8df71576600072802be025119984190e3c45798f;hb=9553e9622bb26dfbe6296ef6f330b1cf0f5b40e6;hpb=9eec72cb2bf132600db3330f49dace3bdf74080a

diff --git a/session.c b/session.c
index 8df7157..4d794df 100644
--- a/session.c
+++ b/session.c
@@ -18,9 +18,9 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#include "libsigrokdecode.h" /* First, so we avoid a _POSIX_C_SOURCE warning. */
-#include "libsigrokdecode-internal.h"
-#include "config.h"
+#include <config.h>
+#include "libsigrokdecode-internal.h" /* First, so we avoid a _POSIX_C_SOURCE warning. */
+#include "libsigrokdecode.h"
 #include <inttypes.h>
 #include <glib.h>
 
@@ -41,7 +41,7 @@
 /** @cond PRIVATE */
 
 SRD_PRIV GSList *sessions = NULL;
-int max_session_id = -1;
+SRD_PRIV int max_session_id = -1;
 
 /** @endcond */
 
@@ -76,8 +76,7 @@ SRD_API int srd_session_new(struct srd_session **sess)
 		return SRD_ERR_ARG;
 	}
 
-	if (!(*sess = g_try_malloc(sizeof(struct srd_session))))
-		return SRD_ERR_MALLOC;
+	*sess = g_malloc(sizeof(struct srd_session));
 	(*sess)->session_id = ++max_session_id;
 	(*sess)->di_list = (*sess)->callbacks = NULL;
 
@@ -129,19 +128,32 @@ static int srd_inst_send_meta(struct srd_decoder_inst *di, int key,
 		GVariant *data)
 {
 	PyObject *py_ret;
+	GSList *l;
+	struct srd_decoder_inst *next_di;
+	int ret;
+	PyGILState_STATE gstate;
 
 	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;
+	gstate = PyGILState_Ensure();
 
-	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);
+	if (PyObject_HasAttrString(di->py_inst, "metadata")) {
+		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);
+	}
+
+	PyGILState_Release(gstate);
+
+	/* Push metadata to all the PDs stacked on top of this one. */
+	for (l = di->next_di; l; l = l->next) {
+		next_di = l->data;
+		if ((ret = srd_inst_send_meta(next_di, key, data)) != SRD_OK)
+			return ret;
+	}
 
 	return SRD_OK;
 }
@@ -192,7 +204,7 @@ SRD_API int srd_session_metadata_set(struct srd_session *sess, int key,
 		return SRD_ERR_ARG;
 	}
 
-	srd_dbg("Setting session %d samplerate to %"PRIu64".",
+	srd_dbg("Setting session %d samplerate to %"G_GUINT64_FORMAT".",
 			sess->session_id, g_variant_get_uint64(data));
 
 	ret = SRD_OK;
@@ -209,27 +221,64 @@ SRD_API int srd_session_metadata_set(struct srd_session *sess, int key,
 /**
  * Send a chunk of logic sample data to a running decoder session.
  *
- * If no probe map has been set up, the logic samples must be arranged
- * in probe order, in the least amount of space possible. The default
- * probe set consists of all required probes + all optional probes.
+ * 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'.
  *
- * The size of a sample in inbuf is the unit size passed to
- * srd_inst_probe_set_all(). If no probe map has been configured, it is
- * the minimum number of bytes needed to store the default probes.
+ * 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);
  *
- * @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.
+ * 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);
+ *
+ * @param sess The session to use. Must not be NULL.
+ * @param abs_start_samplenum The absolute starting sample number for the
+ *              buffer's sample set, relative to the start of capture.
+ * @param abs_end_samplenum The absolute ending sample number for the
+ *              buffer's sample set, relative to the start of capture.
+ * @param inbuf Pointer to sample data. Must not be NULL.
+ * @param inbuflen Length in bytes of the buffer. Must be > 0.
+ * @param unitsize The number of bytes per sample. Must be > 0.
  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
  *
- * @since 0.3.0
+ * @since 0.4.0
  */
 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)
+		uint64_t abs_start_samplenum, uint64_t abs_end_samplenum,
+		const uint8_t *inbuf, uint64_t inbuflen, uint64_t unitsize)
 {
 	GSList *d;
 	int ret;
@@ -239,19 +288,54 @@ SRD_API int srd_session_send(struct srd_session *sess,
 		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);
-
 	for (d = sess->di_list; d; d = d->next) {
-		if ((ret = srd_inst_decode(d->data, start_samplenum,
-				end_samplenum, inbuf, inbuflen)) != SRD_OK)
+		if ((ret = srd_inst_decode(d->data, abs_start_samplenum,
+				abs_end_samplenum, inbuf, inbuflen, unitsize)) != SRD_OK)
 			return ret;
 	}
 
 	return SRD_OK;
 }
 
+/**
+ * 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.
+ *
+ * @param sess The session in which to terminate decoders.
+ * @return SRD_OK upon success, a (negative) error code otherwise.
+ *
+ * @since 0.6.0
+ */
+SRD_API int srd_session_terminate_reset(struct srd_session *sess)
+{
+	GSList *d;
+	int ret;
+
+	if (session_is_valid(sess) != SRD_OK) {
+		srd_err("Invalid session.");
+		return SRD_ERR_ARG;
+	}
+
+	for (d = sess->di_list; d; d = d->next) {
+		ret = srd_inst_terminate_reset(d->data);
+		if (ret != SRD_OK)
+			return ret;
+	}
+	return SRD_OK;
+}
+
 /**
  * Destroy a decoding session.
  *
@@ -274,7 +358,7 @@ SRD_API int srd_session_destroy(struct srd_session *sess)
 
 	session_id = sess->session_id;
 	if (sess->di_list)
-		srd_inst_free_all(sess, NULL);
+		srd_inst_free_all(sess);
 	if (sess->callbacks)
 		g_slist_free_full(sess->callbacks, g_free);
 	sessions = g_slist_remove(sessions, sess);
@@ -301,7 +385,7 @@ SRD_API int srd_session_destroy(struct srd_session *sess)
  * @since 0.3.0
  */
 SRD_API int srd_pd_output_callback_add(struct srd_session *sess,
-		int output_type, srd_pd_output_callback_t cb, void *cb_data)
+		int output_type, srd_pd_output_callback cb, void *cb_data)
 {
 	struct srd_pd_callback *pd_cb;
 
@@ -312,11 +396,7 @@ SRD_API int srd_pd_output_callback_add(struct srd_session *sess,
 
 	srd_dbg("Registering new callback for output type %d.", output_type);
 
-	if (!(pd_cb = g_try_malloc(sizeof(struct srd_pd_callback)))) {
-		srd_err("Failed to g_malloc() struct srd_pd_callback.");
-		return SRD_ERR_MALLOC;
-	}
-
+	pd_cb = g_malloc(sizeof(struct srd_pd_callback));
 	pd_cb->output_type = output_type;
 	pd_cb->cb = cb;
 	pd_cb->cb_data = cb_data;