libsigrokdecode
0.2.0
sigrok protocol decoding library
Main Page
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerator
Macros
Groups
Pages
libsigrokdecode.h
Go to the documentation of this file.
1
/*
2
* This file is part of the libsigrokdecode project.
3
*
4
* Copyright (C) 2010 Uwe Hermann <uwe@hermann-uwe.de>
5
* Copyright (C) 2012 Bert Vermeulen <bert@biot.com>
6
*
7
* This program is free software; you can redistribute it and/or modify
8
* it under the terms of the GNU General Public License as published by
9
* the Free Software Foundation; either version 2 of the License, or
10
* (at your option) any later version.
11
*
12
* This program is distributed in the hope that it will be useful,
13
* but WITHOUT ANY WARRANTY; without even the implied warranty of
14
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15
* GNU General Public License for more details.
16
*
17
* You should have received a copy of the GNU General Public License
18
* along with this program; if not, write to the Free Software
19
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
20
*/
21
22
#ifndef LIBSIGROKDECODE_SIGROKDECODE_H
23
#define LIBSIGROKDECODE_SIGROKDECODE_H
24
25
#include <Python.h>
/* First, so we avoid a _POSIX_C_SOURCE warning. */
26
#include <stdint.h>
27
#include <glib.h>
28
29
#ifdef __cplusplus
30
extern
"C"
{
31
#endif
32
33
/**
34
* @file
35
*
36
* The public libsigrokdecode header file to be used by frontends.
37
*
38
* This is the only file that libsigrokdecode users (frontends) are supposed
39
* to use and include. There are other header files which get installed with
40
* libsigrokdecode, but those are not meant to be used directly by frontends.
41
*
42
* The correct way to get/use the libsigrokdecode API functions is:
43
*
44
* @code{.c}
45
* #include <libsigrokdecode/libsigrokdecode.h>
46
* @endcode
47
*/
48
49
/*
50
* Package version macros (can be used for conditional compilation).
51
*/
52
53
/** The libsigrokdecode package 'major' version number. */
54
#define SRD_PACKAGE_VERSION_MAJOR 0
55
56
/** The libsigrokdecode package 'minor' version number. */
57
#define SRD_PACKAGE_VERSION_MINOR 2
58
59
/** The libsigrokdecode package 'micro' version number. */
60
#define SRD_PACKAGE_VERSION_MICRO 0
61
62
/** The libsigrokdecode package version ("major.minor.micro") as string. */
63
#define SRD_PACKAGE_VERSION_STRING "0.2.0"
64
65
/*
66
* Library/libtool version macros (can be used for conditional compilation).
67
*/
68
69
/** The libsigrokdecode libtool 'current' version number. */
70
#define SRD_LIB_VERSION_CURRENT 1
71
72
/** The libsigrokdecode libtool 'revision' version number. */
73
#define SRD_LIB_VERSION_REVISION 0
74
75
/** The libsigrokdecode libtool 'age' version number. */
76
#define SRD_LIB_VERSION_AGE 0
77
78
/** The libsigrokdecode libtool version ("current:revision:age") as string. */
79
#define SRD_LIB_VERSION_STRING "1:0:0"
80
81
/*
82
* All possible return codes of libsigrokdecode functions must be listed here.
83
* Functions should never return hardcoded numbers as status, but rather
84
* use these enum values. All error codes are negative numbers.
85
*
86
* The error codes are globally unique in libsigrokdecode, i.e. if one of the
87
* libsigrokdecode functions returns a "malloc error" it must be exactly the
88
* same return value as used by all other functions to indicate "malloc error".
89
* There must be no functions which indicate two different errors via the
90
* same return code.
91
*
92
* Also, for compatibility reasons, no defined return codes are ever removed
93
* or reused for different errors later. You can only add new entries and
94
* return codes, but never remove or redefine existing ones.
95
*/
96
97
/** Status/error codes returned by libsigrokdecode functions. */
98
enum
{
99
SRD_OK
= 0,
/**< No error */
100
SRD_ERR
= -1,
/**< Generic/unspecified error */
101
SRD_ERR_MALLOC
= -2,
/**< Malloc/calloc/realloc error */
102
SRD_ERR_ARG
= -3,
/**< Function argument error */
103
SRD_ERR_BUG
= -4,
/**< Errors hinting at internal bugs */
104
SRD_ERR_PYTHON
= -5,
/**< Python C API error */
105
SRD_ERR_DECODERS_DIR
= -6,
/**< Protocol decoder path invalid */
106
107
/*
108
* Note: When adding entries here, don't forget to also update the
109
* srd_strerror() and srd_strerror_name() functions in error.c.
110
*/
111
};
112
113
/* libsigrokdecode loglevels. */
114
enum
{
115
SRD_LOG_NONE
= 0,
/**< Output no messages at all. */
116
SRD_LOG_ERR
= 1,
/**< Output error messages. */
117
SRD_LOG_WARN
= 2,
/**< Output warnings. */
118
SRD_LOG_INFO
= 3,
/**< Output informational messages. */
119
SRD_LOG_DBG
= 4,
/**< Output debug messages. */
120
SRD_LOG_SPEW
= 5,
/**< Output very noisy debug messages. */
121
};
122
123
/*
124
* Use SRD_API to mark public API symbols, and SRD_PRIV for private symbols.
125
*
126
* Variables and functions marked 'static' are private already and don't
127
* need SRD_PRIV. However, functions which are not static (because they need
128
* to be used in other libsigrokdecode-internal files) but are also not
129
* meant to be part of the public libsigrokdecode API, must use SRD_PRIV.
130
*
131
* This uses the 'visibility' feature of gcc (requires gcc >= 4.0).
132
*
133
* This feature is not available on MinGW/Windows, as it is a feature of
134
* ELF files and MinGW/Windows uses PE files.
135
*
136
* Details: http://gcc.gnu.org/wiki/Visibility
137
*/
138
139
/* Marks public libsigrokdecode API symbols. */
140
#ifndef _WIN32
141
#define SRD_API __attribute__((visibility("default")))
142
#else
143
#define SRD_API
144
#endif
145
146
/* Marks private, non-public libsigrokdecode symbols (not part of the API). */
147
#ifndef _WIN32
148
#define SRD_PRIV __attribute__((visibility("hidden")))
149
#else
150
#define SRD_PRIV
151
#endif
152
153
/*
154
* When adding an output type, don't forget to...
155
* - expose it to PDs in controller.c:PyInit_sigrokdecode()
156
* - add a check in module_sigrokdecode.c:Decoder_put()
157
* - add a debug string in type_decoder.c:OUTPUT_TYPES
158
*/
159
enum
{
160
SRD_OUTPUT_ANN
,
161
SRD_OUTPUT_PROTO
,
162
SRD_OUTPUT_BINARY
,
163
};
164
165
#define SRD_MAX_NUM_PROBES 64
166
167
struct
srd_decoder
{
168
/** The decoder ID. Must be non-NULL and unique for all decoders. */
169
char
*
id
;
170
171
/** The (short) decoder name. Must be non-NULL. */
172
char
*
name
;
173
174
/** The (long) decoder name. Must be non-NULL. */
175
char
*
longname
;
176
177
/** A (short, one-line) description of the decoder. Must be non-NULL. */
178
char
*
desc
;
179
180
/**
181
* The license of the decoder. Valid values: "gplv2+", "gplv3+".
182
* Other values are currently not allowed. Must be non-NULL.
183
*/
184
char
*
license
;
185
186
/** List of probes required by this decoder. */
187
GSList *
probes
;
188
189
/** List of optional probes for this decoder. */
190
GSList *
opt_probes
;
191
192
/**
193
* List of NULL-terminated char[], containing descriptions of the
194
* supported annotation output.
195
*/
196
GSList *
annotations
;
197
198
/** List of decoder options. */
199
GSList *
options
;
200
201
/** Python module. */
202
PyObject *
py_mod
;
203
204
/** sigrokdecode.Decoder class. */
205
PyObject *
py_dec
;
206
};
207
208
/**
209
* Structure which contains information about one protocol decoder probe.
210
* For example, I2C has two probes, SDA and SCL.
211
*/
212
struct
srd_probe
{
213
/** The ID of the probe. Must be non-NULL. */
214
char
*
id
;
215
/** The name of the probe. Must not be NULL. */
216
char
*
name
;
217
/** The description of the probe. Must not be NULL. */
218
char
*
desc
;
219
/** The index of the probe, i.e. its order in the list of probes. */
220
int
order
;
221
};
222
223
struct
srd_decoder_option
{
224
char
*
id
;
225
char
*
desc
;
226
GVariant *
def
;
227
};
228
229
struct
srd_decoder_inst
{
230
struct
srd_decoder
*
decoder
;
231
PyObject *
py_inst
;
232
char
*
inst_id
;
233
GSList *
pd_output
;
234
int
dec_num_probes
;
235
int
*
dec_probemap
;
236
int
data_num_probes
;
237
int
data_unitsize
;
238
uint64_t
data_samplerate
;
239
GSList *
next_di
;
240
};
241
242
struct
srd_pd_output
{
243
int
pdo_id
;
244
int
output_type
;
245
struct
srd_decoder_inst
*
di
;
246
char
*
proto_id
;
247
};
248
249
struct
srd_proto_data
{
250
uint64_t
start_sample
;
251
uint64_t
end_sample
;
252
struct
srd_pd_output
*
pdo
;
253
int
ann_format
;
254
void
*
data
;
255
};
256
257
typedef
void (*
srd_pd_output_callback_t
)(
struct
srd_proto_data
*pdata,
258
void
*cb_data);
259
260
struct
srd_pd_callback
{
261
int
output_type
;
262
srd_pd_output_callback_t
cb
;
263
void
*
cb_data
;
264
};
265
266
/* Custom Python types: */
267
268
typedef
struct
{
269
PyObject_HEAD
270
}
srd_Decoder
;
271
272
typedef
struct
{
273
PyObject_HEAD
274
struct
srd_decoder_inst
*
di
;
275
uint64_t
start_samplenum
;
276
unsigned
int
itercnt
;
277
uint8_t *
inbuf
;
278
uint64_t
inbuflen
;
279
PyObject *
sample
;
280
}
srd_logic
;
281
282
/*--- controller.c ----------------------------------------------------------*/
283
284
SRD_API
int
srd_init
(
const
char
*path);
285
SRD_API
int
srd_exit
(
void
);
286
SRD_API
int
srd_inst_option_set
(
struct
srd_decoder_inst
*di,
287
GHashTable *options);
288
SRD_API
int
srd_inst_probe_set_all
(
struct
srd_decoder_inst
*di,
289
GHashTable *probes);
290
SRD_API
struct
srd_decoder_inst
*
srd_inst_new
(
const
char
*
id
,
291
GHashTable *options);
292
SRD_API
int
srd_inst_stack
(
struct
srd_decoder_inst
*di_from,
293
struct
srd_decoder_inst
*di_to);
294
SRD_API
struct
srd_decoder_inst
*
srd_inst_find_by_id
(
const
char
*
inst_id
);
295
SRD_API
int
srd_session_start
(
int
num_probes,
int
unitsize, uint64_t samplerate);
296
SRD_API
int
srd_session_send
(uint64_t start_samplenum,
const
uint8_t *inbuf,
297
uint64_t inbuflen);
298
SRD_API
int
srd_pd_output_callback_add
(
int
output_type,
299
srd_pd_output_callback_t
cb,
void
*cb_data);
300
301
/*--- decoder.c -------------------------------------------------------------*/
302
303
SRD_API
const
GSList *
srd_decoder_list
(
void
);
304
SRD_API
struct
srd_decoder
*
srd_decoder_get_by_id
(
const
char
*
id
);
305
SRD_API
int
srd_decoder_load
(
const
char
*
name
);
306
SRD_API
int
srd_decoder_unload
(
struct
srd_decoder
*dec);
307
SRD_API
int
srd_decoder_load_all
(
void
);
308
SRD_API
int
srd_decoder_unload_all
(
void
);
309
SRD_API
char
*
srd_decoder_doc_get
(
const
struct
srd_decoder
*dec);
310
311
/*--- log.c -----------------------------------------------------------------*/
312
313
typedef
int (*
srd_log_callback_t
)(
void
*cb_data,
int
loglevel,
314
const
char
*format, va_list args);
315
316
SRD_API
int
srd_log_loglevel_set
(
int
loglevel);
317
SRD_API
int
srd_log_loglevel_get
(
void
);
318
SRD_API
int
srd_log_callback_set
(
srd_log_callback_t
cb,
void
*cb_data);
319
SRD_API
int
srd_log_callback_set_default
(
void
);
320
SRD_API
int
srd_log_logdomain_set
(
const
char
*logdomain);
321
SRD_API
char
*
srd_log_logdomain_get
(
void
);
322
323
/*--- version.c -------------------------------------------------------------*/
324
325
SRD_API
int
srd_package_version_major_get
(
void
);
326
SRD_API
int
srd_package_version_minor_get
(
void
);
327
SRD_API
int
srd_package_version_micro_get
(
void
);
328
SRD_API
const
char
*
srd_package_version_string_get
(
void
);
329
330
SRD_API
int
srd_lib_version_current_get
(
void
);
331
SRD_API
int
srd_lib_version_revision_get
(
void
);
332
SRD_API
int
srd_lib_version_age_get
(
void
);
333
SRD_API
const
char
*
srd_lib_version_string_get
(
void
);
334
335
/*--- error.c ---------------------------------------------------------------*/
336
337
SRD_API
const
char
*
srd_strerror
(
int
error_code);
338
SRD_API
const
char
*
srd_strerror_name
(
int
error_code);
339
340
#ifdef __cplusplus
341
}
342
#endif
343
344
#endif
Generated on Thu May 9 2013 13:23:11 for libsigrokdecode by
1.8.3.1