libsigrokdecode
 All Data Structures Files Functions Variables Typedefs Enumerator Macros
Functions | Variables
controller.c File Reference
#include "sigrokdecode.h"
#include "sigrokdecode-internal.h"
#include "config.h"
#include <glib.h>
#include <inttypes.h>
#include <stdlib.h>
Include dependency graph for controller.c:

Go to the source code of this file.

Functions

PyMODINIT_FUNC PyInit_sigrokdecode (void)
 
SRD_API int srd_init (const char *path)
 Initialize libsigrokdecode. More...
 
SRD_API int srd_exit (void)
 Shutdown libsigrokdecode. More...
 
SRD_PRIV int srd_decoder_searchpath_add (const char *path)
 Add an additional search directory for the protocol decoders. More...
 
SRD_API int srd_inst_option_set (struct srd_decoder_inst *di, GHashTable *options)
 Set one or more options in a decoder instance. More...
 
SRD_API int srd_inst_probe_set_all (struct srd_decoder_inst *di, GHashTable *new_probes)
 Set all probes in a decoder instance. More...
 
SRD_API struct srd_decoder_instsrd_inst_new (const char *decoder_id, GHashTable *options)
 Create a new protocol decoder instance. More...
 
SRD_API int srd_inst_stack (struct srd_decoder_inst *di_from, struct srd_decoder_inst *di_to)
 Stack a decoder instance on top of another. More...
 
SRD_API struct srd_decoder_instsrd_inst_find_by_id (const char *inst_id)
 Find a decoder instance by its instance ID. More...
 
SRD_PRIV struct srd_decoder_instsrd_inst_find_by_obj (const GSList *stack, const PyObject *obj)
 Find a decoder instance by its Python object. More...
 
SRD_PRIV int srd_inst_start (struct srd_decoder_inst *di, PyObject *args)
 
SRD_PRIV int srd_inst_decode (uint64_t start_samplenum, const struct srd_decoder_inst *di, const uint8_t *inbuf, uint64_t inbuflen)
 Run the specified decoder function. More...
 
SRD_PRIV void srd_inst_free (struct srd_decoder_inst *di)
 
SRD_PRIV void srd_inst_free_all (GSList *stack)
 
SRD_API int srd_session_start (int num_probes, int unitsize, uint64_t samplerate)
 Start a decoding session. More...
 
SRD_API int srd_session_send (uint64_t start_samplenum, const uint8_t *inbuf, uint64_t inbuflen)
 Send a chunk of logic sample data to a running decoder session. More...
 
SRD_API int srd_pd_output_callback_add (int output_type, srd_pd_output_callback_t cb, void *cb_data)
 Register/add a decoder output callback function. More...
 
SRD_PRIV void * srd_pd_output_callback_find (int output_type)
 
SRD_PRIV int srd_inst_pd_output_add (struct srd_decoder_inst *di, int output_type, const char *proto_id)
 

Variables

SRD_PRIV GSList * pd_list
 
SRD_PRIV PyTypeObject srd_logic_type
 

Function Documentation

PyMODINIT_FUNC PyInit_sigrokdecode ( void  )
SRD_PRIV int srd_decoder_searchpath_add ( const char *  path)

Add an additional search directory for the protocol decoders.

The specified directory is prepended (not appended!) to Python's sys.path, in order to search for sigrok protocol decoders in the specified directories first, and in the generic Python module directories (and in the current working directory) last. This avoids conflicts if there are Python modules which have the same name as a sigrok protocol decoder in sys.path or in the current working directory.

Parameters
pathPath to the directory containing protocol decoders which shall be added to the Python sys.path, or NULL.
Returns
SRD_OK upon success, a (negative) error code otherwise.

Definition at line 148 of file controller.c.

References py_str_as_str(), srd_dbg(), SRD_ERR_MALLOC, and SRD_OK.

Referenced by srd_init().

Here is the call graph for this function:

