X-Git-Url: https://sigrok.org/gitweb/?p=libsigrok.git;a=blobdiff_plain;f=include%2Flibsigrok%2Flibsigrok.h;h=6c5dea08ab0d3ca3eeaa7fe45f1761876f1da353;hp=0cbaa0049aadf3126d24d5943d3bccd7751898f4;hb=HEAD;hpb=6928c4a9289368573f44b683a464bf6b8dcc71d7 diff --git a/include/libsigrok/libsigrok.h b/include/libsigrok/libsigrok.h index 0cbaa004..6c5dea08 100644 --- a/include/libsigrok/libsigrok.h +++ b/include/libsigrok/libsigrok.h @@ -80,15 +80,22 @@ enum sr_error_code { /* Update sr_strerror()/sr_strerror_name() (error.c) upon changes! */ }; +/** Ternary return type for DMM/LCR/etc packet parser validity checks. */ +enum sr_valid_code { + SR_PACKET_INVALID = -1, /**< Certainly invalid. */ + SR_PACKET_VALID = 0, /**< Certainly valid. */ + SR_PACKET_NEED_RX = +1, /**< Need more RX data. */ +}; + #define SR_MAX_CHANNELNAME_LEN 32 /* Handy little macros */ #define SR_HZ(n) (n) -#define SR_KHZ(n) ((n) * (uint64_t)(1000ULL)) -#define SR_MHZ(n) ((n) * (uint64_t)(1000000ULL)) -#define SR_GHZ(n) ((n) * (uint64_t)(1000000000ULL)) +#define SR_KHZ(n) ((n) * UINT64_C(1000)) +#define SR_MHZ(n) ((n) * UINT64_C(1000000)) +#define SR_GHZ(n) ((n) * UINT64_C(1000000000)) -#define SR_HZ_TO_NS(n) ((uint64_t)(1000000000ULL) / (n)) +#define SR_HZ_TO_NS(n) (UINT64_C(1000000000) / (n)) /** libsigrok loglevels. */ enum sr_loglevel { @@ -146,6 +153,7 @@ enum sr_datatype { SR_T_DOUBLE_RANGE, SR_T_INT32, SR_T_MQ, + SR_T_UINT32, /* Update sr_variant_type_get() (hwdriver.c) upon changes! */ }; @@ -233,6 +241,10 @@ enum sr_mq { SR_MQ_MASS, /** Harmonic ratio */ SR_MQ_HARMONIC_RATIO, + /** Energy. */ + SR_MQ_ENERGY, + /** Electric charge. */ + SR_MQ_ELECTRIC_CHARGE, /* Update sr_key_info_mq[] (hwdriver.c) upon changes! */ }; @@ -290,7 +302,7 @@ enum sr_unit { SR_UNIT_VOLT_AMPERE, /** Real power [W]. */ SR_UNIT_WATT, - /** Consumption [Wh]. */ + /** Energy (consumption) in watt hour [Wh]. */ SR_UNIT_WATT_HOUR, /** Wind speed in meters per second. */ SR_UNIT_METER_SECOND, @@ -324,6 +336,12 @@ enum sr_unit { SR_UNIT_TOLA, /** Pieces (number of items). */ SR_UNIT_PIECE, + /** Energy in joule. */ + SR_UNIT_JOULE, + /** Electric charge in coulomb. */ + SR_UNIT_COULOMB, + /** Electric charge in ampere hour [Ah]. */ + SR_UNIT_AMPERE_HOUR, /* * Update unit_strings[] (analog.c) and fancyprint() (output/analog.c) @@ -511,9 +529,22 @@ struct sr_analog_encoding { gboolean is_float; gboolean is_bigendian; /** - * Number of significant digits after the decimal point if positive, - * or number of non-significant digits before the decimal point if - * negative (refers to the value we actually read on the wire). + * Number of significant digits after the decimal point, if positive. + * When negative, exponent with reversed polarity that is necessary to + * express the value with all digits without a decimal point. + * Refers to the value we actually read on the wire. + * + * Examples: + * + * | Disp. value | Exp. notation | Exp. not. normalized | digits | + * |-------------|---------------------|----------------------|--------| + * | 12.34 MOhm | 1.234 * 10^7 Ohm | 1234 * 10^4 Ohm | -4 | + * | 1.2345 MOhm | 1.2345 * 10^6 Ohm | 12345 * 10^2 Ohm | -2 | + * | 123.4 kOhm | 1.234 * 10^5 Ohm | 1234 * 10^2 Ohm | -2 | + * | 1234 Ohm | 1.234 * 10^3 Ohm | 1234 * 10^0 Ohm | 0 | + * | 12.34 Ohm | 1.234 * 10^1 Ohm | 1234 * 10^-2 Ohm | 2 | + * | 0.0123 Ohm | 1.23 * 10^-2 Ohm | 123 * 10^-4 Ohm | 4 | + * | 1.234 pF | 1.234 * 10^-12 F | 1234 * 10^-15 F | 15 | */ int8_t digits; gboolean is_digits_decimal; @@ -530,10 +561,22 @@ struct sr_analog_meaning { struct sr_analog_spec { /** - * Number of significant digits after the decimal point if positive, - * or number of non-significant digits before the decimal point if - * negative (refers to vendor specifications/datasheet or actual - * device display). + * Number of significant digits after the decimal point, if positive. + * When negative, exponent with reversed polarity that is necessary to + * express the value with all digits without a decimal point. + * Refers to vendor specifications/datasheet or actual device display. + * + * Examples: + * + * | On the wire | Exp. notation | Exp. not. normalized | spec_digits | + * |-------------|---------------------|----------------------|-------------| + * | 12.34 MOhm | 1.234 * 10^7 Ohm | 1234 * 10^4 Ohm | -4 | + * | 1.2345 MOhm | 1.2345 * 10^6 Ohm | 12345 * 10^2 Ohm | -2 | + * | 123.4 kOhm | 1.234 * 10^5 Ohm | 1234 * 10^2 Ohm | -2 | + * | 1234 Ohm | 1.234 * 10^3 Ohm | 1234 * 10^0 Ohm | 0 | + * | 12.34 Ohm | 1.234 * 10^1 Ohm | 1234 * 10^-2 Ohm | 2 | + * | 0.0123 Ohm | 1.23 * 10^-2 Ohm | 123 * 10^-4 Ohm | 4 | + * | 1.234 pF | 1.234 * 10^-12 F | 1234 * 10^-15 F | 15 | */ int8_t spec_digits; }; @@ -650,11 +693,11 @@ struct sr_key_info { /** Configuration capabilities. */ enum sr_configcap { /** Value can be read. */ - SR_CONF_GET = (1 << 31), + SR_CONF_GET = (1UL << 31), /** Value can be written. */ - SR_CONF_SET = (1 << 30), + SR_CONF_SET = (1UL << 30), /** Possible values can be enumerated. */ - SR_CONF_LIST = (1 << 29), + SR_CONF_LIST = (1UL << 29), }; /** Configuration keys */ @@ -703,6 +746,15 @@ enum sr_configkey { /** The device can act as a function generator. */ SR_CONF_SIGNAL_GENERATOR, + /** The device can measure power. */ + SR_CONF_POWERMETER, + + /** + * The device can switch between multiple sources, e.g. a relay actuator + * or multiplexer. + */ + SR_CONF_MULTIPLEXER, + /* Update sr_key_info_config[] (hwdriver.c) upon changes! */ /*--- Driver scan options -------------------------------------------*/ @@ -748,6 +800,36 @@ enum sr_configkey { */ SR_CONF_MODBUSADDR, + /** + * User specified forced driver attachment to unknown devices. + * + * By design the interpretation of the string depends on the + * specific driver. It typically would be either a replacement + * '*IDN?' response value, or a sub-driver name. But could also + * be anything else and totally arbitrary. + */ + SR_CONF_FORCE_DETECT, + + /** + * Override builtin probe names from user specs. + * + * Users may want to override the names which are assigned to + * probes during scan (these usually match the vendor's labels + * on the device). This avoids the interactive tedium of + * changing channel names after device creation and before + * protocol decoder attachment. Think of IEEE488 recorders or + * parallel computer bus loggers. The scan option eliminates + * the issue of looking up previously assigned names before + * renaming a channel (see sigrok-cli -C), which depends on + * the device as well as the application, and is undesirable. + * The scan option is limited to those drivers which implement + * support for it, but works identically across those drivers. + * + * The value is a string, either a comma separated list of + * probe names, or an alias for a typical set of names. + */ + SR_CONF_PROBE_NAMES, + /* Update sr_key_info_config[] (hwdriver.c) upon changes! */ /*--- Device (or channel group) configuration -----------------------*/ @@ -797,7 +879,7 @@ enum sr_configkey { /** Coupling. */ SR_CONF_COUPLING, - /** Trigger matches. */ + /** Trigger matches. */ SR_CONF_TRIGGER_MATCH, /** The device supports setting its sample interval, in ms. */ @@ -806,16 +888,16 @@ enum sr_configkey { /** Number of horizontal divisions, as related to SR_CONF_TIMEBASE. */ SR_CONF_NUM_HDIV, - /** Number of vertical divisions, as related to SR_CONF_VDIV. */ + /** Number of vertical divisions, as related to SR_CONF_VDIV. */ SR_CONF_NUM_VDIV, - /** Sound pressure level frequency weighting. */ + /** Sound pressure level frequency weighting. */ SR_CONF_SPL_WEIGHT_FREQ, - /** Sound pressure level time weighting. */ + /** Sound pressure level time weighting. */ SR_CONF_SPL_WEIGHT_TIME, - /** Sound pressure level measurement range. */ + /** Sound pressure level measurement range. */ SR_CONF_SPL_MEASUREMENT_RANGE, /** Max hold mode. */ @@ -953,6 +1035,8 @@ enum sr_configkey { * Channel regulation * get: "CV", "CC" or "UR", denoting constant voltage, constant current * or unregulated. + * "CC-" denotes a power supply in current sink mode (e.g. HP 66xxB). + * "" is used when there is no regulation, e.g. the output is disabled. */ SR_CONF_REGULATION, @@ -983,6 +1067,76 @@ enum sr_configkey { /** Trigger level. */ SR_CONF_TRIGGER_LEVEL, + /** Under-voltage condition threshold. */ + SR_CONF_UNDER_VOLTAGE_CONDITION_THRESHOLD, + + /** + * Which external clock source to use if the device supports + * multiple external clock channels. + */ + SR_CONF_EXTERNAL_CLOCK_SOURCE, + + /** Offset of a source without strictly-defined MQ. */ + SR_CONF_OFFSET, + + /** The device supports setting a pattern for the logic trigger. */ + SR_CONF_TRIGGER_PATTERN, + + /** High resolution mode. */ + SR_CONF_HIGH_RESOLUTION, + + /** Peak detection. */ + SR_CONF_PEAK_DETECTION, + + /** Logic threshold: predefined levels (TTL, ECL, CMOS, etc). */ + SR_CONF_LOGIC_THRESHOLD, + + /** Logic threshold: custom numerical value. */ + SR_CONF_LOGIC_THRESHOLD_CUSTOM, + + /** The measurement range of a DMM or the output range of a power supply. */ + SR_CONF_RANGE, + + /** The number of digits (e.g. for a DMM). */ + SR_CONF_DIGITS, + + /** Phase of a source signal. */ + SR_CONF_PHASE, + + /** Duty cycle of a source signal. */ + SR_CONF_DUTY_CYCLE, + + /** + * Current power. + * @arg type: double + * @arg get: get measured power + */ + SR_CONF_POWER, + + /** + * Power target. + * @arg type: double + * @arg get: get power target + * @arg set: change power target + */ + SR_CONF_POWER_TARGET, + + /** + * Resistance target. + * @arg type: double + * @arg get: get resistance target + * @arg set: change resistance target + */ + SR_CONF_RESISTANCE_TARGET, + + /** + * Over-current protection (OCP) delay + * @arg type: double (time) + * @arg get: get current delay + * @arg set: set new delay + */ + SR_CONF_OVER_CURRENT_PROTECTION_DELAY, + /* Update sr_key_info_config[] (hwdriver.c) upon changes! */ /*--- Special stuff -------------------------------------------------*/