[libsigrok.git] / src / hwdriver.c

/*
 * This file is part of the libsigrok project.
 *
 * Copyright (C) 2013 Bert Vermeulen <bert@biot.com>
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

#include <stdlib.h>
#include <stdio.h>
#include <sys/types.h>
#include <dirent.h>
#include <string.h>
#include <glib.h>
#include "config.h" /* Needed for HAVE_LIBUSB_1_0 and others. */
#include "libsigrok.h"
#include "libsigrok-internal.h"

/** @cond PRIVATE */
#define LOG_PREFIX "hwdriver"
/** @endcond */

extern SR_PRIV struct sr_dev_driver *drivers_list[];

/**
 * @file
 *
 * Hardware driver handling in libsigrok.
 */

/**
 * @defgroup grp_driver Hardware drivers
 *
 * Hardware driver handling in libsigrok.
 *
 * @{
 */

static struct sr_config_info sr_config_info_data[] = {
	{SR_CONF_CONN, SR_T_STRING, "conn",
		"Connection", NULL},
	{SR_CONF_SERIALCOMM, SR_T_STRING, "serialcomm",
		"Serial communication", NULL},
	{SR_CONF_SAMPLERATE, SR_T_UINT64, "samplerate",
		"Sample rate", NULL},
	{SR_CONF_CAPTURE_RATIO, SR_T_UINT64, "captureratio",
		"Pre-trigger capture ratio", NULL},
	{SR_CONF_PATTERN_MODE, SR_T_STRING, "pattern",
		"Pattern", NULL},
	{SR_CONF_TRIGGER_MATCH, SR_T_INT32, "triggermatch",
		"Trigger matches", NULL},
	{SR_CONF_EXTERNAL_CLOCK, SR_T_BOOL, "external_clock",
		"External clock mode", NULL},
	{SR_CONF_SWAP, SR_T_BOOL, "swap",
		"Swap channel order", NULL},
	{SR_CONF_RLE, SR_T_BOOL, "rle",
		"Run Length Encoding", NULL},
	{SR_CONF_TRIGGER_SLOPE, SR_T_STRING, "triggerslope",
		"Trigger slope", NULL},
	{SR_CONF_TRIGGER_SOURCE, SR_T_STRING, "triggersource",
		"Trigger source", NULL},
	{SR_CONF_HORIZ_TRIGGERPOS, SR_T_FLOAT, "horiz_triggerpos",
		"Horizontal trigger position", NULL},
	{SR_CONF_BUFFERSIZE, SR_T_UINT64, "buffersize",
		"Buffer size", NULL},
	{SR_CONF_TIMEBASE, SR_T_RATIONAL_PERIOD, "timebase",
		"Time base", NULL},
	{SR_CONF_FILTER, SR_T_STRING, "filter",
		"Filter targets", NULL},
	{SR_CONF_VDIV, SR_T_RATIONAL_VOLT, "vdiv",
		"Volts/div", NULL},
	{SR_CONF_COUPLING, SR_T_STRING, "coupling",
		"Coupling", NULL},
	{SR_CONF_DATALOG, SR_T_BOOL, "datalog",
		"Datalog", NULL},
	{SR_CONF_SPL_WEIGHT_FREQ, SR_T_STRING, "spl_weight_freq",
		"Sound pressure level frequency weighting", NULL},
	{SR_CONF_SPL_WEIGHT_TIME, SR_T_STRING, "spl_weight_time",
		"Sound pressure level time weighting", NULL},
	{SR_CONF_HOLD_MAX, SR_T_BOOL, "hold_max",
		"Hold max", NULL},
	{SR_CONF_HOLD_MIN, SR_T_BOOL, "hold_min",
		"Hold min", NULL},
	{SR_CONF_SPL_MEASUREMENT_RANGE, SR_T_UINT64_RANGE, "spl_meas_range",
		"Sound pressure level measurement range", NULL},
	{SR_CONF_VOLTAGE_THRESHOLD, SR_T_DOUBLE_RANGE, "voltage_threshold",
		"Voltage threshold", NULL },
	{SR_CONF_POWER_OFF, SR_T_BOOL, "power_off",
		"Power off", NULL},
	{SR_CONF_DATA_SOURCE, SR_T_STRING, "data_source",
		"Data source", NULL},
	{SR_CONF_NUM_LOGIC_CHANNELS, SR_T_INT32, "logic_channels",
		"Number of logic channels", NULL},
	{SR_CONF_NUM_ANALOG_CHANNELS, SR_T_INT32, "analog_channels",
		"Number of analog channels", NULL},
	{SR_CONF_OUTPUT_VOLTAGE, SR_T_FLOAT, "output_voltage",
		"Current output voltage", NULL},
	{SR_CONF_OUTPUT_VOLTAGE_MAX, SR_T_FLOAT, "output_voltage_max",
		"Maximum output voltage", NULL},
	{SR_CONF_OUTPUT_CURRENT, SR_T_FLOAT, "output_current",
		"Current output current", NULL},
	{SR_CONF_OUTPUT_CURRENT_MAX, SR_T_FLOAT, "output_current_max",
		"Maximum output current", NULL},
	{SR_CONF_OUTPUT_ENABLED, SR_T_BOOL, "output_enabled",
		"Output enabled", NULL},
	{SR_CONF_OUTPUT_CHANNEL_CONFIG, SR_T_STRING, "output_channel_config",
		"Output channel modes", NULL},
	{SR_CONF_OVER_VOLTAGE_PROTECTION_ENABLED, SR_T_BOOL, "ovp_enabled",
		"Over-voltage protection enabled", NULL},
	{SR_CONF_OVER_VOLTAGE_PROTECTION_ACTIVE, SR_T_BOOL, "ovp_active",
		"Over-voltage protection active", NULL},
	{SR_CONF_OVER_VOLTAGE_PROTECTION_THRESHOLD, SR_T_FLOAT, "ovp_threshold",
		"Over-voltage protection threshold", NULL},
	{SR_CONF_OVER_CURRENT_PROTECTION_ENABLED, SR_T_BOOL, "ocp_enabled",
		"Over-current protection enabled", NULL},
	{SR_CONF_OVER_CURRENT_PROTECTION_ACTIVE, SR_T_BOOL, "ocp_active",
		"Over-current protection active", NULL},
	{SR_CONF_OVER_CURRENT_PROTECTION_THRESHOLD, SR_T_FLOAT, "ocp_threshold",
		"Over-current protection threshold", NULL},
	{SR_CONF_LIMIT_SAMPLES, SR_T_UINT64, "limit_samples",
		"Sample limit", NULL},
	{SR_CONF_CLOCK_EDGE, SR_T_STRING, "clock_edge",
		"Clock edge", NULL},
	{SR_CONF_AMPLITUDE, SR_T_FLOAT, "amplitude",
		"Amplitude", NULL},
	{SR_CONF_OVER_TEMPERATURE_PROTECTION, SR_T_BOOL, "otp",
		"Over-temperature protection", NULL},
	{SR_CONF_OUTPUT_REGULATION, SR_T_STRING, "output_regulation",
		"Output channel regulation", NULL},
	{0, 0, NULL, NULL, NULL},
};

