srd: Doxygen comments for srd_init() and srd_exit().

[libsigrokdecode.git] / decode.c

diff --git a/decode.c b/decode.c
index 398a9f73c5e9ba4f24f7e66f8879745cf71b6a52..6c63fa7c1f069ca44faa1ed4b80966cb752a0aba 100644 (file)
--- a/decode.c
+++ b/decode.c
@@ -77,7 +77,24 @@ static PyMethodDef EmbMethods[] = {
 /**
  * Initialize libsigrokdecode.
  *
+ * This initializes the Python interpreter, and creates and initializes
+ * a "sigrok" Python module with a single put() method.
+ *
+ * Then, it searches for sigrok protocol decoder files (*.py) in the
+ * "decoders" subdirectory of the the sigrok installation directory.
+ * All decoders that are found are loaded into memory and added to an
+ * internal list of decoders, which can be queried via srd_list_decoders().
+ *
+ * The caller is responsible for calling the clean-up function srd_exit(),
+ * which will properly shut down libsigrokdecode and free its allocated memory.
+ *
+ * Multiple calls to srd_init(), without calling srd_exit() inbetween,
+ * are not allowed.
+ *
  * @return SRD_OK upon success, a (negative) error code otherwise.
+ *         Upon Python errors, return SRD_ERR_PYTHON. If the sigrok decoders
+ *         directory cannot be accessed, return SRD_ERR_DECODERS_DIR.
+ *         If not enough memory could be allocated, return SRD_ERR_MALLOC.
  */
 int srd_init(void)
 {
@@ -284,6 +301,8 @@ static int srd_load_decoder(const char *name,
 struct srd_decoder_instance *srd_instance_new(const char *id)
 {
        struct srd_decoder *dec = srd_get_decoder_by_id(id);
+       if (!dec) 
+               return NULL;
        struct srd_decoder_instance *di = g_malloc(sizeof(*di));
        PyObject *py_args, *py_value;
 
@@ -317,6 +336,26 @@ struct srd_decoder_instance *srd_instance_new(const char *id)
        return di;
 }
 
+int srd_instance_set_probe(struct srd_decoder_instance *di,
+                               const char *probename, int num)
+{
+       PyObject *probedict, *probenum;
+       probedict = PyObject_GetAttrString(di->py_instance, "probes"); /* NEWREF */
+       if (!probedict) {
+               if (PyErr_Occurred())
+                       PyErr_Print(); /* Returns void. */
+               
+               return SRD_ERR_PYTHON; /* TODO: More specific error? */
+       }
+
+       probenum = PyInt_FromLong(num);
+       PyMapping_SetItemString(probedict, (char*)probename, probenum);
+
+       Py_XDECREF(probenum);
+       Py_XDECREF(probedict);
+       return SRD_OK;
+}
+
 /**
  * Run the specified decoder function.
  *
@@ -333,7 +372,7 @@ int srd_run_decoder(struct srd_decoder_instance *dec,
                             uint8_t **outbuf, uint64_t *outbuflen)
 {
        PyObject *py_instance, *py_value, *py_res;
-       int r, ret;
+       int ret;
        
        /* FIXME: Don't have a timebase available here. Make one up. */
        static int _timehack = 0;
@@ -428,6 +467,13 @@ static int srd_unload_all_decoders(void)
 /**
  * Shutdown libsigrokdecode.
  *
+ * This frees all the memory allocated for protocol decoders and shuts down
+ * the Python interpreter.
+ *
+ * This function should only be called if there was a (successful!) invocation
+ * of srd_init() before. Calling this function multiple times in a row, without
+ * any successful srd_init() calls inbetween, is not allowed.
+ *
  * @return SRD_OK upon success, a (negative) error code otherwise.
  */
 int srd_exit(void)