SRD_API int srd_exit ( 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 in between, is not allowed.

Returns
SRD_OK upon success, a (negative) error code otherwise.

Definition at line 119 of file controller.c.

References pd_list, srd_dbg(), srd_decoder_unload_all(), and SRD_OK.

Here is the call graph for this function:

SRD_API int srd_init ( const char *  path)

Initialize libsigrokdecode.

This initializes the Python interpreter, and creates and initializes a "sigrokdecode" Python module.

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_decoders_list().

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() in between, are not allowed.

Parameters
pathPath to an extra directory containing protocol decoders which will be added to the Python sys.path, or NULL.
Returns
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.

Definition at line 69 of file controller.c.

References PyInit_sigrokdecode(), srd_dbg(), srd_decoder_searchpath_add(), and SRD_OK.

Here is the call graph for this function:

SRD_PRIV int srd_inst_decode ( uint64_t  start_samplenum,
const struct srd_decoder_inst di,
const uint8_t *  inbuf,
uint64_t  inbuflen 
)

Run the specified decoder function.

Parameters
start_samplenumThe starting sample number for the buffer's sample set, relative to the start of capture.
diThe decoder instance to call. Must not be NULL.
inbufThe buffer to decode. Must not be NULL.
inbuflenLength of the buffer. Must be > 0.
Returns
SRD_OK upon success, a (negative) error code otherwise.

Definition at line 612 of file controller.c.

References srd_decoder_inst::data_unitsize, srd_logic::di, srd_logic::inbuf, srd_logic::inbuflen, srd_decoder_inst::inst_id, srd_logic::itercnt, srd_decoder_inst::py_inst, srd_logic::sample, srd_dbg(), SRD_ERR_ARG, SRD_ERR_PYTHON, srd_exception_catch(), srd_logic_type, SRD_OK, and srd_logic::start_samplenum.

Referenced by srd_session_send().

Here is the call graph for this function:

SRD_API struct srd_decoder_inst* srd_inst_find_by_id ( const char *  inst_id)
read

Find a decoder instance by its instance ID.

Only the bottom level of instances are searched – instances already stacked on top of another one will not be found.

Parameters
inst_idThe instance ID to be found.
Returns
Pointer to struct srd_decoder_inst, or NULL if not found.

Definition at line 513 of file controller.c.

References srd_decoder_inst::inst_id.

SRD_PRIV struct srd_decoder_inst* srd_inst_find_by_obj ( const GSList *  stack,
const PyObject *  obj 
)
read

Find a decoder instance by its Python object.

I.e. find that instance's instantiation of the sigrokdecode.Decoder class. This will recurse to find the instance anywhere in the stack tree.

Parameters
stackPointer to a GSList of struct srd_decoder_inst, indicating the stack to search. To start searching at the bottom level of decoder instances, pass NULL.
objThe Python class instantiation.
Returns
Pointer to struct srd_decoder_inst, or NULL if not found.

Definition at line 543 of file controller.c.

References srd_decoder_inst::next_di, srd_decoder_inst::py_inst, and srd_inst_find_by_obj().

Referenced by srd_inst_find_by_obj().

Here is the call graph for this function:

SRD_PRIV void srd_inst_free ( struct srd_decoder_inst di)
SRD_PRIV void srd_inst_free_all ( GSList *  stack)

Definition at line 684 of file controller.c.

References srd_decoder_inst::next_di, srd_inst_free(), and srd_inst_free_all().

Referenced by srd_decoder_unload(), and srd_inst_free_all().

Here is the call graph for this function:

SRD_API struct srd_decoder_inst* srd_inst_new ( const char *  decoder_id,
GHashTable *  options 
)
read

Create a new protocol decoder instance.

Parameters
idDecoder 'id' field.
optionsGHashtable of options which override the defaults set in the decoder class.
Returns
Pointer to a newly allocated struct srd_decoder_inst, or NULL in case of failure.

Definition at line 412 of file controller.c.

References srd_decoder_inst::dec_num_probes, srd_decoder_inst::dec_probemap, srd_decoder_inst::decoder, srd_decoder_inst::inst_id, srd_decoder::opt_probes, srd_decoder::probes, srd_decoder::py_dec, srd_decoder_inst::py_inst, srd_dbg(), srd_decoder_get_by_id(), srd_err(), srd_exception_catch(), srd_inst_option_set(), and SRD_OK.

Here is the call graph for this function:

SRD_API int srd_inst_option_set ( struct srd_decoder_inst di,
GHashTable *  options 
)

Set one or more options in a decoder instance.

Handled options are removed from the hash.

Parameters
diDecoder instance.
optionsA GHashTable of options to set.
Returns
SRD_OK upon success, a (negative) error code otherwise.

Definition at line 211 of file controller.c.

References srd_decoder_inst::decoder, srd_decoder::py_dec, srd_decoder_inst::py_inst, py_str_as_str(), srd_err(), SRD_ERR_ARG, SRD_ERR_PYTHON, srd_exception_catch(), and SRD_OK.

Referenced by srd_inst_new().

Here is the call graph for this function:

SRD_PRIV int srd_inst_pd_output_add ( struct srd_decoder_inst di,
int  output_type,
const char *  proto_id 
)
SRD_API int srd_inst_probe_set_all ( struct srd_decoder_inst di,
GHashTable *  new_probes 
)

Set all probes in a decoder instance.

This function sets all probes for the specified decoder instance, i.e., it overwrites any probes that were already defined (if any).

Parameters
diDecoder instance.
probesA 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.
Returns
SRD_OK upon success, a (negative) error code otherwise.

Definition at line 339 of file controller.c.

References srd_decoder_inst::dec_num_probes, srd_decoder_inst::dec_probemap, srd_decoder_inst::decoder, srd_decoder_inst::inst_id, srd_decoder::name, srd_decoder::opt_probes, srd_probe::order, srd_decoder::probes, srd_dbg(), srd_err(), SRD_ERR_ARG, SRD_ERR_MALLOC, and SRD_OK.

Here is the call graph for this function:

SRD_API int srd_inst_stack ( struct srd_decoder_inst di_from,
struct srd_decoder_inst di_to 
)

Stack a decoder instance on top of another.

Parameters
di_fromThe instance to move.
di_toThe instance on top of which di_from will be stacked.
Returns
SRD_OK upon success, a (negative) error code otherwise.

Definition at line 484 of file controller.c.

References srd_decoder_inst::next_di, srd_err(), SRD_ERR_ARG, and SRD_OK.

Here is the call graph for this function:

SRD_PRIV int srd_inst_start ( struct srd_decoder_inst di,
PyObject *  args 
)
SRD_API int srd_pd_output_callback_add ( int  output_type,
srd_pd_output_callback_t  cb,
void *  cb_data 
)

Register/add a decoder output callback function.

The function will be called when a protocol decoder sends output back to the PD controller (except for Python objects, which only go up the stack).

Parameters
output_typeThe output type this callback will receive. Only one callback per output type can be registered.
cbThe function to call. Must not be NULL.
cb_dataPrivate data for the callback function. Can be NULL.

Definition at line 787 of file controller.c.

References srd_pd_callback::cb, srd_pd_callback::cb_data, srd_pd_callback::output_type, srd_dbg(), srd_err(), SRD_ERR_MALLOC, and SRD_OK.

Here is the call graph for this function:

SRD_PRIV void* srd_pd_output_callback_find ( int  output_type)

Definition at line 807 of file controller.c.

References srd_pd_callback::cb, and srd_pd_callback::output_type.

SRD_API int srd_session_send ( uint64_t  start_samplenum,
const uint8_t *  inbuf,
uint64_t  inbuflen 
)

Send a chunk of logic sample data to a running decoder session.

Parameters
start_samplenumThe sample number of the first sample in this chunk.
inbufPointer to sample data.
inbufLength in bytes of the buffer.
Returns
SRD_OK upon success, a (negative) error code otherwise.

Definition at line 756 of file controller.c.

References srd_dbg(), srd_inst_decode(), and SRD_OK.

Here is the call graph for this function:

SRD_API int srd_session_start ( int  num_probes,
int  unitsize,
uint64_t  samplerate 
)

Start a decoding session.

Decoders, instances and stack must have been prepared beforehand.

Parameters
num_probesThe number of probes which the incoming feed will contain.
unitsizeThe number of bytes per sample in the incoming feed.
samplerateThe samplerate of the incoming feed.
Returns
SRD_OK upon success, a (negative) error code otherwise.

Definition at line 713 of file controller.c.

References srd_decoder_inst::data_num_probes, srd_decoder_inst::data_samplerate, srd_decoder_inst::data_unitsize, srd_dbg(), srd_err(), SRD_ERR_PYTHON, srd_inst_start(), and SRD_OK.

Here is the call graph for this function:

Variable Documentation

SRD_PRIV GSList* pd_list

Definition at line 27 of file decoder.c.

Referenced by srd_decoder_list(), srd_decoder_load(), and srd_exit().

SRD_PRIV PyTypeObject srd_logic_type

Definition at line 68 of file type_logic.c.

Referenced by PyInit_sigrokdecode(), and srd_inst_decode().