libsigrok
0.3.0
sigrok hardware access and backend library
Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
libsigrok.h
Go to the documentation of this file.
1
/*
2
* This file is part of the libsigrok project.
3
*
4
* Copyright (C) 2013 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_LIBSIGROK_H
21
#define LIBSIGROK_LIBSIGROK_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
sr_error_code
{
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
SR_ERR_NA
= -6,
/**< Not applicable. */
74
SR_ERR_DEV_CLOSED
= -7,
/**< Device is closed, but must be open. */
75
SR_ERR_TIMEOUT
= -8,
/**< A timeout occurred. */
76
SR_ERR_CHANNEL_GROUP
= -9,
/**< A channel group must be specified. */
77
78
/*
79
* Note: When adding entries here, don't forget to also update the
80
* sr_strerror() and sr_strerror_name() functions in error.c.
81
*/
82
};
83
84
#define SR_MAX_CHANNELNAME_LEN 32
85
86
/* Handy little macros */
87
#define SR_HZ(n) (n)
88
#define SR_KHZ(n) ((n) * (uint64_t)(1000ULL))
89
#define SR_MHZ(n) ((n) * (uint64_t)(1000000ULL))
90
#define SR_GHZ(n) ((n) * (uint64_t)(1000000000ULL))
91
92
#define SR_HZ_TO_NS(n) ((uint64_t)(1000000000ULL) / (n))
93
94
/** libsigrok loglevels. */
95
enum
sr_loglevel
{
96
SR_LOG_NONE
= 0,
/**< Output no messages at all. */
97
SR_LOG_ERR
= 1,
/**< Output error messages. */
98
SR_LOG_WARN
= 2,
/**< Output warnings. */
99
SR_LOG_INFO
= 3,
/**< Output informational messages. */
100
SR_LOG_DBG
= 4,
/**< Output debug messages. */
101
SR_LOG_SPEW
= 5,
/**< Output very noisy debug messages. */
102
};
103
104
/*
105
* Use SR_API to mark public API symbols, and SR_PRIV for private symbols.
106
*
107
* Variables and functions marked 'static' are private already and don't
108
* need SR_PRIV. However, functions which are not static (because they need
109
* to be used in other libsigrok-internal files) but are also not meant to
110
* be part of the public libsigrok API, must use SR_PRIV.
111
*
112
* This uses the 'visibility' feature of gcc (requires gcc >= 4.0).
113
*
114
* This feature is not available on MinGW/Windows, as it is a feature of
115
* ELF files and MinGW/Windows uses PE files.
116
*
117
* Details: http://gcc.gnu.org/wiki/Visibility
118
*/
119
120
/* Marks public libsigrok API symbols. */
121
#ifndef _WIN32
122
#define SR_API __attribute__((visibility("default")))
123
#else
124
#define SR_API
125
#endif
126
127
/* Marks private, non-public libsigrok symbols (not part of the API). */
128
#ifndef _WIN32
129
#define SR_PRIV __attribute__((visibility("hidden")))
130
#else
131
#define SR_PRIV
132
#endif
133
134
/** Type definition for callback function for data reception. */
135
typedef
int (*
sr_receive_data_callback
)(
int
fd,
int
revents,
void
*cb_data);
136
137
/** Data types used by sr_config_info(). */
138
enum
sr_datatype
{
139
SR_T_UINT64
= 10000,
140
SR_T_STRING
,
141
SR_T_BOOL
,
142
SR_T_FLOAT
,
143
SR_T_RATIONAL_PERIOD
,
144
SR_T_RATIONAL_VOLT
,
145
SR_T_KEYVALUE
,
146
SR_T_UINT64_RANGE
,
147
SR_T_DOUBLE_RANGE
,
148
SR_T_INT32
,
149
};
150
151
/** Value for sr_datafeed_packet.type. */
152
enum
sr_packettype
{
153
/** Payload is sr_datafeed_header. */
154
SR_DF_HEADER
= 10000,
155
/** End of stream (no further data). */
156
SR_DF_END
,
157
/** Payload is struct sr_datafeed_meta */
158
SR_DF_META
,
159
/** The trigger matched at this point in the data feed. No payload. */
160
SR_DF_TRIGGER
,
161
/** Payload is struct sr_datafeed_logic. */
162
SR_DF_LOGIC
,
163
/** Payload is struct sr_datafeed_analog. */
164
SR_DF_ANALOG
,
165
/** Beginning of frame. No payload. */
166
SR_DF_FRAME_BEGIN
,
167
/** End of frame. No payload. */
168
SR_DF_FRAME_END
,
169
};
170
171
/** Measured quantity, sr_datafeed_analog.mq. */
172
enum
sr_mq
{
173
SR_MQ_VOLTAGE
= 10000,
174
SR_MQ_CURRENT
,
175
SR_MQ_RESISTANCE
,
176
SR_MQ_CAPACITANCE
,
177
SR_MQ_TEMPERATURE
,
178
SR_MQ_FREQUENCY
,
179
/** Duty cycle, e.g. on/off ratio. */
180
SR_MQ_DUTY_CYCLE
,
181
/** Continuity test. */
182
SR_MQ_CONTINUITY
,
183
SR_MQ_PULSE_WIDTH
,
184
SR_MQ_CONDUCTANCE
,
185
/** Electrical power, usually in W, or dBm. */
186
SR_MQ_POWER
,
187
/** Gain (a transistor's gain, or hFE, for example). */
188
SR_MQ_GAIN
,
189
/** Logarithmic representation of sound pressure relative to a
190
* reference value. */
191
SR_MQ_SOUND_PRESSURE_LEVEL
,
192
/** Carbon monoxide level */
193
SR_MQ_CARBON_MONOXIDE
,
194
/** Humidity */
195
SR_MQ_RELATIVE_HUMIDITY
,
196
/** Time */
197
SR_MQ_TIME
,
198
};
199
200
/** Unit of measured quantity, sr_datafeed_analog.unit. */
201
enum
sr_unit
{
202
/** Volt */
203
SR_UNIT_VOLT
= 10000,
204
/** Ampere (current). */
205
SR_UNIT_AMPERE
,
206
/** Ohm (resistance). */
207
SR_UNIT_OHM
,
208
/** Farad (capacity). */
209
SR_UNIT_FARAD
,
210
/** Kelvin (temperature). */
211
SR_UNIT_KELVIN
,
212
/** Degrees Celsius (temperature). */
213
SR_UNIT_CELSIUS
,
214
/** Degrees Fahrenheit (temperature). */
215
SR_UNIT_FAHRENHEIT
,
216
/** Hertz (frequency, 1/s, [Hz]). */
217
SR_UNIT_HERTZ
,
218
/** Percent value. */
219
SR_UNIT_PERCENTAGE
,
220
/** Boolean value. */
221
SR_UNIT_BOOLEAN
,
222
/** Time in seconds. */
223
SR_UNIT_SECOND
,
224
/** Unit of conductance, the inverse of resistance. */
225
SR_UNIT_SIEMENS
,
226
/**
227
* An absolute measurement of power, in decibels, referenced to
228
* 1 milliwatt (dBu).
229
*/
230
SR_UNIT_DECIBEL_MW
,
231
/** Voltage in decibel, referenced to 1 volt (dBV). */
232
SR_UNIT_DECIBEL_VOLT
,
233
/**
234
* Measurements that intrinsically do not have units attached, such
235
* as ratios, gains, etc. Specifically, a transistor's gain (hFE) is
236
* a unitless quantity, for example.
237
*/
238
SR_UNIT_UNITLESS
,
239
/** Sound pressure level relative so 20 micropascals. */
240
SR_UNIT_DECIBEL_SPL
,
241
/**
242
* Normalized (0 to 1) concentration of a substance or compound with 0
243
* representing a concentration of 0%, and 1 being 100%. This is
244
* represented as the fraction of number of particles of the substance.
245
*/
246
SR_UNIT_CONCENTRATION
,
247
/** Revolutions per minute. */
248
SR_UNIT_REVOLUTIONS_PER_MINUTE
,
249
/** Apparent power [VA]. */
250
SR_UNIT_VOLT_AMPERE
,
251
/** Real power [W]. */
252
SR_UNIT_WATT
,
253
/** Consumption [Wh]. */
254
SR_UNIT_WATT_HOUR
,
255
};
256
257
/** Values for sr_datafeed_analog.flags. */
258
enum
sr_mqflag
{
259
/** Voltage measurement is alternating current (AC). */
260
SR_MQFLAG_AC
= 0x01,
261
/** Voltage measurement is direct current (DC). */
262
SR_MQFLAG_DC
= 0x02,
263
/** This is a true RMS measurement. */
264
SR_MQFLAG_RMS
= 0x04,
265
/** Value is voltage drop across a diode, or NAN. */
266
SR_MQFLAG_DIODE
= 0x08,
267
/** Device is in "hold" mode (repeating the last measurement). */
268
SR_MQFLAG_HOLD
= 0x10,
269
/** Device is in "max" mode, only updating upon a new max value. */
270
SR_MQFLAG_MAX
= 0x20,
271
/** Device is in "min" mode, only updating upon a new min value. */
272
SR_MQFLAG_MIN
= 0x40,
273
/** Device is in autoranging mode. */
274
SR_MQFLAG_AUTORANGE
= 0x80,
275
/** Device is in relative mode. */
276
SR_MQFLAG_RELATIVE
= 0x100,
277
/** Sound pressure level is A-weighted in the frequency domain,
278
* according to IEC 61672:2003. */
279
SR_MQFLAG_SPL_FREQ_WEIGHT_A
= 0x200,
280
/** Sound pressure level is C-weighted in the frequency domain,
281
* according to IEC 61672:2003. */
282
SR_MQFLAG_SPL_FREQ_WEIGHT_C
= 0x400,
283
/** Sound pressure level is Z-weighted (i.e. not at all) in the
284
* frequency domain, according to IEC 61672:2003. */
285
SR_MQFLAG_SPL_FREQ_WEIGHT_Z
= 0x800,
286
/** Sound pressure level is not weighted in the frequency domain,
287
* albeit without standards-defined low and high frequency limits. */
288
SR_MQFLAG_SPL_FREQ_WEIGHT_FLAT
= 0x1000,
289
/** Sound pressure level measurement is S-weighted (1s) in the
290
* time domain. */
291
SR_MQFLAG_SPL_TIME_WEIGHT_S
= 0x2000,
292
/** Sound pressure level measurement is F-weighted (125ms) in the
293
* time domain. */
294
SR_MQFLAG_SPL_TIME_WEIGHT_F
= 0x4000,
295
/** Sound pressure level is time-averaged (LAT), also known as
296
* Equivalent Continuous A-weighted Sound Level (LEQ). */
297
SR_MQFLAG_SPL_LAT
= 0x8000,
298
/** Sound pressure level represented as a percentage of measurements
299
* that were over a preset alarm level. */
300
SR_MQFLAG_SPL_PCT_OVER_ALARM
= 0x10000,
301
/** Time is duration (as opposed to epoch, ...). */
302
SR_MQFLAG_DURATION
= 0x20000,
303
/** Device is in "avg" mode, averaging upon each new value. */
304
SR_MQFLAG_AVG
= 0x40000,
305
};
306
307
/**
308
* @struct sr_context
309
* Opaque structure representing a libsigrok context.
310
*
311
* None of the fields of this structure are meant to be accessed directly.
312
*
313
* @see sr_init(), sr_exit().
314
*/
315
struct
sr_context
;
316
317
/** Packet in a sigrok data feed. */
318
struct
sr_datafeed_packet
{
319
uint16_t
type
;
320
const
void
*
payload
;
321
};
322
323
/** Header of a sigrok data feed. */
324
struct
sr_datafeed_header
{
325
int
feed_version
;
326
struct
timeval
starttime
;
327
};
328
329
/** Datafeed payload for type SR_DF_META. */
330
struct
sr_datafeed_meta
{
331
GSList *
config
;
332
};
333
334
/** Logic datafeed payload for type SR_DF_LOGIC. */
335
struct
sr_datafeed_logic
{
336
uint64_t
length
;
337
uint16_t
unitsize
;
338
void
*
data
;
339
};
340
341
/** Analog datafeed payload for type SR_DF_ANALOG. */
342
struct
sr_datafeed_analog
{
343
/** The channels for which data is included in this packet. */
344
GSList *
channels
;
345
/** Number of samples in data */
346
int
num_samples
;
347
/** Measured quantity (voltage, current, temperature, and so on).
348
* Use SR_MQ_VOLTAGE, ... */
349
int
mq
;
350
/** Unit in which the MQ is measured. Use SR_UNIT_VOLT, ... */
351
int
unit
;
352
/** Bitmap with extra information about the MQ. Use SR_MQFLAG_AC, ... */
353
uint64_t
mqflags
;
354
/** The analog value(s). The data is interleaved according to
355
* the channels list. */
356
float
*
data
;
357
};
358
359
/** Input (file) format struct. */
360
struct
sr_input
{
361
/**
362
* A pointer to this input format's 'struct sr_input_format'.
363
* The frontend can use this to call the module's callbacks.
364
*/
365
struct
sr_input_format
*
format
;
366
367
GHashTable *
param
;
368
369
struct
sr_dev_inst
*
sdi
;
370
371
void
*
internal
;
372
};
373
374
/** Input (file) format driver. */
375
struct
sr_input_format
{
376
/** The unique ID for this input format. Must not be NULL. */
377
char
*
id
;
378
379
/**
380
* A short description of the input format, which can (for example)
381
* be displayed to the user by frontends. Must not be NULL.
382
*/
383
char
*
description
;
384
385
/**
386
* Check if this input module can load and parse the specified file.
387
*
388
* @param[in] filename The name (and path) of the file to check.
389
*
390
* @retval TRUE This module knows the format.
391
* @retval FALSE This module does not know the format.
392
*/
393
int (*
format_match
) (
const
char
*filename);
394
395
/**
396
* Initialize the input module.
397
*
398
* @param in A pointer to a valid 'struct sr_input' that the caller
399
* has to allocate and provide to this function. It is also
400
* the responsibility of the caller to free it later.
401
* @param[in] filename The name (and path) of the file to use.
402
*
403
* @retval SR_OK Success
404
* @retval other Negative error code.
405
*/
406
int (*
init
) (
struct
sr_input
*in,
const
char
*filename);
407
408
/**
409
* Load a file, parsing the input according to the file's format.
410
*
411
* This function will send datafeed packets to the session bus, so
412
* the calling frontend must have registered its session callbacks
413
* beforehand.
414
*
415
* The packet types sent across the session bus by this function must
416
* include at least SR_DF_HEADER, SR_DF_END, and an appropriate data
417
* type such as SR_DF_LOGIC. It may also send a SR_DF_TRIGGER packet
418
* if appropriate.
419
*
420
* @param in A pointer to a valid 'struct sr_input' that the caller
421
* has to allocate and provide to this function. It is also
422
* the responsibility of the caller to free it later.
423
* @param filename The name (and path) of the file to use.
424
*
425
* @retval SR_OK Success
426
* @retval other Negative error code.
427
*/
428
int (*
loadfile
) (
struct
sr_input
*in,
const
char
*filename);
429
};
430
431
/** Output (file) format struct. */
432
struct
sr_output
{
433
/** A pointer to this output's format. */
434
struct
sr_output_format
*
format
;
435
436
/**
437
* The device for which this output module is creating output. This
438
* can be used by the module to find out channel names and numbers.
439
*/
440
const
struct
sr_dev_inst
*
sdi
;
441
442
/**
443
* An optional parameter which the frontend can pass in to the
444
* output module. How the string is interpreted is entirely up to
445
* the module.
446
*/
447
GHashTable *
params
;
448
449
/**
450
* A generic pointer which can be used by the module to keep internal
451
* state between calls into its callback functions.
452
*
453
* For example, the module might store a pointer to a chunk of output
454
* there, and only flush it when it reaches a certain size.
455
*/
456
void
*
internal
;
457
};
458
459
/** Output (file) format driver. */
460
struct
sr_output_format
{
461
/**
462
* A unique ID for this output format. Must not be NULL.
463
*
464
* It can be used by frontends to select this output format for use.
465
*
466
* For example, calling sigrok-cli with <code>-O hex</code> will
467
* select the hexadecimal text output format.
468
*/
469
char
*
id
;
470
471
/**
472
* A short description of the output format. Must not be NULL.
473
*
474
* This can be displayed by frontends, e.g. when selecting the output
475
* format for saving a file.
476
*/
477
char
*
description
;
478
479
/**
480
* This function is called once, at the beginning of an output stream.
481
*
482
* The device struct will be available in the output struct passed in,
483
* as well as the param field -- which may be NULL or an empty string,
484
* if no parameter was passed.
485
*
486
* The module can use this to initialize itself, create a struct for
487
* keeping state and storing it in the <code>internal</code> field.
488
*
489
* @param o Pointer to the respective 'struct sr_output'.
490
*
491
* @retval SR_OK Success
492
* @retval other Negative error code.
493
*/
494
int (*
init
) (
struct
sr_output
*o);
495
496
/**
497
* This function is passed a copy of every packed in the data feed.
498
* Any output generated by the output module in response to the
499
* packet should be returned in a newly allocated GString
500
* <code>out</code>, which will be freed by the caller.
501
*
502
* Packets not of interest to the output module can just be ignored,
503
* and the <code>out</code> parameter set to NULL.
504
*
505
* @param o Pointer to the respective 'struct sr_output'.
506
* @param sdi The device instance that generated the packet.
507
* @param packet The complete packet.
508
* @param out A pointer where a GString * should be stored if
509
* the module generates output, or NULL if not.
510
*
511
* @retval SR_OK Success
512
* @retval other Negative error code.
513
*/
514
int (*
receive
) (
struct
sr_output
*o,
515
const
struct
sr_datafeed_packet
*packet, GString **out);
516
517
/**
518
* This function is called after the caller is finished using
519
* the output module, and can be used to free any internal
520
* resources the module may keep.
521
*
522
* @retval SR_OK Success
523
* @retval other Negative error code.
524
*/
525
int (*
cleanup
) (
struct
sr_output
*o);
526
};
527
528
/** Constants for channel type. */
529
enum
sr_channeltype
{
530
/** Channel type is logic channel. */
531
SR_CHANNEL_LOGIC
= 10000,
532
/** Channel type is analog channel. */
533
SR_CHANNEL_ANALOG
,
534
};
535
536
/** Information on single channel. */
537
struct
sr_channel
{
538
/** Number of channels, starting at 0. */
539
int
index
;
540
/** Channel type (SR_CHANNEL_LOGIC, ...) */
541
int
type
;
542
/** Is this channel enabled? */
543
gboolean
enabled
;
544
/** Name of channel. */
545
char
*
name
;
546
/** Trigger string, format like used by sigrok-cli */
547
char
*
trigger
;
548
};
549
550
/** Structure for groups of channels that have common properties. */
551
struct
sr_channel_group
{
552
/** Name of the channel group. */
553
char
*
name
;
554
/** List of sr_channel structs of the channels belonging to this group. */
555
GSList *
channels
;
556
/** Private data for driver use. */
557
void
*
priv
;
558
};
559
560
/** Used for setting or getting value of a config item. */
561
struct
sr_config
{
562
/** Config key like SR_CONF_CONN, etc. */
563
int
key
;
564
/** Key-specific data. */
565
GVariant *
data
;
566
};
567
568
/** Information about a config key. */
569
struct
sr_config_info
{
570
/** Config key like SR_CONF_CONN, etc. */
571
int
key
;
572
/** Data type like SR_T_STRING, etc. */
573
int
datatype
;
574
/** Id string, e.g. "serialcomm". */
575
char
*
id
;
576
/** Name, e.g. "Serial communication". */
577
char
*
name
;
578
/** Verbose description (unused currently). */
579
char
*
description
;
580
};
581
582
/** Constants for device classes */
583
enum
sr_configkey
{
584
/*--- Device classes ------------------------------------------------*/
585
586
/** The device can act as logic analyzer. */
587
SR_CONF_LOGIC_ANALYZER
= 10000,
588
589
/** The device can act as an oscilloscope. */
590
SR_CONF_OSCILLOSCOPE
,
591
592
/** The device can act as a multimeter. */
593
SR_CONF_MULTIMETER
,
594
595
/** The device is a demo device. */
596
SR_CONF_DEMO_DEV
,
597
598
/** The device can act as a sound level meter. */
599
SR_CONF_SOUNDLEVELMETER
,
600
601
/** The device can measure temperature. */
602
SR_CONF_THERMOMETER
,
603
604
/** The device can measure humidity. */
605
SR_CONF_HYGROMETER
,
606
607
/** The device can measure energy consumption. */
608
SR_CONF_ENERGYMETER
,
609
610
/** The device can demodulate signals. */
611
SR_CONF_DEMODULATOR
,
612
613
/** Programmable power supply. */
614
SR_CONF_POWER_SUPPLY
,
615
616
/*--- Driver scan options -------------------------------------------*/
617
618
/**
619
* Specification on how to connect to a device.
620
*
621
* In combination with SR_CONF_SERIALCOMM, this is a serial port in
622
* the form which makes sense to the OS (e.g., /dev/ttyS0).
623
* Otherwise this specifies a USB device, either in the form of
624
* @verbatim <bus>.<address> @endverbatim (decimal, e.g. 1.65) or
625
* @verbatim <vendorid>.<productid> @endverbatim
626
* (hexadecimal, e.g. 1d6b.0001).
627
*/
628
SR_CONF_CONN
= 20000,
629
630
/**
631
* Serial communication specification, in the form:
632
*
633
* @verbatim <baudrate>/<databits><parity><stopbits> @endverbatim
634
*
635
* Example: 9600/8n1
636
*
637
* The string may also be followed by one or more special settings,
638
* in the form "/key=value". Supported keys and their values are:
639
*
640
* rts 0,1 set the port's RTS pin to low or high
641
* dtr 0,1 set the port's DTR pin to low or high
642
* flow 0 no flow control
643
* 1 hardware-based (RTS/CTS) flow control
644
* 2 software-based (XON/XOFF) flow control
645
*
646
* This is always an optional parameter, since a driver typically
647
* knows the speed at which the device wants to communicate.
648
*/
649
SR_CONF_SERIALCOMM
,
650
651
/*--- Device configuration ------------------------------------------*/
652
653
/** The device supports setting its samplerate, in Hz. */
654
SR_CONF_SAMPLERATE
= 30000,
655
656
/** The device supports setting a pre/post-trigger capture ratio. */
657
SR_CONF_CAPTURE_RATIO
,
658
659
/** The device supports setting a pattern (pattern generator mode). */
660
SR_CONF_PATTERN_MODE
,
661
662
/** The device supports Run Length Encoding. */
663
SR_CONF_RLE
,
664
665
/** The device supports setting trigger slope. */
666
SR_CONF_TRIGGER_SLOPE
,
667
668
/** Trigger source. */
669
SR_CONF_TRIGGER_SOURCE
,
670
671
/** Horizontal trigger position. */
672
SR_CONF_HORIZ_TRIGGERPOS
,
673
674
/** Buffer size. */
675
SR_CONF_BUFFERSIZE
,
676
677
/** Time base. */
678
SR_CONF_TIMEBASE
,
679
680
/** Filter. */
681
SR_CONF_FILTER
,
682
683
/** Volts/div. */
684
SR_CONF_VDIV
,
685
686
/** Coupling. */
687
SR_CONF_COUPLING
,
688
689
/** Trigger types. */
690
SR_CONF_TRIGGER_TYPE
,
691
692
/** The device supports setting its sample interval, in ms. */
693
SR_CONF_SAMPLE_INTERVAL
,
694
695
/** Number of timebases, as related to SR_CONF_TIMEBASE. */
696
SR_CONF_NUM_TIMEBASE
,
697
698
/** Number of vertical divisions, as related to SR_CONF_VDIV. */
699
SR_CONF_NUM_VDIV
,
700
701
/** Sound pressure level frequency weighting. */
702
SR_CONF_SPL_WEIGHT_FREQ
,
703
704
/** Sound pressure level time weighting. */
705
SR_CONF_SPL_WEIGHT_TIME
,
706
707
/** Sound pressure level measurement range. */
708
SR_CONF_SPL_MEASUREMENT_RANGE
,
709
710
/** Max hold mode. */
711
SR_CONF_HOLD_MAX
,
712
713
/** Min hold mode. */
714
SR_CONF_HOLD_MIN
,
715
716
/** Logic low-high threshold range. */
717
SR_CONF_VOLTAGE_THRESHOLD
,
718
719
/** The device supports using an external clock. */
720
SR_CONF_EXTERNAL_CLOCK
,
721
722
/**
723
* The device supports swapping channels. Typical this is between
724
* buffered and unbuffered channels.
725
*/
726
SR_CONF_SWAP
,
727
728
/** Center frequency.
729
* The input signal is downmixed by this frequency before the ADC
730
* anti-aliasing filter.
731
*/
732
SR_CONF_CENTER_FREQUENCY
,
733
734
/** The device supports setting the number of logic channels. */
735
SR_CONF_NUM_LOGIC_CHANNELS
,
736
737
/** The device supports setting the number of analog channels. */
738
SR_CONF_NUM_ANALOG_CHANNELS
,
739
740
/** Output voltage. */
741
SR_CONF_OUTPUT_VOLTAGE
,
742
743
/** Maximum output voltage. */
744
SR_CONF_OUTPUT_VOLTAGE_MAX
,
745
746
/** Output current. */
747
SR_CONF_OUTPUT_CURRENT
,
748
749
/** Maximum output current. */
750
SR_CONF_OUTPUT_CURRENT_MAX
,
751
752
/** Enabling/disabling output. */
753
SR_CONF_OUTPUT_ENABLED
,
754
755
/** Channel output configuration. */
756
SR_CONF_OUTPUT_CHANNEL
,
757
758
/** Over-voltage protection (OVP) */
759
SR_CONF_OVER_VOLTAGE_PROTECTION
,
760
761
/** Over-current protection (OCP) */
762
SR_CONF_OVER_CURRENT_PROTECTION
,
763
764
/** Choice of clock edge for external clock ("r" or "f"). */
765
SR_CONF_CLOCK_EDGE
,
766
767
/*--- Special stuff -------------------------------------------------*/
768
769
/** Scan options supported by the driver. */
770
SR_CONF_SCAN_OPTIONS
= 40000,
771
772
/** Device options for a particular device. */
773
SR_CONF_DEVICE_OPTIONS
,
774
775
/** Session filename. */
776
SR_CONF_SESSIONFILE
,
777
778
/** The device supports specifying a capturefile to inject. */
779
SR_CONF_CAPTUREFILE
,
780
781
/** The device supports specifying the capturefile unit size. */
782
SR_CONF_CAPTURE_UNITSIZE
,
783
784
/** Power off the device. */
785
SR_CONF_POWER_OFF
,
786
787
/**
788
* Data source for acquisition. If not present, acquisition from
789
* the device is always "live", i.e. acquisition starts when the
790
* frontend asks and the results are sent out as soon as possible.
791
*
792
* If present, it indicates that either the device has no live
793
* acquisition capability (for example a pure data logger), or
794
* there is a choice. sr_config_list() returns those choices.
795
*
796
* In any case if a device has live acquisition capabilities, it
797
* is always the default.
798
*/
799
SR_CONF_DATA_SOURCE
,
800
801
/*--- Acquisition modes ---------------------------------------------*/
802
803
/**
804
* The device supports setting a sample time limit (how long
805
* the sample acquisition should run, in ms).
806
*/
807
SR_CONF_LIMIT_MSEC
= 50000,
808
809
/**
810
* The device supports setting a sample number limit (how many
811
* samples should be acquired).
812
*/
813
SR_CONF_LIMIT_SAMPLES
,
814
815
/**
816
* The device supports setting a frame limit (how many
817
* frames should be acquired).
818
*/
819
SR_CONF_LIMIT_FRAMES
,
820
821
/**
822
* The device supports continuous sampling. Neither a time limit
823
* nor a sample number limit has to be supplied, it will just acquire
824
* samples continuously, until explicitly stopped by a certain command.
825
*/
826
SR_CONF_CONTINUOUS
,
827
828
/** The device has internal storage, into which data is logged. This
829
* starts or stops the internal logging. */
830
SR_CONF_DATALOG
,
831
832
/** Device mode for multi-function devices. */
833
SR_CONF_DEVICE_MODE
,
834
835
/** Self test mode. */
836
SR_CONF_TEST_MODE
,
837
};
838
839
/** Device instance data
840
*/
841
struct
sr_dev_inst
{
842
/** Device driver. */
843
struct
sr_dev_driver
*
driver
;
844
/** Index of device in driver. */
845
int
index
;
846
/** Device instance status. SR_ST_NOT_FOUND, etc. */
847
int
status
;
848
/** Device instance type. SR_INST_USB, etc. */
849
int
inst_type
;
850
/** Device vendor. */
851
char
*
vendor
;
852
/** Device model. */
853
char
*
model
;
854
/** Device version. */
855
char
*
version
;
856
/** List of channels. */
857
GSList *
channels
;
858
/** List of sr_channel_group structs */
859
GSList *
channel_groups
;
860
/** Device instance connection data (used?) */
861
void
*
conn
;
862
/** Device instance private data (used?) */
863
void
*
priv
;
864
};
865
866
/** Types of device instance, struct sr_dev_inst.type */
867
enum
sr_dev_inst_type
{
868
/** Device instance type for USB devices. */
869
SR_INST_USB
= 10000,
870
/** Device instance type for serial port devices. */
871
SR_INST_SERIAL
,
872
/** Device instance type for SCPI devices. */
873
SR_INST_SCPI
,
874
};
875
876
/** Device instance status, struct sr_dev_inst.status */
877
enum
sr_dev_inst_status
{
878
/** The device instance was not found. */
879
SR_ST_NOT_FOUND
= 10000,
880
/** The device instance was found, but is still booting. */
881
SR_ST_INITIALIZING
,
882
/** The device instance is live, but not in use. */
883
SR_ST_INACTIVE
,
884
/** The device instance is actively in use in a session. */
885
SR_ST_ACTIVE
,
886
/** The device is winding down its session. */
887
SR_ST_STOPPING
,
888
};
889
890
/** Device driver data. See also http://sigrok.org/wiki/Hardware_driver_API . */
891
struct
sr_dev_driver
{
892
/* Driver-specific */
893
/** Driver name. Lowercase a-z, 0-9 and dashes (-) only. */
894
char
*
name
;
895
/** Long name. Verbose driver name shown to user. */
896
char
*
longname
;
897
/** API version (currently 1). */
898
int
api_version
;
899
/** Called when driver is loaded, e.g. program startup. */
900
int (*
init
) (
struct
sr_context
*sr_ctx);
901
/** Called before driver is unloaded.
902
* Driver must free all resouces held by it. */
903
int (*
cleanup
) (void);
904
/** Scan for devices. Driver should do all initialisation required.
905
* Can be called several times, e.g. with different port options.
906
* \retval NULL Error or no devices found.
907
* \retval other GSList of a struct sr_dev_inst for each device.
908
* Must be freed by caller!
909
*/
910
GSList *(*scan) (GSList *options);
911
/** Get list of device instances the driver knows about.
912
* \returns NULL or GSList of a struct sr_dev_inst for each device.
913
* Must not be freed by caller!
914
*/
915
GSList *(*dev_list) (void);
916
/** Clear list of devices the driver knows about. */
917
int (*
dev_clear
) (void);
918
/** Query value of a configuration key in driver or given device instance.
919
* @see sr_config_get().
920
*/
921
int (*
config_get
) (
int
id, GVariant **data,
922
const
struct
sr_dev_inst
*sdi,
923
const
struct
sr_channel_group
*cg);
924
/** Set value of a configuration key in driver or a given device instance.
925
* @see sr_config_set(). */
926
int (*
config_set
) (
int
id, GVariant *data,
927
const
struct
sr_dev_inst
*sdi,
928
const
struct
sr_channel_group
*cg);
929
/** Channel status change.
930
* @see sr_dev_channel_enable(), sr_dev_trigger_set(). */
931
int (*
config_channel_set
) (
const
struct
sr_dev_inst
*sdi,
932
struct
sr_channel
*ch,
unsigned
int
changes);
933
/** Apply configuration settings to the device hardware.
934
* @see sr_config_commit().*/
935
int (*
config_commit
) (
const
struct
sr_dev_inst
*sdi);
936
/** List all possible values for a configuration key in a device instance.
937
* @see sr_config_list().
938
*/
939
int (*
config_list
) (
int
info_id, GVariant **data,
940
const
struct
sr_dev_inst
*sdi,
941
const
struct
sr_channel_group
*cg);
942
943
/* Device-specific */
944
/** Open device */
945
int (*
dev_open
) (
struct
sr_dev_inst
*sdi);
946
/** Close device */
947
int (*
dev_close
) (
struct
sr_dev_inst
*sdi);
948
/** Begin data acquisition on the specified device. */
949
int (*
dev_acquisition_start
) (
const
struct
sr_dev_inst
*sdi,
950
void
*cb_data);
951
/** End data acquisition on the specified device. */
952
int (*
dev_acquisition_stop
) (
struct
sr_dev_inst
*sdi,
953
void
*cb_data);
954
955
/* Dynamic */
956
/** Device driver private data. Initialized by init(). */
957
void
*
priv
;
958
};
959
960
/**
961
* @struct sr_session
962
*
963
* Opaque data structure representing a libsigrok session. None of the fields
964
* of this structure are meant to be accessed directly.
965
*/
966
struct
sr_session
;
967
968
#include "
proto.h
"
969
#include "
version.h
"
970
971
#ifdef __cplusplus
972
}
973
#endif
974
975
#endif
Generated on Sat Sep 20 2014 08:10:15 for libsigrok by
1.8.3.1