decode.c: Simplify sigrokdecode_run_decoder().
[libsigrokdecode.git] / decode.c
1 /*
2  * This file is part of the sigrok project.
3  *
4  * Copyright (C) 2010 Uwe Hermann <uwe@hermann-uwe.de>
5  *
6  * This program is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 2 of the License, or
9  * (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software
18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
19  */
20
21 #include <sigrokdecode.h> /* First, so we avoid a _POSIX_C_SOURCE warning. */
22 #include <stdio.h>
23 #include <string.h>
24 #include <dirent.h>
25 #include <config.h>
26
27 /* Re-define some string functions for Python >= 3.0. */
28 #if PY_VERSION_HEX >= 0x03000000
29 #define PyString_AsString PyBytes_AsString
30 #define PyString_FromString PyBytes_FromString
31 #define PyString_Check PyBytes_Check
32 #endif
33
34 /* The list of protocol decoders. */
35 GSList *list_pds = NULL;
36
37 /*
38  * Here's a quick overview of Python/C API reference counting.
39  *
40  * Check the Python/C API docs for what type of reference a function returns.
41  *
42  *  - If it returns a "new reference", you're responsible to Py_DECREF() it.
43  *
44  *  - If it returns a "borrowed reference", you MUST NOT Py_DECREF() it.
45  *
46  *  - If a function "steals" a reference, you no longer are responsible for
47  *    Py_DECREF()ing it (someone else will do it for you at some point).
48  */
49
50 /**
51  * Initialize libsigrokdecode.
52  *
53  * @return SIGROKDECODE_OK upon success, a (negative) error code otherwise.
54  */
55 int sigrokdecode_init(void)
56 {
57         DIR *dir;
58         struct dirent *dp;
59         char *tmp;
60
61         /* Py_Initialize() returns void and usually cannot fail. */
62         Py_Initialize();
63
64         /* Add search directory for the protocol decoders. */
65         /* FIXME: Check error code. */
66         /* FIXME: What happens if this function is called multiple times? */
67         PyRun_SimpleString("import sys;"
68                            "sys.path.append(r'" DECODERS_DIR "');");
69
70         if (!(dir = opendir(DECODERS_DIR)))
71                 return SIGROKDECODE_ERR_DECODERS_DIR;
72
73         while ((dp = readdir(dir)) != NULL) {
74                 if (!g_str_has_suffix(dp->d_name, ".py"))
75                         continue;
76                 /* For now use the filename (without .py) as decoder name. */
77                 if ((tmp = g_strndup(dp->d_name, strlen(dp->d_name) - 3)))
78                         list_pds = g_slist_append(list_pds, tmp);
79         }
80         closedir(dir);
81
82         return SIGROKDECODE_OK;
83 }
84
85 /**
86  * Returns the list of supported/loaded protocol decoders.
87  *
88  * This is a GSList containing the names of the decoders as strings.
89  *
90  * @return List of decoders, NULL if none are supported or loaded.
91  */
92 GSList *sigrokdecode_list_decoders(void)
93 {
94         return list_pds;
95 }
96
97 /**
98  * Helper function to handle Python strings.
99  *
100  * TODO: @param entries.
101  *
102  * @return SIGROKDECODE_OK upon success, a (negative) error code otherwise.
103  *         The 'outstr' argument points to a malloc()ed string upon success.
104  */
105 static int h_str(PyObject *py_res, PyObject *py_func, PyObject *py_mod,
106                  const char *key, char **outstr)
107 {
108         PyObject *py_str;
109         char *str;
110
111         py_str = PyMapping_GetItemString(py_res, (char *)key);
112         if (!py_str || !PyString_Check(py_str)) {
113                 if (PyErr_Occurred())
114                         PyErr_Print(); /* Returns void. */
115                 Py_DECREF(py_func);
116                 Py_DECREF(py_mod);
117                 return SIGROKDECODE_ERR_PYTHON; /* TODO: More specific error? */
118         }
119
120         /*
121          * PyString_AsString()'s returned string refers to an internal buffer
122          * (not a copy), i.e. the data must not be modified, and the memory
123          * must not be free()'d.
124          */
125         if (!(str = PyString_AsString(py_str))) {
126                 if (PyErr_Occurred())
127                         PyErr_Print(); /* Returns void. */
128                 Py_DECREF(py_str);
129                 Py_DECREF(py_func);
130                 Py_DECREF(py_mod);
131                 return SIGROKDECODE_ERR_PYTHON; /* TODO: More specific error? */
132         }
133
134         if (!(*outstr = strdup(str))) {
135                 if (PyErr_Occurred())
136                         PyErr_Print(); /* Returns void. */
137                 Py_DECREF(py_str);
138                 Py_DECREF(py_func);
139                 Py_DECREF(py_mod);
140                 return SIGROKDECODE_ERR_MALLOC;
141         }
142
143         Py_DECREF(py_str);
144
145         return SIGROKDECODE_OK;
146 }
147
148 /**
149  * TODO
150  *
151  * @param name TODO
152  *
153  * @return SIGROKDECODE_OK upon success, a (negative) error code otherwise.
154  */
155 int sigrokdecode_load_decoder(const char *name,
156                               struct sigrokdecode_decoder **dec)
157 {
158         struct sigrokdecode_decoder *d;
159         PyObject *py_name, *py_mod, *py_func, *py_res /* , *py_tuple */;
160         int r;
161
162         /* Get the name of the decoder module as Python string. */
163         if (!(py_name = PyString_FromString(name))) { /* NEWREF */
164                 PyErr_Print(); /* Returns void. */
165                 return SIGROKDECODE_ERR_PYTHON; /* TODO: More specific error? */
166         }
167
168         /* "Import" the Python module. */
169         if (!(py_mod = PyImport_Import(py_name))) { /* NEWREF */
170                 PyErr_Print(); /* Returns void. */
171                 Py_DECREF(py_name);
172                 return SIGROKDECODE_ERR_PYTHON; /* TODO: More specific error? */
173         }
174         Py_DECREF(py_name);
175
176         /* Get the 'register' function name as Python callable object. */
177         py_func = PyObject_GetAttrString(py_mod, "register"); /* NEWREF */
178         if (!py_func || !PyCallable_Check(py_func)) {
179                 if (PyErr_Occurred())
180                         PyErr_Print(); /* Returns void. */
181                 Py_DECREF(py_mod);
182                 return SIGROKDECODE_ERR_PYTHON; /* TODO: More specific error? */
183         }
184
185         /* Call the 'register' function without arguments, get the result. */
186         if (!(py_res = PyObject_CallFunction(py_func, NULL))) { /* NEWREF */
187                 PyErr_Print(); /* Returns void. */
188                 Py_DECREF(py_func);
189                 Py_DECREF(py_mod);
190                 return SIGROKDECODE_ERR_PYTHON; /* TODO: More specific error? */
191         }
192
193         if (!(d = malloc(sizeof(struct sigrokdecode_decoder))))
194                 return SIGROKDECODE_ERR_MALLOC;
195
196         if ((r = h_str(py_res, py_func, py_mod, "id", &(d->id))) < 0)
197                 return r;
198
199         if ((r = h_str(py_res, py_func, py_mod, "name", &(d->name))) < 0)
200                 return r;
201
202         if ((r = h_str(py_res, py_func, py_mod, "desc", &(d->desc))) < 0)
203                 return r;
204
205         d->py_mod = py_mod;
206
207         Py_DECREF(py_res);
208         Py_DECREF(py_func);
209
210         /* Get the 'decode' function name as Python callable object. */
211         py_func = PyObject_GetAttrString(py_mod, "decode"); /* NEWREF */
212         if (!py_func || !PyCallable_Check(py_func)) {
213                 if (PyErr_Occurred())
214                         PyErr_Print(); /* Returns void. */
215                 Py_DECREF(py_mod);
216                 return SIGROKDECODE_ERR_PYTHON; /* TODO: More specific error? */
217         }
218
219         d->py_func = py_func;
220
221         /* TODO: Handle inputformats, outputformats. */
222
223         *dec = d;
224
225         return SIGROKDECODE_OK;
226 }
227
228 /**
229  * Run the specified decoder function.
230  *
231  * @param dec TODO
232  * @param inbuf TODO
233  * @param inbuflen TODO
234  * @param outbuf TODO
235  * @param outbuflen TODO
236  *
237  * @return SIGROKDECODE_OK upon success, a (negative) error code otherwise.
238  */
239 int sigrokdecode_run_decoder(struct sigrokdecode_decoder *dec,
240                              uint8_t *inbuf, uint64_t inbuflen,
241                              uint8_t **outbuf, uint64_t *outbuflen)
242 {
243         PyObject *py_mod, *py_func, *py_args, *py_value, *py_res;
244         int r, ret;
245
246         /* TODO: Use #defines for the return codes. */
247
248         /* Return an error upon unusable input. */
249         if (dec == NULL)
250                 return SIGROKDECODE_ERR_ARGS; /* TODO: More specific error? */
251         if (inbuf == NULL)
252                 return SIGROKDECODE_ERR_ARGS; /* TODO: More specific error? */
253         if (inbuflen == 0) /* No point in working on empty buffers. */
254                 return SIGROKDECODE_ERR_ARGS; /* TODO: More specific error? */
255         if (outbuf == NULL)
256                 return SIGROKDECODE_ERR_ARGS; /* TODO: More specific error? */
257         if (outbuflen == NULL)
258                 return SIGROKDECODE_ERR_ARGS; /* TODO: More specific error? */
259
260         /* TODO: Error handling. */
261         py_mod = dec->py_mod;
262         Py_INCREF(py_mod);
263         py_func = dec->py_func;
264         Py_INCREF(py_func);
265
266         /* Create a Python tuple of size 1. */
267         if (!(py_args = PyTuple_New(1))) { /* NEWREF */
268                 ret = SIGROKDECODE_ERR_PYTHON; /* TODO: More specific error? */
269                 goto err_run_decref_func;
270         }
271
272         /* Get the input buffer as Python "string" (byte array). */
273         /* TODO: int vs. uint64_t for 'inbuflen'? */
274         if (!(py_value = Py_BuildValue("s#", inbuf, inbuflen))) { /* NEWREF */
275                 ret = SIGROKDECODE_ERR_PYTHON; /* TODO: More specific error? */
276                 goto err_run_decref_args;
277         }
278
279         /*
280          * IMPORTANT: PyTuple_SetItem() "steals" a reference to py_value!
281          * That means we are no longer responsible for Py_DECREF()'ing it.
282          * It will automatically be free'd when the 'py_args' tuple is free'd.
283          */
284         if (PyTuple_SetItem(py_args, 0, py_value) != 0) { /* STEAL */
285                 ret = SIGROKDECODE_ERR_PYTHON; /* TODO: More specific error? */
286                 Py_DECREF(py_value); /* TODO: Ref. stolen upon error? */
287                 goto err_run_decref_args;
288         }
289
290         if (!(py_res = PyObject_CallObject(py_func, py_args))) { /* NEWREF */
291                 ret = SIGROKDECODE_ERR_PYTHON; /* TODO: More specific error? */
292                 goto err_run_decref_args;
293         }
294
295         if ((r = PyObject_AsCharBuffer(py_res, (const char **)outbuf,
296                                       (Py_ssize_t *)outbuflen))) {
297                 ret = SIGROKDECODE_ERR_PYTHON; /* TODO: More specific error? */
298                 Py_DECREF(py_res);
299                 goto err_run_decref_args;
300         }
301
302         ret = SIGROKDECODE_OK;
303
304         Py_DECREF(py_res);
305
306 err_run_decref_args:
307         Py_DECREF(py_args);
308 err_run_decref_func:
309         Py_DECREF(py_func);
310 err_run_decref_mod:
311         Py_DECREF(py_mod);
312
313         if (PyErr_Occurred())
314                 PyErr_Print(); /* Returns void. */
315
316         return ret;
317 }
318
319 /**
320  * Shutdown libsigrokdecode.
321  *
322  * @return SIGROKDECODE_OK upon success, a (negative) error code otherwise.
323  */
324 int sigrokdecode_shutdown(void)
325 {
326         /* Py_Finalize() returns void, any finalization errors are ignored. */
327         Py_Finalize();
328
329         return SIGROKDECODE_OK;
330 }