X-Git-Url: https://sigrok.org/gitweb/?a=blobdiff_plain;f=libsigrok.h;h=d7d31a33f131d9a46fa0e572945e5bd7e1c4824f;hb=39e5d79826cd2c1991007faf1a6cde05af995aa9;hp=4c46734663cfa7bf3be72105f53f0dda55231ddc;hpb=3c0839d52475605d61ce385eda95f824fc448c88;p=libsigrok.git diff --git a/libsigrok.h b/libsigrok.h index 4c467346..d7d31a33 100644 --- a/libsigrok.h +++ b/libsigrok.h @@ -30,6 +30,22 @@ extern "C" { #endif +/** + * @file + * + * The public libsigrok header file to be used by frontends. + * + * This is the only file that libsigrok users (frontends) are supposed to + * use and #include. There are other header files which get installed with + * libsigrok, but those are not meant to be used directly by frontends. + * + * The correct way to get/use the libsigrok API functions is: + * + * @code{.c} + * #include + * @endcode + */ + /* * All possible return codes of libsigrok functions must be listed here. * Functions should never return hardcoded numbers as status, but rather @@ -111,7 +127,7 @@ typedef int (*sr_receive_data_callback_t)(int fd, int revents, void *cb_data); /** Data types used by hardware drivers for dev_config_set(). */ enum { - SR_T_UINT64, + SR_T_UINT64 = 10000, SR_T_CHAR, SR_T_BOOL, SR_T_FLOAT, @@ -130,7 +146,7 @@ struct sr_rational { /** Value for sr_datafeed_packet.type. */ enum { - SR_DF_HEADER, + SR_DF_HEADER = 10000, SR_DF_END, SR_DF_TRIGGER, SR_DF_LOGIC, @@ -143,7 +159,7 @@ enum { /** Values for sr_datafeed_analog.mq. */ enum { - SR_MQ_VOLTAGE, + SR_MQ_VOLTAGE = 10000, SR_MQ_CURRENT, SR_MQ_RESISTANCE, SR_MQ_CAPACITANCE, @@ -155,13 +171,16 @@ enum { SR_MQ_CONDUCTANCE, /** Electrical power, usually in W, or dBm. */ SR_MQ_POWER, - /** Gain (e.g. a transistor's gain, or hFE). */ + /** Gain (a transistor's gain, or hFE, for example). */ SR_MQ_GAIN, + /** Logarithmic representation of sound pressure relative to a + * reference value. */ + SR_MQ_SOUND_PRESSURE_LEVEL, }; /** Values for sr_datafeed_analog.unit. */ enum { - SR_UNIT_VOLT, + SR_UNIT_VOLT = 10000, SR_UNIT_AMPERE, SR_UNIT_OHM, SR_UNIT_FARAD, @@ -187,6 +206,8 @@ enum { * a unitless quantity, for example. */ SR_UNIT_UNITLESS, + /** Sound pressure level relative so 20 micropascals. */ + SR_UNIT_DECIBEL_SPL, }; /** Values for sr_datafeed_analog.flags. */ @@ -199,7 +220,7 @@ enum { SR_MQFLAG_RMS = 0x04, /** Value is voltage drop across a diode, or NAN. */ SR_MQFLAG_DIODE = 0x08, - /** Device is in "hold" mode, i.e. repeating the last measurement. */ + /** Device is in "hold" mode (repeating the last measurement). */ SR_MQFLAG_HOLD = 0x10, /** Device is in "max" mode, only updating upon a new max value. */ SR_MQFLAG_MAX = 0x20, @@ -209,6 +230,30 @@ enum { SR_MQFLAG_AUTORANGE = 0x80, /** Device is in relative mode. */ SR_MQFLAG_RELATIVE = 0x100, + /** Sound pressure level is A-weighted in the frequency domain, + * according to IEC 61672:2003. */ + SR_MQFLAG_SPL_FREQ_WEIGHT_A = 0x200, + /** Sound pressure level is C-weighted in the frequency domain, + * according to IEC 61672:2003. */ + SR_MQFLAG_SPL_FREQ_WEIGHT_C = 0x400, + /** Sound pressure level is Z-weighted (i.e. not at all) in the + * frequency domain, according to IEC 61672:2003. */ + SR_MQFLAG_SPL_FREQ_WEIGHT_Z = 0x800, + /** Sound pressure level is not weighted in the frequency domain, + * albeit without standards-defined low and high frequency limits. */ + SR_MQFLAG_SPL_FREQ_WEIGHT_FLAT = 0x1000, + /** Sound pressure level measurement is S-weighted (1s) in the + * time domain. */ + SR_MQFLAG_SPL_TIME_WEIGHT_S = 0x2000, + /** Sound pressure level measurement is F-weighted (125ms) in the + * time domain. */ + SR_MQFLAG_SPL_TIME_WEIGHT_F = 0x4000, + /** Sound pressure level is time-averaged (LAT), also known as + * Equivalent Continuous A-weighted Sound Level (LEQ). */ + SR_MQFLAG_SPL_LAT = 0x8000, + /** Sound pressure level represented as a percentage of measurements + * that were over a preset alarm level. */ + SR_MQFLAG_SPL_PCT_OVER_ALARM = 0x10000, }; struct sr_context; @@ -240,7 +285,7 @@ struct sr_datafeed_meta_analog { struct sr_datafeed_analog { int num_samples; - /** Measured quantity (e.g. voltage, current, temperature). */ + /** Measured quantity (voltage, current, temperature, and so on). */ int mq; /** Unit in which the MQ is measured. */ int unit; @@ -312,7 +357,7 @@ struct sr_dev { }; enum { - SR_PROBE_LOGIC, + SR_PROBE_LOGIC = 10000, SR_PROBE_ANALOG, }; @@ -331,28 +376,30 @@ struct sr_hwopt { /** Hardware driver options. */ enum { - /** Used to terminate lists. Must be 0! */ - SR_HWOPT_DUMMY = 0, - /** * Some drivers cannot detect the exact model they're talking to * (may be phased out). */ - SR_HWOPT_MODEL, + SR_HWOPT_MODEL = 10000, /** - * Specification on how to connect to a device. In combination - * with SR_HWOPT_SERIALCOMM, this is a serial port in the form - * which makes sense to the operating system (e.g., /dev/ttyS0). + * Specification on how to connect to a device. + * + * In combination with SR_HWOPT_SERIALCOMM, this is a serial port in + * the form which makes sense to the OS (e.g., /dev/ttyS0). * Otherwise this specifies a USB device, either in the form of - * [bus].[address] (decimal, e.g. 1.65) or [vendorid].[productid] + * @verbatim .
@endverbatim (decimal, e.g. 1.65) or + * @verbatim . @endverbatim * (hexadecimal, e.g. 1d6b.0001). */ SR_HWOPT_CONN, /** * Serial communication specification, in the form: - * [baudrate]/[databits][parity][stopbits], e.g. 9600/8n1 + * + * @verbatim / @endverbatim + * + * Example: 9600/8n1 * * This is always an optional parameter, since a driver typically * knows the speed at which the device wants to communicate. @@ -362,13 +409,10 @@ enum { /** Hardware device capabilities. */ enum { - /** Used to terminate lists. Must be 0! */ - SR_HWCAP_DUMMY = 0, - /*--- Device classes ------------------------------------------------*/ /** The device can act as logic analyzer. */ - SR_HWCAP_LOGIC_ANALYZER, + SR_HWCAP_LOGIC_ANALYZER = 10000, /** The device can act as an oscilloscope. */ SR_HWCAP_OSCILLOSCOPE, @@ -379,11 +423,13 @@ enum { /** The device is a demo device. */ SR_HWCAP_DEMO_DEV, + /** The device can act as a sound level meter. */ + SR_HWCAP_SOUNDLEVELMETER, /*--- Device configuration ------------------------------------------*/ /** The device supports setting/changing its samplerate. */ - SR_HWCAP_SAMPLERATE, + SR_HWCAP_SAMPLERATE = 20000, /** The device supports setting a pre/post-trigger capture ratio. */ SR_HWCAP_CAPTURE_RATIO, @@ -419,11 +465,10 @@ enum { /** Coupling. */ SR_HWCAP_COUPLING, - /*--- Special stuff -------------------------------------------------*/ /** Session filename. */ - SR_HWCAP_SESSIONFILE, + SR_HWCAP_SESSIONFILE = 30000, /* TODO: Better description. */ /** The device supports specifying a capturefile to inject. */ @@ -437,34 +482,32 @@ enum { /** The device supports setting the number of probes. */ SR_HWCAP_CAPTURE_NUM_PROBES, - /*--- Acquisition modes ---------------------------------------------*/ /** - * The device supports setting a sample time limit, i.e. how long the - * sample acquisition should run (in ms). + * The device supports setting a sample time limit (how long + * the sample acquisition should run, in ms). */ - SR_HWCAP_LIMIT_MSEC, + SR_HWCAP_LIMIT_MSEC = 40000, /** - * The device supports setting a sample number limit, i.e. how many - * samples should be acquired. + * The device supports setting a sample number limit (how many + * samples should be acquired). */ SR_HWCAP_LIMIT_SAMPLES, /** - * The device supports setting a frame limit, i.e. how many - * frames should be acquired. + * The device supports setting a frame limit (how many + * frames should be acquired). */ SR_HWCAP_LIMIT_FRAMES, /** - * The device supports continuous sampling, i.e. neither a time limit + * The device supports continuous sampling. Neither a time limit * nor a sample number limit has to be supplied, it will just acquire * samples continuously, until explicitly stopped by a certain command. */ SR_HWCAP_CONTINUOUS, - }; struct sr_hwcap_option { @@ -489,7 +532,7 @@ struct sr_dev_inst { /** Types of device instances (sr_dev_inst). */ enum { /** Device instance type for USB devices. */ - SR_INST_USB, + SR_INST_USB = 10000, /** Device instance type for serial port devices. */ SR_INST_SERIAL, }; @@ -497,13 +540,15 @@ enum { /** Device instance status. */ enum { /** The device instance was not found. */ - SR_ST_NOT_FOUND, + SR_ST_NOT_FOUND = 10000, /** The device instance was found, but is still booting. */ SR_ST_INITIALIZING, /** The device instance is live, but not in use. */ SR_ST_INACTIVE, /** The device instance is actively in use in a session. */ SR_ST_ACTIVE, + /** The device is winding down its session. */ + SR_ST_STOPPING, }; /* @@ -514,7 +559,7 @@ enum { /** Device info IDs. */ enum { /** A list of options supported by the driver. */ - SR_DI_HWOPTS, + SR_DI_HWOPTS = 10000, /** A list of capabilities supported by the device. */ SR_DI_HWCAPS, /** The number of probes connected to this device. */ @@ -575,7 +620,7 @@ struct sr_dev_driver { const void *value); int (*dev_acquisition_start) (const struct sr_dev_inst *sdi, void *cb_data); - int (*dev_acquisition_stop) (const struct sr_dev_inst *sdi, + int (*dev_acquisition_stop) (struct sr_dev_inst *sdi, void *cb_data); /* Dynamic */