/**
 * Return the list of supported hardware drivers.
 *
 * @return Pointer to the NULL-terminated list of hardware driver pointers.
 *
 * @since 0.1.0
 */
SR_API struct sr_dev_driver **sr_driver_list(void)
{

	return drivers_list;
}

/**
 * Initialize a hardware driver.
 *
 * This usually involves memory allocations and variable initializations
 * within the driver, but _not_ scanning for attached devices.
 * The API call sr_driver_scan() is used for that.
 *
 * @param ctx A libsigrok context object allocated by a previous call to
 *            sr_init(). Must not be NULL.
 * @param driver The driver to initialize. This must be a pointer to one of
 *               the entries returned by sr_driver_list(). Must not be NULL.
 *
 * @retval SR_OK Success
 * @retval SR_ERR_ARG Invalid parameter(s).
 * @retval SR_ERR_BUG Internal errors.
 * @retval other Another negative error code upon other errors.
 *
 * @since 0.2.0
 */
SR_API int sr_driver_init(struct sr_context *ctx, struct sr_dev_driver *driver)
{
	int ret;

	if (!ctx) {
		sr_err("Invalid libsigrok context, can't initialize.");
		return SR_ERR_ARG;
	}

	if (!driver) {
		sr_err("Invalid driver, can't initialize.");
		return SR_ERR_ARG;
	}

	sr_spew("Initializing driver '%s'.", driver->name);
	if ((ret = driver->init(ctx)) < 0)
		sr_err("Failed to initialize the driver: %d.", ret);

	return ret;
}

/**
 * Tell a hardware driver to scan for devices.
 *
 * In addition to the detection, the devices that are found are also
 * initialized automatically. On some devices, this involves a firmware upload,
 * or other such measures.
 *
 * The order in which the system is scanned for devices is not specified. The
 * caller should not assume or rely on any specific order.
 *
 * Before calling sr_driver_scan(), the user must have previously initialized
 * the driver by calling sr_driver_init().
 *
 * @param driver The driver that should scan. This must be a pointer to one of
 *               the entries returned by sr_driver_list(). Must not be NULL.
 * @param options A list of 'struct sr_hwopt' options to pass to the driver's
 *                scanner. Can be NULL/empty.
 *
 * @return A GSList * of 'struct sr_dev_inst', or NULL if no devices were
 *         found (or errors were encountered). This list must be freed by the
 *         caller using g_slist_free(), but without freeing the data pointed
 *         to in the list.
 *
 * @since 0.2.0
 */
SR_API GSList *sr_driver_scan(struct sr_dev_driver *driver, GSList *options)
{
	GSList *l;

	if (!driver) {
		sr_err("Invalid driver, can't scan for devices.");
		return NULL;
	}

	if (!driver->priv) {
		sr_err("Driver not initialized, can't scan for devices.");
		return NULL;
	}

	l = driver->scan(options);

	sr_spew("Scan of '%s' found %d devices.", driver->name,
		g_slist_length(l));

	return l;
}

/** Call driver cleanup function for all drivers.
 *  @private */
