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

Improved doxygen docs.

This commit is contained in:
Matthias Heidbrink 2013-11-22 20:40:52 +01:00 committed by Bert Vermeulen
parent 86fa0ef594
commit 04cb915716
8 changed files with 282 additions and 180 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
backend.c
View File

@ -119,7 +119,8 @@ extern struct sr_session *session;
/**
* Sanity-check all libsigrok drivers.
*
* @return SR_OK if all drivers are OK, SR_ERR if one or more have issues.
* @retval SR_OK All drivers are OK
* @retval SR_ERR One or more drivers have issues.
*/
static int sanity_check_all_drivers(void)
{
@ -209,7 +210,8 @@ static int sanity_check_all_drivers(void)
/**
* Sanity-check all libsigrok input modules.
*
* @return SR_OK if all modules are OK, SR_ERR if one or more have issues.
* @retval SR_OK All modules are OK
* @retval SR_ERR One or more modules have issues.
*/
static int sanity_check_all_input_modules(void)
{
@ -258,7 +260,8 @@ static int sanity_check_all_input_modules(void)
/**
* Sanity-check all libsigrok output modules.
*
* @return SR_OK if all modules are OK, SR_ERR if one or more have issues.
* @retval SR_OK All modules are OK
* @retval SR_ERR One or more modules have issues.
*/
static int sanity_check_all_output_modules(void)
{
@ -382,7 +385,8 @@ done:
*
* @param ctx Pointer to a libsigrok context struct. Must not be NULL.
*
* @return SR_OK upon success, a (negative) error code otherwise.
* @retval SR_OK Success
* @retval other Error code SR_ERR, ...
*
* @since 0.2.0
*/

76
device.c
View File

@ -46,7 +46,15 @@
* @{
*/
/** @private */
/** @private
* Allocate and initialize new struct sr_probe
* @param[in] index \copydoc sr_probe::index
* @param[in] type \copydoc sr_probe::type
* @param[in] enabled \copydoc sr_probe::enabled
* @param[in] name \copydoc sr_probe::name
*
* @return NULL (failure) or new struct sr_probe*.
*/
SR_PRIV struct sr_probe *sr_probe_new(int index, int type,
gboolean enabled, const char *name)
{
@ -73,9 +81,9 @@ SR_PRIV struct sr_probe *sr_probe_new(int index, int type,
* removed, and the new name will be saved instead.
*
* @param sdi The device instance the probe is connected to.
* @param probenum The number of the probe whose name to set.
* @param[in] probenum The number of the probe whose name to set.
* Note that the probe numbers start at 0.
* @param name The new name that the specified probe should get. A copy
* @param[in] name The new name that the specified probe should get. A copy
* of the string is made.
*
* @return SR_OK on success, or SR_ERR_ARG on invalid arguments.
@ -148,9 +156,9 @@ SR_API int sr_dev_probe_enable(const struct sr_dev_inst *sdi, int probenum,
* If the specified probe of this device already has a trigger, it will
* be silently replaced.
*
* @param sdi Must not be NULL.
* @param probenum The probe number, starting from 0.
* @param trigger Trigger string, in the format used by sigrok-cli
* @param[in,out] sdi Pointer to the device instance; must not be NULL.
* @param[in] probenum Number of probe, starting at 0.
* @param[in] trigger Trigger string, in the format used by sigrok-cli
*
* @return SR_OK on success, or SR_ERR_ARG on invalid arguments.
*
@ -189,12 +197,12 @@ SR_API int sr_dev_trigger_set(const struct sr_dev_inst *sdi, int probenum,
* If the device's 'driver' field is NULL (virtual device), this
* function will always return FALSE (virtual devices don't have
* a hardware capabilities list).
* @param key The option that should be checked for support on the
* @param[in] key The option that should be checked for is supported by the
* specified device.
*
* @return TRUE if the device has the specified option, FALSE otherwise.
* FALSE is also returned on invalid input parameters or other
* error conditions.
* @retval TRUE Device has the specified option
* @retval FALSE Device does not have the specified option, invalid input
* parameters or other error conditions.
*
* @since 0.2.0
*/
@ -225,7 +233,18 @@ SR_API gboolean sr_dev_has_option(const struct sr_dev_inst *sdi, int key)
return ret;
}
/** @private */
/** @private
* Allocate and init new device instance struct.
* \param[in] index \copydoc sr_dev_inst::index
* \param[in] status \copydoc sr_dev_inst::status
* \param[in] vendor \copydoc sr_dev_inst::vendor
* \param[in] model \copydoc sr_dev_inst::model
* \param[in] version \copydoc sr_dev_inst::version
*
* \retval NULL Error
* \retval struct sr_dev_inst *. Dynamically allocated, free using
* sr_dev_inst_free().
*/
SR_PRIV struct sr_dev_inst *sr_dev_inst_new(int index, int status,
const char *vendor, const char *model, const char *version)
{
@ -251,7 +270,10 @@ SR_PRIV struct sr_dev_inst *sr_dev_inst_new(int index, int status,
return sdi;
}
/** @private */
/** @private
* Free device instance struct created by sr_dev_inst().
* \param sdi struct* to free.
*/
SR_PRIV void sr_dev_inst_free(struct sr_dev_inst *sdi)
{
struct sr_probe *probe;
@ -276,7 +298,15 @@ SR_PRIV void sr_dev_inst_free(struct sr_dev_inst *sdi)
#ifdef HAVE_LIBUSB_1_0
/** @private */
/** @private
* Allocate and init struct for USB device instance.
* \param[in] bus \copydoc sr_usb_dev_inst::bus
* \param[in] address \copydoc sr_usb_dev_inst::address
* \param[in] hdl \copydoc sr_usb_dev_inst::devhdl
*
* \retval NULL Error
* \retval other struct sr_usb_dev_inst * for USB device instance.
*/
SR_PRIV struct sr_usb_dev_inst *sr_usb_dev_inst_new(uint8_t bus,
uint8_t address, struct libusb_device_handle *hdl)
{
@ -294,7 +324,10 @@ SR_PRIV struct sr_usb_dev_inst *sr_usb_dev_inst_new(uint8_t bus,
return udi;
}
/** @private */
/** @private
* Free struct * allocated by sr_usb_dev_inst().
* \param usb struct* to free. Must not be NULL.
*/
SR_PRIV void sr_usb_dev_inst_free(struct sr_usb_dev_inst *usb)
{
g_free(usb);
@ -310,12 +343,12 @@ SR_PRIV void sr_usb_dev_inst_free(struct sr_usb_dev_inst *usb)
* Both parameters are copied to newly allocated strings, and freed
* automatically by sr_serial_dev_inst_free().
*
* @param pathname OS-specific serial port specification. Examples:
* @param[in] port OS-specific serial port specification. Examples:
* "/dev/ttyUSB0", "/dev/ttyACM1", "/dev/tty.Modem-0", "COM1".
* @param serialcomm A serial communication parameters string, in the form
* of <speed>/<data bits><parity><stopbits>, for example
* "9600/8n1" or "600/7o2". This is an optional parameter;
* it may be filled in later.
* @param[in] serialcomm A serial communication parameters string, in the form
* of \<speed\>/\<data bits\>\<parity\>\<stopbits\>, for example
* "9600/8n1" or "600/7o2". This is an optional parameter;
* it may be filled in later.
*
* @return A pointer to a newly initialized struct sr_serial_dev_inst,
* or NULL on error.
@ -342,7 +375,10 @@ SR_PRIV struct sr_serial_dev_inst *sr_serial_dev_inst_new(const char *port,
return serial;
}
/** @private */
/** @private
* Free struct sr_serial_dev_inst * allocated by sr_serial_dev_inst().
* \param serial struct sr_serial_dev_inst * to free. Must not be NULL.
*/
SR_PRIV void sr_serial_dev_inst_free(struct sr_serial_dev_inst *serial)
{
g_free(serial->port);

44
hardware/common/serial.c
View File

@ -268,14 +268,17 @@ SR_PRIV int serial_read(struct sr_serial_dev_inst *serial, void *buf,
* Set serial parameters for the specified serial port.
*
* @param serial Previously initialized serial port structure.
* @param baudrate The baudrate to set.
* @param bits The number of data bits to use.
* @param parity The parity setting to use (0 = none, 1 = even, 2 = odd).
* @param stopbits The number of stop bits to use (1 or 2).
* @param flowcontrol The flow control settings to use (0 = none, 1 = RTS/CTS,
* 2 = XON/XOFF).
* @param[in] baudrate The baudrate to set.
* @param[in] bits The number of data bits to use (5, 6, 7 or 8).
* @param[in] parity The parity setting to use (0 = none, 1 = even, 2 = odd).
* @param[in] stopbits The number of stop bits to use (1 or 2).
* @param[in] flowcontrol The flow control settings to use (0 = none,
* 1 = RTS/CTS, 2 = XON/XOFF).
* @param[in] rts Status of RTS line (0 or 1; required by some interfaces).
* @param[in] dtr Status of DTR line (0 or 1; required by some interfaces).
*
* @return SR_OK upon success, SR_ERR upon failure.
* @retval SR_OK Success
* @retval SR_ERR Failure.
*/
SR_PRIV int serial_set_params(struct sr_serial_dev_inst *serial, int baudrate,
int bits, int parity, int stopbits,
@ -341,11 +344,13 @@ SR_PRIV int serial_set_params(struct sr_serial_dev_inst *serial, int baudrate,
* Set serial parameters for the specified serial port.
*
* @param serial Previously initialized serial port structure.
* @param paramstr A serial communication parameters string, in the form
* of <speed>/<data bits><parity><stopbits><flow>, for example "9600/8n1" or
* "600/7o2" or "460800/8n1/flow=2" where flow is 0 for none, 1 for rts/cts and 2 for xon/xoff.
* @param[in] paramstr A serial communication parameters string, in the form
* of \<speed\>/\<data bits\>\<parity\>\<stopbits\>\<flow\>, for example
* "9600/8n1" or "600/7o2" or "460800/8n1/flow=2" where flow is 0 for none,
* 1 for rts/cts and 2 for xon/xoff.
*
* @return SR_OK upon success, SR_ERR upon failure.
* @retval SR_OK Success.
* @retval SR_ERR Failure.
*/
#define SERIAL_COMM_SPEC "^(\\d+)/([5678])([neo])([12])(.*)$"
SR_PRIV int serial_set_paramstr(struct sr_serial_dev_inst *serial,
@ -448,11 +453,12 @@ SR_PRIV int serial_set_paramstr(struct sr_serial_dev_inst *serial,
* @param serial Previously initialized serial port structure.
* @param buf Buffer where to store the bytes that are read.
* @param buflen Size of the buffer.
* @param timeout_ms How long to wait for a line to come in.
* @param[in] timeout_ms How long to wait for a line to come in.
*
* Reading stops when CR of LR is found, which is stripped from the buffer.
*
* @return SR_OK on success, SR_ERR on failure.
* @retval SR_OK Success.
* @retval SR_ERR Failure.
*/
SR_PRIV int serial_readline(struct sr_serial_dev_inst *serial, char **buf,
int *buflen, gint64 timeout_ms)
@ -507,17 +513,17 @@ SR_PRIV int serial_readline(struct sr_serial_dev_inst *serial, char **buf,
*
* @param serial Previously initialized serial port structure.
* @param buf Buffer containing the bytes to write.
* @param count Size of the buffer.
* @param packet_size Size, in bytes, of a valid packet.
* @param buflen Size of the buffer.
* @param[in] packet_size Size, in bytes, of a valid packet.
* @param is_valid Callback that assesses whether the packet is valid or not.
* @param timeout_ms The timeout after which, if no packet is detected, to
* @param[in] timeout_ms The timeout after which, if no packet is detected, to
* abort scanning.
* @param baudrate The baudrate of the serial port. This parameter is not
* @param[in] baudrate The baudrate of the serial port. This parameter is not
* critical, but it helps fine tune the serial port polling
* delay.
*
* @return SR_OK if a valid packet is found within the given timeout,
* SR_ERR upon failure.
* @retval SR_OK Valid packet was found within the given timeout
* @retval SR_ERR Failure.
*/
SR_PRIV int serial_stream_detect(struct sr_serial_dev_inst *serial,
uint8_t *buf, size_t *buflen,

2
hardware/norma-dmm/protocol.c
View File

@ -70,7 +70,7 @@ SR_PRIV int xgittoint(char xgit)
}
/**
* Process received line. It consists of 20 hex digits + \r\n,
* Process received line. It consists of 20 hex digits + \\r\\n,
* e.g. '08100400018100400000'.
*/
static void nma_process_line(const struct sr_dev_inst *sdi)

22
libsigrok-internal.h
View File

@ -17,6 +17,10 @@
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/** @file
* @internal
*/
#ifndef LIBSIGROK_SIGROK_INTERNAL_H
#define LIBSIGROK_SIGROK_INTERNAL_H
@ -60,10 +64,11 @@ struct sr_context {
};
#ifdef HAVE_LIBUSB_1_0
/** USB device instance */
struct sr_usb_dev_inst {
uint8_t bus;
uint8_t address;
struct libusb_device_handle *devhdl;
uint8_t bus; /**< USB bus */
uint8_t address; /**< Device address on USB bus */
struct libusb_device_handle *devhdl; /**< libusb device handle */
};
#endif
@ -72,10 +77,10 @@ struct sr_usb_dev_inst {
#define SERIAL_PARITY_EVEN SP_PARITY_EVEN
#define SERIAL_PARITY_ODD SP_PARITY_ODD
struct sr_serial_dev_inst {
char *port;
char *serialcomm;
char *port; /**< Port name, e.g. '/dev/tty42'. */
char *serialcomm; /**< Comm params for serial_set_paramstr(). */
int nonblocking;
struct sp_port *data;
struct sp_port *data; /**< libserialport port handle */
};
#endif
@ -86,7 +91,7 @@ struct sr_usbtmc_dev_inst {
/* Private driver context. */
struct drv_context {
struct sr_context *sr_ctx;
struct sr_context *sr_ctx; /**< sigrok context */
GSList *instances;
};
@ -164,8 +169,9 @@ struct sr_session {
* an async fashion. We need to make sure the session is stopped from
* within the session thread itself.
*/
GMutex stop_mutex;
GMutex stop_mutex; /**< Mutex protecting access to abort_session. */
gboolean abort_session;
/**< Abort current session. See sr_session_stop(). */
};
SR_PRIV int sr_session_send(const struct sr_dev_inst *sdi,

212
libsigrok.h
View File

@ -41,9 +41,9 @@ extern "C" {
*
* The correct way to get/use the libsigrok API functions is:
*
* @code{.c}
* #include <libsigrok/libsigrok.h>
* @endcode
@code{.c}
#include <libsigrok/libsigrok.h>
@endcode
*/
/*
@ -131,6 +131,7 @@ enum {
#define SR_PRIV
#endif
/** Type definition for callback function for data reception. */
typedef int (*sr_receive_data_callback_t)(int fd, int revents, void *cb_data);
/** Data types used by sr_config_info(). */
@ -148,17 +149,18 @@ enum {
/** Value for sr_datafeed_packet.type. */
enum {
SR_DF_HEADER = 10000,
SR_DF_END,
SR_DF_META,
SR_DF_TRIGGER,
SR_DF_LOGIC,
SR_DF_ANALOG,
SR_DF_FRAME_BEGIN,
SR_DF_FRAME_END,
SR_DF_HEADER = 10000, /**< Payload is sr_datafeed_header. */
SR_DF_END, /**< End of stream (no further data). */
SR_DF_META, /**< Payload is struct sr_datafeed_meta */
SR_DF_TRIGGER, /**< The trigger matched at this point in the data feed.
No payload. */
SR_DF_LOGIC, /**< Payload is struct sr_datafeed_logic. */
SR_DF_ANALOG, /**< Payload is struct sr_datafeed_analog. */
SR_DF_FRAME_BEGIN, /**< Beginning of frame. No payload. */
SR_DF_FRAME_END, /**< End of frame. No payload. */
};
/** Values for sr_datafeed_analog.mq. */
/** Measured quantity, sr_datafeed_analog.mq. */
enum {
SR_MQ_VOLTAGE = 10000,
SR_MQ_CURRENT,
@ -166,37 +168,34 @@ enum {
SR_MQ_CAPACITANCE,
SR_MQ_TEMPERATURE,
SR_MQ_FREQUENCY,
SR_MQ_DUTY_CYCLE,
SR_MQ_CONTINUITY,
SR_MQ_DUTY_CYCLE, /**< Duty cycle, e.g. on/off ratio. */
SR_MQ_CONTINUITY, /**< Continuity test. */
SR_MQ_PULSE_WIDTH,
SR_MQ_CONDUCTANCE,
/** Electrical power, usually in W, or dBm. */
SR_MQ_POWER,
/** Gain (a transistor's gain, or hFE, for example). */
SR_MQ_GAIN,
SR_MQ_POWER, /**< Electrical power, usually in W, or dBm. */
SR_MQ_GAIN, /**< Gain (a transistor's gain, or hFE, for example). */
/** Logarithmic representation of sound pressure relative to a
* reference value. */
SR_MQ_SOUND_PRESSURE_LEVEL,
SR_MQ_CARBON_MONOXIDE,
SR_MQ_RELATIVE_HUMIDITY,
SR_MQ_CARBON_MONOXIDE, /**< Carbon monoxide level */
SR_MQ_RELATIVE_HUMIDITY,/**< Humidity */
SR_MQ_TIME, /**< Time */
};
/** Values for sr_datafeed_analog.unit. */
/** Unit of measured quantity, sr_datafeed_analog.unit. */
enum {
SR_UNIT_VOLT = 10000,
SR_UNIT_AMPERE,
SR_UNIT_OHM,
SR_UNIT_FARAD,
SR_UNIT_KELVIN,
SR_UNIT_CELSIUS,
SR_UNIT_FAHRENHEIT,
SR_UNIT_HERTZ,
SR_UNIT_PERCENTAGE,
SR_UNIT_BOOLEAN,
SR_UNIT_SECOND,
/** Unit of conductance, the inverse of resistance. */
SR_UNIT_SIEMENS,
SR_UNIT_VOLT = 10000, /**< Volt */
SR_UNIT_AMPERE, /**< Ampere (current). */
SR_UNIT_OHM, /**< Ohm (resistance). */
SR_UNIT_FARAD, /**< Farad (capacity). */
SR_UNIT_KELVIN, /**< Kelvin (temperature). */
SR_UNIT_CELSIUS, /**< Degrees Celsius (temperature). */
SR_UNIT_FAHRENHEIT, /**< Degrees Fahrenheit (temperature). */
SR_UNIT_HERTZ, /**< Hertz (frequency, 1/s, [Hz]). */
SR_UNIT_PERCENTAGE, /**< Percent value. */
SR_UNIT_BOOLEAN, /**< Boolean value. */
SR_UNIT_SECOND, /**< Time in seconds. */
SR_UNIT_SIEMENS, /**< Unit of conductance, the inverse of resistance. */
/**
* An absolute measurement of power, in decibels, referenced to
* 1 milliwatt (dBu).
@ -218,10 +217,10 @@ enum {
* represented as the fraction of number of particles of the substance.
*/
SR_UNIT_CONCENTRATION,
SR_UNIT_REVOLUTIONS_PER_MINUTE,
SR_UNIT_VOLT_AMPERE,
SR_UNIT_WATT,
SR_UNIT_WATT_HOUR,
SR_UNIT_REVOLUTIONS_PER_MINUTE, /**< Revolutions per minute. */
SR_UNIT_VOLT_AMPERE, /**< Apparent power [VA]. */
SR_UNIT_WATT, /**< Real power [W]. */
SR_UNIT_WATT_HOUR, /**< Consumption [Wh]. */
};
/** Values for sr_datafeed_analog.flags. */
@ -272,37 +271,44 @@ enum {
SR_MQFLAG_DURATION = 0x20000,
};
/** sigrok context (opaque). @see sr_init(), sr_exit(). */
struct sr_context;
/** Packet in a sigrok data feed. */
struct sr_datafeed_packet {
uint16_t type;
const void *payload;
};
/** Header of a sigrok data feed. */
struct sr_datafeed_header {
int feed_version;
struct timeval starttime;
};
/** Datafeed payload for type SR_DF_META. */
struct sr_datafeed_meta {
GSList *config;
};
/** Logic datafeed payload for type SR_DF_LOGIC. */
struct sr_datafeed_logic {
uint64_t length;
uint16_t unitsize;
void *data;
};
/** Analog datafeed payload for type SR_DF_ANALOG. */
struct sr_datafeed_analog {
/** The probes for which data is included in this packet. */
GSList *probes;
int num_samples;
/** Measured quantity (voltage, current, temperature, and so on). */
int num_samples; /**< Number of samples in data */
/** Measured quantity (voltage, current, temperature, and so on).
* Use SR_MQ_VOLTAGE, ... */
int mq;
/** Unit in which the MQ is measured. */
/** Unit in which the MQ is measured. Use SR_UNIT_VOLT, ... */
int unit;
/** Bitmap with extra information about the MQ. */
/** Bitmap with extra information about the MQ. Use SR_MQFLAG_AC, ... */
uint64_t mqflags;
/** The analog value(s). The data is interleaved according to
* the probes list. */
@ -324,6 +330,7 @@ struct sr_input {
void *internal;
};
/** Input (file) format driver. */
struct sr_input_format {
/** The unique ID for this input format. Must not be NULL. */
char *id;
@ -337,9 +344,10 @@ struct sr_input_format {
/**
* Check if this input module can load and parse the specified file.
*
* @param filename The name (and path) of the file to check.
* @param[in] filename The name (and path) of the file to check.
*
* @return TRUE if this module knows the format, FALSE if it doesn't.
* @retval TRUE This module knows the format.
* @retval FALSE This module does not know the format.
*/
int (*format_match) (const char *filename);
@ -349,9 +357,10 @@ struct sr_input_format {
* @param in A pointer to a valid 'struct sr_input' that the caller
* has to allocate and provide to this function. It is also
* the responsibility of the caller to free it later.
* @param filename The name (and path) of the file to use.
* @param[in] filename The name (and path) of the file to use.
*
* @return SR_OK upon success, a negative error code upon failure.
* @retval SR_OK Success
* @retval other Negative error code.
*/
int (*init) (struct sr_input *in, const char *filename);
@ -372,7 +381,8 @@ struct sr_input_format {
* the responsibility of the caller to free it later.
* @param filename The name (and path) of the file to use.
*
* @return SR_OK upon success, a negative error code upon failure.
* @retval SR_OK Success
* @retval other Negative error code.
*/
int (*loadfile) (struct sr_input *in, const char *filename);
};
@ -408,6 +418,7 @@ struct sr_output {
void *internal;
};
/** Output (file) format driver. */
struct sr_output_format {
/**
* A unique ID for this output format. Must not be NULL.
@ -427,7 +438,7 @@ struct sr_output_format {
*/
char *description;
int df_type;
int df_type; /**< Datafeed type, SR_DF_HEADER, etc. */
/**
* This function is called once, at the beginning of an output stream.
@ -441,7 +452,8 @@ struct sr_output_format {
*
* @param o Pointer to the respective 'struct sr_output'.
*
* @return SR_OK upon success, a negative error code otherwise.
* @retval SR_OK Success
* @retval other Negative error code.
*/
int (*init) (struct sr_output *o);
@ -473,7 +485,8 @@ struct sr_output_format {
* @param data_out Pointer to the allocated output buffer.
* @param length_out Length (in bytes) of the output.
*
* @return SR_OK upon success, a negative error code otherwise.
* @retval SR_OK Success
* @retval other Negative error code.
*/
int (*data) (struct sr_output *o, const uint8_t *data_in,
uint64_t length_in, uint8_t **data_out,
@ -504,7 +517,8 @@ struct sr_output_format {
* @param data_out Pointer to the allocated output buffer.
* @param length_out Length (in bytes) of the output.
*
* @return SR_OK upon success, a negative error code otherwise.
* @retval SR_OK Success
* @retval other Negative error code.
*/
int (*event) (struct sr_output *o, int event_type, uint8_t **data_out,
uint64_t *length_out);
@ -524,7 +538,8 @@ struct sr_output_format {
* @param out A pointer where a GString * should be stored if
* the module generates output, or NULL if not.
*
* @return SR_OK upon success, a negative error code otherwise.
* @retval SR_OK Success
* @retval other Negative error code.
*/
int (*receive) (struct sr_output *o, const struct sr_dev_inst *sdi,
const struct sr_datafeed_packet *packet, GString **out);
@ -534,23 +549,26 @@ struct sr_output_format {
* the output module, and can be used to free any internal
* resources the module may keep.
*
* @return SR_OK upon success, a negative error code otherwise.
* @retval SR_OK Success
* @retval other Negative error code.
*/
int (*cleanup) (struct sr_output *o);
};
/** Constants for probe type. */
enum {
SR_PROBE_LOGIC = 10000,
SR_PROBE_ANALOG,
SR_PROBE_LOGIC = 10000, /**< Probe type is logic probe. */
SR_PROBE_ANALOG, /**< Probe type is analog probe. */
};
/** Information on single probe. */
struct sr_probe {
/* The index field will go: use g_slist_length(sdi->probes) instead. */
int index;
int type;
gboolean enabled;
char *name;
char *trigger;
int index; /**< Number of probe, starting at 0. @deprecated The
index field will go: use g_slist_length(sdi->probes) instead. */
int type; /**< Probe type (SR_PROBE_LOGIC, ...) */
gboolean enabled; /**< Is this probe enabled? */
char *name;/**< Name of probe. */
char *trigger;/**< Trigger string, format like used by sigrok-cli */
};
/** Structure for groups of probes that have common properties. */
@ -563,19 +581,22 @@ struct sr_probe_group {
void *priv;
};
/** Used for setting or getting value of a config item. */
struct sr_config {
int key;
GVariant *data;
int key; /**< Config key like SR_CONF_CONN, etc. */
GVariant *data; /**< Key-specific data. */
};
/** Information about a config key. */
struct sr_config_info {
int key;
int datatype;
char *id;
char *name;
char *description;
int key; /**< Config key like SR_CONF_CONN, etc. */
int datatype; /**< Data type like SR_T_CHAR, etc. */
char *id; /**< Id string, e.g. "serialcomm". */
char *name; /**< Name, e.g. "Serial communication". */
char *description; /**< Verbose description (unused currently). */
};
/** Constants for device classes */
enum {
/*--- Device classes ------------------------------------------------*/
@ -782,22 +803,24 @@ enum {
SR_CONF_DATALOG,
};
/** @private
* Device instance data
*/
struct sr_dev_inst {
struct sr_dev_driver *driver;
int index;
int status;
int inst_type;
char *vendor;
char *model;
char *version;
GSList *probes;
/* List of sr_probe_group structs */
GSList *probe_groups;
void *conn;
void *priv;
struct sr_dev_driver *driver; /**< Device driver. */
int index; /**< Index of device in driver. */
int status; /**< Device instance status. SR_ST_NOT_FOUND, etc. */
int inst_type; /**< Device instance type. SR_INST_USB, etc. */
char *vendor; /**< Device vendor. */
char *model; /**< Device model. */
char *version; /**< Device version. */
GSList *probes; /**< List of probes. */
GSList *probe_groups; /**< List of sr_probe_group structs */
void *conn; /**< Device instance connection data (used?) */
void *priv; /**< Device instance private data (used?) */
};
/** Types of device instances (sr_dev_inst). */
/** Types of device instance, struct sr_dev_inst.type */
enum {
/** Device instance type for USB devices. */
SR_INST_USB = 10000,
@ -807,7 +830,7 @@ enum {
SR_INST_SCPI,
};
/** Device instance status. */
/** Device instance status, struct sr_dev_inst.status */
enum {
/** The device instance was not found. */
SR_ST_NOT_FOUND = 10000,
@ -821,15 +844,16 @@ enum {
SR_ST_STOPPING,
};
/** Device driver data */
struct sr_dev_driver {
/* Driver-specific */
char *name;
char *longname;
int api_version;
int (*init) (struct sr_context *sr_ctx);
int (*cleanup) (void);
GSList *(*scan) (GSList *options);
GSList *(*dev_list) (void);
char *name; /**< Driver name */
char *longname; /**< Long name, e.g. device name. */
int api_version; /**< API version (currently 1). */
int (*init) (struct sr_context *sr_ctx); /**< Init driver */
int (*cleanup) (void); /**< Free driver */
GSList *(*scan) (GSList *options); /**< Scan for devices */
GSList *(*dev_list) (void); /**< Get device list */
int (*dev_clear) (void);
int (*config_get) (int id, GVariant **data,
const struct sr_dev_inst *sdi,
@ -842,15 +866,15 @@ struct sr_dev_driver {
const struct sr_probe_group *probe_group);
/* Device-specific */
int (*dev_open) (struct sr_dev_inst *sdi);
int (*dev_close) (struct sr_dev_inst *sdi);
int (*dev_open) (struct sr_dev_inst *sdi); /**< Open device */
int (*dev_close) (struct sr_dev_inst *sdi); /**< Close device */
int (*dev_acquisition_start) (const struct sr_dev_inst *sdi,
void *cb_data);
void *cb_data); /**< Start data aquisition. */
int (*dev_acquisition_stop) (struct sr_dev_inst *sdi,
void *cb_data);
void *cb_data); /**< Stop data aquisition. */
/* Dynamic */
void *priv;
void *priv; /**< Device driver private data */
};
/**

87
session.c
View File

@ -74,7 +74,8 @@ struct sr_session *session;
* @todo Should it use the file-global "session" variable or take an argument?
* The same question applies to all the other session functions.
*
* @return A pointer to the newly allocated session, or NULL upon errors.
* @retval NULL Error.
* @retval other A pointer to the newly allocated session->
*/
SR_API struct sr_session *sr_session_new(void)
{
@ -93,10 +94,10 @@ SR_API struct sr_session *sr_session_new(void)
/**
* Destroy the current session.
*
* This frees up all memory used by the session.
*
* @return SR_OK upon success, SR_ERR_BUG if no session exists.
* @retval SR_OK Success.
* @retval SR_ERR_BUG No session exists.
*/
SR_API int sr_session_destroy(void)
{
@ -123,7 +124,8 @@ SR_API int sr_session_destroy(void)
* The session itself (i.e., the struct sr_session) is not free'd and still
* exists after this function returns.
*
* @return SR_OK upon success, SR_ERR_BUG if no session exists.
* @retval SR_OK Success.
* @retval SR_ERR_BUG No session exists.
*/
SR_API int sr_session_dev_remove_all(void)
{
@ -145,7 +147,9 @@ SR_API int sr_session_dev_remove_all(void)
* be NULL. Also, sdi->driver and sdi->driver->dev_open must
* not be NULL.
*
* @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
* @retval SR_OK Success.
* @retval SR_ERR_ARG Invalid argument.
* @retval SR_ERR_BUG No session exists.
*/
SR_API int sr_session_dev_add(const struct sr_dev_inst *sdi)
{
@ -200,7 +204,8 @@ SR_API int sr_session_dev_add(const struct sr_dev_inst *sdi)
* The list must be freed by the caller, but not the
* elements pointed to.
*
* @return SR_OK upon success, SR_ERR upon invalid arguments.
* @retval SR_OK Success.
* @retval SR_ERR Invalid argument.
*/
SR_API int sr_session_dev_list(GSList **devlist)
{
@ -218,7 +223,8 @@ SR_API int sr_session_dev_list(GSList **devlist)
/**
* Remove all datafeed callbacks in the current session.
*
* @return SR_OK upon success, SR_ERR_BUG if no session exists.
* @retval SR_OK Success.
* @retval SR_ERR_BUG No session exists.
*/
SR_API int sr_session_datafeed_callback_remove_all(void)
{
@ -240,7 +246,8 @@ SR_API int sr_session_datafeed_callback_remove_all(void)
* Must not be NULL.
* @param cb_data Opaque pointer passed in by the caller.
*
* @return SR_OK upon success, SR_ERR_BUG if no session exists.
* @retval SR_OK Success.
* @retval SR_ERR_BUG No session exists.
*/
SR_API int sr_session_datafeed_callback_add(sr_datafeed_callback_t cb, void *cb_data)
{
@ -282,7 +289,8 @@ SR_API int sr_session_datafeed_callback_add(sr_datafeed_callback_t cb, void *cb_
* If FALSE, all sources have their callback run, regardless
* of file descriptor or timeout status.
*
* @return SR_OK upon success, SR_ERR on errors.
* @retval SR_OK Success.
* @retval SR_ERR Error occured.
*/
static int sr_session_iteration(gboolean block)
{
@ -327,7 +335,8 @@ static int sr_session_iteration(gboolean block)
*
* There can only be one session at a time.
*
* @return SR_OK upon success, SR_ERR upon errors.
* @retval SR_OK Success.
* @retval SR_ERR Error occured.
*/
SR_API int sr_session_start(void)
{
@ -367,7 +376,8 @@ SR_API int sr_session_start(void)
/**
* Run the session.
*
* @return SR_OK upon success, SR_ERR_BUG upon errors.
* @retval SR_OK Success.
* @retval SR_ERR_BUG Error occured.
*/
SR_API int sr_session_run(void)
{
@ -410,7 +420,8 @@ SR_API int sr_session_run(void)
* This must be called from within the session thread, to prevent freeing
* resources that the session thread will try to use.
*
* @return SR_OK upon success, SR_ERR_BUG if no session exists.
* @retval SR_OK Success.
* @retval SR_ERR_BUG No session exists.
*
* @private
*/
@ -449,7 +460,8 @@ SR_PRIV int sr_session_stop_sync(void)
* to wait for the session thread to return before assuming that the session is
* completely decommissioned.
*
* @return SR_OK upon success, SR_ERR_BUG if no session exists.
* @retval SR_OK Success.
* @retval SR_ERR_BUG No session exists.
*/
SR_API int sr_session_stop(void)
{
@ -518,7 +530,8 @@ static void datafeed_dump(const struct sr_datafeed_packet *packet)
* @param sdi TODO.
* @param packet The datafeed packet to send to the session bus.
*
* @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
* @retval SR_OK Success.
* @retval SR_ERR_ARG Invalid argument.
*
* @private
*/
@ -552,13 +565,15 @@ SR_PRIV int sr_session_send(const struct sr_dev_inst *sdi,
* Add an event source for a file descriptor.
*
* @param pollfd The GPollFD.
* @param timeout Max time to wait before the callback is called, ignored if 0.
* @param[in] timeout Max time to wait before the callback is called,
* ignored if 0.
* @param cb Callback function to add. Must not be NULL.
* @param cb_data Data for the callback function. Can be NULL.
* @param poll_object TODO.
*
* @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
* SR_ERR_MALLOC upon memory allocation errors.
* @retval SR_OK Success.
* @retval SR_ERR_ARG Invalid argument.
* @retval SR_ERR_MALLOC Memory allocation error.
*/
static int _sr_session_source_add(GPollFD *pollfd, int timeout,
sr_receive_data_callback_t cb, void *cb_data, gintptr poll_object)
@ -612,8 +627,9 @@ static int _sr_session_source_add(GPollFD *pollfd, int timeout,
* @param cb Callback function to add. Must not be NULL.
* @param cb_data Data for the callback function. Can be NULL.
*
* @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
* SR_ERR_MALLOC upon memory allocation errors.
* @retval SR_OK Success.
* @retval SR_ERR_ARG Invalid argument.
* @retval SR_ERR_MALLOC Memory allocation error.
*/
SR_API int sr_session_source_add(int fd, int events, int timeout,
sr_receive_data_callback_t cb, void *cb_data)
@ -634,8 +650,9 @@ SR_API int sr_session_source_add(int fd, int events, int timeout,
* @param cb Callback function to add. Must not be NULL.
* @param cb_data Data for the callback function. Can be NULL.
*
* @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
* SR_ERR_MALLOC upon memory allocation errors.
* @retval SR_OK Success.
* @retval SR_ERR_ARG Invalid argument.
* @retval SR_ERR_MALLOC Memory allocation error.
*/
SR_API int sr_session_source_add_pollfd(GPollFD *pollfd, int timeout,
sr_receive_data_callback_t cb, void *cb_data)
@ -653,8 +670,9 @@ SR_API int sr_session_source_add_pollfd(GPollFD *pollfd, int timeout,
* @param cb Callback function to add. Must not be NULL.
* @param cb_data Data for the callback function. Can be NULL.
*
* @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
* SR_ERR_MALLOC upon memory allocation errors.
* @retval SR_OK Success.
* @retval SR_ERR_ARG Invalid argument.
* @retval SR_ERR_MALLOC Memory allocation error.
*/
SR_API int sr_session_source_add_channel(GIOChannel *channel, int events,
int timeout, sr_receive_data_callback_t cb, void *cb_data)
@ -676,11 +694,12 @@ SR_API int sr_session_source_add_channel(GIOChannel *channel, int events,
*
* @todo Add more error checks and logging.
*
* @param channel The channel for which the source should be removed.
* @param poll_object The channel for which the source should be removed.
*
* @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
* SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon
* internal errors.
* @retval SR_OK Success
* @retval SR_ERR_ARG Invalid arguments
* @retval SR_ERR_MALLOC Memory allocation error
* @retval SR_ERR_BUG Internal error
*/
static int _sr_session_source_remove(gintptr poll_object)
{
@ -734,9 +753,10 @@ static int _sr_session_source_remove(gintptr poll_object)
*
* @param fd The file descriptor for which the source should be removed.
*
* @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
* SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon
* internal errors.
* @retval SR_OK Success
* @retval SR_ERR_ARG Invalid argument
* @retval SR_ERR_MALLOC Memory allocation error.
* @retval SR_ERR_BUG Internal error.
*/
SR_API int sr_session_source_remove(int fd)
{
@ -762,9 +782,10 @@ SR_API int sr_session_source_remove_pollfd(GPollFD *pollfd)
*
* @param channel The channel for which the source should be removed.
*
* @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
* SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon
* internal errors.
* @retval SR_OK Success.
* @retval SR_ERR_ARG Invalid argument.
* @retval SR_ERR_MALLOC Memory allocation error.
* @return SR_ERR_BUG Internal error.
*/
SR_API int sr_session_source_remove_channel(GIOChannel *channel)
{

7
std.c
View File

@ -18,6 +18,11 @@
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*/
/** \file
* Standard API helper functions.
* @internal
*/
#include <glib.h>
#include "libsigrok.h"
#include "libsigrok-internal.h"
@ -32,7 +37,7 @@
*
* @param sr_ctx The libsigrok context to assign.
* @param di The driver instance to use.
* @param prefix A driver-specific prefix string used for log messages.
* @param[in] prefix A driver-specific prefix string used for log messages.
*
* @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
* SR_ERR_MALLOC upon memory allocation errors.