libsigrok
|
00001 /* 00002 * This file is part of the sigrok project. 00003 * 00004 * Copyright (C) 2010-2012 Bert Vermeulen <bert@biot.com> 00005 * 00006 * This program is free software: you can redistribute it and/or modify 00007 * it under the terms of the GNU General Public License as published by 00008 * the Free Software Foundation, either version 3 of the License, or 00009 * (at your option) any later version. 00010 * 00011 * This program is distributed in the hope that it will be useful, 00012 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00014 * GNU General Public License for more details. 00015 * 00016 * You should have received a copy of the GNU General Public License 00017 * along with this program. If not, see <http://www.gnu.org/licenses/>. 00018 */ 00019 00020 #ifndef LIBSIGROK_SIGROK_H 00021 #define LIBSIGROK_SIGROK_H 00022 00023 #include <stdio.h> 00024 #include <sys/time.h> 00025 #include <stdint.h> 00026 #include <inttypes.h> 00027 #include <glib.h> 00028 00029 #ifdef __cplusplus 00030 extern "C" { 00031 #endif 00032 00033 /* 00034 * Package version macros (can be used for conditional compilation). 00035 */ 00036 00037 /** The libsigrok package 'major' version number. */ 00038 #define SR_PACKAGE_VERSION_MAJOR 0 00039 00040 /** The libsigrok package 'minor' version number. */ 00041 #define SR_PACKAGE_VERSION_MINOR 1 00042 00043 /** The libsigrok package 'micro' version number. */ 00044 #define SR_PACKAGE_VERSION_MICRO 1 00045 00046 /** The libsigrok package version ("major.minor.micro") as string. */ 00047 #define SR_PACKAGE_VERSION_STRING "0.1.1" 00048 00049 /* 00050 * Library/libtool version macros (can be used for conditional compilation). 00051 */ 00052 00053 /** The libsigrok libtool 'current' version number. */ 00054 #define SR_LIB_VERSION_CURRENT 0 00055 00056 /** The libsigrok libtool 'revision' version number. */ 00057 #define SR_LIB_VERSION_REVISION 0 00058 00059 /** The libsigrok libtool 'age' version number. */ 00060 #define SR_LIB_VERSION_AGE 0 00061 00062 /** The libsigrok libtool version ("current:revision:age") as string. */ 00063 #define SR_LIB_VERSION_STRING "0:0:0" 00064 00065 /* 00066 * Status/error codes returned by libsigrok functions. 00067 * 00068 * All possible return codes of libsigrok functions must be listed here. 00069 * Functions should never return hardcoded numbers as status, but rather 00070 * use these #defines instead. All error codes are negative numbers. 00071 * 00072 * The error codes are globally unique in libsigrok, i.e. if one of the 00073 * libsigrok functions returns a "malloc error" it must be exactly the same 00074 * return value as used by all other functions to indicate "malloc error". 00075 * There must be no functions which indicate two different errors via the 00076 * same return code. 00077 * 00078 * Also, for compatibility reasons, no defined return codes are ever removed 00079 * or reused for different #defines later. You can only add new #defines and 00080 * return codes, but never remove or redefine existing ones. 00081 */ 00082 #define SR_OK 0 /* No error */ 00083 #define SR_ERR -1 /* Generic/unspecified error */ 00084 #define SR_ERR_MALLOC -2 /* Malloc/calloc/realloc error */ 00085 #define SR_ERR_ARG -3 /* Function argument error */ 00086 #define SR_ERR_BUG -4 /* Errors hinting at internal bugs */ 00087 #define SR_ERR_SAMPLERATE -5 /* Incorrect samplerate */ 00088 00089 #define SR_MAX_NUM_PROBES 64 /* Limited by uint64_t. */ 00090 #define SR_MAX_PROBENAME_LEN 32 00091 00092 /* Handy little macros */ 00093 #define SR_HZ(n) (n) 00094 #define SR_KHZ(n) ((n) * 1000) 00095 #define SR_MHZ(n) ((n) * 1000000) 00096 #define SR_GHZ(n) ((n) * 1000000000) 00097 00098 #define SR_HZ_TO_NS(n) (1000000000 / (n)) 00099 00100 /* libsigrok loglevels. */ 00101 #define SR_LOG_NONE 0 /**< Output no messages at all. */ 00102 #define SR_LOG_ERR 1 /**< Output error messages. */ 00103 #define SR_LOG_WARN 2 /**< Output warnings. */ 00104 #define SR_LOG_INFO 3 /**< Output informational messages. */ 00105 #define SR_LOG_DBG 4 /**< Output debug messages. */ 00106 #define SR_LOG_SPEW 5 /**< Output very noisy debug messages. */ 00107 00108 /* 00109 * Use SR_API to mark public API symbols, and SR_PRIV for private symbols. 00110 * 00111 * Variables and functions marked 'static' are private already and don't 00112 * need SR_PRIV. However, functions which are not static (because they need 00113 * to be used in other libsigrok-internal files) but are also not meant to 00114 * be part of the public libsigrok API, must use SR_PRIV. 00115 * 00116 * This uses the 'visibility' feature of gcc (requires gcc >= 4.0). 00117 * 00118 * This feature is not available on MinGW/Windows, as it is a feature of 00119 * ELF files and MinGW/Windows uses PE files. 00120 * 00121 * Details: http://gcc.gnu.org/wiki/Visibility 00122 */ 00123 00124 /* Marks public libsigrok API symbols. */ 00125 #ifndef _WIN32 00126 #define SR_API __attribute__((visibility("default"))) 00127 #else 00128 #define SR_API 00129 #endif 00130 00131 /* Marks private, non-public libsigrok symbols (not part of the API). */ 00132 #ifndef _WIN32 00133 #define SR_PRIV __attribute__((visibility("hidden"))) 00134 #else 00135 #define SR_PRIV 00136 #endif 00137 00138 typedef int (*sr_receive_data_callback_t)(int fd, int revents, void *cb_data); 00139 00140 /* Data types used by hardware drivers for dev_config_set() */ 00141 enum { 00142 SR_T_UINT64, 00143 SR_T_CHAR, 00144 SR_T_BOOL, 00145 }; 00146 00147 /* sr_datafeed_packet.type values */ 00148 enum { 00149 SR_DF_HEADER, 00150 SR_DF_END, 00151 SR_DF_TRIGGER, 00152 SR_DF_LOGIC, 00153 SR_DF_PD, 00154 }; 00155 00156 struct sr_datafeed_packet { 00157 uint16_t type; 00158 void *payload; 00159 }; 00160 00161 struct sr_datafeed_header { 00162 int feed_version; 00163 struct timeval starttime; 00164 uint64_t samplerate; 00165 int num_logic_probes; 00166 }; 00167 00168 struct sr_datafeed_logic { 00169 uint64_t length; 00170 uint16_t unitsize; 00171 void *data; 00172 }; 00173 00174 struct sr_input { 00175 struct sr_input_format *format; 00176 char *param; 00177 struct sr_dev *vdev; 00178 }; 00179 00180 struct sr_input_format { 00181 char *id; 00182 char *description; 00183 int (*format_match) (const char *filename); 00184 int (*init) (struct sr_input *in); 00185 int (*loadfile) (struct sr_input *in, const char *filename); 00186 }; 00187 00188 struct sr_output { 00189 struct sr_output_format *format; 00190 struct sr_dev *dev; 00191 char *param; 00192 void *internal; 00193 }; 00194 00195 struct sr_output_format { 00196 char *id; 00197 char *description; 00198 int df_type; 00199 int (*init) (struct sr_output *o); 00200 int (*data) (struct sr_output *o, const uint8_t *data_in, 00201 uint64_t length_in, uint8_t **data_out, 00202 uint64_t *length_out); 00203 int (*event) (struct sr_output *o, int event_type, uint8_t **data_out, 00204 uint64_t *length_out); 00205 }; 00206 00207 struct sr_datastore { 00208 /* Size in bytes of the number of units stored in this datastore */ 00209 int ds_unitsize; 00210 unsigned int num_units; /* TODO: uint64_t */ 00211 GSList *chunklist; 00212 }; 00213 00214 /* 00215 * This represents a generic device connected to the system. 00216 * For device-specific information, ask the driver. The driver_index refers 00217 * to the device index within that driver; it may be handling more than one 00218 * device. All relevant driver calls take a dev_index parameter for this. 00219 */ 00220 struct sr_dev { 00221 /* Which driver handles this device */ 00222 struct sr_dev_driver *driver; 00223 /* A driver may handle multiple devices of the same type */ 00224 int driver_index; 00225 /* List of struct sr_probe* */ 00226 GSList *probes; 00227 /* Data acquired by this device, if any */ 00228 struct sr_datastore *datastore; 00229 }; 00230 00231 enum { 00232 SR_PROBE_TYPE_LOGIC, 00233 }; 00234 00235 struct sr_probe { 00236 int index; 00237 int type; 00238 gboolean enabled; 00239 char *name; 00240 char *trigger; 00241 }; 00242 00243 /* Hardware driver capabilities */ 00244 enum { 00245 SR_HWCAP_DUMMY = 0, /* Used to terminate lists. Must be 0! */ 00246 00247 /*--- Device classes ------------------------------------------------*/ 00248 00249 /** The device can act as logic analyzer. */ 00250 SR_HWCAP_LOGIC_ANALYZER, 00251 00252 /* TODO: SR_HWCAP_SCOPE, SW_HWCAP_PATTERN_GENERATOR, etc.? */ 00253 00254 /*--- Device types --------------------------------------------------*/ 00255 00256 /** The device is demo device. */ 00257 SR_HWCAP_DEMO_DEV, 00258 00259 /*--- Device options ------------------------------------------------*/ 00260 00261 /** The device supports setting/changing its samplerate. */ 00262 SR_HWCAP_SAMPLERATE, 00263 00264 /* TODO: Better description? Rename to PROBE_AND_TRIGGER_CONFIG? */ 00265 /** The device supports setting a probe mask. */ 00266 SR_HWCAP_PROBECONFIG, 00267 00268 /** The device supports setting a pre/post-trigger capture ratio. */ 00269 SR_HWCAP_CAPTURE_RATIO, 00270 00271 /* TODO? */ 00272 /** The device supports setting a pattern (pattern generator mode). */ 00273 SR_HWCAP_PATTERN_MODE, 00274 00275 /** The device supports Run Length Encoding. */ 00276 SR_HWCAP_RLE, 00277 00278 /*--- Special stuff -------------------------------------------------*/ 00279 00280 /* TODO: Better description. */ 00281 /** The device supports specifying a capturefile to inject. */ 00282 SR_HWCAP_CAPTUREFILE, 00283 00284 /* TODO: Better description. */ 00285 /** The device supports specifying the capturefile unit size. */ 00286 SR_HWCAP_CAPTURE_UNITSIZE, 00287 00288 /* TODO: Better description. */ 00289 /** The device supports setting the number of probes. */ 00290 SR_HWCAP_CAPTURE_NUM_PROBES, 00291 00292 /*--- Acquisition modes ---------------------------------------------*/ 00293 00294 /** 00295 * The device supports setting a sample time limit, i.e. how long the 00296 * sample acquisition should run (in ms). 00297 */ 00298 SR_HWCAP_LIMIT_MSEC, 00299 00300 /** 00301 * The device supports setting a sample number limit, i.e. how many 00302 * samples should be acquired. 00303 */ 00304 SR_HWCAP_LIMIT_SAMPLES, 00305 00306 /** 00307 * The device supports continuous sampling, i.e. neither a time limit 00308 * nor a sample number limit has to be supplied, it will just acquire 00309 * samples continuously, until explicitly stopped by a certain command. 00310 */ 00311 SR_HWCAP_CONTINUOUS, 00312 00313 /* TODO: SR_HWCAP_JUST_SAMPLE or similar. */ 00314 }; 00315 00316 struct sr_hwcap_option { 00317 int hwcap; 00318 int type; 00319 char *description; 00320 char *shortname; 00321 }; 00322 00323 struct sr_dev_inst { 00324 int index; 00325 int status; 00326 int inst_type; 00327 char *vendor; 00328 char *model; 00329 char *version; 00330 void *priv; 00331 }; 00332 00333 /* sr_dev_inst types */ 00334 enum { 00335 /** Device instance type for USB devices. */ 00336 SR_INST_USB, 00337 /** Device instance type for serial port devices. */ 00338 SR_INST_SERIAL, 00339 }; 00340 00341 /* Device instance status */ 00342 enum { 00343 SR_ST_NOT_FOUND, 00344 /* Found, but still booting */ 00345 SR_ST_INITIALIZING, 00346 /* Live, but not in use */ 00347 SR_ST_INACTIVE, 00348 /* Actively in use in a session */ 00349 SR_ST_ACTIVE, 00350 }; 00351 00352 /* 00353 * TODO: This sucks, you just kinda have to "know" the returned type. 00354 * TODO: Need a DI to return the number of trigger stages supported. 00355 */ 00356 00357 /* Device info IDs */ 00358 enum { 00359 /* struct sr_dev_inst for this specific device */ 00360 SR_DI_INST, 00361 /* The number of probes connected to this device */ 00362 SR_DI_NUM_PROBES, 00363 /* The probe names on this device */ 00364 SR_DI_PROBE_NAMES, 00365 /* Samplerates supported by this device, (struct sr_samplerates) */ 00366 SR_DI_SAMPLERATES, 00367 /* Types of trigger supported, out of "01crf" (char *) */ 00368 SR_DI_TRIGGER_TYPES, 00369 /* The currently set samplerate in Hz (uint64_t) */ 00370 SR_DI_CUR_SAMPLERATE, 00371 /* Supported patterns (in pattern generator mode) */ 00372 SR_DI_PATTERNS, 00373 }; 00374 00375 /* 00376 * A device supports either a range of samplerates with steps of a given 00377 * granularity, or is limited to a set of defined samplerates. Use either 00378 * step or list, but not both. 00379 */ 00380 struct sr_samplerates { 00381 uint64_t low; 00382 uint64_t high; 00383 uint64_t step; 00384 uint64_t *list; 00385 }; 00386 00387 struct sr_dev_driver { 00388 /* Driver-specific */ 00389 char *name; 00390 char *longname; 00391 int api_version; 00392 int (*init) (const char *devinfo); 00393 int (*cleanup) (void); 00394 00395 /* Device-specific */ 00396 int (*dev_open) (int dev_index); 00397 int (*dev_close) (int dev_index); 00398 void *(*dev_info_get) (int dev_index, int dev_info_id); 00399 int (*dev_status_get) (int dev_index); 00400 int *(*hwcap_get_all) (void); 00401 int (*dev_config_set) (int dev_index, int hwcap, void *value); 00402 int (*dev_acquisition_start) (int dev_index, void *session_dev_id); 00403 int (*dev_acquisition_stop) (int dev_index, void *session_dev_id); 00404 }; 00405 00406 struct sr_session { 00407 /* List of struct sr_dev* */ 00408 GSList *devs; 00409 /* list of sr_receive_data_callback_t */ 00410 GSList *datafeed_callbacks; 00411 GTimeVal starttime; 00412 gboolean running; 00413 }; 00414 00415 #include "sigrok-proto.h" 00416 00417 #ifdef __cplusplus 00418 } 00419 #endif 00420 00421 #endif