libsigrokdecode
0.3.0
sigrok protocol decoding library
Main Page
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
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
struct
srd_session;
34
35
/**
36
* @file
37
*
38
* The public libsigrokdecode header file to be used by frontends.
39
*
40
* This is the only file that libsigrokdecode users (frontends) are supposed
41
* to use and include. There are other header files which get installed with
42
* libsigrokdecode, but those are not meant to be used directly by frontends.
43
*
44
* The correct way to get/use the libsigrokdecode API functions is:
45
*
46
* @code{.c}
47
* #include <libsigrokdecode/libsigrokdecode.h>
48
* @endcode
49
*/
50
51
/*
52
* All possible return codes of libsigrokdecode functions must be listed here.
53
* Functions should never return hardcoded numbers as status, but rather
54
* use these enum values. All error codes are negative numbers.
55
*
56
* The error codes are globally unique in libsigrokdecode, i.e. if one of the
57
* libsigrokdecode functions returns a "malloc error" it must be exactly the
58
* same return value as used by all other functions to indicate "malloc error".
59
* There must be no functions which indicate two different errors via the
60
* same return code.
61
*
62
* Also, for compatibility reasons, no defined return codes are ever removed
63
* or reused for different errors later. You can only add new entries and
64
* return codes, but never remove or redefine existing ones.
65
*/
66
67
/** Status/error codes returned by libsigrokdecode functions. */
68
enum
srd_error_code
{
69
SRD_OK
= 0,
/**< No error */
70
SRD_ERR
= -1,
/**< Generic/unspecified error */
71
SRD_ERR_MALLOC
= -2,
/**< Malloc/calloc/realloc error */
72
SRD_ERR_ARG
= -3,
/**< Function argument error */
73
SRD_ERR_BUG
= -4,
/**< Errors hinting at internal bugs */
74
SRD_ERR_PYTHON
= -5,
/**< Python C API error */
75
SRD_ERR_DECODERS_DIR
= -6,
/**< Protocol decoder path invalid */
76
77
/*
78
* Note: When adding entries here, don't forget to also update the
79
* srd_strerror() and srd_strerror_name() functions in error.c.
80
*/
81
};
82
83
/* libsigrokdecode loglevels. */
84
enum
srd_loglevel
{
85
SRD_LOG_NONE
= 0,
/**< Output no messages at all. */
86
SRD_LOG_ERR
= 1,
/**< Output error messages. */
87
SRD_LOG_WARN
= 2,
/**< Output warnings. */
88
SRD_LOG_INFO
= 3,
/**< Output informational messages. */
89
SRD_LOG_DBG
= 4,
/**< Output debug messages. */
90
SRD_LOG_SPEW
= 5,
/**< Output very noisy debug messages. */
91
};
92
93
/*
94
* Use SRD_API to mark public API symbols, and SRD_PRIV for private symbols.
95
*
96
* Variables and functions marked 'static' are private already and don't
97
* need SRD_PRIV. However, functions which are not static (because they need
98
* to be used in other libsigrokdecode-internal files) but are also not
99
* meant to be part of the public libsigrokdecode API, must use SRD_PRIV.
100
*
101
* This uses the 'visibility' feature of gcc (requires gcc >= 4.0).
102
*
103
* This feature is not available on MinGW/Windows, as it is a feature of
104
* ELF files and MinGW/Windows uses PE files.
105
*
106
* Details: http://gcc.gnu.org/wiki/Visibility
107
*/
108
109
/* Marks public libsigrokdecode API symbols. */
110
#ifndef _WIN32
111
#define SRD_API __attribute__((visibility("default")))
112
#else
113
#define SRD_API
114
#endif
115
116
/* Marks private, non-public libsigrokdecode symbols (not part of the API). */
117
#ifndef _WIN32
118
#define SRD_PRIV __attribute__((visibility("hidden")))
119
#else
120
#define SRD_PRIV
121
#endif
122
123
/*
124
* When adding an output type, don't forget to...
125
* - expose it to PDs in controller.c:PyInit_sigrokdecode()
126
* - add a check in module_sigrokdecode.c:Decoder_put()
127
* - add a debug string in type_decoder.c:OUTPUT_TYPES
128
*/
129
enum
srd_output_type
{
130
SRD_OUTPUT_ANN
,
131
SRD_OUTPUT_PYTHON
,
132
SRD_OUTPUT_BINARY
,
133
SRD_OUTPUT_META
,
134
};
135
136
enum
srd_configkey
{
137
SRD_CONF_SAMPLERATE
= 10000,
138
};
139
140
struct
srd_decoder
{
141
/** The decoder ID. Must be non-NULL and unique for all decoders. */
142
char
*
id
;
143
144
/** The (short) decoder name. Must be non-NULL. */
145
char
*
name
;
146
147
/** The (long) decoder name. Must be non-NULL. */
148
char
*
longname
;
149
150
/** A (short, one-line) description of the decoder. Must be non-NULL. */
151
char
*
desc
;
152
153
/**
154
* The license of the decoder. Valid values: "gplv2+", "gplv3+".
155
* Other values are currently not allowed. Must be non-NULL.
156
*/
157
char
*
license
;
158
159
/** List of channels required by this decoder. */
160
GSList *
channels
;
161
162
/** List of optional channels for this decoder. */
163
GSList *
opt_channels
;
164
165
/**
166
* List of NULL-terminated char[], containing descriptions of the
167
* supported annotation output.
168
*/
169
GSList *
annotations
;
170
171
/**
172
* List of annotation rows (row items: id, description, and a list
173
* of annotation classes belonging to this row).
174
*/
175
GSList *
annotation_rows
;
176
177
/**
178
* List of NULL-terminated char[], containing descriptions of the
179
* supported binary output.
180
*/
181
GSList *
binary
;
182
183
/** List of decoder options. */
184
GSList *
options
;
185
186
/** Python module. */
187
PyObject *
py_mod
;
188
189
/** sigrokdecode.Decoder class. */
190
PyObject *
py_dec
;
191
};
192
193
/**
194
* Structure which contains information about one protocol decoder channel.
195
* For example, I2C has two channels, SDA and SCL.
196
*/
197
struct
srd_channel
{
198
/** The ID of the channel. Must be non-NULL. */
199
char
*
id
;
200
/** The name of the channel. Must not be NULL. */
201
char
*
name
;
202
/** The description of the channel. Must not be NULL. */
203
char
*
desc
;
204
/** The index of the channel, i.e. its order in the list of channels. */
205
int
order
;
206
};
207
208
struct
srd_decoder_option
{
209
char
*
id
;
210
char
*
desc
;
211
GVariant *
def
;
212
GSList *
values
;
213
};
214
215
struct
srd_decoder_annotation_row
{
216
char
*
id
;
217
char
*
desc
;
218
GSList *
ann_classes
;
219
};
220
221
struct
srd_decoder_inst
{
222
struct
srd_decoder
*
decoder
;
223
struct
srd_session *
sess
;
224
PyObject *
py_inst
;
225
char
*
inst_id
;
226
GSList *
pd_output
;
227
int
dec_num_channels
;
228
int
*
dec_channelmap
;
229
int
data_unitsize
;
230
uint8_t *
channel_samples
;
231
GSList *
next_di
;
232
};
233
234
struct
srd_pd_output
{
235
int
pdo_id
;
236
int
output_type
;
237
struct
srd_decoder_inst
*
di
;
238
char
*
proto_id
;
239
/* Only used for OUTPUT_META. */
240
const
GVariantType *
meta_type
;
241
char
*
meta_name
;
242
char
*
meta_descr
;
243
};
244
245
struct
srd_proto_data
{
246
uint64_t
start_sample
;
247
uint64_t
end_sample
;
248
struct
srd_pd_output
*
pdo
;
249
void
*
data
;
250
};
251
struct
srd_proto_data_annotation
{
252
int
ann_format
;
253
char
**
ann_text
;
254
};
255
struct
srd_proto_data_binary
{
256
int
bin_class
;
257
uint64_t
size
;
258
const
unsigned
char
*
data
;
259
};
260
261
typedef
void (*
srd_pd_output_callback
)(
struct
srd_proto_data
*pdata,
262
void
*cb_data);
263
264
struct
srd_pd_callback
{
265
int
output_type
;
266
srd_pd_output_callback
cb
;
267
void
*
cb_data
;
268
};
269
270
/* Custom Python types: */
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
283
/* srd.c */
284
SRD_API
int
srd_init
(
const
char
*path);
285
SRD_API
int
srd_exit
(
void
);
286
287
/* session.c */
288
SRD_API
int
srd_session_new
(
struct
srd_session **
sess
);
289
SRD_API
int
srd_session_start
(
struct
srd_session *
sess
);
290
SRD_API
int
srd_session_metadata_set
(
struct
srd_session *
sess
,
int
key,
291
GVariant *data);
292
SRD_API
int
srd_session_send
(
struct
srd_session *
sess
,
293
uint64_t start_samplenum, uint64_t end_samplenum,
294
const
uint8_t *inbuf, uint64_t inbuflen);
295
SRD_API
int
srd_session_destroy
(
struct
srd_session *
sess
);
296
SRD_API
int
srd_pd_output_callback_add
(
struct
srd_session *
sess
,
297
int
output_type,
srd_pd_output_callback
cb,
void
*cb_data);
298
299
/* decoder.c */
300
SRD_API
const
GSList *
srd_decoder_list
(
void
);
301
SRD_API
struct
srd_decoder
*
srd_decoder_get_by_id
(
const
char
*
id
);
302
SRD_API
int
srd_decoder_load
(
const
char
*
name
);
303
SRD_API
char
*
srd_decoder_doc_get
(
const
struct
srd_decoder
*dec);
304
SRD_API
int
srd_decoder_unload
(
struct
srd_decoder
*dec);
305
SRD_API
int
srd_decoder_load_all
(
void
);
306
SRD_API
int
srd_decoder_unload_all
(
void
);
307
308
/* instance.c */
309
SRD_API
int
srd_inst_option_set
(
struct
srd_decoder_inst
*di,
310
GHashTable *
options
);
311
SRD_API
int
srd_inst_channel_set_all
(
struct
srd_decoder_inst
*di,
312
GHashTable *
channels
,
int
unit_size);
313
SRD_API
struct
srd_decoder_inst
*
srd_inst_new
(
struct
srd_session *
sess
,
314
const
char
*
id
, GHashTable *options);
315
SRD_API
int
srd_inst_stack
(
struct
srd_session *
sess
,
316
struct
srd_decoder_inst
*di_from,
struct
srd_decoder_inst
*di_to);
317
SRD_API
struct
srd_decoder_inst
*
srd_inst_find_by_id
(
struct
srd_session *
sess
,
318
const
char
*
inst_id
);
319
320
/* log.c */
321
typedef
int (*
srd_log_callback
)(
void
*cb_data,
int
loglevel,
322
const
char
*format, va_list args);
323
SRD_API
int
srd_log_loglevel_set
(
int
loglevel);
324
SRD_API
int
srd_log_loglevel_get
(
void
);
325
SRD_API
int
srd_log_callback_set
(
srd_log_callback
cb,
void
*cb_data);
326
SRD_API
int
srd_log_callback_set_default
(
void
);
327
SRD_API
int
srd_log_logdomain_set
(
const
char
*logdomain);
328
SRD_API
char
*
srd_log_logdomain_get
(
void
);
329
330
/* error.c */
331
SRD_API
const
char
*
srd_strerror
(
int
error_code);
332
SRD_API
const
char
*
srd_strerror_name
(
int
error_code);
333
334
/* version.c */
335
SRD_API
int
srd_package_version_major_get
(
void
);
336
SRD_API
int
srd_package_version_minor_get
(
void
);
337
SRD_API
int
srd_package_version_micro_get
(
void
);
338
SRD_API
const
char
*
srd_package_version_string_get
(
void
);
339
SRD_API
int
srd_lib_version_current_get
(
void
);
340
SRD_API
int
srd_lib_version_revision_get
(
void
);
341
SRD_API
int
srd_lib_version_age_get
(
void
);
342
SRD_API
const
char
*
srd_lib_version_string_get
(
void
);
343
344
#include "
version.h
"
345
346
#ifdef __cplusplus
347
}
348
#endif
349
350
#endif
Generated on Sat Sep 20 2014 08:20:43 for libsigrokdecode by
1.8.3.1