BLAHAJ
/
libsigrok
10
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Make API docs more consistent, avoid tabs to line up comments.

This commit is contained in:
Bert Vermeulen 2013-12-09 22:49:12 +01:00
parent 5483bb8349
commit 98582bf53f
3 changed files with 161 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
libsigrok-internal.h
View File

@ -66,9 +66,12 @@ struct sr_context {
#ifdef HAVE_LIBUSB_1_0 #ifdef HAVE_LIBUSB_1_0
/** USB device instance */ /** USB device instance */
struct sr_usb_dev_inst { struct sr_usb_dev_inst {
uint8_t bus; /**< USB bus */ /** USB bus */
uint8_t address; /**< Device address on USB bus */ uint8_t bus;
struct libusb_device_handle *devhdl; /**< libusb device handle */ /** Device address on USB bus */
uint8_t address;
/** libusb device handle */
struct libusb_device_handle *devhdl;
}; };
#endif #endif
@ -77,10 +80,14 @@ struct sr_usb_dev_inst {
#define SERIAL_PARITY_EVEN SP_PARITY_EVEN #define SERIAL_PARITY_EVEN SP_PARITY_EVEN
#define SERIAL_PARITY_ODD SP_PARITY_ODD #define SERIAL_PARITY_ODD SP_PARITY_ODD
struct sr_serial_dev_inst { struct sr_serial_dev_inst {
char *port; /**< Port name, e.g. '/dev/tty42'. */ /** Port name, e.g. '/dev/tty42'. */
char *serialcomm; /**< Comm params for serial_set_paramstr(). */ char *port;
/** Comm params for serial_set_paramstr(). */
char *serialcomm;
/** Port is non-blocking. */
int nonblocking; int nonblocking;
struct sp_port *data; /**< libserialport port handle */ /** libserialport port handle */
struct sp_port *data;
}; };
#endif #endif
@ -91,7 +98,8 @@ struct sr_usbtmc_dev_inst {
/* Private driver context. */ /* Private driver context. */
struct drv_context { struct drv_context {
struct sr_context *sr_ctx; /**< sigrok context */ /** sigrok context */
struct sr_context *sr_ctx;
GSList *instances; GSList *instances;
}; };
@ -169,9 +177,10 @@ struct sr_session {
* an async fashion. We need to make sure the session is stopped from * an async fashion. We need to make sure the session is stopped from
* within the session thread itself. * within the session thread itself.
*/ */
GMutex stop_mutex; /**< Mutex protecting access to abort_session. */ /** Mutex protecting access to abort_session. */
GMutex stop_mutex;
/** Abort current session. See sr_session_stop(). */
gboolean abort_session; gboolean abort_session;
/**< Abort current session. See sr_session_stop(). */
}; };
SR_PRIV int sr_session_send(const struct sr_dev_inst *sdi, SR_PRIV int sr_session_send(const struct sr_dev_inst *sdi,

216
libsigrok.h
View File

@ -149,15 +149,22 @@ enum {
/** Value for sr_datafeed_packet.type. */ /** Value for sr_datafeed_packet.type. */
enum { enum {
SR_DF_HEADER = 10000, /**< Payload is sr_datafeed_header. */ /** Payload is sr_datafeed_header. */
SR_DF_END, /**< End of stream (no further data). */ SR_DF_HEADER = 10000,
SR_DF_META, /**< Payload is struct sr_datafeed_meta */ /** End of stream (no further data). */
SR_DF_TRIGGER, /**< The trigger matched at this point in the data feed. SR_DF_END,
No payload. */ /** Payload is struct sr_datafeed_meta */
SR_DF_LOGIC, /**< Payload is struct sr_datafeed_logic. */ SR_DF_META,
SR_DF_ANALOG, /**< Payload is struct sr_datafeed_analog. */ /** The trigger matched at this point in the data feed. No payload. */
SR_DF_FRAME_BEGIN, /**< Beginning of frame. No payload. */ SR_DF_TRIGGER,
SR_DF_FRAME_END, /**< End of frame. No payload. */ /** Payload is struct sr_datafeed_logic. */
SR_DF_LOGIC,
/** Payload is struct sr_datafeed_analog. */
SR_DF_ANALOG,
/** Beginning of frame. No payload. */
SR_DF_FRAME_BEGIN,
/** End of frame. No payload. */
SR_DF_FRAME_END,
}; };
/** Measured quantity, sr_datafeed_analog.mq. */ /** Measured quantity, sr_datafeed_analog.mq. */
@ -168,34 +175,53 @@ enum {
SR_MQ_CAPACITANCE, SR_MQ_CAPACITANCE,
SR_MQ_TEMPERATURE, SR_MQ_TEMPERATURE,
SR_MQ_FREQUENCY, SR_MQ_FREQUENCY,
SR_MQ_DUTY_CYCLE, /**< Duty cycle, e.g. on/off ratio. */ /** Duty cycle, e.g. on/off ratio. */
SR_MQ_CONTINUITY, /**< Continuity test. */ SR_MQ_DUTY_CYCLE,
/** Continuity test. */
SR_MQ_CONTINUITY,
SR_MQ_PULSE_WIDTH, SR_MQ_PULSE_WIDTH,
SR_MQ_CONDUCTANCE, SR_MQ_CONDUCTANCE,
SR_MQ_POWER, /**< Electrical power, usually in W, or dBm. */ /** Electrical power, usually in W, or dBm. */
SR_MQ_GAIN, /**< Gain (a transistor's gain, or hFE, for example). */ SR_MQ_POWER,
/** Gain (a transistor's gain, or hFE, for example). */
SR_MQ_GAIN,
/** Logarithmic representation of sound pressure relative to a /** Logarithmic representation of sound pressure relative to a
* reference value. */ * reference value. */
SR_MQ_SOUND_PRESSURE_LEVEL, SR_MQ_SOUND_PRESSURE_LEVEL,
SR_MQ_CARBON_MONOXIDE, /**< Carbon monoxide level */ /** Carbon monoxide level */
SR_MQ_RELATIVE_HUMIDITY,/**< Humidity */ SR_MQ_CARBON_MONOXIDE,
SR_MQ_TIME, /**< Time */ /** Humidity */
SR_MQ_RELATIVE_HUMIDITY,
/** Time */
SR_MQ_TIME,
}; };
/** Unit of measured quantity, sr_datafeed_analog.unit. */ /** Unit of measured quantity, sr_datafeed_analog.unit. */
enum { enum {
SR_UNIT_VOLT = 10000, /**< Volt */ /** Volt */
SR_UNIT_AMPERE, /**< Ampere (current). */ SR_UNIT_VOLT = 10000,
SR_UNIT_OHM, /**< Ohm (resistance). */ /** Ampere (current). */
SR_UNIT_FARAD, /**< Farad (capacity). */ SR_UNIT_AMPERE,
SR_UNIT_KELVIN, /**< Kelvin (temperature). */ /** Ohm (resistance). */
SR_UNIT_CELSIUS, /**< Degrees Celsius (temperature). */ SR_UNIT_OHM,
SR_UNIT_FAHRENHEIT, /**< Degrees Fahrenheit (temperature). */ /** Farad (capacity). */
SR_UNIT_HERTZ, /**< Hertz (frequency, 1/s, [Hz]). */ SR_UNIT_FARAD,
SR_UNIT_PERCENTAGE, /**< Percent value. */ /** Kelvin (temperature). */
SR_UNIT_BOOLEAN, /**< Boolean value. */ SR_UNIT_KELVIN,
SR_UNIT_SECOND, /**< Time in seconds. */ /** Degrees Celsius (temperature). */
SR_UNIT_SIEMENS, /**< Unit of conductance, the inverse of resistance. */ SR_UNIT_CELSIUS,
/** Degrees Fahrenheit (temperature). */
SR_UNIT_FAHRENHEIT,
/** Hertz (frequency, 1/s, [Hz]). */
SR_UNIT_HERTZ,
/** Percent value. */
SR_UNIT_PERCENTAGE,
/** Boolean value. */
SR_UNIT_BOOLEAN,
/** Time in seconds. */
SR_UNIT_SECOND,
/** Unit of conductance, the inverse of resistance. */
SR_UNIT_SIEMENS,
/** /**
* An absolute measurement of power, in decibels, referenced to * An absolute measurement of power, in decibels, referenced to
* 1 milliwatt (dBu). * 1 milliwatt (dBu).
@ -217,10 +243,14 @@ enum {
* represented as the fraction of number of particles of the substance. * represented as the fraction of number of particles of the substance.
*/ */
SR_UNIT_CONCENTRATION, SR_UNIT_CONCENTRATION,
SR_UNIT_REVOLUTIONS_PER_MINUTE, /**< Revolutions per minute. */ /** Revolutions per minute. */
SR_UNIT_VOLT_AMPERE, /**< Apparent power [VA]. */ SR_UNIT_REVOLUTIONS_PER_MINUTE,
SR_UNIT_WATT, /**< Real power [W]. */ /** Apparent power [VA]. */
SR_UNIT_WATT_HOUR, /**< Consumption [Wh]. */ SR_UNIT_VOLT_AMPERE,
/** Real power [W]. */
SR_UNIT_WATT,
/** Consumption [Wh]. */
SR_UNIT_WATT_HOUR,
}; };
/** Values for sr_datafeed_analog.flags. */ /** Values for sr_datafeed_analog.flags. */
@ -302,7 +332,8 @@ struct sr_datafeed_logic {
struct sr_datafeed_analog { struct sr_datafeed_analog {
/** The probes for which data is included in this packet. */ /** The probes for which data is included in this packet. */
GSList *probes; GSList *probes;
int num_samples; /**< Number of samples in data */ /** Number of samples in data */
int num_samples;
/** Measured quantity (voltage, current, temperature, and so on). /** Measured quantity (voltage, current, temperature, and so on).
* Use SR_MQ_VOLTAGE, ... */ * Use SR_MQ_VOLTAGE, ... */
int mq; int mq;
@ -438,7 +469,8 @@ struct sr_output_format {
*/ */
char *description; char *description;
int df_type; /**< Datafeed type, SR_DF_HEADER, etc. */ /** Datafeed type, SR_DF_HEADER, etc. */
int df_type;
/** /**
* This function is called once, at the beginning of an output stream. * This function is called once, at the beginning of an output stream.
@ -557,18 +589,25 @@ struct sr_output_format {
/** Constants for probe type. */ /** Constants for probe type. */
enum { enum {
SR_PROBE_LOGIC = 10000, /**< Probe type is logic probe. */ /** Probe type is logic probe. */
SR_PROBE_ANALOG, /**< Probe type is analog probe. */ SR_PROBE_LOGIC = 10000,
/** Probe type is analog probe. */
SR_PROBE_ANALOG,
}; };
/** Information on single probe. */ /** Information on single probe. */
struct sr_probe { struct sr_probe {
int index; /**< Number of probe, starting at 0. @deprecated The /** Number of probes, starting at 0. @deprecated The index field
index field will go: use g_slist_length(sdi->probes) instead. */ * will go: use g_slist_length(sdi->probes) instead. */
int type; /**< Probe type (SR_PROBE_LOGIC, ...) */ int index;
gboolean enabled; /**< Is this probe enabled? */ /** Probe type (SR_PROBE_LOGIC, ...) */
char *name;/**< Name of probe. */ int type;
char *trigger;/**< Trigger string, format like used by sigrok-cli */ /** Is this probe enabled? */
gboolean enabled;
/** Name of probe. */
char *name;
/** Trigger string, format like used by sigrok-cli */
char *trigger;
}; };
/** Structure for groups of probes that have common properties. */ /** Structure for groups of probes that have common properties. */
@ -583,17 +622,24 @@ struct sr_probe_group {
/** Used for setting or getting value of a config item. */ /** Used for setting or getting value of a config item. */
struct sr_config { struct sr_config {
int key; /**< Config key like SR_CONF_CONN, etc. */ /** Config key like SR_CONF_CONN, etc. */
GVariant *data; /**< Key-specific data. */ int key;
/** Key-specific data. */
GVariant *data;
}; };
/** Information about a config key. */ /** Information about a config key. */
struct sr_config_info { struct sr_config_info {
int key; /**< Config key like SR_CONF_CONN, etc. */ /** Config key like SR_CONF_CONN, etc. */
int datatype; /**< Data type like SR_T_CHAR, etc. */ int key;
char *id; /**< Id string, e.g. "serialcomm". */ /** Data type like SR_T_CHAR, etc. */
char *name; /**< Name, e.g. "Serial communication". */ int datatype;
char *description; /**< Verbose description (unused currently). */ /** Id string, e.g. "serialcomm". */
char *id;
/** Name, e.g. "Serial communication". */
char *name;
/** Verbose description (unused currently). */
char *description;
}; };
/** Constants for device classes */ /** Constants for device classes */
@ -803,21 +849,31 @@ enum {
SR_CONF_DATALOG, SR_CONF_DATALOG,
}; };
/** @private /** Device instance data
* Device instance data
*/ */
struct sr_dev_inst { struct sr_dev_inst {
struct sr_dev_driver *driver; /**< Device driver. */ /** Device driver. */
int index; /**< Index of device in driver. */ struct sr_dev_driver *driver;
int status; /**< Device instance status. SR_ST_NOT_FOUND, etc. */ /** Index of device in driver. */
int inst_type; /**< Device instance type. SR_INST_USB, etc. */ int index;
char *vendor; /**< Device vendor. */ /** Device instance status. SR_ST_NOT_FOUND, etc. */
char *model; /**< Device model. */ int status;
char *version; /**< Device version. */ /** Device instance type. SR_INST_USB, etc. */
GSList *probes; /**< List of probes. */ int inst_type;
GSList *probe_groups; /**< List of sr_probe_group structs */ /** Device vendor. */
void *conn; /**< Device instance connection data (used?) */ char *vendor;
void *priv; /**< Device instance private data (used?) */ /** Device model. */
char *model;
/** Device version. */
char *version;
/** List of probes. */
GSList *probes;
/** List of sr_probe_group structs */
GSList *probe_groups;
/** Device instance connection data (used?) */
void *conn;
/** Device instance private data (used?) */
void *priv;
}; };
/** Types of device instance, struct sr_dev_inst.type */ /** Types of device instance, struct sr_dev_inst.type */
@ -847,13 +903,20 @@ enum {
/** Device driver data */ /** Device driver data */
struct sr_dev_driver { struct sr_dev_driver {
/* Driver-specific */ /* Driver-specific */
char *name; /**< Driver name */ /** Driver name */
char *longname; /**< Long name, e.g. device name. */ char *name;
int api_version; /**< API version (currently 1). */ /** Long name, e.g. device name. */
int (*init) (struct sr_context *sr_ctx); /**< Init driver */ char *longname;
int (*cleanup) (void); /**< Free driver */ /** API version (currently 1). */
GSList *(*scan) (GSList *options); /**< Scan for devices */ int api_version;
GSList *(*dev_list) (void); /**< Get device list */ /** Init driver */
int (*init) (struct sr_context *sr_ctx);
/** Free driver */
int (*cleanup) (void);
/** Scan for devices */
GSList *(*scan) (GSList *options);
/** Get device list */
GSList *(*dev_list) (void);
int (*dev_clear) (void); int (*dev_clear) (void);
int (*config_get) (int id, GVariant **data, int (*config_get) (int id, GVariant **data,
const struct sr_dev_inst *sdi, const struct sr_dev_inst *sdi,
@ -866,15 +929,20 @@ struct sr_dev_driver {
const struct sr_probe_group *probe_group); const struct sr_probe_group *probe_group);
/* Device-specific */ /* Device-specific */
int (*dev_open) (struct sr_dev_inst *sdi); /**< Open device */ /** Open device */
int (*dev_close) (struct sr_dev_inst *sdi); /**< Close device */ int (*dev_open) (struct sr_dev_inst *sdi);
/** Close device */
int (*dev_close) (struct sr_dev_inst *sdi);
/** Start data aquisition. */
int (*dev_acquisition_start) (const struct sr_dev_inst *sdi, int (*dev_acquisition_start) (const struct sr_dev_inst *sdi,
void *cb_data); /**< Start data aquisition. */ void *cb_data);
/** Stop data aquisition. */
int (*dev_acquisition_stop) (struct sr_dev_inst *sdi, int (*dev_acquisition_stop) (struct sr_dev_inst *sdi,
void *cb_data); /**< Stop data aquisition. */ void *cb_data);
/* Dynamic */ /* Dynamic */
void *priv; /**< Device driver private data */ /** Device driver private data */
void *priv;
}; };
/** /**

2
session.c
View File

@ -75,7 +75,7 @@ struct sr_session *session;
* The same question applies to all the other session functions. * The same question applies to all the other session functions.
* *
* @retval NULL Error. * @retval NULL Error.
* @retval other A pointer to the newly allocated session-> * @retval other A pointer to the newly allocated session.
*/ */
SR_API struct sr_session *sr_session_new(void) SR_API struct sr_session *sr_session_new(void)
{ {