SR_PRIV void sr_hw_cleanup_all(void)
{
	int i;
	struct sr_dev_driver **drivers;

	drivers = sr_driver_list();
	for (i = 0; drivers[i]; i++) {
		if (drivers[i]->cleanup)
			drivers[i]->cleanup();
	}
}

/** Allocate struct sr_config.
 *  A floating reference can be passed in for data.
 *  @private
 */
SR_PRIV struct sr_config *sr_config_new(int key, GVariant *data)
{
	struct sr_config *src;

	if (!(src = g_try_malloc(sizeof(struct sr_config))))
		return NULL;
	src->key = key;
	src->data = g_variant_ref_sink(data);

	return src;
}

/** Free struct sr_config.
 *  @private
 */
SR_PRIV void sr_config_free(struct sr_config *src)
{

	if (!src || !src->data) {
		sr_err("%s: invalid data!", __func__);
		return;
	}

	g_variant_unref(src->data);
	g_free(src);

}

/**
 * Query value of a configuration key at the given driver or device instance.
 *
 * @param[in] driver The sr_dev_driver struct to query.
 * @param[in] sdi (optional) If the key is specific to a device, this must
 *            contain a pointer to the struct sr_dev_inst to be checked.
 *            Otherwise it must be NULL.
 * @param[in] cg The channel group on the device for which to list the
 *                    values, or NULL.
 * @param[in] key The configuration key (SR_CONF_*).
 * @param[in,out] data Pointer to a GVariant where the value will be stored.
 *             Must not be NULL. The caller is given ownership of the GVariant
 *             and must thus decrease the refcount after use. However if
 *             this function returns an error code, the field should be
 *             considered unused, and should not be unreferenced.
 *
 * @retval SR_OK Success.
 * @retval SR_ERR Error.
 * @retval SR_ERR_ARG The driver doesn't know that key, but this is not to be
 *          interpreted as an error by the caller; merely as an indication
 *          that it's not applicable.
 *
 * @since 0.3.0
 */
SR_API int sr_config_get(const struct sr_dev_driver *driver,
		const struct sr_dev_inst *sdi,
		const struct sr_channel_group *cg,
		int key, GVariant **data)
{
	int ret;

	if (!driver || !data)
		return SR_ERR;

	if (!driver->config_get)
		return SR_ERR_ARG;

	if ((ret = driver->config_get(key, data, sdi, cg)) == SR_OK) {
		/* Got a floating reference from the driver. Sink it here,
		 * caller will need to unref when done with it. */
		g_variant_ref_sink(*data);
	}

	return ret;
}

/**
 * Set value of a configuration key in a device instance.
 *
 * @param[in] sdi The device instance.
 * @param[in] cg The channel group on the device for which to list the
 *                    values, or NULL.
 * @param[in] key The configuration key (SR_CONF_*).
 * @param data The new value for the key, as a GVariant with GVariantType
 *        appropriate to that key. A floating reference can be passed
 *        in; its refcount will be sunk and unreferenced after use.
 *
 * @retval SR_OK Success.
 * @retval SR_ERR Error.
 * @retval SR_ERR_ARG The driver doesn't know that key, but this is not to be
 *          interpreted as an error by the caller; merely as an indication
 *          that it's not applicable.
 *
 * @since 0.3.0
 */
SR_API int sr_config_set(const struct sr_dev_inst *sdi,
		const struct sr_channel_group *cg,
		int key, GVariant *data)
{
	int ret;

	g_variant_ref_sink(data);

	if (!sdi || !sdi->driver || !data)
		ret = SR_ERR;
	else if (!sdi->driver->config_set)
		ret = SR_ERR_ARG;
	else
		ret = sdi->driver->config_set(key, data, sdi, cg);

	g_variant_unref(data);

	return ret;
}

/**
 * Apply configuration settings to the device hardware.
 *
 * @param sdi The device instance.
 *
 * @return SR_OK upon success or SR_ERR in case of error.
 *
 * @since 0.3.0
 */
SR_API int sr_config_commit(const struct sr_dev_inst *sdi)
{
	int ret;

	if (!sdi || !sdi->driver)
		ret = SR_ERR;
	else if (!sdi->driver->config_commit)
		ret = SR_OK;
	else
		ret = sdi->driver->config_commit(sdi);

	return ret;
}

/**
 * List all possible values for a configuration key.
 *
 * @param[in] driver The sr_dev_driver struct to query.
 * @param[in] sdi (optional) If the key is specific to a device, this must
 *            contain a pointer to the struct sr_dev_inst to be checked.
 * @param[in] cg The channel group on the device for which to list the
 *                    values, or NULL.
 * @param[in] key The configuration key (SR_CONF_*).
 * @param[in,out] data A pointer to a GVariant where the list will be stored.
 *             The caller is given ownership of the GVariant and must thus
 *             unref the GVariant after use. However if this function
 *             returns an error code, the field should be considered
 *             unused, and should not be unreferenced.
 *
 * @retval SR_OK Success.
 * @retval SR_ERR Error.
 * @retval SR_ERR_ARG The driver doesn't know that key, but this is not to be
 *          interpreted as an error by the caller; merely as an indication
 *          that it's not applicable.
 *
 * @since 0.3.0
 */
SR_API int sr_config_list(const struct sr_dev_driver *driver,
		const struct sr_dev_inst *sdi,
		const struct sr_channel_group *cg,
		int key, GVariant **data)
{
	int ret;

	if (!driver || !data)
		ret = SR_ERR;
	else if (!driver->config_list)
		ret = SR_ERR_ARG;
	else if ((ret = driver->config_list(key, data, sdi, cg)) == SR_OK)
		g_variant_ref_sink(*data);

	return ret;
}

/**
 * Get information about a configuration key, by key.
 *
 * @param[in] key The configuration key.
 *
 * @return A pointer to a struct sr_config_info, or NULL if the key
 *         was not found.
 *
 * @since 0.2.0
 */
SR_API const struct sr_config_info *sr_config_info_get(int key)
{
	int i;

	for (i = 0; sr_config_info_data[i].key; i++) {
		if (sr_config_info_data[i].key == key)
			return &sr_config_info_data[i];
	}

	return NULL;
}

/**
 * Get information about a configuration key, by name.
 *
 * @param[in] optname The configuration key.
 *
 * @return A pointer to a struct sr_config_info, or NULL if the key
 *         was not found.
 *
 * @since 0.2.0
 */
SR_API const struct sr_config_info *sr_config_info_name_get(const char *optname)
{
	int i;

	for (i = 0; sr_config_info_data[i].key; i++) {
		if (!strcmp(sr_config_info_data[i].id, optname))
			return &sr_config_info_data[i];
	}

	return NULL;
}

/** @} */
Commit	Line	Data
a1bb33af	1	/*
50985c20	2	* This file is part of the libsigrok project.
a1bb33af	3	*
13d8e03c	4	* Copyright (C) 2013 Bert Vermeulen <bert@biot.com>
a1bb33af UH	5	*
	6	* This program is free software: you can redistribute it and/or modify
	7	* it under the terms of the GNU General Public License as published by
	8	* the Free Software Foundation, either version 3 of the License, or
	9	* (at your option) any later version.
	10	*
	11	* This program is distributed in the hope that it will be useful,
	12	* but WITHOUT ANY WARRANTY; without even the implied warranty of
	13	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	14	* GNU General Public License for more details.
	15	*
	16	* You should have received a copy of the GNU General Public License
	17	* along with this program. If not, see <http://www.gnu.org/licenses/>.
	18	*/
	19
	20	#include <stdlib.h>
	21	#include <stdio.h>
	22	#include <sys/types.h>
	23	#include <dirent.h>
	24	#include <string.h>
	25	#include <glib.h>
545f9786	26	#include "config.h" /* Needed for HAVE_LIBUSB_1_0 and others. */
45c59c8b BV	27	#include "libsigrok.h"
45c59c8b BV	28	#include "libsigrok-internal.h"
a1bb33af	29
2ad1deb8	30	/** @cond PRIVATE */
3544f848	31	#define LOG_PREFIX "hwdriver"
2ad1deb8	32	/** @endcond */
bd36d826	33
5d8c55f9 BV	34	extern SR_PRIV struct sr_dev_driver *drivers_list[];
5d8c55f9 BV	35
393fb9cb UH	36	/**
	37	* @file
	38	*
	39	* Hardware driver handling in libsigrok.
	40	*/
	41
7b870c38 UH	42	/**
	43	* @defgroup grp_driver Hardware drivers
	44	*
	45	* Hardware driver handling in libsigrok.
	46	*
	47	* @{
	48	*/
8bfdc8c4	49
c89c1c9c	50	static struct sr_config_info sr_config_info_data[] = {
ace218f9	51	{SR_CONF_CONN, SR_T_STRING, "conn",
083d64f9	52	"Connection", NULL},
ace218f9	53	{SR_CONF_SERIALCOMM, SR_T_STRING, "serialcomm",
083d64f9	54	"Serial communication", NULL},
1953564a	55	{SR_CONF_SAMPLERATE, SR_T_UINT64, "samplerate",
083d64f9	56	"Sample rate", NULL},
1953564a	57	{SR_CONF_CAPTURE_RATIO, SR_T_UINT64, "captureratio",
083d64f9	58	"Pre-trigger capture ratio", NULL},
ace218f9	59	{SR_CONF_PATTERN_MODE, SR_T_STRING, "pattern",
2438b737	60	"Pattern", NULL},
795c9de3 BV	61	{SR_CONF_TRIGGER_MATCH, SR_T_INT32, "triggermatch",
795c9de3 BV	62	"Trigger matches", NULL},
eb1b610b MR	63	{SR_CONF_EXTERNAL_CLOCK, SR_T_BOOL, "external_clock",
eb1b610b MR	64	"External clock mode", NULL},
7b0a57fd MR	65	{SR_CONF_SWAP, SR_T_BOOL, "swap",
7b0a57fd MR	66	"Swap channel order", NULL},
1953564a	67	{SR_CONF_RLE, SR_T_BOOL, "rle",
083d64f9	68	"Run Length Encoding", NULL},
ace218f9	69	{SR_CONF_TRIGGER_SLOPE, SR_T_STRING, "triggerslope",
083d64f9	70	"Trigger slope", NULL},
ace218f9	71	{SR_CONF_TRIGGER_SOURCE, SR_T_STRING, "triggersource",
083d64f9	72	"Trigger source", NULL},
1953564a	73	{SR_CONF_HORIZ_TRIGGERPOS, SR_T_FLOAT, "horiz_triggerpos",
083d64f9	74	"Horizontal trigger position", NULL},
1953564a	75	{SR_CONF_BUFFERSIZE, SR_T_UINT64, "buffersize",
083d64f9	76	"Buffer size", NULL},
1953564a	77	{SR_CONF_TIMEBASE, SR_T_RATIONAL_PERIOD, "timebase",
083d64f9	78	"Time base", NULL},
ace218f9	79	{SR_CONF_FILTER, SR_T_STRING, "filter",
083d64f9	80	"Filter targets", NULL},
1953564a	81	{SR_CONF_VDIV, SR_T_RATIONAL_VOLT, "vdiv",
083d64f9	82	"Volts/div", NULL},
ace218f9	83	{SR_CONF_COUPLING, SR_T_STRING, "coupling",
083d64f9	84	"Coupling", NULL},
e6551ea6 BV	85	{SR_CONF_DATALOG, SR_T_BOOL, "datalog",
e6551ea6 BV	86	"Datalog", NULL},
ace218f9	87	{SR_CONF_SPL_WEIGHT_FREQ, SR_T_STRING, "spl_weight_freq",
fd8854c4	88	"Sound pressure level frequency weighting", NULL},
ace218f9	89	{SR_CONF_SPL_WEIGHT_TIME, SR_T_STRING, "spl_weight_time",
fd8854c4	90	"Sound pressure level time weighting", NULL},
9fd6bc20 BV	91	{SR_CONF_HOLD_MAX, SR_T_BOOL, "hold_max",
	92	"Hold max", NULL},
	93	{SR_CONF_HOLD_MIN, SR_T_BOOL, "hold_min",
	94	"Hold min", NULL},
8417ebad BV	95	{SR_CONF_SPL_MEASUREMENT_RANGE, SR_T_UINT64_RANGE, "spl_meas_range",
8417ebad BV	96	"Sound pressure level measurement range", NULL},
db11d7d2 MC	97	{SR_CONF_VOLTAGE_THRESHOLD, SR_T_DOUBLE_RANGE, "voltage_threshold",
db11d7d2 MC	98	"Voltage threshold", NULL },
32de50b7 BV	99	{SR_CONF_POWER_OFF, SR_T_BOOL, "power_off",
32de50b7 BV	100	"Power off", NULL},
ace218f9	101	{SR_CONF_DATA_SOURCE, SR_T_STRING, "data_source",
6caeef6e	102	"Data source", NULL},
fca75cbb UH	103	{SR_CONF_NUM_LOGIC_CHANNELS, SR_T_INT32, "logic_channels",
	104	"Number of logic channels", NULL},
	105	{SR_CONF_NUM_ANALOG_CHANNELS, SR_T_INT32, "analog_channels",
	106	"Number of analog channels", NULL},
471607f0 BV	107	{SR_CONF_OUTPUT_VOLTAGE, SR_T_FLOAT, "output_voltage",
	108	"Current output voltage", NULL},
	109	{SR_CONF_OUTPUT_VOLTAGE_MAX, SR_T_FLOAT, "output_voltage_max",
	110	"Maximum output voltage", NULL},
	111	{SR_CONF_OUTPUT_CURRENT, SR_T_FLOAT, "output_current",
	112	"Current output current", NULL},
	113	{SR_CONF_OUTPUT_CURRENT_MAX, SR_T_FLOAT, "output_current_max",
	114	"Maximum output current", NULL},
	115	{SR_CONF_OUTPUT_ENABLED, SR_T_BOOL, "output_enabled",
	116	"Output enabled", NULL},
a1eaa9e0	117	{SR_CONF_OUTPUT_CHANNEL_CONFIG, SR_T_STRING, "output_channel_config",
471607f0	118	"Output channel modes", NULL},
a1eaa9e0 BV	119	{SR_CONF_OVER_VOLTAGE_PROTECTION_ENABLED, SR_T_BOOL, "ovp_enabled",
	120	"Over-voltage protection enabled", NULL},
	121	{SR_CONF_OVER_VOLTAGE_PROTECTION_ACTIVE, SR_T_BOOL, "ovp_active",
	122	"Over-voltage protection active", NULL},
	123	{SR_CONF_OVER_VOLTAGE_PROTECTION_THRESHOLD, SR_T_FLOAT, "ovp_threshold",
	124	"Over-voltage protection threshold", NULL},
	125	{SR_CONF_OVER_CURRENT_PROTECTION_ENABLED, SR_T_BOOL, "ocp_enabled",
	126	"Over-current protection enabled", NULL},
	127	{SR_CONF_OVER_CURRENT_PROTECTION_ACTIVE, SR_T_BOOL, "ocp_active",
	128	"Over-current protection active", NULL},
	129	{SR_CONF_OVER_CURRENT_PROTECTION_THRESHOLD, SR_T_FLOAT, "ocp_threshold",
	130	"Over-current protection threshold", NULL},
f0de2dd0 BV	131	{SR_CONF_LIMIT_SAMPLES, SR_T_UINT64, "limit_samples",
f0de2dd0 BV	132	"Sample limit", NULL},
ace218f9	133	{SR_CONF_CLOCK_EDGE, SR_T_STRING, "clock_edge",
860bc59b	134	"Clock edge", NULL},
cff7d8d6 BV	135	{SR_CONF_AMPLITUDE, SR_T_FLOAT, "amplitude",
cff7d8d6 BV	136	"Amplitude", NULL},
a1eaa9e0 BV	137	{SR_CONF_OVER_TEMPERATURE_PROTECTION, SR_T_BOOL, "otp",
	138	"Over-temperature protection", NULL},
	139	{SR_CONF_OUTPUT_REGULATION, SR_T_STRING, "output_regulation",
	140	"Output channel regulation", NULL},
083d64f9	141	{0, 0, NULL, NULL, NULL},
a1bb33af UH	142	};
a1bb33af UH	143
a1645fcd	144	/**
cfe064d8	145	* Return the list of supported hardware drivers.
a1645fcd	146	*
c09f0b57	147	* @return Pointer to the NULL-terminated list of hardware driver pointers.
47117241 UH	148	*
47117241 UH	149	* @since 0.1.0
a1645fcd	150	*/
cfe064d8	151	SR_API struct sr_dev_driver **sr_driver_list(void)
a1bb33af	152	{
80bf0426	153
c09f0b57	154	return drivers_list;
a1bb33af UH	155	}
a1bb33af UH	156
a1645fcd	157	/**
c09f0b57	158	* Initialize a hardware driver.
a1645fcd	159	*
c0eea11c UH	160	* This usually involves memory allocations and variable initializations
	161	* within the driver, but _not_ scanning for attached devices.
	162	* The API call sr_driver_scan() is used for that.
	163	*
44fc870c	164	* @param ctx A libsigrok context object allocated by a previous call to
c0eea11c UH	165	* sr_init(). Must not be NULL.
	166	* @param driver The driver to initialize. This must be a pointer to one of
	167	* the entries returned by sr_driver_list(). Must not be NULL.
a1645fcd	168	*
67eb6bcb MH	169	* @retval SR_OK Success
	170	* @retval SR_ERR_ARG Invalid parameter(s).
	171	* @retval SR_ERR_BUG Internal errors.
	172	* @retval other Another negative error code upon other errors.
47117241 UH	173	*
47117241 UH	174	* @since 0.2.0
a1645fcd	175	*/
44fc870c	176	SR_API int sr_driver_init(struct sr_context ctx, struct sr_dev_driver driver)
8722c31e	177	{
c0eea11c UH	178	int ret;
	179
	180	if (!ctx) {
	181	sr_err("Invalid libsigrok context, can't initialize.");
	182	return SR_ERR_ARG;
	183	}
	184
	185	if (!driver) {
	186	sr_err("Invalid driver, can't initialize.");
	187	return SR_ERR_ARG;
	188	}
8722c31e	189
c0eea11c UH	190	sr_spew("Initializing driver '%s'.", driver->name);
	191	if ((ret = driver->init(ctx)) < 0)
	192	sr_err("Failed to initialize the driver: %d.", ret);
80bf0426	193
c0eea11c	194	return ret;
80bf0426 BV	195	}
	196
	197	/**
	198	* Tell a hardware driver to scan for devices.
	199	*
a5f2e707 BV	200	* In addition to the detection, the devices that are found are also
	201	* initialized automatically. On some devices, this involves a firmware upload,
	202	* or other such measures.
	203	*
	204	* The order in which the system is scanned for devices is not specified. The
	205	* caller should not assume or rely on any specific order.
	206	*
4b97c74e UH	207	* Before calling sr_driver_scan(), the user must have previously initialized
4b97c74e UH	208	* the driver by calling sr_driver_init().
80bf0426	209	*
4b97c74e UH	210	* @param driver The driver that should scan. This must be a pointer to one of
	211	* the entries returned by sr_driver_list(). Must not be NULL.
	212	* @param options A list of 'struct sr_hwopt' options to pass to the driver's
	213	* scanner. Can be NULL/empty.
	214	*
	215	* @return A GSList * of 'struct sr_dev_inst', or NULL if no devices were
	216	* found (or errors were encountered). This list must be freed by the
	217	* caller using g_slist_free(), but without freeing the data pointed
	218	* to in the list.
47117241 UH	219	*
47117241 UH	220	* @since 0.2.0
80bf0426 BV	221	*/
	222	SR_API GSList sr_driver_scan(struct sr_dev_driver driver, GSList *options)
	223	{
4b97c74e UH	224	GSList *l;
	225
	226	if (!driver) {
	227	sr_err("Invalid driver, can't scan for devices.");
	228	return NULL;
	229	}
	230
	231	if (!driver->priv) {
	232	sr_err("Driver not initialized, can't scan for devices.");
	233	return NULL;
	234	}
	235
	236	l = driver->scan(options);
80bf0426	237
4b97c74e UH	238	sr_spew("Scan of '%s' found %d devices.", driver->name,
4b97c74e UH	239	g_slist_length(l));
80bf0426	240
4b97c74e	241	return l;
8722c31e BV	242	}
8722c31e BV	243
67eb6bcb MH	244	/** Call driver cleanup function for all drivers.
67eb6bcb MH	245	* @private */
93a04e3b	246	SR_PRIV void sr_hw_cleanup_all(void)
8722c31e	247	{
050e9219	248	int i;
c09f0b57	249	struct sr_dev_driver **drivers;
8722c31e	250
cfe064d8	251	drivers = sr_driver_list();
c09f0b57 UH	252	for (i = 0; drivers[i]; i++) {
	253	if (drivers[i]->cleanup)
	254	drivers[i]->cleanup();
8722c31e	255	}
8722c31e BV	256	}
8722c31e BV	257
67eb6bcb MH	258	/** Allocate struct sr_config.
	259	* A floating reference can be passed in for data.
	260	* @private
	261	*/
bc1c2f00	262	SR_PRIV struct sr_config sr_config_new(int key, GVariant data)
4c0e310c BV	263	{
	264	struct sr_config *src;
	265
	266	if (!(src = g_try_malloc(sizeof(struct sr_config))))
	267	return NULL;
	268	src->key = key;
bc1c2f00	269	src->data = g_variant_ref_sink(data);
4c0e310c BV	270
	271	return src;
	272	}
	273
67eb6bcb MH	274	/** Free struct sr_config.
	275	* @private
	276	*/
722db131 BV	277	SR_PRIV void sr_config_free(struct sr_config *src)
	278	{
	279
	280	if (!src \|\| !src->data) {
	281	sr_err("%s: invalid data!", __func__);
	282	return;
	283	}
	284
	285	g_variant_unref(src->data);
	286	g_free(src);
	287
	288	}
	289
df123801	290	/**
67eb6bcb	291	* Query value of a configuration key at the given driver or device instance.
df123801	292	*
67eb6bcb MH	293	* @param[in] driver The sr_dev_driver struct to query.
67eb6bcb MH	294	* @param[in] sdi (optional) If the key is specific to a device, this must
57ecdbd7 BV	295	* contain a pointer to the struct sr_dev_inst to be checked.
57ecdbd7 BV	296	* Otherwise it must be NULL.
53b4680f	297	* @param[in] cg The channel group on the device for which to list the
57ecdbd7	298	* values, or NULL.
67eb6bcb MH	299	* @param[in] key The configuration key (SR_CONF_*).
	300	* @param[in,out] data Pointer to a GVariant where the value will be stored.
	301	* Must not be NULL. The caller is given ownership of the GVariant
bc1c2f00 BV	302	* and must thus decrease the refcount after use. However if
	303	* this function returns an error code, the field should be
	304	* considered unused, and should not be unreferenced.
df123801	305	*
67eb6bcb MH	306	* @retval SR_OK Success.
	307	* @retval SR_ERR Error.
	308	* @retval SR_ERR_ARG The driver doesn't know that key, but this is not to be
	309	* interpreted as an error by the caller; merely as an indication
	310	* that it's not applicable.
47117241 UH	311	*
47117241 UH	312	* @since 0.3.0
df123801	313	*/
8f996b89 ML	314	SR_API int sr_config_get(const struct sr_dev_driver *driver,
8f996b89 ML	315	const struct sr_dev_inst *sdi,
53b4680f	316	const struct sr_channel_group *cg,
8f996b89	317	int key, GVariant **data)
df123801 BV	318	{
	319	int ret;
	320
cbadb856	321	if (!driver \|\| !data)
df123801 BV	322	return SR_ERR;
df123801 BV	323
6cefe516 BV	324	if (!driver->config_get)
	325	return SR_ERR_ARG;
	326
53b4680f	327	if ((ret = driver->config_get(key, data, sdi, cg)) == SR_OK) {
bc1c2f00 BV	328	/* Got a floating reference from the driver. Sink it here,
	329	* caller will need to unref when done with it. */
	330	g_variant_ref_sink(*data);
	331	}
df123801 BV	332
	333	return ret;
	334	}
	335
cbadb856	336	/**
67eb6bcb	337	* Set value of a configuration key in a device instance.
cbadb856	338	*
67eb6bcb	339	* @param[in] sdi The device instance.
53b4680f	340	* @param[in] cg The channel group on the device for which to list the
57ecdbd7	341	* values, or NULL.
67eb6bcb	342	* @param[in] key The configuration key (SR_CONF_*).
bc1c2f00 BV	343	* @param data The new value for the key, as a GVariant with GVariantType
	344	* appropriate to that key. A floating reference can be passed
	345	* in; its refcount will be sunk and unreferenced after use.
cbadb856	346	*
67eb6bcb MH	347	* @retval SR_OK Success.
	348	* @retval SR_ERR Error.
	349	* @retval SR_ERR_ARG The driver doesn't know that key, but this is not to be
	350	* interpreted as an error by the caller; merely as an indication
	351	* that it's not applicable.
47117241 UH	352	*
47117241 UH	353	* @since 0.3.0
cbadb856	354	*/
8f996b89	355	SR_API int sr_config_set(const struct sr_dev_inst *sdi,
53b4680f	356	const struct sr_channel_group *cg,
8f996b89	357	int key, GVariant *data)
cbadb856 BV	358	{
	359	int ret;
	360
bc1c2f00	361	g_variant_ref_sink(data);
cbadb856	362
bc1c2f00 BV	363	if (!sdi \|\| !sdi->driver \|\| !data)
	364	ret = SR_ERR;
	365	else if (!sdi->driver->config_set)
	366	ret = SR_ERR_ARG;
	367	else
53b4680f	368	ret = sdi->driver->config_set(key, data, sdi, cg);
cbadb856	369
bc1c2f00	370	g_variant_unref(data);
cbadb856 BV	371
	372	return ret;
	373	}
	374
2a854d71 DE	375	/**
	376	* Apply configuration settings to the device hardware.
	377	*
	378	* @param sdi The device instance.
	379	*
	380	* @return SR_OK upon success or SR_ERR in case of error.
47117241 UH	381	*
47117241 UH	382	* @since 0.3.0
2a854d71 DE	383	*/
	384	SR_API int sr_config_commit(const struct sr_dev_inst *sdi)
	385	{
	386	int ret;
	387
	388	if (!sdi \|\| !sdi->driver)
	389	ret = SR_ERR;
	390	else if (!sdi->driver->config_commit)
	391	ret = SR_OK;
	392	else
	393	ret = sdi->driver->config_commit(sdi);
	394
	395	return ret;
	396	}
	397
cbadb856 BV	398	/**
	399	* List all possible values for a configuration key.
	400	*
67eb6bcb MH	401	* @param[in] driver The sr_dev_driver struct to query.
67eb6bcb MH	402	* @param[in] sdi (optional) If the key is specific to a device, this must
57ecdbd7	403	* contain a pointer to the struct sr_dev_inst to be checked.
53b4680f	404	* @param[in] cg The channel group on the device for which to list the
57ecdbd7	405	* values, or NULL.
67eb6bcb MH	406	* @param[in] key The configuration key (SR_CONF_*).
	407	* @param[in,out] data A pointer to a GVariant where the list will be stored.
	408	* The caller is given ownership of the GVariant and must thus
bc1c2f00 BV	409	* unref the GVariant after use. However if this function
	410	* returns an error code, the field should be considered
	411	* unused, and should not be unreferenced.
cbadb856	412	*
67eb6bcb MH	413	* @retval SR_OK Success.
	414	* @retval SR_ERR Error.
	415	* @retval SR_ERR_ARG The driver doesn't know that key, but this is not to be
	416	* interpreted as an error by the caller; merely as an indication
	417	* that it's not applicable.
47117241 UH	418	*
47117241 UH	419	* @since 0.3.0
cbadb856	420	*/
8f996b89 ML	421	SR_API int sr_config_list(const struct sr_dev_driver *driver,
8f996b89 ML	422	const struct sr_dev_inst *sdi,
53b4680f	423	const struct sr_channel_group *cg,
8f996b89	424	int key, GVariant **data)
c5fb502f BV	425	{
	426	int ret;
	427
6cefe516	428	if (!driver \|\| !data)
bc1c2f00	429	ret = SR_ERR;
d8284802	430	else if (!driver->config_list)
6cefe516	431	ret = SR_ERR_ARG;
53b4680f	432	else if ((ret = driver->config_list(key, data, sdi, cg)) == SR_OK)
bc1c2f00	433	g_variant_ref_sink(*data);
c5fb502f BV	434
	435	return ret;
	436	}
	437
8bfdc8c4	438	/**
67eb6bcb	439	* Get information about a configuration key, by key.
a1645fcd	440	*
67eb6bcb	441	* @param[in] key The configuration key.
15cb43d6	442	*
c89c1c9c	443	* @return A pointer to a struct sr_config_info, or NULL if the key
15cb43d6	444	* was not found.
47117241 UH	445	*
47117241 UH	446	* @since 0.2.0
15cb43d6	447	*/
c89c1c9c	448	SR_API const struct sr_config_info *sr_config_info_get(int key)
15cb43d6 BV	449	{
	450	int i;
	451
c89c1c9c BV	452	for (i = 0; sr_config_info_data[i].key; i++) {
	453	if (sr_config_info_data[i].key == key)
	454	return &sr_config_info_data[i];
15cb43d6 BV	455	}
	456
	457	return NULL;
	458	}
	459
	460	/**
67eb6bcb	461	* Get information about a configuration key, by name.
15cb43d6	462	*
67eb6bcb	463	* @param[in] optname The configuration key.
a1645fcd	464	*
c89c1c9c	465	* @return A pointer to a struct sr_config_info, or NULL if the key
15cb43d6	466	* was not found.
47117241 UH	467	*
47117241 UH	468	* @since 0.2.0
a1645fcd	469	*/
c89c1c9c	470	SR_API const struct sr_config_info sr_config_info_name_get(const char optname)
a1bb33af	471	{
a1bb33af UH	472	int i;
a1bb33af UH	473
c89c1c9c BV	474	for (i = 0; sr_config_info_data[i].key; i++) {
	475	if (!strcmp(sr_config_info_data[i].id, optname))
	476	return &sr_config_info_data[i];
a1bb33af UH	477	}
a1bb33af UH	478
49d0ce50	479	return NULL;
a1bb33af UH	480	}
a1bb33af UH	481
7b870c38	482	/** @} */