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, see <http://www.gnu.org/licenses/>. 19 */ 20 21 #ifndef LIBSIGROKDECODE_LIBSIGROKDECODE_H 22 #define LIBSIGROKDECODE_LIBSIGROKDECODE_H 23 24 #include <stdint.h> 25 #include <glib.h> 26 27 #ifdef __cplusplus 28 extern "C" { 29 #endif 30 31 struct srd_session; 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 * All possible return codes of libsigrokdecode functions must be listed here. 51 * Functions should never return hardcoded numbers as status, but rather 52 * use these enum values. All error codes are negative numbers. 53 * 54 * The error codes are globally unique in libsigrokdecode, i.e. if one of the 55 * libsigrokdecode functions returns a "malloc error" it must be exactly the 56 * same return value as used by all other functions to indicate "malloc error". 57 * There must be no functions which indicate two different errors via the 58 * same return code. 59 * 60 * Also, for compatibility reasons, no defined return codes are ever removed 61 * or reused for different errors later. You can only add new entries and 62 * return codes, but never remove or redefine existing ones. 63 */ 64 65 /** Status/error codes returned by libsigrokdecode functions. */ 66 enum srd_error_code { 67 SRD_OK = 0, /**< No error */ 68 SRD_ERR = -1, /**< Generic/unspecified error */ 69 SRD_ERR_MALLOC = -2, /**< Malloc/calloc/realloc error */ 70 SRD_ERR_ARG = -3, /**< Function argument error */ 71 SRD_ERR_BUG = -4, /**< Errors hinting at internal bugs */ 72 SRD_ERR_PYTHON = -5, /**< Python C API error */ 73 SRD_ERR_DECODERS_DIR = -6, /**< Protocol decoder path invalid */ 74 SRD_ERR_TERM_REQ = -7, /**< Termination requested */ 75 76 /* 77 * Note: When adding entries here, don't forget to also update the 78 * srd_strerror() and srd_strerror_name() functions in error.c. 79 */ 80 }; 81 82 /* libsigrokdecode loglevels. */ 83 enum srd_loglevel { 84 SRD_LOG_NONE = 0, /**< Output no messages at all. */ 85 SRD_LOG_ERR = 1, /**< Output error messages. */ 86 SRD_LOG_WARN = 2, /**< Output warnings. */ 87 SRD_LOG_INFO = 3, /**< Output informational messages. */ 88 SRD_LOG_DBG = 4, /**< Output debug messages. */ 89 SRD_LOG_SPEW = 5, /**< Output very noisy debug messages. */ 90 }; 91 92 /* 93 * Use SRD_API to mark public API symbols, and SRD_PRIV for private symbols. 94 * 95 * Variables and functions marked 'static' are private already and don't 96 * need SRD_PRIV. However, functions which are not static (because they need 97 * to be used in other libsigrokdecode-internal files) but are also not 98 * meant to be part of the public libsigrokdecode API, must use SRD_PRIV. 99 * 100 * This uses the 'visibility' feature of gcc (requires gcc >= 4.0). 101 * 102 * This feature is not available on MinGW/Windows, as it is a feature of 103 * ELF files and MinGW/Windows uses PE files. 104 * 105 * Details: http://gcc.gnu.org/wiki/Visibility 106 */ 107 108 /* Marks public libsigrokdecode API symbols. */ 109 #ifndef _WIN32 110 #define SRD_API __attribute__((visibility("default"))) 111 #else 112 #define SRD_API 113 #endif 114 115 /* Marks private, non-public libsigrokdecode symbols (not part of the API). */ 116 #ifndef _WIN32 117 #define SRD_PRIV __attribute__((visibility("hidden"))) 118 #else 119 #define SRD_PRIV 120 #endif 121 122 /* 123 * When adding an output type, don't forget to... 124 * - expose it to PDs in controller.c:PyInit_sigrokdecode() 125 * - add a check in module_sigrokdecode.c:Decoder_put() 126 * - add a debug string in type_decoder.c:OUTPUT_TYPES 127 */ 128 enum srd_output_type { 129 SRD_OUTPUT_ANN, 130 SRD_OUTPUT_PYTHON, 131 SRD_OUTPUT_BINARY, 132 SRD_OUTPUT_META, 133 }; 134 135 enum srd_configkey { 136 SRD_CONF_SAMPLERATE = 10000, 137 }; 138 139 struct srd_decoder { 140 /** The decoder ID. Must be non-NULL and unique for all decoders. */ 141 char *id; 142 143 /** The (short) decoder name. Must be non-NULL. */ 144 char *name; 145 146 /** The (long) decoder name. Must be non-NULL. */ 147 char *longname; 148 149 /** A (short, one-line) description of the decoder. Must be non-NULL. */ 150 char *desc; 151 152 /** 153 * The license of the decoder. Valid values: "gplv2+", "gplv3+". 154 * Other values are currently not allowed. Must be non-NULL. 155 */ 156 char *license; 157 158 /** List of possible decoder input IDs. */ 159 GSList *inputs; 160 161 /** List of possible decoder output IDs. */ 162 GSList *outputs; 163 164 /** List of channels required by this decoder. */ 165 GSList *channels; 166 167 /** List of optional channels for this decoder. */ 168 GSList *opt_channels; 169 170 /** 171 * List of annotation classes. Each list item is a GSList itself, with 172 * two NUL-terminated strings: name and description. 173 */ 174 GSList *annotations; 175 176 /** 177 * List of annotation rows (row items: id, description, and a list 178 * of annotation classes belonging to this row). 179 */ 180 GSList *annotation_rows; 181 182 /** 183 * List of binary classes. Each list item is a GSList itself, with 184 * two NUL-terminated strings: name and description. 185 */ 186 GSList *binary; 187 188 /** List of decoder options. */ 189 GSList *options; 190 191 /** Python module. */ 192 void *py_mod; 193 194 /** sigrokdecode.Decoder class. */ 195 void *py_dec; 196 }; 197 198 enum srd_initial_pin { 199 SRD_INITIAL_PIN_LOW, 200 SRD_INITIAL_PIN_HIGH, 201 SRD_INITIAL_PIN_SAME_AS_SAMPLE0, 202 }; 203 204 /** 205 * Structure which contains information about one protocol decoder channel. 206 * For example, I2C has two channels, SDA and SCL. 207 */ 208 struct srd_channel { 209 /** The ID of the channel. Must be non-NULL. */ 210 char *id; 211 /** The name of the channel. Must not be NULL. */ 212 char *name; 213 /** The description of the channel. Must not be NULL. */ 214 char *desc; 215 /** The index of the channel, i.e. its order in the list of channels. */ 216 int order; 217 }; 218 219 struct srd_decoder_option { 220 char *id; 221 char *desc; 222 GVariant *def; 223 GSList *values; 224 }; 225 226 struct srd_decoder_annotation_row { 227 char *id; 228 char *desc; 229 GSList *ann_classes; 230 }; 231 232 struct srd_decoder_inst { 233 struct srd_decoder *decoder; 234 struct srd_session *sess; 235 void *py_inst; 236 char *inst_id; 237 GSList *pd_output; 238 int dec_num_channels; 239 int *dec_channelmap; 240 int data_unitsize; 241 uint8_t *channel_samples; 242 GSList *next_di; 243 244 /** List of conditions a PD wants to wait for. */ 245 GSList *condition_list; 246 247 /** Array of booleans denoting which conditions matched. */ 248 GArray *match_array; 249 250 /** Absolute start sample number. */ 251 uint64_t abs_start_samplenum; 252 253 /** Absolute end sample number. */ 254 uint64_t abs_end_samplenum; 255 256 /** Pointer to the buffer/chunk of input samples. */ 257 const uint8_t *inbuf; 258 259 /** Length (in bytes) of the input sample buffer. */ 260 uint64_t inbuflen; 261 262 /** Absolute current samplenumber. */ 263 uint64_t abs_cur_samplenum; 264 265 /** Array of "old" (previous sample) pin values. */ 266 GArray *old_pins_array; 267 268 /** Handle for this PD stack's worker thread. */ 269 GThread *thread_handle; 270 271 /** Indicates whether new samples are available for processing. */ 272 gboolean got_new_samples; 273 274 /** Indicates whether the worker thread has handled all samples. */ 275 gboolean handled_all_samples; 276 277 /** Requests termination of wait() and decode(). */ 278 gboolean want_wait_terminate; 279 280 /** Indicates the current state of the decoder stack. */ 281 int decoder_state; 282 283 GCond got_new_samples_cond; 284 GCond handled_all_samples_cond; 285 GMutex data_mutex; 286 }; 287 288 struct srd_pd_output { 289 int pdo_id; 290 int output_type; 291 struct srd_decoder_inst *di; 292 char *proto_id; 293 /* Only used for OUTPUT_META. */ 294 const GVariantType *meta_type; 295 char *meta_name; 296 char *meta_descr; 297 }; 298 299 struct srd_proto_data { 300 uint64_t start_sample; 301 uint64_t end_sample; 302 struct srd_pd_output *pdo; 303 void *data; 304 }; 305 struct srd_proto_data_annotation { 306 int ann_class; /* Index into "struct srd_decoder"->annotations. */ 307 char **ann_text; 308 }; 309 struct srd_proto_data_binary { 310 int bin_class; /* Index into "struct srd_decoder"->binary. */ 311 uint64_t size; 312 const unsigned char *data; 313 }; 314 315 typedef void (*srd_pd_output_callback)(struct srd_proto_data *pdata, 316 void *cb_data); 317 318 struct srd_pd_callback { 319 int output_type; 320 srd_pd_output_callback cb; 321 void *cb_data; 322 }; 323 324 /* srd.c */ 325 SRD_API int srd_init(const char *path); 326 SRD_API int srd_exit(void); 327 SRD_API GSList *srd_searchpaths_get(void); 328 329 /* session.c */ 330 SRD_API int srd_session_new(struct srd_session **sess); 331 SRD_API int srd_session_start(struct srd_session *sess); 332 SRD_API int srd_session_metadata_set(struct srd_session *sess, int key, 333 GVariant *data); 334 SRD_API int srd_session_send(struct srd_session *sess, 335 uint64_t abs_start_samplenum, uint64_t abs_end_samplenum, 336 const uint8_t *inbuf, uint64_t inbuflen, uint64_t unitsize); 337 SRD_API int srd_session_terminate_reset(struct srd_session *sess); 338 SRD_API int srd_session_destroy(struct srd_session *sess); 339 SRD_API int srd_pd_output_callback_add(struct srd_session *sess, 340 int output_type, srd_pd_output_callback cb, void *cb_data); 341 342 /* decoder.c */ 343 SRD_API const GSList *srd_decoder_list(void); 344 SRD_API struct srd_decoder *srd_decoder_get_by_id(const char *id); 345 SRD_API int srd_decoder_load(const char *name); 346 SRD_API char *srd_decoder_doc_get(const struct srd_decoder *dec); 347 SRD_API int srd_decoder_unload(struct srd_decoder *dec); 348 SRD_API int srd_decoder_load_all(void); 349 SRD_API int srd_decoder_unload_all(void); 350 351 /* instance.c */ 352 SRD_API int srd_inst_option_set(struct srd_decoder_inst *di, 353 GHashTable *options); 354 SRD_API int srd_inst_channel_set_all(struct srd_decoder_inst *di, 355 GHashTable *channels); 356 SRD_API struct srd_decoder_inst *srd_inst_new(struct srd_session *sess, 357 const char *id, GHashTable *options); 358 SRD_API int srd_inst_stack(struct srd_session *sess, 359 struct srd_decoder_inst *di_from, struct srd_decoder_inst *di_to); 360 SRD_API struct srd_decoder_inst *srd_inst_find_by_id(struct srd_session *sess, 361 const char *inst_id); 362 SRD_API int srd_inst_initial_pins_set_all(struct srd_decoder_inst *di, 363 GArray *initial_pins); 364 365 /* log.c */ 366 typedef int (*srd_log_callback)(void *cb_data, int loglevel, 367 const char *format, va_list args); 368 SRD_API int srd_log_loglevel_set(int loglevel); 369 SRD_API int srd_log_loglevel_get(void); 370 SRD_API int srd_log_callback_get(srd_log_callback *cb, void **cb_data); 371 SRD_API int srd_log_callback_set(srd_log_callback cb, void *cb_data); 372 SRD_API int srd_log_callback_set_default(void); 373 374 /* error.c */ 375 SRD_API const char *srd_strerror(int error_code); 376 SRD_API const char *srd_strerror_name(int error_code); 377 378 /* version.c */ 379 SRD_API int srd_package_version_major_get(void); 380 SRD_API int srd_package_version_minor_get(void); 381 SRD_API int srd_package_version_micro_get(void); 382 SRD_API const char *srd_package_version_string_get(void); 383 SRD_API int srd_lib_version_current_get(void); 384 SRD_API int srd_lib_version_revision_get(void); 385 SRD_API int srd_lib_version_age_get(void); 386 SRD_API const char *srd_lib_version_string_get(void); 387 SRD_API GSList *srd_buildinfo_libs_get(void); 388 SRD_API char *srd_buildinfo_host_get(void); 389 390 #include "version.h" 391 392 #ifdef __cplusplus 393 } 394 #endif 395 396 #endif 397