libsigrokdecode
Main Page
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerator
Macros
sigrokdecode.h
Go to the documentation of this file.
1
/*
2
* This file is part of the sigrok 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
* Package version macros (can be used for conditional compilation).
35
*/
36
37
/** The libsigrokdecode package 'major' version number. */
38
#define SRD_PACKAGE_VERSION_MAJOR 0
39
40
/** The libsigrokdecode package 'minor' version number. */
41
#define SRD_PACKAGE_VERSION_MINOR 1
42
43
/** The libsigrokdecode package 'micro' version number. */
44
#define SRD_PACKAGE_VERSION_MICRO 1
45
46
/** The libsigrokdecode package version ("major.minor.micro") as string. */
47
#define SRD_PACKAGE_VERSION_STRING "0.1.1"
48
49
/*
50
* Library/libtool version macros (can be used for conditional compilation).
51
*/
52
53
/** The libsigrokdecode libtool 'current' version number. */
54
#define SRD_LIB_VERSION_CURRENT 0
55
56
/** The libsigrokdecode libtool 'revision' version number. */
57
#define SRD_LIB_VERSION_REVISION 1
58
59
/** The libsigrokdecode libtool 'age' version number. */
60
#define SRD_LIB_VERSION_AGE 0
61
62
/** The libsigrokdecode libtool version ("current:revision:age") as string. */
63
#define SRD_LIB_VERSION_STRING "0:1:0"
64
65
/*
66
* Status/error codes returned by libsigrokdecode functions.
67
*
68
* All possible return codes of libsigrokdecode functions must be listed here.
69
* Functions should never return hardcoded numbers as status, but rather
70
* use these #defines instead. All error codes are negative numbers.
71
*
72
* The error codes are globally unique in libsigrokdecode, i.e. if one of the
73
* libsigrokdecode functions returns a "malloc error" it must be exactly the
74
* same return value as used by all other functions to indicate "malloc error".
75
* There must be no functions which indicate two different errors via the
76
* same return code.
77
*
78
* Also, for compatibility reasons, no defined return codes are ever removed
79
* or reused for different #defines later. You can only add new #defines and
80
* return codes, but never remove or redefine existing ones.
81
*/
82
#define SRD_OK 0
/**< No error */
83
#define SRD_ERR -1
/**< Generic/unspecified error */
84
#define SRD_ERR_MALLOC -2
/**< Malloc/calloc/realloc error */
85
#define SRD_ERR_ARG -3
/**< Function argument error */
86
#define SRD_ERR_BUG -4
/**< Errors hinting at internal bugs */
87
#define SRD_ERR_PYTHON -5
/**< Python C API error */
88
#define SRD_ERR_DECODERS_DIR -6
/**< Protocol decoder path invalid */
89
90
/* libsigrokdecode loglevels. */
91
#define SRD_LOG_NONE 0
/**< Output no messages at all. */
92
#define SRD_LOG_ERR 1
/**< Output error messages. */
93
#define SRD_LOG_WARN 2
/**< Output warnings. */
94
#define SRD_LOG_INFO 3
/**< Output informational messages. */
95
#define SRD_LOG_DBG 4
/**< Output debug messages. */
96
#define SRD_LOG_SPEW 5
/**< Output very noisy debug messages. */
97
98
/*
99
* Use SRD_API to mark public API symbols, and SRD_PRIV for private symbols.
100
*
101
* Variables and functions marked 'static' are private already and don't
102
* need SRD_PRIV. However, functions which are not static (because they need
103
* to be used in other libsigrokdecode-internal files) but are also not
104
* meant to be part of the public libsigrokdecode API, must use SRD_PRIV.
105
*
106
* This uses the 'visibility' feature of gcc (requires gcc >= 4.0).
107
*
108
* This feature is not available on MinGW/Windows, as it is a feature of
109
* ELF files and MinGW/Windows uses PE files.
110
*
111
* Details: http://gcc.gnu.org/wiki/Visibility
112
*/
113
114
/* Marks public libsigrokdecode API symbols. */
115
#ifndef _WIN32
116
#define SRD_API __attribute__((visibility("default")))
117
#else
118
#define SRD_API
119
#endif
120
121
/* Marks private, non-public libsigrokdecode symbols (not part of the API). */
122
#ifndef _WIN32
123
#define SRD_PRIV __attribute__((visibility("hidden")))
124
#else
125
#define SRD_PRIV
126
#endif
127
128
/*
129
* When adding an output type, don't forget to...
130
* - expose it to PDs in controller.c:PyInit_sigrokdecode()
131
* - add a check in module_sigrokdecode.c:Decoder_put()
132
* - add a debug string in type_decoder.c:OUTPUT_TYPES
133
*/
134
enum
{
135
SRD_OUTPUT_ANN
,
136
SRD_OUTPUT_PROTO
,
137
SRD_OUTPUT_BINARY
,
138
};
139
140
#define SRD_MAX_NUM_PROBES 64
141
142
/* TODO: Documentation. */
143
struct
srd_decoder
{
144
/** The decoder ID. Must be non-NULL and unique for all decoders. */
145
char
*
id
;
146
147
/** The (short) decoder name. Must be non-NULL. */
148
char
*
name
;
149
150
/** The (long) decoder name. Must be non-NULL. */
151
char
*
longname
;
152
153
/** A (short, one-line) description of the decoder. Must be non-NULL. */
154
char
*
desc
;
155
156
/**
157
* The license of the decoder. Valid values: "gplv2+", "gplv3+".
158
* Other values are currently not allowed. Must be non-NULL.
159
*/
160
char
*
license
;
161
162
/** List of probes required by this decoder. */
163
GSList *
probes
;
164
165
/** List of optional probes for this decoder. */
166
GSList *
opt_probes
;
167
168
/**
169
* List of NULL-terminated char[], containing descriptions of the
170
* supported annotation output.
171
*/
172
GSList *
annotations
;
173
174
/** Python module. */
175
PyObject *
py_mod
;
176
177
/** sigrokdecode.Decoder class. */
178
PyObject *
py_dec
;
179
};
180
181
/**
182
* Structure which contains information about one protocol decoder probe.
183
* For example, I2C has two probes, SDA and SCL.
184
*/
185
struct
srd_probe
{
186
/** The ID of the probe. Must be non-NULL. */
187
char
*
id
;
188
/** The name of the probe. Must not be NULL. */
189
char
*
name
;
190
/** The description of the probe. Must not be NULL. */
191
char
*
desc
;
192
/** The index of the probe, i.e. its order in the list of probes. */
193
int
order
;
194
};
195
196
struct
srd_decoder_inst
{
197
struct
srd_decoder
*
decoder
;
198
PyObject *
py_inst
;
199
char
*
inst_id
;
200
GSList *
pd_output
;
201
int
dec_num_probes
;
202
int
*
dec_probemap
;
203
int
data_num_probes
;
204
int
data_unitsize
;
205
uint64_t
data_samplerate
;
206
GSList *
next_di
;
207
};
208
209
struct
srd_pd_output
{
210
int
pdo_id
;
211
int
output_type
;
212
struct
srd_decoder_inst
*
di
;
213
char
*
proto_id
;
214
};
215
216
struct
srd_proto_data
{
217
uint64_t
start_sample
;
218
uint64_t
end_sample
;
219
struct
srd_pd_output
*
pdo
;
220
int
ann_format
;
221
void
*
data
;
222
};
223
224
typedef
void (*
srd_pd_output_callback_t
)(
struct
srd_proto_data
*pdata,
225
void
*cb_data);
226
227
struct
srd_pd_callback
{
228
int
output_type
;
229
srd_pd_output_callback_t
cb
;
230
void
*
cb_data
;
231
};
232
233
/* Custom Python types: */
234
235
typedef
struct
{
236
PyObject_HEAD
237
}
srd_Decoder
;
238
239
typedef
struct
{
240
PyObject_HEAD
241
struct
srd_decoder_inst
*
di
;
242
uint64_t
start_samplenum
;
243
unsigned
int
itercnt
;
244
uint8_t *
inbuf
;
245
uint64_t
inbuflen
;
246
PyObject *
sample
;
247
}
srd_logic
;
248
249
/*--- controller.c ----------------------------------------------------------*/
250
251
SRD_API
int
srd_init
(
const
char
*path);
252
SRD_API
int
srd_exit
(
void
);
253
SRD_API
int
srd_inst_option_set
(
struct
srd_decoder_inst
*di,
254
GHashTable *options);
255
SRD_API
int
srd_inst_probe_set_all
(
struct
srd_decoder_inst
*di,
256
GHashTable *probes);
257
SRD_API
struct
srd_decoder_inst
*
srd_inst_new
(
const
char
*
id
,
258
GHashTable *options);
259
SRD_API
int
srd_inst_stack
(
struct
srd_decoder_inst
*di_from,
260
struct
srd_decoder_inst
*di_to);
261
SRD_API
struct
srd_decoder_inst
*
srd_inst_find_by_id
(
const
char
*
inst_id
);
262
SRD_API
int
srd_session_start
(
int
num_probes,
int
unitsize,
263
uint64_t samplerate);
264
SRD_API
int
srd_session_send
(uint64_t start_samplenum,
const
uint8_t *inbuf,
265
uint64_t inbuflen);
266
SRD_API
int
srd_pd_output_callback_add
(
int
output_type,
267
srd_pd_output_callback_t
cb,
void
*cb_data);
268
269
/*--- decoder.c -------------------------------------------------------------*/
270
271
SRD_API
GSList *
srd_decoder_list
(
void
);
272
SRD_API
struct
srd_decoder
*
srd_decoder_get_by_id
(
const
char
*
id
);
273
SRD_API
int
srd_decoder_load
(
const
char
*
name
);
274
SRD_API
int
srd_decoder_unload
(
struct
srd_decoder
*dec);
275
SRD_API
int
srd_decoder_load_all
(
void
);
276
SRD_API
int
srd_decoder_unload_all
(
void
);
277
SRD_API
char
*
srd_decoder_doc_get
(
const
struct
srd_decoder
*dec);
278
279
/*--- log.c -----------------------------------------------------------------*/
280
281
typedef
int (*
srd_log_callback_t
)(
void
*cb_data,
int
loglevel,
282
const
char
*format, va_list args);
283
284
SRD_API
int
srd_log_loglevel_set
(
int
loglevel);
285
SRD_API
int
srd_log_loglevel_get
(
void
);
286
SRD_API
int
srd_log_callback_set
(
srd_log_callback_t
cb,
void
*cb_data);
287
SRD_API
int
srd_log_callback_set_default
(
void
);
288
SRD_API
int
srd_log_logdomain_set
(
const
char
*logdomain);
289
SRD_API
char
*
srd_log_logdomain_get
(
void
);
290
291
/*--- version.c -------------------------------------------------------------*/
292
293
SRD_API
int
srd_package_version_major_get
(
void
);
294
SRD_API
int
srd_package_version_minor_get
(
void
);
295
SRD_API
int
srd_package_version_micro_get
(
void
);
296
SRD_API
const
char
*
srd_package_version_string_get
(
void
);
297
298
SRD_API
int
srd_lib_version_current_get
(
void
);
299
SRD_API
int
srd_lib_version_revision_get
(
void
);
300
SRD_API
int
srd_lib_version_age_get
(
void
);
301
SRD_API
const
char
*
srd_lib_version_string_get
(
void
);
302
303
#ifdef __cplusplus
304
}
305
#endif
306
307
#endif
Generated on Mon Apr 1 2013 08:18:32 for libsigrokdecode by
1.8.3.1