X-Git-Url: https://sigrok.org/gitweb/?p=libsigrokdecode.git;a=blobdiff_plain;f=controller.c;h=44fd6c76e079359e5a9af4a810bc249a4130385c;hp=5d19e7a6a142ced06b04349449480fbc0b25739d;hb=54fdeeefffe31d32dddaf0f3d6a99dc7b3bc2448;hpb=53a07a6d287ecdd3a9831dd3778676edf6ee8a9e diff --git a/controller.c b/controller.c index 5d19e7a..44fd6c7 100644 --- a/controller.c +++ b/controller.c @@ -25,12 +25,75 @@ #include #include +/** + * @mainpage libsigrokdecode API + * + * @section sec_intro Introduction + * + * The sigrok project aims at creating a + * portable, cross-platform, Free/Libre/Open-Source signal analysis software + * suite that supports various device types (such as logic analyzers, + * oscilloscopes, multimeters, and more). + * + * libsigrokdecode is a + * shared library written in C which provides the basic API for (streaming) + * protocol decoding functionality. + * + * The protocol decoders + * are written in Python (>= 3.0). + * + * @section sec_api API reference + * + * See the "Modules" page for an introduction to various libsigrokdecode + * related topics and the detailed API documentation of the respective + * functions. + * + * You can also browse the API documentation by file, or review all + * data structures. + * + * @section sec_mailinglists Mailing lists + * + * There are two mailing lists for sigrok/libsigrokdecode: sigrok-devel and sigrok-commits. + * + * @section sec_irc IRC + * + * You can find the sigrok developers in the + * \#sigrok + * IRC channel on Freenode. + * + * @section sec_website Website + * + * sigrok.org/wiki/Libsigrokdecode + */ + +/** + * @file + * + * Initializing and shutting down libsigrokdecode. + */ + +/** + * @defgroup grp_init Initialization + * + * Initializing and shutting down libsigrokdecode. + * + * Before using any of the libsigrokdecode functionality, srd_init() must + * be called to initialize the library. + * + * When libsigrokdecode functionality is no longer needed, srd_exit() should + * be called. + * + * @{ + */ + /* List of decoder instances. */ static GSList *di_list = NULL; /* List of frontend callbacks to receive decoder output. */ static GSList *callbacks = NULL; +/** @cond PRIVATE */ + /* decoder.c */ extern SRD_PRIV GSList *pd_list; @@ -41,6 +104,8 @@ extern PyMODINIT_FUNC PyInit_sigrokdecode(void); /* type_logic.c */ extern SRD_PRIV PyTypeObject srd_logic_type; +/** @endcond */ + /** * Initialize libsigrokdecode. * @@ -144,6 +209,8 @@ SRD_API int srd_exit(void) * be added to the Python sys.path, or NULL. * * @return SRD_OK upon success, a (negative) error code otherwise. + * + * @private */ SRD_PRIV int srd_decoder_searchpath_add(const char *path) { @@ -330,9 +397,9 @@ static gint compare_probe_id(const struct srd_probe *a, const char *probe_id) * it overwrites any probes that were already defined (if any). * * @param di Decoder instance. - * @param probes A GHashTable of probes to set. Key is probe name, value is - * the probe number. Samples passed to this instance will be - * arranged in this order. + * @param new_probes A GHashTable of probes to set. Key is probe name, value is + * the probe number. Samples passed to this instance will be + * arranged in this order. * * @return SRD_OK upon success, a (negative) error code otherwise. */ @@ -344,6 +411,7 @@ SRD_API int srd_inst_probe_set_all(struct srd_decoder_inst *di, struct srd_probe *p; int *new_probemap, new_probenum; char *probe_id, *probenum_str; + 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)); @@ -366,6 +434,13 @@ SRD_API int srd_inst_probe_set_all(struct srd_decoder_inst *di, return SRD_ERR_MALLOC; } + /* + * For now, map all indexes to probe -1 (can be overridden later). + * This -1 is interpreted as an unspecified probe later. + */ + for (i = 0; i < di->dec_num_probes; i++) + new_probemap[i] = -1; + for (l = g_hash_table_get_keys(new_probes); l; l = l->next) { probe_id = l->data; probenum_str = g_hash_table_lookup(new_probes, probe_id); @@ -390,9 +465,17 @@ SRD_API int srd_inst_probe_set_all(struct srd_decoder_inst *di, } p = sl->data; new_probemap[p->order] = new_probenum; - srd_dbg("setting probe mapping for %d = probe %d", p->order, - new_probenum); + srd_dbg("Setting probe mapping: %s (index %d) = probe %d.", + p->id, p->order, new_probenum); } + + srd_dbg("Final probe map:"); + num_required_probes = g_slist_length(di->decoder->probes); + for (i = 0; i < di->dec_num_probes; i++) { + srd_dbg(" - index %d = probe %d (%s)", i, new_probemap[i], + (i < num_required_probes) ? "required" : "optional"); + } + g_free(di->dec_probemap); di->dec_probemap = new_probemap; @@ -402,9 +485,9 @@ SRD_API int srd_inst_probe_set_all(struct srd_decoder_inst *di, /** * Create a new protocol decoder instance. * - * @param id Decoder 'id' field. + * @param decoder_id Decoder 'id' field. * @param options GHashtable of options which override the defaults set in - * the decoder class. + * the decoder class. May be NULL. * * @return Pointer to a newly allocated struct srd_decoder_inst, or * NULL in case of failure. @@ -429,10 +512,13 @@ SRD_API struct srd_decoder_inst *srd_inst_new(const char *decoder_id, return NULL; } - inst_id = g_hash_table_lookup(options, "id"); di->decoder = dec; - di->inst_id = g_strdup(inst_id ? inst_id : decoder_id); - g_hash_table_remove(options, "id"); + if (options) { + inst_id = g_hash_table_lookup(options, "id"); + di->inst_id = g_strdup(inst_id ? inst_id : decoder_id); + g_hash_table_remove(options, "id"); + } else + di->inst_id = g_strdup(decoder_id); /* * Prepare a default probe map, where samples come in the @@ -461,7 +547,7 @@ SRD_API struct srd_decoder_inst *srd_inst_new(const char *decoder_id, return NULL; } - if (srd_inst_option_set(di, options) != SRD_OK) { + if (options && srd_inst_option_set(di, options) != SRD_OK) { g_free(di->dec_probemap); g_free(di); return NULL; @@ -539,6 +625,8 @@ SRD_API struct srd_decoder_inst *srd_inst_find_by_id(const char *inst_id) * @param obj The Python class instantiation. * * @return Pointer to struct srd_decoder_inst, or NULL if not found. + * + * @private */ SRD_PRIV struct srd_decoder_inst *srd_inst_find_by_obj(const GSList *stack, const PyObject *obj) @@ -559,6 +647,7 @@ SRD_PRIV struct srd_decoder_inst *srd_inst_find_by_obj(const GSList *stack, return di; } +/** @private */ SRD_PRIV int srd_inst_start(struct srd_decoder_inst *di, PyObject *args) { PyObject *py_name, *py_res; @@ -608,6 +697,8 @@ SRD_PRIV int srd_inst_start(struct srd_decoder_inst *di, PyObject *args) * @param inbuflen Length of the buffer. Must be > 0. * * @return SRD_OK upon success, a (negative) error code otherwise. + * + * @private */ SRD_PRIV int srd_inst_decode(uint64_t start_samplenum, const struct srd_decoder_inst *di, @@ -662,6 +753,7 @@ SRD_PRIV int srd_inst_decode(uint64_t start_samplenum, return SRD_OK; } +/** @private */ SRD_PRIV void srd_inst_free(struct srd_decoder_inst *di) { GSList *l; @@ -681,6 +773,7 @@ SRD_PRIV void srd_inst_free(struct srd_decoder_inst *di) g_slist_free(di->pd_output); } +/** @private */ SRD_PRIV void srd_inst_free_all(GSList *stack) { GSList *l; @@ -717,6 +810,8 @@ SRD_API int srd_session_start(int num_probes, int unitsize, uint64_t samplerate) struct srd_decoder_inst *di; int ret; + ret = SRD_OK; + srd_dbg("Calling start() on all instances with %d probes, " "unitsize %d samplerate %d.", num_probes, unitsize, samplerate); @@ -735,7 +830,7 @@ SRD_API int srd_session_start(int num_probes, int unitsize, uint64_t samplerate) di->data_num_probes = num_probes; di->data_unitsize = unitsize; di->data_samplerate = samplerate; - if ((ret = srd_inst_start(di, args) != SRD_OK)) + if ((ret = srd_inst_start(di, args)) != SRD_OK) break; } @@ -749,7 +844,7 @@ SRD_API int srd_session_start(int num_probes, int unitsize, uint64_t samplerate) * * @param start_samplenum The sample number of the first sample in this chunk. * @param inbuf Pointer to sample data. - * @param inbuf Length in bytes of the buffer. + * @param inbuflen Length in bytes of the buffer. * * @return SRD_OK upon success, a (negative) error code otherwise. */ @@ -804,6 +899,7 @@ SRD_API int srd_pd_output_callback_add(int output_type, return SRD_OK; } +/** @private */ SRD_PRIV void *srd_pd_output_callback_find(int output_type) { GSList *l; @@ -823,6 +919,7 @@ SRD_PRIV void *srd_pd_output_callback_find(int output_type) } /* 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) { @@ -845,3 +942,5 @@ SRD_PRIV int srd_inst_pd_output_add(struct srd_decoder_inst *di, return pdo->pdo_id; } + +/** @} */