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 SR_ERR_DATA =-10, /**< Data is invalid. */ 78 SR_ERR_IO =-11, /**< Input/output error. */ 79 80 /* Update sr_strerror()/sr_strerror_name() (error.c) upon changes! */ 81 }; 82 83 #define SR_MAX_CHANNELNAME_LEN 32 84 85 /* Handy little macros */ 86 #define SR_HZ(n) (n) 87 #define SR_KHZ(n) ((n) * UINT64_C(1000)) 88 #define SR_MHZ(n) ((n) * UINT64_C(1000000)) 89 #define SR_GHZ(n) ((n) * UINT64_C(1000000000)) 90 91 #define SR_HZ_TO_NS(n) (UINT64_C(1000000000) / (n)) 92 93 /** libsigrok loglevels. */ 94 enum sr_loglevel { 95 SR_LOG_NONE = 0, /**< Output no messages at all. */ 96 SR_LOG_ERR = 1, /**< Output error messages. */ 97 SR_LOG_WARN = 2, /**< Output warnings. */ 98 SR_LOG_INFO = 3, /**< Output informational messages. */ 99 SR_LOG_DBG = 4, /**< Output debug messages. */ 100 SR_LOG_SPEW = 5, /**< Output very noisy debug messages. */ 101 }; 102 103 /* 104 * Use SR_API to mark public API symbols, and SR_PRIV for private symbols. 105 * 106 * Variables and functions marked 'static' are private already and don't 107 * need SR_PRIV. However, functions which are not static (because they need 108 * to be used in other libsigrok-internal files) but are also not meant to 109 * be part of the public libsigrok API, must use SR_PRIV. 110 * 111 * This uses the 'visibility' feature of gcc (requires gcc >= 4.0). 112 * 113 * This feature is not available on MinGW/Windows, as it is a feature of 114 * ELF files and MinGW/Windows uses PE files. 115 * 116 * Details: http://gcc.gnu.org/wiki/Visibility 117 */ 118 119 /* Marks public libsigrok API symbols. */ 120 #ifndef _WIN32 121 #define SR_API __attribute__((visibility("default"))) 122 #else 123 #define SR_API 124 #endif 125 126 /* Marks private, non-public libsigrok symbols (not part of the API). */ 127 #ifndef _WIN32 128 #define SR_PRIV __attribute__((visibility("hidden"))) 129 #else 130 #define SR_PRIV 131 #endif 132 133 /** Type definition for callback function for data reception. */ 134 typedef int (*sr_receive_data_callback)(int fd, int revents, void *cb_data); 135 136 /** Data types used by sr_config_info(). */ 137 enum sr_datatype { 138 SR_T_UINT64 = 10000, 139 SR_T_STRING, 140 SR_T_BOOL, 141 SR_T_FLOAT, 142 SR_T_RATIONAL_PERIOD, 143 SR_T_RATIONAL_VOLT, 144 SR_T_KEYVALUE, 145 SR_T_UINT64_RANGE, 146 SR_T_DOUBLE_RANGE, 147 SR_T_INT32, 148 SR_T_MQ, 149 150 /* Update sr_variant_type_get() (hwdriver.c) upon changes! */ 151 }; 152 153 /** Value for sr_datafeed_packet.type. */ 154 enum sr_packettype { 155 /** Payload is sr_datafeed_header. */ 156 SR_DF_HEADER = 10000, 157 /** End of stream (no further data). */ 158 SR_DF_END, 159 /** Payload is struct sr_datafeed_meta */ 160 SR_DF_META, 161 /** The trigger matched at this point in the data feed. No payload. */ 162 SR_DF_TRIGGER, 163 /** Payload is struct sr_datafeed_logic. */ 164 SR_DF_LOGIC, 165 /** Beginning of frame. No payload. */ 166 SR_DF_FRAME_BEGIN, 167 /** End of frame. No payload. */ 168 SR_DF_FRAME_END, 169 /** Payload is struct sr_datafeed_analog. */ 170 SR_DF_ANALOG, 171 172 /* Update datafeed_dump() (session.c) upon changes! */ 173 }; 174 175 /** Measured quantity, sr_analog_meaning.mq. */ 176 enum sr_mq { 177 SR_MQ_VOLTAGE = 10000, 178 SR_MQ_CURRENT, 179 SR_MQ_RESISTANCE, 180 SR_MQ_CAPACITANCE, 181 SR_MQ_TEMPERATURE, 182 SR_MQ_FREQUENCY, 183 /** Duty cycle, e.g. on/off ratio. */ 184 SR_MQ_DUTY_CYCLE, 185 /** Continuity test. */ 186 SR_MQ_CONTINUITY, 187 SR_MQ_PULSE_WIDTH, 188 SR_MQ_CONDUCTANCE, 189 /** Electrical power, usually in W, or dBm. */ 190 SR_MQ_POWER, 191 /** Gain (a transistor's gain, or hFE, for example). */ 192 SR_MQ_GAIN, 193 /** Logarithmic representation of sound pressure relative to a 194 * reference value. */ 195 SR_MQ_SOUND_PRESSURE_LEVEL, 196 /** Carbon monoxide level */ 197 SR_MQ_CARBON_MONOXIDE, 198 /** Humidity */ 199 SR_MQ_RELATIVE_HUMIDITY, 200 /** Time */ 201 SR_MQ_TIME, 202 /** Wind speed */ 203 SR_MQ_WIND_SPEED, 204 /** Pressure */ 205 SR_MQ_PRESSURE, 206 /** Parallel inductance (LCR meter model). */ 207 SR_MQ_PARALLEL_INDUCTANCE, 208 /** Parallel capacitance (LCR meter model). */ 209 SR_MQ_PARALLEL_CAPACITANCE, 210 /** Parallel resistance (LCR meter model). */ 211 SR_MQ_PARALLEL_RESISTANCE, 212 /** Series inductance (LCR meter model). */ 213 SR_MQ_SERIES_INDUCTANCE, 214 /** Series capacitance (LCR meter model). */ 215 SR_MQ_SERIES_CAPACITANCE, 216 /** Series resistance (LCR meter model). */ 217 SR_MQ_SERIES_RESISTANCE, 218 /** Dissipation factor. */ 219 SR_MQ_DISSIPATION_FACTOR, 220 /** Quality factor. */ 221 SR_MQ_QUALITY_FACTOR, 222 /** Phase angle. */ 223 SR_MQ_PHASE_ANGLE, 224 /** Difference from reference value. */ 225 SR_MQ_DIFFERENCE, 226 /** Count. */ 227 SR_MQ_COUNT, 228 /** Power factor. */ 229 SR_MQ_POWER_FACTOR, 230 /** Apparent power */ 231 SR_MQ_APPARENT_POWER, 232 /** Mass */ 233 SR_MQ_MASS, 234 /** Harmonic ratio */ 235 SR_MQ_HARMONIC_RATIO, 236 237 /* Update sr_key_info_mq[] (hwdriver.c) upon changes! */ 238 }; 239 240 /** Unit of measured quantity, sr_analog_meaning.unit. */ 241 enum sr_unit { 242 /** Volt */ 243 SR_UNIT_VOLT = 10000, 244 /** Ampere (current). */ 245 SR_UNIT_AMPERE, 246 /** Ohm (resistance). */ 247 SR_UNIT_OHM, 248 /** Farad (capacity). */ 249 SR_UNIT_FARAD, 250 /** Kelvin (temperature). */ 251 SR_UNIT_KELVIN, 252 /** Degrees Celsius (temperature). */ 253 SR_UNIT_CELSIUS, 254 /** Degrees Fahrenheit (temperature). */ 255 SR_UNIT_FAHRENHEIT, 256 /** Hertz (frequency, 1/s, [Hz]). */ 257 SR_UNIT_HERTZ, 258 /** Percent value. */ 259 SR_UNIT_PERCENTAGE, 260 /** Boolean value. */ 261 SR_UNIT_BOOLEAN, 262 /** Time in seconds. */ 263 SR_UNIT_SECOND, 264 /** Unit of conductance, the inverse of resistance. */ 265 SR_UNIT_SIEMENS, 266 /** 267 * An absolute measurement of power, in decibels, referenced to 268 * 1 milliwatt (dBm). 269 */ 270 SR_UNIT_DECIBEL_MW, 271 /** Voltage in decibel, referenced to 1 volt (dBV). */ 272 SR_UNIT_DECIBEL_VOLT, 273 /** 274 * Measurements that intrinsically do not have units attached, such 275 * as ratios, gains, etc. Specifically, a transistor's gain (hFE) is 276 * a unitless quantity, for example. 277 */ 278 SR_UNIT_UNITLESS, 279 /** Sound pressure level, in decibels, relative to 20 micropascals. */ 280 SR_UNIT_DECIBEL_SPL, 281 /** 282 * Normalized (0 to 1) concentration of a substance or compound with 0 283 * representing a concentration of 0%, and 1 being 100%. This is 284 * represented as the fraction of number of particles of the substance. 285 */ 286 SR_UNIT_CONCENTRATION, 287 /** Revolutions per minute. */ 288 SR_UNIT_REVOLUTIONS_PER_MINUTE, 289 /** Apparent power [VA]. */ 290 SR_UNIT_VOLT_AMPERE, 291 /** Real power [W]. */ 292 SR_UNIT_WATT, 293 /** Consumption [Wh]. */ 294 SR_UNIT_WATT_HOUR, 295 /** Wind speed in meters per second. */ 296 SR_UNIT_METER_SECOND, 297 /** Pressure in hectopascal */ 298 SR_UNIT_HECTOPASCAL, 299 /** Relative humidity assuming air temperature of 293 Kelvin (%rF). */ 300 SR_UNIT_HUMIDITY_293K, 301 /** Plane angle in 1/360th of a full circle. */ 302 SR_UNIT_DEGREE, 303 /** Henry (inductance). */ 304 SR_UNIT_HENRY, 305 /** Mass in gram [g]. */ 306 SR_UNIT_GRAM, 307 /** Mass in carat [ct]. */ 308 SR_UNIT_CARAT, 309 /** Mass in ounce [oz]. */ 310 SR_UNIT_OUNCE, 311 /** Mass in troy ounce [oz t]. */ 312 SR_UNIT_TROY_OUNCE, 313 /** Mass in pound [lb]. */ 314 SR_UNIT_POUND, 315 /** Mass in pennyweight [dwt]. */ 316 SR_UNIT_PENNYWEIGHT, 317 /** Mass in grain [gr]. */ 318 SR_UNIT_GRAIN, 319 /** Mass in tael (variants: Hong Kong, Singapore/Malaysia, Taiwan) */ 320 SR_UNIT_TAEL, 321 /** Mass in momme. */ 322 SR_UNIT_MOMME, 323 /** Mass in tola. */ 324 SR_UNIT_TOLA, 325 /** Pieces (number of items). */ 326 SR_UNIT_PIECE, 327 328 /* 329 * Update unit_strings[] (analog.c) and fancyprint() (output/analog.c) 330 * upon changes! 331 */ 332 }; 333 334 /** Values for sr_analog_meaning.mqflags. */ 335 enum sr_mqflag { 336 /** Voltage measurement is alternating current (AC). */ 337 SR_MQFLAG_AC = 0x01, 338 /** Voltage measurement is direct current (DC). */ 339 SR_MQFLAG_DC = 0x02, 340 /** This is a true RMS measurement. */ 341 SR_MQFLAG_RMS = 0x04, 342 /** Value is voltage drop across a diode, or NAN. */ 343 SR_MQFLAG_DIODE = 0x08, 344 /** Device is in "hold" mode (repeating the last measurement). */ 345 SR_MQFLAG_HOLD = 0x10, 346 /** Device is in "max" mode, only updating upon a new max value. */ 347 SR_MQFLAG_MAX = 0x20, 348 /** Device is in "min" mode, only updating upon a new min value. */ 349 SR_MQFLAG_MIN = 0x40, 350 /** Device is in autoranging mode. */ 351 SR_MQFLAG_AUTORANGE = 0x80, 352 /** Device is in relative mode. */ 353 SR_MQFLAG_RELATIVE = 0x100, 354 /** Sound pressure level is A-weighted in the frequency domain, 355 * according to IEC 61672:2003. */ 356 SR_MQFLAG_SPL_FREQ_WEIGHT_A = 0x200, 357 /** Sound pressure level is C-weighted in the frequency domain, 358 * according to IEC 61672:2003. */ 359 SR_MQFLAG_SPL_FREQ_WEIGHT_C = 0x400, 360 /** Sound pressure level is Z-weighted (i.e. not at all) in the 361 * frequency domain, according to IEC 61672:2003. */ 362 SR_MQFLAG_SPL_FREQ_WEIGHT_Z = 0x800, 363 /** Sound pressure level is not weighted in the frequency domain, 364 * albeit without standards-defined low and high frequency limits. */ 365 SR_MQFLAG_SPL_FREQ_WEIGHT_FLAT = 0x1000, 366 /** Sound pressure level measurement is S-weighted (1s) in the 367 * time domain. */ 368 SR_MQFLAG_SPL_TIME_WEIGHT_S = 0x2000, 369 /** Sound pressure level measurement is F-weighted (125ms) in the 370 * time domain. */ 371 SR_MQFLAG_SPL_TIME_WEIGHT_F = 0x4000, 372 /** Sound pressure level is time-averaged (LAT), also known as 373 * Equivalent Continuous A-weighted Sound Level (LEQ). */ 374 SR_MQFLAG_SPL_LAT = 0x8000, 375 /** Sound pressure level represented as a percentage of measurements 376 * that were over a preset alarm level. */ 377 SR_MQFLAG_SPL_PCT_OVER_ALARM = 0x10000, 378 /** Time is duration (as opposed to epoch, ...). */ 379 SR_MQFLAG_DURATION = 0x20000, 380 /** Device is in "avg" mode, averaging upon each new value. */ 381 SR_MQFLAG_AVG = 0x40000, 382 /** Reference value shown. */ 383 SR_MQFLAG_REFERENCE = 0x80000, 384 /** Unstable value (hasn't settled yet). */ 385 SR_MQFLAG_UNSTABLE = 0x100000, 386 /** Measurement is four wire (e.g. Kelvin connection). */ 387 SR_MQFLAG_FOUR_WIRE = 0x200000, 388 389 /* 390 * Update mq_strings[] (analog.c) and fancyprint() (output/analog.c) 391 * upon changes! 392 */ 393 }; 394 395 enum sr_trigger_matches { 396 SR_TRIGGER_ZERO = 1, 397 SR_TRIGGER_ONE, 398 SR_TRIGGER_RISING, 399 SR_TRIGGER_FALLING, 400 SR_TRIGGER_EDGE, 401 SR_TRIGGER_OVER, 402 SR_TRIGGER_UNDER, 403 }; 404 405 /** The representation of a trigger, consisting of one or more stages 406 * containing one or more matches on a channel. 407 */ 408 struct sr_trigger { 409 /** A name for this trigger. This may be NULL if none is needed. */ 410 char *name; 411 /** List of pointers to struct sr_trigger_stage. */ 412 GSList *stages; 413 }; 414 415 /** A trigger stage. */ 416 struct sr_trigger_stage { 417 /** Starts at 0. */ 418 int stage; 419 /** List of pointers to struct sr_trigger_match. */ 420 GSList *matches; 421 }; 422 423 /** A channel to match and what to match it on. */ 424 struct sr_trigger_match { 425 /** The channel to trigger on. */ 426 struct sr_channel *channel; 427 /** The trigger match to use. 428 * For logic channels, only the following matches may be used: 429 * SR_TRIGGER_ZERO 430 * SR_TRIGGER_ONE 431 * SR_TRIGGER_RISING 432 * SR_TRIGGER_FALLING 433 * SR_TRIGGER_EDGE 434 * 435 * For analog channels, only these matches may be used: 436 * SR_TRIGGER_RISING 437 * SR_TRIGGER_FALLING 438 * SR_TRIGGER_OVER 439 * SR_TRIGGER_UNDER 440 * 441 */ 442 int match; 443 /** If the trigger match is one of SR_TRIGGER_OVER or SR_TRIGGER_UNDER, 444 * this contains the value to compare against. */ 445 float value; 446 }; 447 448 /** 449 * @struct sr_context 450 * Opaque structure representing a libsigrok context. 451 * 452 * None of the fields of this structure are meant to be accessed directly. 453 * 454 * @see sr_init(), sr_exit(). 455 */ 456 struct sr_context; 457 458 /** 459 * @struct sr_session 460 * Opaque structure representing a libsigrok session. 461 * 462 * None of the fields of this structure are meant to be accessed directly. 463 * 464 * @see sr_session_new(), sr_session_destroy(). 465 */ 466 struct sr_session; 467 468 struct sr_rational { 469 /** Numerator of the rational number. */ 470 int64_t p; 471 /** Denominator of the rational number. */ 472 uint64_t q; 473 }; 474 475 /** Packet in a sigrok data feed. */ 476 struct sr_datafeed_packet { 477 uint16_t type; 478 const void *payload; 479 }; 480 481 /** Header of a sigrok data feed. */ 482 struct sr_datafeed_header { 483 int feed_version; 484 struct timeval starttime; 485 }; 486 487 /** Datafeed payload for type SR_DF_META. */ 488 struct sr_datafeed_meta { 489 GSList *config; 490 }; 491 492 /** Logic datafeed payload for type SR_DF_LOGIC. */ 493 struct sr_datafeed_logic { 494 uint64_t length; 495 uint16_t unitsize; 496 void *data; 497 }; 498 499 /** Analog datafeed payload for type SR_DF_ANALOG. */ 500 struct sr_datafeed_analog { 501 void *data; 502 uint32_t num_samples; 503 struct sr_analog_encoding *encoding; 504 struct sr_analog_meaning *meaning; 505 struct sr_analog_spec *spec; 506 }; 507 508 struct sr_analog_encoding { 509 uint8_t unitsize; 510 gboolean is_signed; 511 gboolean is_float; 512 gboolean is_bigendian; 513 /** 514 * Number of significant digits after the decimal point if positive, 515 * or number of non-significant digits before the decimal point if 516 * negative (refers to the value we actually read on the wire). 517 */ 518 int8_t digits; 519 gboolean is_digits_decimal; 520 struct sr_rational scale; 521 struct sr_rational offset; 522 }; 523 524 struct sr_analog_meaning { 525 enum sr_mq mq; 526 enum sr_unit unit; 527 enum sr_mqflag mqflags; 528 GSList *channels; 529 }; 530 531 struct sr_analog_spec { 532 /** 533 * Number of significant digits after the decimal point if positive, 534 * or number of non-significant digits before the decimal point if 535 * negative (refers to vendor specifications/datasheet or actual 536 * device display). 537 */ 538 int8_t spec_digits; 539 }; 540 541 /** Generic option struct used by various subsystems. */ 542 struct sr_option { 543 /* Short name suitable for commandline usage, [a-z0-9-]. */ 544 const char *id; 545 /* Short name suitable for GUI usage, can contain UTF-8. */ 546 const char *name; 547 /* Description of the option, in a sentence. */ 548 const char *desc; 549 /* Default value for this option. */ 550 GVariant *def; 551 /* List of possible values, if this is an option with few values. */ 552 GSList *values; 553 }; 554 555 /** Resource type. 556 * @since 0.4.0 557 */ 558 enum sr_resource_type { 559 SR_RESOURCE_FIRMWARE = 1, 560 }; 561 562 /** Resource descriptor. 563 * @since 0.4.0 564 */ 565 struct sr_resource { 566 /** Size of resource in bytes; set by resource open callback. */ 567 uint64_t size; 568 /** File handle or equivalent; set by resource open callback. */ 569 void *handle; 570 /** Resource type (SR_RESOURCE_FIRMWARE, ...) */ 571 int type; 572 }; 573 574 /** Output module flags. */ 575 enum sr_output_flag { 576 /** If set, this output module writes the output itself. */ 577 SR_OUTPUT_INTERNAL_IO_HANDLING = 0x01, 578 }; 579 580 struct sr_input; 581 struct sr_input_module; 582 struct sr_output; 583 struct sr_output_module; 584 struct sr_transform; 585 struct sr_transform_module; 586 587 /** Constants for channel type. */ 588 enum sr_channeltype { 589 /** Channel type is logic channel. */ 590 SR_CHANNEL_LOGIC = 10000, 591 /** Channel type is analog channel. */ 592 SR_CHANNEL_ANALOG, 593 }; 594 595 /** Information on single channel. */ 596 struct sr_channel { 597 /** The device this channel is attached to. */ 598 struct sr_dev_inst *sdi; 599 /** The index of this channel, starting at 0. Logic channels will 600 * be encoded according to this index in SR_DF_LOGIC packets. */ 601 int index; 602 /** Channel type (SR_CHANNEL_LOGIC, ...) */ 603 int type; 604 /** Is this channel enabled? */ 605 gboolean enabled; 606 /** Name of channel. */ 607 char *name; 608 /** Private data for driver use. */ 609 void *priv; 610 }; 611 612 /** Structure for groups of channels that have common properties. */ 613 struct sr_channel_group { 614 /** Name of the channel group. */ 615 char *name; 616 /** List of sr_channel structs of the channels belonging to this group. */ 617 GSList *channels; 618 /** Private data for driver use. */ 619 void *priv; 620 }; 621 622 /** Used for setting or getting value of a config item. */ 623 struct sr_config { 624 /** Config key like SR_CONF_CONN, etc. */ 625 uint32_t key; 626 /** Key-specific data. */ 627 GVariant *data; 628 }; 629 630 enum sr_keytype { 631 SR_KEY_CONFIG, 632 SR_KEY_MQ, 633 SR_KEY_MQFLAGS, 634 }; 635 636 /** Information about a key. */ 637 struct sr_key_info { 638 /** Config key like SR_CONF_CONN, MQ value like SR_MQ_VOLTAGE, etc. */ 639 uint32_t key; 640 /** Data type like SR_T_STRING, etc if applicable. */ 641 int datatype; 642 /** Short, lowercase ID string, e.g. "serialcomm", "voltage". */ 643 const char *id; 644 /** Full capitalized name, e.g. "Serial communication". */ 645 const char *name; 646 /** Verbose description (unused currently). */ 647 const char *description; 648 }; 649 650 /** Configuration capabilities. */ 651 enum sr_configcap { 652 /** Value can be read. */ 653 SR_CONF_GET = (1UL << 31), 654 /** Value can be written. */ 655 SR_CONF_SET = (1UL << 30), 656 /** Possible values can be enumerated. */ 657 SR_CONF_LIST = (1UL << 29), 658 }; 659 660 /** Configuration keys */ 661 enum sr_configkey { 662 /*--- Device classes ------------------------------------------------*/ 663 664 /** The device can act as logic analyzer. */ 665 SR_CONF_LOGIC_ANALYZER = 10000, 666 667 /** The device can act as an oscilloscope. */ 668 SR_CONF_OSCILLOSCOPE, 669 670 /** The device can act as a multimeter. */ 671 SR_CONF_MULTIMETER, 672 673 /** The device is a demo device. */ 674 SR_CONF_DEMO_DEV, 675 676 /** The device can act as a sound level meter. */ 677 SR_CONF_SOUNDLEVELMETER, 678 679 /** The device can measure temperature. */ 680 SR_CONF_THERMOMETER, 681 682 /** The device can measure humidity. */ 683 SR_CONF_HYGROMETER, 684 685 /** The device can measure energy consumption. */ 686 SR_CONF_ENERGYMETER, 687 688 /** The device can act as a signal demodulator. */ 689 SR_CONF_DEMODULATOR, 690 691 /** The device can act as a programmable power supply. */ 692 SR_CONF_POWER_SUPPLY, 693 694 /** The device can act as an LCR meter. */ 695 SR_CONF_LCRMETER, 696 697 /** The device can act as an electronic load. */ 698 SR_CONF_ELECTRONIC_LOAD, 699 700 /** The device can act as a scale. */ 701 SR_CONF_SCALE, 702 703 /** The device can act as a function generator. */ 704 SR_CONF_SIGNAL_GENERATOR, 705 706 /** The device can measure power. */ 707 SR_CONF_POWERMETER, 708 709 /* Update sr_key_info_config[] (hwdriver.c) upon changes! */ 710 711 /*--- Driver scan options -------------------------------------------*/ 712 713 /** 714 * Specification on how to connect to a device. 715 * 716 * In combination with SR_CONF_SERIALCOMM, this is a serial port in 717 * the form which makes sense to the OS (e.g., /dev/ttyS0). 718 * Otherwise this specifies a USB device, either in the form of 719 * @verbatim <bus>.<address> @endverbatim (decimal, e.g. 1.65) or 720 * @verbatim <vendorid>.<productid> @endverbatim 721 * (hexadecimal, e.g. 1d6b.0001). 722 */ 723 SR_CONF_CONN = 20000, 724 725 /** 726 * Serial communication specification, in the form: 727 * 728 * @verbatim <baudrate>/<databits><parity><stopbits> @endverbatim 729 * 730 * Example: 9600/8n1 731 * 732 * The string may also be followed by one or more special settings, 733 * in the form "/key=value". Supported keys and their values are: 734 * 735 * rts 0,1 set the port's RTS pin to low or high 736 * dtr 0,1 set the port's DTR pin to low or high 737 * flow 0 no flow control 738 * 1 hardware-based (RTS/CTS) flow control 739 * 2 software-based (XON/XOFF) flow control 740 * 741 * This is always an optional parameter, since a driver typically 742 * knows the speed at which the device wants to communicate. 743 */ 744 SR_CONF_SERIALCOMM, 745 746 /** 747 * Modbus slave address specification. 748 * 749 * This is always an optional parameter, since a driver typically 750 * knows the default slave address of the device. 751 */ 752 SR_CONF_MODBUSADDR, 753 754 /* Update sr_key_info_config[] (hwdriver.c) upon changes! */ 755 756 /*--- Device (or channel group) configuration -----------------------*/ 757 758 /** The device supports setting its samplerate, in Hz. */ 759 SR_CONF_SAMPLERATE = 30000, 760 761 /** The device supports setting a pre/post-trigger capture ratio. */ 762 SR_CONF_CAPTURE_RATIO, 763 764 /** The device supports setting a pattern (pattern generator mode). */ 765 SR_CONF_PATTERN_MODE, 766 767 /** The device supports run-length encoding (RLE). */ 768 SR_CONF_RLE, 769 770 /** The device supports setting trigger slope. */ 771 SR_CONF_TRIGGER_SLOPE, 772 773 /** The device supports averaging. */ 774 SR_CONF_AVERAGING, 775 776 /** 777 * The device supports setting number of samples to be 778 * averaged over. 779 */ 780 SR_CONF_AVG_SAMPLES, 781 782 /** Trigger source. */ 783 SR_CONF_TRIGGER_SOURCE, 784 785 /** Horizontal trigger position. */ 786 SR_CONF_HORIZ_TRIGGERPOS, 787 788 /** Buffer size. */ 789 SR_CONF_BUFFERSIZE, 790 791 /** Time base. */ 792 SR_CONF_TIMEBASE, 793 794 /** Filter. */ 795 SR_CONF_FILTER, 796 797 /** Volts/div. */ 798 SR_CONF_VDIV, 799 800 /** Coupling. */ 801 SR_CONF_COUPLING, 802 803 /** Trigger matches. */ 804 SR_CONF_TRIGGER_MATCH, 805 806 /** The device supports setting its sample interval, in ms. */ 807 SR_CONF_SAMPLE_INTERVAL, 808 809 /** Number of horizontal divisions, as related to SR_CONF_TIMEBASE. */ 810 SR_CONF_NUM_HDIV, 811 812 /** Number of vertical divisions, as related to SR_CONF_VDIV. */ 813 SR_CONF_NUM_VDIV, 814 815 /** Sound pressure level frequency weighting. */ 816 SR_CONF_SPL_WEIGHT_FREQ, 817 818 /** Sound pressure level time weighting. */ 819 SR_CONF_SPL_WEIGHT_TIME, 820 821 /** Sound pressure level measurement range. */ 822 SR_CONF_SPL_MEASUREMENT_RANGE, 823 824 /** Max hold mode. */ 825 SR_CONF_HOLD_MAX, 826 827 /** Min hold mode. */ 828 SR_CONF_HOLD_MIN, 829 830 /** Logic low-high threshold range. */ 831 SR_CONF_VOLTAGE_THRESHOLD, 832 833 /** The device supports using an external clock. */ 834 SR_CONF_EXTERNAL_CLOCK, 835 836 /** 837 * The device supports swapping channels. Typical this is between 838 * buffered and unbuffered channels. 839 */ 840 SR_CONF_SWAP, 841 842 /** Center frequency. 843 * The input signal is downmixed by this frequency before the ADC 844 * anti-aliasing filter. 845 */ 846 SR_CONF_CENTER_FREQUENCY, 847 848 /** The device supports setting the number of logic channels. */ 849 SR_CONF_NUM_LOGIC_CHANNELS, 850 851 /** The device supports setting the number of analog channels. */ 852 SR_CONF_NUM_ANALOG_CHANNELS, 853 854 /** 855 * Current voltage. 856 * @arg type: double 857 * @arg get: get measured voltage 858 */ 859 SR_CONF_VOLTAGE, 860 861 /** 862 * Maximum target voltage. 863 * @arg type: double 864 * @arg get: get target voltage 865 * @arg set: change target voltage 866 */ 867 SR_CONF_VOLTAGE_TARGET, 868 869 /** 870 * Current current. 871 * @arg type: double 872 * @arg get: get measured current 873 */ 874 SR_CONF_CURRENT, 875 876 /** 877 * Current limit. 878 * @arg type: double 879 * @arg get: get current limit 880 * @arg set: change current limit 881 */ 882 SR_CONF_CURRENT_LIMIT, 883 884 /** 885 * Enabling/disabling channel. 886 * @arg type: boolean 887 * @arg get: @b true if currently enabled 888 * @arg set: enable/disable 889 */ 890 SR_CONF_ENABLED, 891 892 /** 893 * Channel configuration. 894 * @arg type: string 895 * @arg get: get current setting 896 * @arg set: change current setting 897 * @arg list: array of possible values 898 */ 899 SR_CONF_CHANNEL_CONFIG, 900 901 /** 902 * Over-voltage protection (OVP) feature 903 * @arg type: boolean 904 * @arg get: @b true if currently enabled 905 * @arg set: enable/disable 906 */ 907 SR_CONF_OVER_VOLTAGE_PROTECTION_ENABLED, 908 909 /** 910 * Over-voltage protection (OVP) active 911 * @arg type: boolean 912 * @arg get: @b true if device has activated OVP, i.e. the output voltage 913 * exceeds the over-voltage protection threshold. 914 */ 915 SR_CONF_OVER_VOLTAGE_PROTECTION_ACTIVE, 916 917 /** 918 * Over-voltage protection (OVP) threshold 919 * @arg type: double (voltage) 920 * @arg get: get current threshold 921 * @arg set: set new threshold 922 */ 923 SR_CONF_OVER_VOLTAGE_PROTECTION_THRESHOLD, 924 925 /** 926 * Over-current protection (OCP) feature 927 * @arg type: boolean 928 * @arg get: @b true if currently enabled 929 * @arg set: enable/disable 930 */ 931 SR_CONF_OVER_CURRENT_PROTECTION_ENABLED, 932 933 /** 934 * Over-current protection (OCP) active 935 * @arg type: boolean 936 * @arg get: @b true if device has activated OCP, i.e. the current current 937 * exceeds the over-current protection threshold. 938 */ 939 SR_CONF_OVER_CURRENT_PROTECTION_ACTIVE, 940 941 /** 942 * Over-current protection (OCP) threshold 943 * @arg type: double (current) 944 * @arg get: get current threshold 945 * @arg set: set new threshold 946 */ 947 SR_CONF_OVER_CURRENT_PROTECTION_THRESHOLD, 948 949 /** Choice of clock edge for external clock ("r" or "f"). */ 950 SR_CONF_CLOCK_EDGE, 951 952 /** Amplitude of a source without strictly-defined MQ. */ 953 SR_CONF_AMPLITUDE, 954 955 /** 956 * Channel regulation 957 * get: "CV", "CC" or "UR", denoting constant voltage, constant current 958 * or unregulated. 959 * "CC-" denotes a power supply in current sink mode (e.g. HP 66xxB). 960 * "" is used when there is no regulation, e.g. the output is disabled. 961 */ 962 SR_CONF_REGULATION, 963 964 /** Over-temperature protection (OTP) */ 965 SR_CONF_OVER_TEMPERATURE_PROTECTION, 966 967 /** Output frequency in Hz. */ 968 SR_CONF_OUTPUT_FREQUENCY, 969 970 /** Output frequency target in Hz. */ 971 SR_CONF_OUTPUT_FREQUENCY_TARGET, 972 973 /** Measured quantity. */ 974 SR_CONF_MEASURED_QUANTITY, 975 976 /** Equivalent circuit model. */ 977 SR_CONF_EQUIV_CIRCUIT_MODEL, 978 979 /** Over-temperature protection (OTP) active. */ 980 SR_CONF_OVER_TEMPERATURE_PROTECTION_ACTIVE, 981 982 /** Under-voltage condition. */ 983 SR_CONF_UNDER_VOLTAGE_CONDITION, 984 985 /** Under-voltage condition active. */ 986 SR_CONF_UNDER_VOLTAGE_CONDITION_ACTIVE, 987 988 /** Trigger level. */ 989 SR_CONF_TRIGGER_LEVEL, 990 991 /** Under-voltage condition threshold. */ 992 SR_CONF_UNDER_VOLTAGE_CONDITION_THRESHOLD, 993 994 /** 995 * Which external clock source to use if the device supports 996 * multiple external clock channels. 997 */ 998 SR_CONF_EXTERNAL_CLOCK_SOURCE, 999 1000 /** Offset of a source without strictly-defined MQ. */ 1001 SR_CONF_OFFSET, 1002 1003 /** The device supports setting a pattern for the logic trigger. */ 1004 SR_CONF_TRIGGER_PATTERN, 1005 1006 /** High resolution mode. */ 1007 SR_CONF_HIGH_RESOLUTION, 1008 1009 /** Peak detection. */ 1010 SR_CONF_PEAK_DETECTION, 1011 1012 /** Logic threshold: predefined levels (TTL, ECL, CMOS, etc). */ 1013 SR_CONF_LOGIC_THRESHOLD, 1014 1015 /** Logic threshold: custom numerical value. */ 1016 SR_CONF_LOGIC_THRESHOLD_CUSTOM, 1017 1018 /** The measurement range of a DMM or the output range of a power supply. */ 1019 SR_CONF_RANGE, 1020 1021 /** The number of digits (e.g. for a DMM). */ 1022 SR_CONF_DIGITS, 1023 1024 /* Update sr_key_info_config[] (hwdriver.c) upon changes! */ 1025 1026 /*--- Special stuff -------------------------------------------------*/ 1027 1028 /** Session filename. */ 1029 SR_CONF_SESSIONFILE = 40000, 1030 1031 /** The device supports specifying a capturefile to inject. */ 1032 SR_CONF_CAPTUREFILE, 1033 1034 /** The device supports specifying the capturefile unit size. */ 1035 SR_CONF_CAPTURE_UNITSIZE, 1036 1037 /** Power off the device. */ 1038 SR_CONF_POWER_OFF, 1039 1040 /** 1041 * Data source for acquisition. If not present, acquisition from 1042 * the device is always "live", i.e. acquisition starts when the 1043 * frontend asks and the results are sent out as soon as possible. 1044 * 1045 * If present, it indicates that either the device has no live 1046 * acquisition capability (for example a pure data logger), or 1047 * there is a choice. sr_config_list() returns those choices. 1048 * 1049 * In any case if a device has live acquisition capabilities, it 1050 * is always the default. 1051 */ 1052 SR_CONF_DATA_SOURCE, 1053 1054 /** The device supports setting a probe factor. */ 1055 SR_CONF_PROBE_FACTOR, 1056 1057 /** Number of powerline cycles for ADC integration time. */ 1058 SR_CONF_ADC_POWERLINE_CYCLES, 1059 1060 /* Update sr_key_info_config[] (hwdriver.c) upon changes! */ 1061 1062 /*--- Acquisition modes, sample limiting ----------------------------*/ 1063 1064 /** 1065 * The device supports setting a sample time limit (how long 1066 * the sample acquisition should run, in ms). 1067 */ 1068 SR_CONF_LIMIT_MSEC = 50000, 1069 1070 /** 1071 * The device supports setting a sample number limit (how many 1072 * samples should be acquired). 1073 */ 1074 SR_CONF_LIMIT_SAMPLES, 1075 1076 /** 1077 * The device supports setting a frame limit (how many 1078 * frames should be acquired). 1079 */ 1080 SR_CONF_LIMIT_FRAMES, 1081 1082 /** 1083 * The device supports continuous sampling. Neither a time limit 1084 * nor a sample number limit has to be supplied, it will just acquire 1085 * samples continuously, until explicitly stopped by a certain command. 1086 */ 1087 SR_CONF_CONTINUOUS, 1088 1089 /** The device has internal storage, into which data is logged. This 1090 * starts or stops the internal logging. */ 1091 SR_CONF_DATALOG, 1092 1093 /** Device mode for multi-function devices. */ 1094 SR_CONF_DEVICE_MODE, 1095 1096 /** Self test mode. */ 1097 SR_CONF_TEST_MODE, 1098 1099 /* Update sr_key_info_config[] (hwdriver.c) upon changes! */ 1100 }; 1101 1102 /** 1103 * Opaque structure representing a libsigrok device instance. 1104 * 1105 * None of the fields of this structure are meant to be accessed directly. 1106 */ 1107 struct sr_dev_inst; 1108 1109 /** Types of device instance, struct sr_dev_inst.type */ 1110 enum sr_dev_inst_type { 1111 /** Device instance type for USB devices. */ 1112 SR_INST_USB = 10000, 1113 /** Device instance type for serial port devices. */ 1114 SR_INST_SERIAL, 1115 /** Device instance type for SCPI devices. */ 1116 SR_INST_SCPI, 1117 /** Device-instance type for user-created "devices". */ 1118 SR_INST_USER, 1119 /** Device instance type for Modbus devices. */ 1120 SR_INST_MODBUS, 1121 }; 1122 1123 /** Device instance status, struct sr_dev_inst.status */ 1124 enum sr_dev_inst_status { 1125 /** The device instance was not found. */ 1126 SR_ST_NOT_FOUND = 10000, 1127 /** The device instance was found, but is still booting. */ 1128 SR_ST_INITIALIZING, 1129 /** The device instance is live, but not in use. */ 1130 SR_ST_INACTIVE, 1131 /** The device instance is actively in use in a session. */ 1132 SR_ST_ACTIVE, 1133 /** The device is winding down its session. */ 1134 SR_ST_STOPPING, 1135 }; 1136 1137 /** Device driver data. See also http://sigrok.org/wiki/Hardware_driver_API . */ 1138 struct sr_dev_driver { 1139 /* Driver-specific */ 1140 /** Driver name. Lowercase a-z, 0-9 and dashes (-) only. */ 1141 const char *name; 1142 /** Long name. Verbose driver name shown to user. */ 1143 const char *longname; 1144 /** API version (currently 1). */ 1145 int api_version; 1146 /** Called when driver is loaded, e.g. program startup. */ 1147 int (*init) (struct sr_dev_driver *driver, struct sr_context *sr_ctx); 1148 /** Called before driver is unloaded. 1149 * Driver must free all resources held by it. */ 1150 int (*cleanup) (const struct sr_dev_driver *driver); 1151 /** Scan for devices. Driver should do all initialisation required. 1152 * Can be called several times, e.g. with different port options. 1153 * @retval NULL Error or no devices found. 1154 * @retval other GSList of a struct sr_dev_inst for each device. 1155 * Must be freed by caller! 1156 */ 1157 GSList *(*scan) (struct sr_dev_driver *driver, GSList *options); 1158 /** Get list of device instances the driver knows about. 1159 * @returns NULL or GSList of a struct sr_dev_inst for each device. 1160 * Must not be freed by caller! 1161 */ 1162 GSList *(*dev_list) (const struct sr_dev_driver *driver); 1163 /** Clear list of devices the driver knows about. */ 1164 int (*dev_clear) (const struct sr_dev_driver *driver); 1165 /** Query value of a configuration key in driver or given device instance. 1166 * @see sr_config_get(). 1167 */ 1168 int (*config_get) (uint32_t key, GVariant **data, 1169 const struct sr_dev_inst *sdi, 1170 const struct sr_channel_group *cg); 1171 /** Set value of a configuration key in driver or a given device instance. 1172 * @see sr_config_set(). */ 1173 int (*config_set) (uint32_t key, GVariant *data, 1174 const struct sr_dev_inst *sdi, 1175 const struct sr_channel_group *cg); 1176 /** Channel status change. 1177 * @see sr_dev_channel_enable(). */ 1178 int (*config_channel_set) (const struct sr_dev_inst *sdi, 1179 struct sr_channel *ch, unsigned int changes); 1180 /** Apply configuration settings to the device hardware. 1181 * @see sr_config_commit().*/ 1182 int (*config_commit) (const struct sr_dev_inst *sdi); 1183 /** List all possible values for a configuration key in a device instance. 1184 * @see sr_config_list(). 1185 */ 1186 int (*config_list) (uint32_t key, GVariant **data, 1187 const struct sr_dev_inst *sdi, 1188 const struct sr_channel_group *cg); 1189 1190 /* Device-specific */ 1191 /** Open device */ 1192 int (*dev_open) (struct sr_dev_inst *sdi); 1193 /** Close device */ 1194 int (*dev_close) (struct sr_dev_inst *sdi); 1195 /** Begin data acquisition on the specified device. */ 1196 int (*dev_acquisition_start) (const struct sr_dev_inst *sdi); 1197 /** End data acquisition on the specified device. */ 1198 int (*dev_acquisition_stop) (struct sr_dev_inst *sdi); 1199 1200 /* Dynamic */ 1201 /** Device driver context, considered private. Initialized by init(). */ 1202 void *context; 1203 }; 1204 1205 /** Serial port descriptor. */ 1206 struct sr_serial_port { 1207 /** The OS dependent name of the serial port. */ 1208 char *name; 1209 /** An end user friendly description for the serial port. */ 1210 char *description; 1211 }; 1212 1213 #include <libsigrok/proto.h> 1214 #include <libsigrok/version.h> 1215 1216 #ifdef __cplusplus 1217 } 1218 #endif 1219 1220 #endif 1221