libsigrok  0.2.2
sigrok hardware access and backend library
 All Data Structures Files Functions Variables Typedefs Enumerator Macros Groups Pages
Functions
Probe filter

Helper functions to filter out unused probes from samples. More...

Functions

int sr_filter_probes (unsigned int in_unitsize, unsigned int out_unitsize, const GArray *probe_array, const uint8_t *data_in, uint64_t length_in, uint8_t **data_out, uint64_t *length_out)
 Remove unused probes from samples. More...
 

Detailed Description

Helper functions to filter out unused probes from samples.

Function Documentation

int sr_filter_probes ( unsigned int  in_unitsize,
unsigned int  out_unitsize,
const GArray *  probe_array,
const uint8_t *  data_in,
uint64_t  length_in,
uint8_t **  data_out,
uint64_t *  length_out 
)

Remove unused probes from samples.

Convert sample from maximum probes – the way the hardware driver sent it – to a sample taking up only as much space as required, with unused probes removed.

The "unit size" is the number of bytes used to store probe values. For example, a unit size of 1 means one byte is used (which can store 8 probe values, each of them is 1 bit). A unit size of 2 means we can store 16 probe values, 3 means we can store 24 probe values, and so on.

If the data coming from the logic analyzer has a unit size of 4 for example (as the device has 32 probes), but only 2 of them are actually used in an acquisition, this function can convert the samples to only use up 1 byte per sample (unit size = 1) instead of 4 bytes per sample.

The output will contain the probe values in the order specified via the probelist. For example, if in_unitsize = 4, probelist = [5, 16, 30], and out_unitsize = 1, then the output samples (each of them one byte in size) will have the following format: bit 0 = value of probe 5, bit 1 = value of probe 16, bit 2 = value of probe 30. Unused bit(s) in the output byte(s) are zero.

The caller must make sure that length_in is not bigger than the memory actually allocated for the input data (data_in), as this function does not check that.

Parameters
in_unitsizeThe unit size (>= 1) of the input (data_in).
out_unitsizeThe unit size (>= 1) the output shall have (data_out). The requested unit size must be big enough to hold as much data as is specified by the number of enabled probes in 'probelist'.
probe_arrayPointer to a list of probe numbers, numbered starting from 0. The list is terminated with -1.
data_inPointer to the input data buffer. Must not be NULL.
length_inThe input data length (>= 1), in number of bytes.
data_outVariable which will point to the newly allocated buffer of output data. The caller is responsible for g_free()'ing the buffer when it's no longer needed. Must not be NULL.
length_outPointer to the variable which will contain the output data length (in number of bytes) when the function returns SR_OK. Must not be NULL.
Returns
SR_OK upon success, SR_ERR_MALLOC upon memory allocation errors, or SR_ERR_ARG upon invalid arguments. If something other than SR_OK is returned, the values of out_unitsize, data_out, and length_out are undefined.
Since
0.2.0

Definition at line 101 of file filter.c.

References sr_err, SR_ERR_ARG, SR_ERR_MALLOC, and SR_OK.