/**
* 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)
{
/**
* 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)
{
/**
* 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)
{
*
* @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
*/
* @{
*/
-/** @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)
{
* 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.
* 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.
*
* 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
*/
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)
{
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;
#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)
{
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);
* 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.
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);
* 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,
* 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,
* @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)
*
* @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,
}
/**
- * 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)
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
+/** @file
+ * @internal
+ */
+
#ifndef LIBSIGROK_SIGROK_INTERNAL_H
#define LIBSIGROK_SIGROK_INTERNAL_H
};
#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
#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
/* Private driver context. */
struct drv_context {
- struct sr_context *sr_ctx;
+ struct sr_context *sr_ctx; /**< sigrok context */
GSList *instances;
};
* 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,
*
* 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
*/
/*
#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(). */
/** 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,
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).
* 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. */
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. */
void *internal;
};
+/** Input (file) format driver. */
struct sr_input_format {
/** The unique ID for this input format. Must not be NULL. */
char *id;
/**
* 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);
* @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);
* 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);
};
void *internal;
};
+/** Output (file) format driver. */
struct sr_output_format {
/**
* A unique ID for this output format. Must not be NULL.
*/
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.
*
* @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);
* @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,
* @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);
* @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);
* 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. */
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 ------------------------------------------------*/
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,
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,
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,
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 */
};
/**
* @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)
{
/**
* 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)
{
* 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)
{
* 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)
{
* 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)
{
/**
* 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)
{
* 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)
{
* 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)
{
*
* 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)
{
/**
* 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)
{
* 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
*/
* 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)
{
* @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
*/
* 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)
* @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)
* @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)
* @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)
*
* @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)
{
*
* @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)
{
*
* @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)
{
* 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"
*
* @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.
projects / libsigrok.git / commitdiff