Add sr_spew/SR_LOG_SPEW for even more debug output.

[libsigrok.git] / sigrok.h

diff --git a/sigrok.h b/sigrok.h
index db747075fc6fb75ddb4fe54b98eaeaa94f9a7a49..898785612e60dd3a696fbd195c66d564a478cda1 100644 (file)
--- a/sigrok.h
+++ b/sigrok.h
@@ -53,7 +53,8 @@ extern "C" {
 #define SR_OK                 0 /* No error */
 #define SR_ERR               -1 /* Generic/unspecified error */
 #define SR_ERR_MALLOC        -2 /* Malloc/calloc/realloc error */
-#define SR_ERR_SAMPLERATE    -3 /* Incorrect samplerate */
+#define SR_ERR_ARG           -3 /* Function argument error */
+#define SR_ERR_SAMPLERATE    -4 /* Incorrect samplerate */
 
 #define SR_MAX_NUM_PROBES      64 /* Limited by uint64_t. */
 #define SR_MAX_PROBENAME_LEN   32
@@ -66,6 +67,14 @@ extern "C" {
 
 #define SR_HZ_TO_NS(n) (1000000000 / (n))
 
+/* libsigrok loglevels. */
+#define SR_LOG_NONE    0
+#define SR_LOG_ERR     1
+#define SR_LOG_WARN    2
+#define SR_LOG_INFO    3
+#define SR_LOG_DBG     4
+#define SR_LOG_SPEW    5
+
 typedef int (*sr_receive_data_callback) (int fd, int revents, void *user_data);
 
 /* Data types used by hardware plugins for set_configuration() */
@@ -79,12 +88,14 @@ enum {
        SR_PROTO_RAW,
 };
 
+#if 0
 /* (Unused) protocol decoder stack entry */
 struct sr_protocol {
        char *name;
        int id;
        int stackindex;
 };
+#endif
 
 /* sr_datafeed_packet.type values */
 enum {
@@ -112,6 +123,7 @@ struct sr_datafeed_header {
        int num_logic_probes;
 };
 
+#if defined(HAVE_LA_ALSA)
 struct sr_analog_probe {
        uint8_t att;
        uint8_t res;    /* Needs to be a power of 2, FIXME */
@@ -122,6 +134,7 @@ struct sr_analog_sample {
        uint8_t num_probes; /* Max hardware probes is 256 */
        struct sr_analog_probe probes[];
 };
+#endif
 
 struct sr_input {
        struct sr_input_format *format;
@@ -130,7 +143,7 @@ struct sr_input {
 };
 
 struct sr_input_format {
-       char *extension;
+       char *id;
        char *description;
        int (*format_match) (const char *filename);
        int (*init) (struct sr_input *in);
@@ -145,7 +158,7 @@ struct sr_output {
 };
 
 struct sr_output_format {
-       char *extension;
+       char *id;
        char *description;
        int df_type;
        int (*init) (struct sr_output *o);
@@ -155,6 +168,7 @@ struct sr_output_format {
                      uint64_t *length_out);
 };
 
+#if 0
 struct sr_analyzer {
        char *name;
        char *filename;
@@ -163,9 +177,7 @@ struct sr_analyzer {
         * TODO: Input and output format?
         */
 };
-
-/* Size of a chunk in units */
-#define DATASTORE_CHUNKSIZE 512000
+#endif
 
 struct sr_datastore {
        /* Size in bytes of the number of units stored in this datastore */
@@ -204,29 +216,72 @@ struct sr_probe {
        char *trigger;
 };
 
+/* TODO: Get rid of this global variable. */
 extern GSList *devices;
 
 /* Hardware plugin capabilities */
 enum {
        SR_HWCAP_DUMMY,             /* Used to terminate lists */
-       /* device classes */
+
+       /*--- Device classes ------------------------------------------------*/
+
+       /** The device can act as logic analyzer. */
        SR_HWCAP_LOGIC_ANALYZER,
 
-       /* device options */
-       SR_HWCAP_SAMPLERATE,        /* Change samplerate */
-       SR_HWCAP_PROBECONFIG,       /* Configure probe mask */
-       SR_HWCAP_CAPTURE_RATIO,     /* Set pre/post-trigger capture ratio */
-       SR_HWCAP_PATTERN_MODE,      /* Pattern generator mode */
+       /* TODO: SR_HWCAP_SCOPE, SW_HWCAP_PATTERN_GENERATOR, etc.? */
+
+       /*--- Device options ------------------------------------------------*/
+
+       /** The device supports setting/changing its samplerate. */
+       SR_HWCAP_SAMPLERATE,
+
+       /* TODO: Better description? Rename to PROBE_AND_TRIGGER_CONFIG? */
+       /** The device supports setting a probe mask. */
+       SR_HWCAP_PROBECONFIG,
+
+       /** The device supports setting a pre/post-trigger capture ratio. */
+       SR_HWCAP_CAPTURE_RATIO,
 
-       /* special stuff */
-       SR_HWCAP_CAPTUREFILE,       /* capturefile to inject */
-       SR_HWCAP_CAPTURE_UNITSIZE,  /* unitsize of capturefile data */
-       SR_HWCAP_CAPTURE_NUM_PROBES,/* set number of probes */
+       /* TODO? */
+       /** The device supports setting a pattern (pattern generator mode). */
+       SR_HWCAP_PATTERN_MODE,
 
-       /* acquisition modes */
-       SR_HWCAP_LIMIT_MSEC,        /* Set a time limit for sample acquisition */
-       SR_HWCAP_LIMIT_SAMPLES,     /* Set a limit on number of samples */
+       /*--- Special stuff -------------------------------------------------*/
+
+       /* TODO: Better description. */
+       /** The device supports specifying a capturefile to inject. */
+       SR_HWCAP_CAPTUREFILE,
+
+       /* TODO: Better description. */
+       /** The device supports specifying the capturefile unit size. */
+       SR_HWCAP_CAPTURE_UNITSIZE,
+
+       /* TODO: Better description. */
+       /** 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).
+        */
+       SR_HWCAP_LIMIT_MSEC,
+
+       /**
+        * The device supports setting a sample number limit, i.e. how many
+        * samples should be acquired.
+        */
+       SR_HWCAP_LIMIT_SAMPLES,
+
+       /**
+        * The device supports continuous sampling, i.e. 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,
+
+       /* TODO: SR_HWCAP_JUST_SAMPLE or similar. */
 };
 
 struct sr_hwcap_option {
@@ -322,8 +377,8 @@ struct sr_device_plugin {
        void (*cleanup) (void);
 
        /* Device-specific */
-       int (*open) (int device_index);
-       void (*close) (int device_index);
+       int (*opendev) (int device_index);
+       int (*closedev) (int device_index);
        void *(*get_device_info) (int device_index, int device_info_id);
        int (*get_status) (int device_index);
        int *(*get_capabilities) (void);