]> sigrok.org Git - libsigrok.git/blob - libsigrok.h
add relative humidity MQ
[libsigrok.git] / libsigrok.h
1 /*
2  * This file is part of the sigrok project.
3  *
4  * Copyright (C) 2010-2012 Bert Vermeulen <bert@biot.com>
5  *
6  * This program is free software: you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation, either version 3 of the License, or
9  * (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
18  */
19
20 #ifndef LIBSIGROK_SIGROK_H
21 #define LIBSIGROK_SIGROK_H
22
23 #include <stdio.h>
24 #include <sys/time.h>
25 #include <stdint.h>
26 #include <inttypes.h>
27 #include <glib.h>
28
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32
33 /**
34  * @file
35  *
36  * The public libsigrok header file to be used by frontends.
37  *
38  * This is the only file that libsigrok users (frontends) are supposed to
39  * use and #include. There are other header files which get installed with
40  * libsigrok, but those are not meant to be used directly by frontends.
41  *
42  * The correct way to get/use the libsigrok API functions is:
43  *
44  * @code{.c}
45  *   #include <libsigrok/libsigrok.h>
46  * @endcode
47  */
48
49 /*
50  * All possible return codes of libsigrok 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 libsigrok, i.e. if one of the
55  * libsigrok functions returns a "malloc error" it must be exactly the same
56  * 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 libsigrok functions. */
66 enum {
67         SR_OK             =  0, /**< No error. */
68         SR_ERR            = -1, /**< Generic/unspecified error. */
69         SR_ERR_MALLOC     = -2, /**< Malloc/calloc/realloc error. */
70         SR_ERR_ARG        = -3, /**< Function argument error. */
71         SR_ERR_BUG        = -4, /**< Errors hinting at internal bugs. */
72         SR_ERR_SAMPLERATE = -5, /**< Incorrect samplerate. */
73 };
74
75 #define SR_MAX_NUM_PROBES    64 /* Limited by uint64_t. */
76 #define SR_MAX_PROBENAME_LEN 32
77
78 /* Handy little macros */
79 #define SR_HZ(n)  (n)
80 #define SR_KHZ(n) ((n) * 1000)
81 #define SR_MHZ(n) ((n) * 1000000)
82 #define SR_GHZ(n) ((n) * 1000000000)
83
84 #define SR_HZ_TO_NS(n) (1000000000 / (n))
85
86 /** libsigrok loglevels. */
87 enum {
88         SR_LOG_NONE = 0, /**< Output no messages at all. */
89         SR_LOG_ERR  = 1, /**< Output error messages. */
90         SR_LOG_WARN = 2, /**< Output warnings. */
91         SR_LOG_INFO = 3, /**< Output informational messages. */
92         SR_LOG_DBG  = 4, /**< Output debug messages. */
93         SR_LOG_SPEW = 5, /**< Output very noisy debug messages. */
94 };
95
96 /*
97  * Use SR_API to mark public API symbols, and SR_PRIV for private symbols.
98  *
99  * Variables and functions marked 'static' are private already and don't
100  * need SR_PRIV. However, functions which are not static (because they need
101  * to be used in other libsigrok-internal files) but are also not meant to
102  * be part of the public libsigrok API, must use SR_PRIV.
103  *
104  * This uses the 'visibility' feature of gcc (requires gcc >= 4.0).
105  *
106  * This feature is not available on MinGW/Windows, as it is a feature of
107  * ELF files and MinGW/Windows uses PE files.
108  *
109  * Details: http://gcc.gnu.org/wiki/Visibility
110  */
111
112 /* Marks public libsigrok API symbols. */
113 #ifndef _WIN32
114 #define SR_API __attribute__((visibility("default")))
115 #else
116 #define SR_API
117 #endif
118
119 /* Marks private, non-public libsigrok symbols (not part of the API). */
120 #ifndef _WIN32
121 #define SR_PRIV __attribute__((visibility("hidden")))
122 #else
123 #define SR_PRIV
124 #endif
125
126 typedef int (*sr_receive_data_callback_t)(int fd, int revents, void *cb_data);
127
128 /** Data types used by hardware drivers for dev_config_set(). */
129 enum {
130         SR_T_UINT64 = 10000,
131         SR_T_CHAR,
132         SR_T_BOOL,
133         SR_T_FLOAT,
134         SR_T_RATIONAL_PERIOD,
135         SR_T_RATIONAL_VOLT,
136         SR_T_KEYVALUE,
137 };
138
139 /** Rational number data type, containing numerator and denominator values. */
140 struct sr_rational {
141         /** Numerator of the rational number. */
142         uint64_t p;
143         /** Denominator of the rational number. */
144         uint64_t q;
145 };
146
147 /** Value for sr_datafeed_packet.type. */
148 enum {
149         SR_DF_HEADER = 10000,
150         SR_DF_END,
151         SR_DF_TRIGGER,
152         SR_DF_LOGIC,
153         SR_DF_META_LOGIC,
154         SR_DF_ANALOG,
155         SR_DF_META_ANALOG,
156         SR_DF_FRAME_BEGIN,
157         SR_DF_FRAME_END,
158 };
159
160 /** Values for sr_datafeed_analog.mq. */
161 enum {
162         SR_MQ_VOLTAGE = 10000,
163         SR_MQ_CURRENT,
164         SR_MQ_RESISTANCE,
165         SR_MQ_CAPACITANCE,
166         SR_MQ_TEMPERATURE,
167         SR_MQ_FREQUENCY,
168         SR_MQ_DUTY_CYCLE,
169         SR_MQ_CONTINUITY,
170         SR_MQ_PULSE_WIDTH,
171         SR_MQ_CONDUCTANCE,
172         /** Electrical power, usually in W, or dBm. */
173         SR_MQ_POWER,
174         /** Gain (a transistor's gain, or hFE, for example). */
175         SR_MQ_GAIN,
176         /** Logarithmic representation of sound pressure relative to a
177          * reference value. */
178         SR_MQ_SOUND_PRESSURE_LEVEL,
179         SR_MQ_CARBON_MONOXIDE,
180         SR_MQ_RELATIVE_HUMIDITY,
181 };
182
183 /** Values for sr_datafeed_analog.unit. */
184 enum {
185         SR_UNIT_VOLT = 10000,
186         SR_UNIT_AMPERE,
187         SR_UNIT_OHM,
188         SR_UNIT_FARAD,
189         SR_UNIT_KELVIN,
190         SR_UNIT_CELSIUS,
191         SR_UNIT_FAHRENHEIT,
192         SR_UNIT_HERTZ,
193         SR_UNIT_PERCENTAGE,
194         SR_UNIT_BOOLEAN,
195         SR_UNIT_SECOND,
196         /** Unit of conductance, the inverse of resistance. */
197         SR_UNIT_SIEMENS,
198         /**
199          * An absolute measurement of power, in decibels, referenced to
200          * 1 milliwatt (dBu).
201          */
202         SR_UNIT_DECIBEL_MW,
203         /** Voltage in decibel, referenced to 1 volt (dBV). */
204         SR_UNIT_DECIBEL_VOLT,
205         /**
206          * Measurements that intrinsically do not have units attached, such
207          * as ratios, gains, etc. Specifically, a transistor's gain (hFE) is
208          * a unitless quantity, for example.
209          */
210         SR_UNIT_UNITLESS,
211         /** Sound pressure level relative so 20 micropascals. */
212         SR_UNIT_DECIBEL_SPL,
213         SR_UNIT_CONCENTRATION,
214 };
215
216 /** Values for sr_datafeed_analog.flags. */
217 enum {
218         /** Voltage measurement is alternating current (AC). */
219         SR_MQFLAG_AC = 0x01,
220         /** Voltage measurement is direct current (DC). */
221         SR_MQFLAG_DC = 0x02,
222         /** This is a true RMS measurement. */
223         SR_MQFLAG_RMS = 0x04,
224         /** Value is voltage drop across a diode, or NAN. */
225         SR_MQFLAG_DIODE = 0x08,
226         /** Device is in "hold" mode (repeating the last measurement). */
227         SR_MQFLAG_HOLD = 0x10,
228         /** Device is in "max" mode, only updating upon a new max value. */
229         SR_MQFLAG_MAX = 0x20,
230         /** Device is in "min" mode, only updating upon a new min value. */
231         SR_MQFLAG_MIN = 0x40,
232         /** Device is in autoranging mode. */
233         SR_MQFLAG_AUTORANGE = 0x80,
234         /** Device is in relative mode. */
235         SR_MQFLAG_RELATIVE = 0x100,
236         /** Sound pressure level is A-weighted in the frequency domain,
237          * according to IEC 61672:2003. */
238         SR_MQFLAG_SPL_FREQ_WEIGHT_A = 0x200,
239         /** Sound pressure level is C-weighted in the frequency domain,
240          * according to IEC 61672:2003. */
241         SR_MQFLAG_SPL_FREQ_WEIGHT_C = 0x400,
242         /** Sound pressure level is Z-weighted (i.e. not at all) in the
243          * frequency domain, according to IEC 61672:2003. */
244         SR_MQFLAG_SPL_FREQ_WEIGHT_Z = 0x800,
245         /** Sound pressure level is not weighted in the frequency domain,
246          * albeit without standards-defined low and high frequency limits. */
247         SR_MQFLAG_SPL_FREQ_WEIGHT_FLAT = 0x1000,
248         /** Sound pressure level measurement is S-weighted (1s) in the
249          * time domain. */
250         SR_MQFLAG_SPL_TIME_WEIGHT_S = 0x2000,
251         /** Sound pressure level measurement is F-weighted (125ms) in the
252          * time domain. */
253         SR_MQFLAG_SPL_TIME_WEIGHT_F = 0x4000,
254         /** Sound pressure level is time-averaged (LAT), also known as
255          * Equivalent Continuous A-weighted Sound Level (LEQ). */
256         SR_MQFLAG_SPL_LAT = 0x8000,
257         /** Sound pressure level represented as a percentage of measurements
258          * that were over a preset alarm level. */
259         SR_MQFLAG_SPL_PCT_OVER_ALARM = 0x10000,
260 };
261
262 struct sr_context;
263
264 struct sr_datafeed_packet {
265         uint16_t type;
266         void *payload;
267 };
268
269 struct sr_datafeed_header {
270         int feed_version;
271         struct timeval starttime;
272 };
273
274 struct sr_datafeed_meta_logic {
275         int num_probes;
276         uint64_t samplerate;
277 };
278
279 struct sr_datafeed_logic {
280         uint64_t length;
281         uint16_t unitsize;
282         void *data;
283 };
284
285 struct sr_datafeed_meta_analog {
286         int num_probes;
287 };
288
289 struct sr_datafeed_analog {
290         int num_samples;
291         /** Measured quantity (voltage, current, temperature, and so on). */
292         int mq;
293         /** Unit in which the MQ is measured. */
294         int unit;
295         /** Bitmap with extra information about the MQ. */
296         uint64_t mqflags;
297         /** The analog value. */
298         float *data;
299 };
300
301 struct sr_input {
302         struct sr_input_format *format;
303         GHashTable *param;
304         struct sr_dev_inst *sdi;
305         void *internal;
306 };
307
308 struct sr_input_format {
309         char *id;
310         char *description;
311         int (*format_match) (const char *filename);
312         int (*init) (struct sr_input *in);
313         int (*loadfile) (struct sr_input *in, const char *filename);
314 };
315
316 struct sr_output {
317         struct sr_output_format *format;
318         struct sr_dev_inst *sdi;
319         char *param;
320         void *internal;
321 };
322
323 struct sr_output_format {
324         char *id;
325         char *description;
326         int df_type;
327         int (*init) (struct sr_output *o);
328         int (*data) (struct sr_output *o, const uint8_t *data_in,
329                      uint64_t length_in, uint8_t **data_out,
330                      uint64_t *length_out);
331         int (*event) (struct sr_output *o, int event_type, uint8_t **data_out,
332                       uint64_t *length_out);
333         GString *(*recv) (struct sr_output *o, const struct sr_dev_inst *sdi,
334                         struct sr_datafeed_packet *packet);
335         int (*cleanup) (struct sr_output *o);
336 };
337
338 struct sr_datastore {
339         /** Size in bytes of the number of units stored in this datastore. */
340         int ds_unitsize;
341         unsigned int num_units; /* TODO: uint64_t */
342         GSList *chunklist;
343 };
344
345 /*
346  * This represents a generic device connected to the system.
347  * For device-specific information, ask the driver. The driver_index refers
348  * to the device index within that driver; it may be handling more than one
349  * device. All relevant driver calls take a dev_index parameter for this.
350  */
351 struct sr_dev {
352         /** Which driver handles this device. */
353         struct sr_dev_driver *driver;
354         /** A driver may handle multiple devices of the same type. */
355         int driver_index;
356         /** List of struct sr_probe pointers. */
357         GSList *probes;
358         /** Data acquired by this device, if any. */
359         struct sr_datastore *datastore;
360 };
361
362 enum {
363         SR_PROBE_LOGIC = 10000,
364         SR_PROBE_ANALOG,
365 };
366
367 struct sr_probe {
368         int index;
369         int type;
370         gboolean enabled;
371         char *name;
372         char *trigger;
373 };
374
375 struct sr_hwopt {
376         int hwopt;
377         const void *value;
378 };
379
380 /** Hardware driver options. */
381 enum {
382         /**
383          * Some drivers cannot detect the exact model they're talking to
384          * (may be phased out).
385          */
386         SR_HWOPT_MODEL = 10000,
387
388         /**
389          * Specification on how to connect to a device.
390          *
391          * In combination with SR_HWOPT_SERIALCOMM, this is a serial port in
392          * the form which makes sense to the OS (e.g., /dev/ttyS0).
393          * Otherwise this specifies a USB device, either in the form of
394          * @verbatim <bus>.<address> @endverbatim (decimal, e.g. 1.65) or
395          * @verbatim <vendorid>.<productid> @endverbatim
396          * (hexadecimal, e.g. 1d6b.0001).
397          */
398         SR_HWOPT_CONN,
399
400         /**
401          * Serial communication specification, in the form:
402          *
403          *   @verbatim <baudrate>/<databits><parity><stopbits> @endverbatim
404          *
405          * Example: 9600/8n1
406          *
407          * This is always an optional parameter, since a driver typically
408          * knows the speed at which the device wants to communicate.
409          */
410         SR_HWOPT_SERIALCOMM,
411 };
412
413 /** Hardware device capabilities. */
414 enum {
415         /*--- Device classes ------------------------------------------------*/
416
417         /** The device can act as logic analyzer. */
418         SR_HWCAP_LOGIC_ANALYZER = 10000,
419
420         /** The device can act as an oscilloscope. */
421         SR_HWCAP_OSCILLOSCOPE,
422
423         /** The device can act as a multimeter. */
424         SR_HWCAP_MULTIMETER,
425
426         /** The device is a demo device. */
427         SR_HWCAP_DEMO_DEV,
428
429         /** The device can act as a sound level meter. */
430         SR_HWCAP_SOUNDLEVELMETER,
431
432         /** The device can measure temperature. */
433         SR_HWCAP_THERMOMETER,
434
435         /** The device can measure humidity. */
436         SR_HWCAP_HYGROMETER,
437
438         /*--- Device configuration ------------------------------------------*/
439
440         /** The device supports setting/changing its samplerate. */
441         SR_HWCAP_SAMPLERATE = 20000,
442
443         /** The device supports setting a pre/post-trigger capture ratio. */
444         SR_HWCAP_CAPTURE_RATIO,
445
446         /* TODO? */
447         /** The device supports setting a pattern (pattern generator mode). */
448         SR_HWCAP_PATTERN_MODE,
449
450         /** The device supports Run Length Encoding. */
451         SR_HWCAP_RLE,
452
453         /** The device supports setting trigger slope. */
454         SR_HWCAP_TRIGGER_SLOPE,
455
456         /** Trigger source. */
457         SR_HWCAP_TRIGGER_SOURCE,
458
459         /** Horizontal trigger position. */
460         SR_HWCAP_HORIZ_TRIGGERPOS,
461
462         /** Buffer size. */
463         SR_HWCAP_BUFFERSIZE,
464
465         /** Time base. */
466         SR_HWCAP_TIMEBASE,
467
468         /** Filter. */
469         SR_HWCAP_FILTER,
470
471         /** Volts/div. */
472         SR_HWCAP_VDIV,
473
474         /** Coupling. */
475         SR_HWCAP_COUPLING,
476
477         /*--- Special stuff -------------------------------------------------*/
478
479         /** Session filename. */
480         SR_HWCAP_SESSIONFILE = 30000,
481
482         /* TODO: Better description. */
483         /** The device supports specifying a capturefile to inject. */
484         SR_HWCAP_CAPTUREFILE,
485
486         /* TODO: Better description. */
487         /** The device supports specifying the capturefile unit size. */
488         SR_HWCAP_CAPTURE_UNITSIZE,
489
490         /* TODO: Better description. */
491         /** The device supports setting the number of probes. */
492         SR_HWCAP_CAPTURE_NUM_PROBES,
493
494         /*--- Acquisition modes ---------------------------------------------*/
495
496         /**
497          * The device supports setting a sample time limit (how long
498          * the sample acquisition should run, in ms).
499          */
500         SR_HWCAP_LIMIT_MSEC = 40000,
501
502         /**
503          * The device supports setting a sample number limit (how many
504          * samples should be acquired).
505          */
506         SR_HWCAP_LIMIT_SAMPLES,
507
508         /**
509          * The device supports setting a frame limit (how many
510          * frames should be acquired).
511          */
512         SR_HWCAP_LIMIT_FRAMES,
513
514         /**
515          * The device supports continuous sampling. Neither a time limit
516          * nor a sample number limit has to be supplied, it will just acquire
517          * samples continuously, until explicitly stopped by a certain command.
518          */
519         SR_HWCAP_CONTINUOUS,
520 };
521
522 struct sr_hwcap_option {
523         int hwcap;
524         int type;
525         char *description;
526         char *shortname;
527 };
528
529 struct sr_dev_inst {
530         struct sr_dev_driver *driver;
531         int index;
532         int status;
533         int inst_type;
534         char *vendor;
535         char *model;
536         char *version;
537         GSList *probes;
538         void *priv;
539 };
540
541 /** Types of device instances (sr_dev_inst). */
542 enum {
543         /** Device instance type for USB devices. */
544         SR_INST_USB = 10000,
545         /** Device instance type for serial port devices. */
546         SR_INST_SERIAL,
547 };
548
549 /** Device instance status. */
550 enum {
551         /** The device instance was not found. */
552         SR_ST_NOT_FOUND = 10000,
553         /** The device instance was found, but is still booting. */
554         SR_ST_INITIALIZING,
555         /** The device instance is live, but not in use. */
556         SR_ST_INACTIVE,
557         /** The device instance is actively in use in a session. */
558         SR_ST_ACTIVE,
559         /** The device is winding down its session. */
560         SR_ST_STOPPING,
561 };
562
563 /*
564  * TODO: This sucks, you just kinda have to "know" the returned type.
565  * TODO: Need a DI to return the number of trigger stages supported.
566  */
567
568 /** Device info IDs. */
569 enum {
570         /** A list of options supported by the driver. */
571         SR_DI_HWOPTS = 10000,
572         /** A list of capabilities supported by the device. */
573         SR_DI_HWCAPS,
574         /** The number of probes connected to this device. */
575         SR_DI_NUM_PROBES,
576         /** The probe names on this device. */
577         SR_DI_PROBE_NAMES,
578         /** Samplerates supported by this device (struct sr_samplerates). */
579         SR_DI_SAMPLERATES,
580         /** Types of logic trigger supported, out of "01crf" (char *). */
581         SR_DI_TRIGGER_TYPES,
582         /** The currently set samplerate in Hz (uint64_t). */
583         SR_DI_CUR_SAMPLERATE,
584         /** Supported patterns (in pattern generator mode). */
585         SR_DI_PATTERNS,
586         /** Supported buffer sizes. */
587         SR_DI_BUFFERSIZES,
588         /** Supported time bases. */
589         SR_DI_TIMEBASES,
590         /** Supported trigger sources. */
591         SR_DI_TRIGGER_SOURCES,
592         /** Supported filter targets. */
593         SR_DI_FILTERS,
594         /** Valid volts/div values. */
595         SR_DI_VDIVS,
596         /** Coupling options. */
597         SR_DI_COUPLING,
598 };
599
600 /*
601  * A device supports either a range of samplerates with steps of a given
602  * granularity, or is limited to a set of defined samplerates. Use either
603  * step or list, but not both.
604  */
605 struct sr_samplerates {
606         uint64_t low;
607         uint64_t high;
608         uint64_t step;
609         const uint64_t *list;
610 };
611
612 struct sr_dev_driver {
613         /* Driver-specific */
614         char *name;
615         char *longname;
616         int api_version;
617         int (*init) (struct sr_context *sr_ctx);
618         int (*cleanup) (void);
619         GSList *(*scan) (GSList *options);
620         GSList *(*dev_list) (void);
621         int (*dev_clear) (void);
622
623         /* Device-specific */
624         int (*dev_open) (struct sr_dev_inst *sdi);
625         int (*dev_close) (struct sr_dev_inst *sdi);
626         int (*info_get) (int info_id, const void **data,
627                         const struct sr_dev_inst *sdi);
628         int (*dev_config_set) (const struct sr_dev_inst *sdi, int hwcap,
629                         const void *value);
630         int (*dev_acquisition_start) (const struct sr_dev_inst *sdi,
631                         void *cb_data);
632         int (*dev_acquisition_stop) (struct sr_dev_inst *sdi,
633                         void *cb_data);
634
635         /* Dynamic */
636         void *priv;
637 };
638
639 struct sr_session {
640         /** List of struct sr_dev pointers. */
641         GSList *devs;
642         /** List of sr_receive_data_callback_t items. */
643         GSList *datafeed_callbacks;
644         GTimeVal starttime;
645
646         unsigned int num_sources;
647
648         /*
649          * Both "sources" and "pollfds" are of the same size and contain pairs
650          * of descriptor and callback function. We can not embed the GPollFD
651          * into the source struct since we want to be able to pass the array
652          * of all poll descriptors to g_poll().
653          */
654         struct source *sources;
655         GPollFD *pollfds;
656         int source_timeout;
657 };
658
659 #include "proto.h"
660 #include "version.h"
661
662 #ifdef __cplusplus
663 }
664 #endif
665
666 #endif