atsha204a: Add missing full stop in description.

[libsigrokdecode.git] / session.c

diff --git a/session.c b/session.c
index e1bb4f9880d36a8f64f8603827a7df8585d088bc..36b5005cc30d2aa4b8c4d322704fdf7079807180 100644 (file)
--- a/session.c
+++ b/session.c
@@ -45,16 +45,6 @@ SRD_PRIV int max_session_id = -1;
 
 /** @endcond */
 
 
 /** @endcond */
 

-/** @private */
-SRD_PRIV int session_is_valid(struct srd_session *sess)
-{
-
-       if (!sess || sess->session_id < 1)
-               return SRD_ERR;
-
-       return SRD_OK;
-}
-

 /**
  * Create a decoding session.
  *
 /**
  * Create a decoding session.
  *


@@ -62,7 +52,7 @@ SRD_PRIV int session_is_valid(struct srd_session *sess)
  * output callbacks.
  *
  * @param sess A pointer which will hold a pointer to a newly
  * output callbacks.
  *
  * @param sess A pointer which will hold a pointer to a newly

- *             initialized session on return.
+ *             initialized session on return. Must not be NULL.

  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
  *
  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
  *


@@ -70,11 +60,8 @@ SRD_PRIV int session_is_valid(struct srd_session *sess)
  */
 SRD_API int srd_session_new(struct srd_session **sess)
 {
  */
 SRD_API int srd_session_new(struct srd_session **sess)
 {

-
-       if (!sess) {
-               srd_err("Invalid session pointer.");
+       if (!sess)

                return SRD_ERR_ARG;
                return SRD_ERR_ARG;

-       }

 
        *sess = g_malloc(sizeof(struct srd_session));
        (*sess)->session_id = ++max_session_id;
 
        *sess = g_malloc(sizeof(struct srd_session));
        (*sess)->session_id = ++max_session_id;


@@ -94,7 +81,7 @@ SRD_API int srd_session_new(struct srd_session **sess)
  * Decoders, instances and stack must have been prepared beforehand,
  * and all SRD_CONF parameters set.
  *
  * Decoders, instances and stack must have been prepared beforehand,
  * and all SRD_CONF parameters set.
  *

- * @param sess The session to start.
+ * @param sess The session to start. Must not be NULL.

  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
  *
  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
  *


@@ -106,10 +93,8 @@ SRD_API int srd_session_start(struct srd_session *sess)
        struct srd_decoder_inst *di;
        int ret;
 
        struct srd_decoder_inst *di;
        int ret;
 

-       if (session_is_valid(sess) != SRD_OK) {
-               srd_err("Invalid session pointer.");
-               return SRD_ERR;
-       }
+       if (!sess)
+               return SRD_ERR_ARG;

 
        srd_dbg("Calling start() on all instances in session %d.", sess->session_id);
 
 
        srd_dbg("Calling start() on all instances in session %d.", sess->session_id);
 


@@ -131,11 +116,14 @@ static int srd_inst_send_meta(struct srd_decoder_inst *di, int key,
        GSList *l;
        struct srd_decoder_inst *next_di;
        int 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 (key != SRD_CONF_SAMPLERATE)
                /* This is the only key we pass on to the decoder for now. */
                return SRD_OK;
 

+       gstate = PyGILState_Ensure();
+

        if (PyObject_HasAttrString(di->py_inst, "metadata")) {
                py_ret = PyObject_CallMethod(di->py_inst, "metadata", "lK",
                                (long)SRD_CONF_SAMPLERATE,
        if (PyObject_HasAttrString(di->py_inst, "metadata")) {
                py_ret = PyObject_CallMethod(di->py_inst, "metadata", "lK",
                                (long)SRD_CONF_SAMPLERATE,


@@ -143,6 +131,8 @@ static int srd_inst_send_meta(struct srd_decoder_inst *di, int key,
                Py_XDECREF(py_ret);
        }
 
                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;
        /* 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;


@@ -156,7 +146,7 @@ static int srd_inst_send_meta(struct srd_decoder_inst *di, int key,
 /**
  * Set a metadata configuration key in a session.
  *
 /**
  * Set a metadata configuration key in a session.
  *

- * @param sess The session to configure.
+ * @param sess The session to configure. Must not be NULL.

  * @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
  * @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


@@ -172,10 +162,8 @@ SRD_API int srd_session_metadata_set(struct srd_session *sess, int key,
        GSList *l;
        int ret;
 
        GSList *l;
        int ret;
 

-       if (session_is_valid(sess) != SRD_OK) {
-               srd_err("Invalid session.");
+       if (!sess)

                return SRD_ERR_ARG;
                return SRD_ERR_ARG;

-       }

 
        if (!key) {
                srd_err("Invalid key.");
 
        if (!key) {
                srd_err("Invalid key.");


@@ -199,7 +187,7 @@ SRD_API int srd_session_metadata_set(struct srd_session *sess, int key,
                return SRD_ERR_ARG;
        }
 
                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;
                        sess->session_id, g_variant_get_uint64(data));
 
        ret = SRD_OK;


@@ -224,9 +212,45 @@ SRD_API int srd_session_metadata_set(struct srd_session *sess, int key,
  * has been configured, it is the minimum number of bytes needed to store
  * the default channels.
  *
  * 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);
+ *

  * @param sess The session to use. Must not be NULL.
  * @param sess The session to use. Must not be NULL.

- * @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 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.
  * @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.


@@ -236,20 +260,57 @@ SRD_API int srd_session_metadata_set(struct srd_session *sess, int key,
  * @since 0.4.0
  */
 SRD_API int srd_session_send(struct srd_session *sess,
  * @since 0.4.0
  */
 SRD_API int srd_session_send(struct srd_session *sess,

-               uint64_t start_samplenum, uint64_t end_samplenum,
+               uint64_t abs_start_samplenum, uint64_t abs_end_samplenum,

                const uint8_t *inbuf, uint64_t inbuflen, uint64_t unitsize)
 {
        GSList *d;
        int ret;
 
                const uint8_t *inbuf, uint64_t inbuflen, uint64_t unitsize)
 {
        GSList *d;
        int ret;
 

-       if (session_is_valid(sess) != SRD_OK) {
-               srd_err("Invalid session.");
+       if (!sess)

                return SRD_ERR_ARG;
                return SRD_ERR_ARG;

+
+       for (d = sess->di_list; d; d = d->next) {
+               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. Must not be NULL.
+ *
+ * @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 (!sess)
+               return SRD_ERR_ARG;
+

        for (d = sess->di_list; d; d = d->next) {
        for (d = sess->di_list; d; d = d->next) {

-               if ((ret = srd_inst_decode(d->data, start_samplenum,
-                               end_samplenum, inbuf, inbuflen, unitsize)) != SRD_OK)
+               ret = srd_inst_terminate_reset(d->data);
+               if (ret != SRD_OK)

                        return ret;
        }
 
                        return ret;
        }
 


@@ -261,7 +322,7 @@ SRD_API int srd_session_send(struct srd_session *sess,
  *
  * All decoder instances and output callbacks are properly released.
  *
  *
  * All decoder instances and output callbacks are properly released.
  *

- * @param sess The session to be destroyed.
+ * @param sess The session to be destroyed. Must not be NULL.

  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
  *
  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
  *


@@ -271,14 +332,12 @@ SRD_API int srd_session_destroy(struct srd_session *sess)
 {
        int session_id;
 
 {
        int session_id;
 

-       if (!sess) {
-               srd_err("Invalid session.");
+       if (!sess)

                return SRD_ERR_ARG;
                return SRD_ERR_ARG;

-       }

 
        session_id = sess->session_id;
        if (sess->di_list)
 
        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);
        if (sess->callbacks)
                g_slist_free_full(sess->callbacks, g_free);
        sessions = g_slist_remove(sessions, sess);


@@ -297,6 +356,7 @@ SRD_API int srd_session_destroy(struct srd_session *sess)
  * stack).
  *
  * @param sess The output session in which to register the callback.
  * stack).
  *
  * @param sess The output session in which to register the callback.

+ *             Must not be NULL.

  * @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 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.


@@ -309,10 +369,8 @@ SRD_API int srd_pd_output_callback_add(struct srd_session *sess,
 {
        struct srd_pd_callback *pd_cb;
 
 {
        struct srd_pd_callback *pd_cb;
 

-       if (session_is_valid(sess) != SRD_OK) {
-               srd_err("Invalid session.");
+       if (!sess)

                return SRD_ERR_ARG;
                return SRD_ERR_ARG;

-       }

 
        srd_dbg("Registering new callback for output type %d.", output_type);
 
 
        srd_dbg("Registering new callback for output type %d.", output_type);
 


@@ -332,10 +390,8 @@ SRD_PRIV struct srd_pd_callback *srd_pd_output_callback_find(
        GSList *l;
        struct srd_pd_callback *tmp, *pd_cb;
 
        GSList *l;
        struct srd_pd_callback *tmp, *pd_cb;
 

-       if (session_is_valid(sess) != SRD_OK) {
-               srd_err("Invalid session.");
+       if (!sess)

                return NULL;
                return NULL;

-       }

 
        pd_cb = NULL;
        for (l = sess->callbacks; l; l = l->next) {
 
        pd_cb = NULL;
        for (l = sess->callbacks; l; l = l->next) {