libsigrok
sigrok.h
Go to the documentation of this file.
00001 /*
00002  * This file is part of the sigrok project.
00003  *
00004  * Copyright (C) 2010-2012 Bert Vermeulen <bert@biot.com>
00005  *
00006  * This program is free software: you can redistribute it and/or modify
00007  * it under the terms of the GNU General Public License as published by
00008  * the Free Software Foundation, either version 3 of the License, or
00009  * (at your option) any later version.
00010  *
00011  * This program is distributed in the hope that it will be useful,
00012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00014  * GNU General Public License for more details.
00015  *
00016  * You should have received a copy of the GNU General Public License
00017  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
00018  */
00019 
00020 #ifndef LIBSIGROK_SIGROK_H
00021 #define LIBSIGROK_SIGROK_H
00022 
00023 #include <stdio.h>
00024 #include <sys/time.h>
00025 #include <stdint.h>
00026 #include <inttypes.h>
00027 #include <glib.h>
00028 
00029 #ifdef __cplusplus
00030 extern "C" {
00031 #endif
00032 
00033 /*
00034  * Package version macros (can be used for conditional compilation).
00035  */
00036 
00037 /** The libsigrok package 'major' version number. */
00038 #define SR_PACKAGE_VERSION_MAJOR 0
00039 
00040 /** The libsigrok package 'minor' version number. */
00041 #define SR_PACKAGE_VERSION_MINOR 1
00042 
00043 /** The libsigrok package 'micro' version number. */
00044 #define SR_PACKAGE_VERSION_MICRO 1
00045 
00046 /** The libsigrok package version ("major.minor.micro") as string. */
00047 #define SR_PACKAGE_VERSION_STRING "0.1.1"
00048 
00049 /*
00050  * Library/libtool version macros (can be used for conditional compilation).
00051  */
00052 
00053 /** The libsigrok libtool 'current' version number. */
00054 #define SR_LIB_VERSION_CURRENT 0
00055 
00056 /** The libsigrok libtool 'revision' version number. */
00057 #define SR_LIB_VERSION_REVISION 0
00058 
00059 /** The libsigrok libtool 'age' version number. */
00060 #define SR_LIB_VERSION_AGE 0
00061 
00062 /** The libsigrok libtool version ("current:revision:age") as string. */
00063 #define SR_LIB_VERSION_STRING "0:0:0"
00064 
00065 /*
00066  * Status/error codes returned by libsigrok functions.
00067  *
00068  * All possible return codes of libsigrok functions must be listed here.
00069  * Functions should never return hardcoded numbers as status, but rather
00070  * use these #defines instead. All error codes are negative numbers.
00071  *
00072  * The error codes are globally unique in libsigrok, i.e. if one of the
00073  * libsigrok functions returns a "malloc error" it must be exactly the same
00074  * return value as used by all other functions to indicate "malloc error".
00075  * There must be no functions which indicate two different errors via the
00076  * same return code.
00077  *
00078  * Also, for compatibility reasons, no defined return codes are ever removed
00079  * or reused for different #defines later. You can only add new #defines and
00080  * return codes, but never remove or redefine existing ones.
00081  */
00082 #define SR_OK                 0 /* No error */
00083 #define SR_ERR               -1 /* Generic/unspecified error */
00084 #define SR_ERR_MALLOC        -2 /* Malloc/calloc/realloc error */
00085 #define SR_ERR_ARG           -3 /* Function argument error */
00086 #define SR_ERR_BUG           -4 /* Errors hinting at internal bugs */
00087 #define SR_ERR_SAMPLERATE    -5 /* Incorrect samplerate */
00088 
00089 #define SR_MAX_NUM_PROBES    64 /* Limited by uint64_t. */
00090 #define SR_MAX_PROBENAME_LEN 32
00091 
00092 /* Handy little macros */
00093 #define SR_HZ(n)  (n)
00094 #define SR_KHZ(n) ((n) * 1000)
00095 #define SR_MHZ(n) ((n) * 1000000)
00096 #define SR_GHZ(n) ((n) * 1000000000)
00097 
00098 #define SR_HZ_TO_NS(n) (1000000000 / (n))
00099 
00100 /* libsigrok loglevels. */
00101 #define SR_LOG_NONE           0 /**< Output no messages at all. */
00102 #define SR_LOG_ERR            1 /**< Output error messages. */
00103 #define SR_LOG_WARN           2 /**< Output warnings. */
00104 #define SR_LOG_INFO           3 /**< Output informational messages. */
00105 #define SR_LOG_DBG            4 /**< Output debug messages. */
00106 #define SR_LOG_SPEW           5 /**< Output very noisy debug messages. */
00107 
00108 /*
00109  * Use SR_API to mark public API symbols, and SR_PRIV for private symbols.
00110  *
00111  * Variables and functions marked 'static' are private already and don't
00112  * need SR_PRIV. However, functions which are not static (because they need
00113  * to be used in other libsigrok-internal files) but are also not meant to
00114  * be part of the public libsigrok API, must use SR_PRIV.
00115  *
00116  * This uses the 'visibility' feature of gcc (requires gcc >= 4.0).
00117  *
00118  * This feature is not available on MinGW/Windows, as it is a feature of
00119  * ELF files and MinGW/Windows uses PE files.
00120  *
00121  * Details: http://gcc.gnu.org/wiki/Visibility
00122  */
00123 
00124 /* Marks public libsigrok API symbols. */
00125 #ifndef _WIN32
00126 #define SR_API __attribute__((visibility("default")))
00127 #else
00128 #define SR_API
00129 #endif
00130 
00131 /* Marks private, non-public libsigrok symbols (not part of the API). */
00132 #ifndef _WIN32
00133 #define SR_PRIV __attribute__((visibility("hidden")))
00134 #else
00135 #define SR_PRIV
00136 #endif
00137 
00138 typedef int (*sr_receive_data_callback_t)(int fd, int revents, void *cb_data);
00139 
00140 /* Data types used by hardware drivers for dev_config_set() */
00141 enum {
00142         SR_T_UINT64,
00143         SR_T_CHAR,
00144         SR_T_BOOL,
00145 };
00146 
00147 /* sr_datafeed_packet.type values */
00148 enum {
00149         SR_DF_HEADER,
00150         SR_DF_END,
00151         SR_DF_TRIGGER,
00152         SR_DF_LOGIC,
00153         SR_DF_PD,
00154 };
00155 
00156 struct sr_datafeed_packet {
00157         uint16_t type;
00158         void *payload;
00159 };
00160 
00161 struct sr_datafeed_header {
00162         int feed_version;
00163         struct timeval starttime;
00164         uint64_t samplerate;
00165         int num_logic_probes;
00166 };
00167 
00168 struct sr_datafeed_logic {
00169         uint64_t length;
00170         uint16_t unitsize;
00171         void *data;
00172 };
00173 
00174 struct sr_input {
00175         struct sr_input_format *format;
00176         char *param;
00177         struct sr_dev *vdev;
00178 };
00179 
00180 struct sr_input_format {
00181         char *id;
00182         char *description;
00183         int (*format_match) (const char *filename);
00184         int (*init) (struct sr_input *in);
00185         int (*loadfile) (struct sr_input *in, const char *filename);
00186 };
00187 
00188 struct sr_output {
00189         struct sr_output_format *format;
00190         struct sr_dev *dev;
00191         char *param;
00192         void *internal;
00193 };
00194 
00195 struct sr_output_format {
00196         char *id;
00197         char *description;
00198         int df_type;
00199         int (*init) (struct sr_output *o);
00200         int (*data) (struct sr_output *o, const uint8_t *data_in,
00201                      uint64_t length_in, uint8_t **data_out,
00202                      uint64_t *length_out);
00203         int (*event) (struct sr_output *o, int event_type, uint8_t **data_out,
00204                       uint64_t *length_out);
00205 };
00206 
00207 struct sr_datastore {
00208         /* Size in bytes of the number of units stored in this datastore */
00209         int ds_unitsize;
00210         unsigned int num_units; /* TODO: uint64_t */
00211         GSList *chunklist;
00212 };
00213 
00214 /*
00215  * This represents a generic device connected to the system.
00216  * For device-specific information, ask the driver. The driver_index refers
00217  * to the device index within that driver; it may be handling more than one
00218  * device. All relevant driver calls take a dev_index parameter for this.
00219  */
00220 struct sr_dev {
00221         /* Which driver handles this device */
00222         struct sr_dev_driver *driver;
00223         /* A driver may handle multiple devices of the same type */
00224         int driver_index;
00225         /* List of struct sr_probe* */
00226         GSList *probes;
00227         /* Data acquired by this device, if any */
00228         struct sr_datastore *datastore;
00229 };
00230 
00231 enum {
00232         SR_PROBE_TYPE_LOGIC,
00233 };
00234 
00235 struct sr_probe {
00236         int index;
00237         int type;
00238         gboolean enabled;
00239         char *name;
00240         char *trigger;
00241 };
00242 
00243 /* Hardware driver capabilities */
00244 enum {
00245         SR_HWCAP_DUMMY = 0, /* Used to terminate lists. Must be 0! */
00246 
00247         /*--- Device classes ------------------------------------------------*/
00248 
00249         /** The device can act as logic analyzer. */
00250         SR_HWCAP_LOGIC_ANALYZER,
00251 
00252         /* TODO: SR_HWCAP_SCOPE, SW_HWCAP_PATTERN_GENERATOR, etc.? */
00253 
00254         /*--- Device types --------------------------------------------------*/
00255 
00256         /** The device is demo device. */
00257         SR_HWCAP_DEMO_DEV,
00258 
00259         /*--- Device options ------------------------------------------------*/
00260 
00261         /** The device supports setting/changing its samplerate. */
00262         SR_HWCAP_SAMPLERATE,
00263 
00264         /* TODO: Better description? Rename to PROBE_AND_TRIGGER_CONFIG? */
00265         /** The device supports setting a probe mask. */
00266         SR_HWCAP_PROBECONFIG,
00267 
00268         /** The device supports setting a pre/post-trigger capture ratio. */
00269         SR_HWCAP_CAPTURE_RATIO,
00270 
00271         /* TODO? */
00272         /** The device supports setting a pattern (pattern generator mode). */
00273         SR_HWCAP_PATTERN_MODE,
00274 
00275         /** The device supports Run Length Encoding. */
00276         SR_HWCAP_RLE,
00277 
00278         /*--- Special stuff -------------------------------------------------*/
00279 
00280         /* TODO: Better description. */
00281         /** The device supports specifying a capturefile to inject. */
00282         SR_HWCAP_CAPTUREFILE,
00283 
00284         /* TODO: Better description. */
00285         /** The device supports specifying the capturefile unit size. */
00286         SR_HWCAP_CAPTURE_UNITSIZE,
00287 
00288         /* TODO: Better description. */
00289         /** The device supports setting the number of probes. */
00290         SR_HWCAP_CAPTURE_NUM_PROBES,
00291 
00292         /*--- Acquisition modes ---------------------------------------------*/
00293 
00294         /**
00295          * The device supports setting a sample time limit, i.e. how long the
00296          * sample acquisition should run (in ms).
00297          */
00298         SR_HWCAP_LIMIT_MSEC,
00299 
00300         /**
00301          * The device supports setting a sample number limit, i.e. how many
00302          * samples should be acquired.
00303          */
00304         SR_HWCAP_LIMIT_SAMPLES,
00305 
00306         /**
00307          * The device supports continuous sampling, i.e. neither a time limit
00308          * nor a sample number limit has to be supplied, it will just acquire
00309          * samples continuously, until explicitly stopped by a certain command.
00310          */
00311         SR_HWCAP_CONTINUOUS,
00312 
00313         /* TODO: SR_HWCAP_JUST_SAMPLE or similar. */
00314 };
00315 
00316 struct sr_hwcap_option {
00317         int hwcap;
00318         int type;
00319         char *description;
00320         char *shortname;
00321 };
00322 
00323 struct sr_dev_inst {
00324         int index;
00325         int status;
00326         int inst_type;
00327         char *vendor;
00328         char *model;
00329         char *version;
00330         void *priv;
00331 };
00332 
00333 /* sr_dev_inst types */
00334 enum {
00335         /** Device instance type for USB devices. */
00336         SR_INST_USB,
00337         /** Device instance type for serial port devices. */
00338         SR_INST_SERIAL,
00339 };
00340 
00341 /* Device instance status */
00342 enum {
00343         SR_ST_NOT_FOUND,
00344         /* Found, but still booting */
00345         SR_ST_INITIALIZING,
00346         /* Live, but not in use */
00347         SR_ST_INACTIVE,
00348         /* Actively in use in a session */
00349         SR_ST_ACTIVE,
00350 };
00351 
00352 /*
00353  * TODO: This sucks, you just kinda have to "know" the returned type.
00354  * TODO: Need a DI to return the number of trigger stages supported.
00355  */
00356 
00357 /* Device info IDs */
00358 enum {
00359         /* struct sr_dev_inst for this specific device */
00360         SR_DI_INST,
00361         /* The number of probes connected to this device */
00362         SR_DI_NUM_PROBES,
00363         /* The probe names on this device */
00364         SR_DI_PROBE_NAMES,
00365         /* Samplerates supported by this device, (struct sr_samplerates) */
00366         SR_DI_SAMPLERATES,
00367         /* Types of trigger supported, out of "01crf" (char *) */
00368         SR_DI_TRIGGER_TYPES,
00369         /* The currently set samplerate in Hz (uint64_t) */
00370         SR_DI_CUR_SAMPLERATE,
00371         /* Supported patterns (in pattern generator mode) */
00372         SR_DI_PATTERNS,
00373 };
00374 
00375 /*
00376  * A device supports either a range of samplerates with steps of a given
00377  * granularity, or is limited to a set of defined samplerates. Use either
00378  * step or list, but not both.
00379  */
00380 struct sr_samplerates {
00381         uint64_t low;
00382         uint64_t high;
00383         uint64_t step;
00384         uint64_t *list;
00385 };
00386 
00387 struct sr_dev_driver {
00388         /* Driver-specific */
00389         char *name;
00390         char *longname;
00391         int api_version;
00392         int (*init) (const char *devinfo);
00393         int (*cleanup) (void);
00394 
00395         /* Device-specific */
00396         int (*dev_open) (int dev_index);
00397         int (*dev_close) (int dev_index);
00398         void *(*dev_info_get) (int dev_index, int dev_info_id);
00399         int (*dev_status_get) (int dev_index);
00400         int *(*hwcap_get_all) (void);
00401         int (*dev_config_set) (int dev_index, int hwcap, void *value);
00402         int (*dev_acquisition_start) (int dev_index, void *session_dev_id);
00403         int (*dev_acquisition_stop) (int dev_index, void *session_dev_id);
00404 };
00405 
00406 struct sr_session {
00407         /* List of struct sr_dev* */
00408         GSList *devs;
00409         /* list of sr_receive_data_callback_t */
00410         GSList *datafeed_callbacks;
00411         GTimeVal starttime;
00412         gboolean running;
00413 };
00414 
00415 #include "sigrok-proto.h"
00416 
00417 #ifdef __cplusplus
00418 }
00419 #endif
00420 
00421 #endif
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines