[libsigrok.git] / src / std.c

/*
 * This file is part of the libsigrok project.
 *
 * Copyright (C) 2013 Uwe Hermann <uwe@hermann-uwe.de>
 *
 * 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 2 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/>.
 */

/**
 * @file
 *
 * Standard API helper functions.
 *
 * @internal
 */

#include <config.h>
#include <glib.h>
#include <libsigrok/libsigrok.h>
#include "libsigrok-internal.h"
#include "scpi.h"

#define LOG_PREFIX "std"

/**
 * Standard driver init() callback API helper.
 *
 * This function can be used to simplify most driver's init() API callback.
 *
 * Create a new 'struct drv_context' (drvc), assign sr_ctx to it, and
 * then assign 'drvc' to the 'struct sr_dev_driver' (di) that is passed.
 *
 * @param[in] di The driver instance to use. Must not be NULL.
 * @param[in] sr_ctx The libsigrok context to assign. May be NULL.
 *
 * @retval SR_OK Success.
 * @retval SR_ERR_ARG Invalid argument.
 */
SR_PRIV int std_init(struct sr_dev_driver *di, struct sr_context *sr_ctx)
{
	struct drv_context *drvc;

	if (!di) {
		sr_err("%s: Invalid argument.", __func__);
		return SR_ERR_ARG;
	}

	drvc = g_malloc0(sizeof(struct drv_context));
	drvc->sr_ctx = sr_ctx;
	drvc->instances = NULL;
	di->context = drvc;

	return SR_OK;
}

/**
 * Standard driver cleanup() callback API helper.
 *
 * This function can be used to simplify most driver's cleanup() API callback.
 *
 * Free all device instances by calling sr_dev_clear() and then release any
 * resources allocated by std_init().
 *
 * @param[in] di The driver instance to use. Must not be NULL.
 *
 * @retval SR_OK Success.
 * @retval SR_ERR_ARG Invalid argument.
 * @retval other Other error.
 */
SR_PRIV int std_cleanup(const struct sr_dev_driver *di)
{
	int ret;

	if (!di) {
		sr_err("%s: Invalid argument.", __func__);
		return SR_ERR_ARG;
	}

	ret = sr_dev_clear(di);
	g_free(di->context);

	return ret;
}

/**
 * Dummmy driver dev_open() callback API helper.
 *
 * @param[in] sdi The device instance to use. May be NULL (unused).
 *
 * @retval SR_OK Success.
 */
SR_PRIV int std_dummy_dev_open(struct sr_dev_inst *sdi)
{
	(void)sdi;

	return SR_OK;
}

/**
 * Dummmy driver dev_close() callback API helper.
 *
 * @param[in] sdi The device instance to use. May be NULL (unused).
 *
 * @retval SR_OK Success.
 */
SR_PRIV int std_dummy_dev_close(struct sr_dev_inst *sdi)
{
	(void)sdi;

	return SR_OK;
}

/**
 * Dummmy driver dev_acquisition_start() callback API helper.
 *
 * @param[in] sdi The device instance to use. May be NULL (unused).
 *
 * @retval SR_OK Success.
 */
SR_PRIV int std_dummy_dev_acquisition_start(const struct sr_dev_inst *sdi)
{
	(void)sdi;

	return SR_OK;
}

/**
 * Dummmy driver dev_acquisition_stop() callback API helper.
 *
 * @param[in] sdi The device instance to use. May be NULL (unused).
 *
 * @retval SR_OK Success.
 */
SR_PRIV int std_dummy_dev_acquisition_stop(struct sr_dev_inst *sdi)
{
	(void)sdi;

	return SR_OK;
}

/**
 * Standard API helper for sending an SR_DF_HEADER packet.
 *
 * This function can be used to simplify most drivers'
 * dev_acquisition_start() API callback.
 *
 * @param[in] sdi The device instance to use. Must not be NULL.
 *
 * @retval SR_OK Success.
 * @retval SR_ERR_ARG Invalid argument.
 * @retval other Other error.
 */
SR_PRIV int std_session_send_df_header(const struct sr_dev_inst *sdi)
{
	const char *prefix;
	int ret;
	struct sr_datafeed_packet packet;
	struct sr_datafeed_header header;

	if (!sdi) {
		sr_err("%s: Invalid argument.", __func__);
		return SR_ERR_ARG;
	}

	prefix = (sdi->driver) ? sdi->driver->name : "unknown";

	/* Send header packet to the session bus. */
	sr_dbg("%s: Sending SR_DF_HEADER packet.", prefix);
	packet.type = SR_DF_HEADER;
	packet.payload = (uint8_t *)&header;
	header.feed_version = 1;
	gettimeofday(&header.starttime, NULL);

	if ((ret = sr_session_send(sdi, &packet)) < 0) {
		sr_err("%s: Failed to send SR_DF_HEADER packet: %d.", prefix, ret);
		return ret;
	}

	return SR_OK;
}

/**
 * Standard API helper for sending an SR_DF_END packet.
 *
 * This function can be used to simplify most drivers'
 * dev_acquisition_stop() API callback.
 *
 * @param[in] sdi The device instance to use. Must not be NULL.
 *
 * @retval SR_OK Success.
 * @retval SR_ERR_ARG Invalid argument.
 * @retval other Other error.
 */
SR_PRIV int std_session_send_df_end(const struct sr_dev_inst *sdi)
{
	const char *prefix;
	int ret;
	struct sr_datafeed_packet packet;

	if (!sdi) {
		sr_err("%s: Invalid argument.", __func__);
		return SR_ERR_ARG;
	}

	prefix = (sdi->driver) ? sdi->driver->name : "unknown";

	sr_dbg("%s: Sending SR_DF_END packet.", prefix);

	packet.type = SR_DF_END;
	packet.payload = NULL;

	if ((ret = sr_session_send(sdi, &packet)) < 0) {
		sr_err("%s: Failed to send SR_DF_END packet: %d.", prefix, ret);
		return ret;
	}

	return SR_OK;
}

#ifdef HAVE_LIBSERIALPORT

/**
 * Standard serial driver dev_open() callback API helper.
 *
 * This function can be used to implement the dev_open() driver API
 * callback in drivers that use a serial port. The port is opened
 * with the SERIAL_RDWR flag.
 *
 * @param[in] sdi The device instance to use. Must not be NULL.
 *
 * @retval SR_OK Success.
 * @retval SR_ERR_ARG Invalid argument.
 * @retval other Serial port open failed.
 */
SR_PRIV int std_serial_dev_open(struct sr_dev_inst *sdi)
{
	struct sr_serial_dev_inst *serial;

	if (!sdi) {
		sr_err("%s: Invalid argument.", __func__);
		return SR_ERR_ARG;
	}

	serial = sdi->conn;

	return serial_open(serial, SERIAL_RDWR);
}

/**
 * Standard serial driver dev_close() callback API helper.
 *
 * This function can be used to implement the dev_close() driver API
 * callback in drivers that use a serial port.
 *
 * @param[in] sdi The device instance to use. Must not be NULL.
 *
 * @retval SR_OK Success.
 * @retval SR_ERR_ARG Invalid argument.
 * @retval other Serial port close failed.
 */
SR_PRIV int std_serial_dev_close(struct sr_dev_inst *sdi)
{
	struct sr_serial_dev_inst *serial;

	if (!sdi) {
		sr_err("%s: Invalid argument.", __func__);
		return SR_ERR_ARG;
	}

	serial = sdi->conn;

	return serial_close(serial);
}

/**
 * Standard serial driver dev_acquisition_stop() callback API helper.
 *
 * This function can be used to simplify most (serial port based) drivers'
 * dev_acquisition_stop() API callback.
 *
 * @param[in] sdi The device instance for which acquisition should stop.
 *                Must not be NULL.
 *
 * @retval SR_OK Success.
 * @retval SR_ERR_ARG Invalid argument.
 * @retval other Other error.
 */
SR_PRIV int std_serial_dev_acquisition_stop(struct sr_dev_inst *sdi)
{
	struct sr_serial_dev_inst *serial;
	const char *prefix;
	int ret;

	if (!sdi) {
		sr_err("%s: Invalid argument.", __func__);
		return SR_ERR_ARG;
	}

	serial = sdi->conn;
	prefix = sdi->driver->name;

	if ((ret = serial_source_remove(sdi->session, serial)) < 0) {
		sr_err("%s: Failed to remove source: %d.", prefix, ret);
		return ret;
	}

	if ((ret = sr_dev_close(sdi)) < 0) {
		sr_err("%s: Failed to close device: %d.", prefix, ret);
		return ret;
	}

	return std_session_send_df_end(sdi);
}

#endif

/**
 * Standard driver dev_clear() callback API helper.
 *
 * Clear driver, this means, close all instances.
 *
 * This function can be used to implement the dev_clear() driver API
 * callback. dev_close() is called before every sr_dev_inst is cleared.
 *
 * The only limitation is driver-specific device contexts (sdi->priv / devc).
 * These are freed, but any dynamic allocation within structs stored
 * there cannot be freed.
 *
 * @param[in] driver The driver which will have its instances released.
 *                   Must not be NULL.
 * @param[in] clear_private If not NULL, this points to a function called
 *            with sdi->priv (devc) as argument. The function can then clear
 *            any device instance-specific resources kept there.
 *            It must NOT clear the struct pointed to by sdi->priv (devc),
 *            since this function will always free it after clear_private()
 *            has run.
 *
 * @retval SR_OK Success.
 * @retval SR_ERR_ARG Invalid argument.
 * @retval SR_ERR_BUG Implementation bug.
 * @retval other Other error.
 */
SR_PRIV int std_dev_clear_with_callback(const struct sr_dev_driver *driver,
		std_dev_clear_callback clear_private)
{
	struct drv_context *drvc;
	struct sr_dev_inst *sdi;
	GSList *l;
	int ret;

	if (!driver) {
		sr_err("%s: Invalid argument.", __func__);
		return SR_ERR_ARG;
	}

	drvc = driver->context; /* Caller checked for context != NULL. */

	ret = SR_OK;
	for (l = drvc->instances; l; l = l->next) {
		if (!(sdi = l->data)) {
			sr_err("%s: Invalid device instance.", __func__);
			ret = SR_ERR_BUG;
			continue;
		}
		if (driver->dev_close)
			driver->dev_close(sdi);

		if (sdi->conn) {
#ifdef HAVE_LIBSERIALPORT
			if (sdi->inst_type == SR_INST_SERIAL)
				sr_serial_dev_inst_free(sdi->conn);
#endif
#ifdef HAVE_LIBUSB_1_0
			if (sdi->inst_type == SR_INST_USB)
				sr_usb_dev_inst_free(sdi->conn);
#endif
			if (sdi->inst_type == SR_INST_SCPI)
				sr_scpi_free(sdi->conn);
			if (sdi->inst_type == SR_INST_MODBUS)
				sr_modbus_free(sdi->conn);
		}

		/* Clear driver-specific stuff, if any. */
		if (clear_private)
			clear_private(sdi->priv);

		/* Clear sdi->priv (devc). */
		g_free(sdi->priv);

		sr_dev_inst_free(sdi);
	}

	g_slist_free(drvc->instances);
	drvc->instances = NULL;

	return ret;
}

SR_PRIV int std_dev_clear(const struct sr_dev_driver *driver)
{
	return std_dev_clear_with_callback(driver, NULL);
}

/**
 * Standard driver dev_list() callback API helper.
 *
 * This function can be used as the dev_list() callback by most drivers.
 *
 * Return the devices contained in the driver context instances list.
 *
 * @param[in] di The driver instance to use. Must not be NULL.
 *
 * @retval NULL Error, or the list is empty.
 * @retval other The list of device instances of this driver.
 */
SR_PRIV GSList *std_dev_list(const struct sr_dev_driver *di)
{
	struct drv_context *drvc;

	if (!di) {
		sr_err("%s: Invalid argument.", __func__);
		return NULL;
	}

	drvc = di->context;

	return drvc->instances;
}

/**
 * Standard driver scan() callback API helper.
 *
 * This function can be used to perform common tasks required by a driver's
 * scan() callback. It will initialize the driver for each device on the list
 * and add the devices on the list to the driver's device instance list.
 * Usually it should be used as the last step in the scan() callback, right
 * before returning.
 *
 * Note: This function can only be used if std_init() has been called
 * previously by the driver.
 *
 * Example:
 * @code{c}
 * static GSList *scan(struct sr_dev_driver *di, GSList *options)
 * {
 *     struct GSList *device;
 *     struct sr_dev_inst *sdi;
 *
 *     sdi = g_new0(sr_dev_inst, 1);
 *     sdi->vendor = ...;
 *     ...
 *     devices = g_slist_append(devices, sdi);
 *     ...
 *     return std_scan_complete(di, devices);
 * }
 * @endcode
 *
 * @param[in] di The driver instance to use. Must not be NULL.
 * @param[in] devices List of newly discovered devices (struct sr_dev_inst).
 *                    May be NULL.
 *
 * @return The @p devices list.
 */
SR_PRIV GSList *std_scan_complete(struct sr_dev_driver *di, GSList *devices)
{
	struct drv_context *drvc;
	GSList *l;

	if (!di) {
		sr_err("Invalid driver instance (di), cannot complete scan.");
		return NULL;
	}

	drvc = di->context;

	for (l = devices; l; l = l->next) {
		struct sr_dev_inst *sdi = l->data;
		if (!sdi) {
			sr_err("Invalid device instance, cannot complete scan.");
			return NULL;
		}
		sdi->driver = di;
	}

	drvc->instances = g_slist_concat(drvc->instances, g_slist_copy(devices));

	return devices;
}
Commit	Line	Data
063e7aef	1	/*
50985c20	2	* This file is part of the libsigrok project.
063e7aef UH	3	*
	4	* Copyright (C) 2013 Uwe Hermann <uwe@hermann-uwe.de>
	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 2 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
2ea1fdf1	17	* along with this program; if not, see <http://www.gnu.org/licenses/>.
063e7aef UH	18	*/
063e7aef UH	19
d9251a2c UH	20	/**
	21	* @file
	22	*
	23	* Standard API helper functions.
	24	*
	25	* @internal
	26	*/
04cb9157	27
6ec6c43b	28	#include <config.h>
063e7aef	29	#include <glib.h>
c1aae900	30	#include <libsigrok/libsigrok.h>
063e7aef	31	#include "libsigrok-internal.h"
5a1afc09	32	#include "scpi.h"
063e7aef	33
3544f848 ML	34	#define LOG_PREFIX "std"
3544f848 ML	35
063e7aef	36	/**
12852b03	37	* Standard driver init() callback API helper.
063e7aef	38	*
6078d2c9	39	* This function can be used to simplify most driver's init() API callback.
063e7aef	40	*
12852b03 UH	41	* Create a new 'struct drv_context' (drvc), assign sr_ctx to it, and
12852b03 UH	42	* then assign 'drvc' to the 'struct sr_dev_driver' (di) that is passed.
063e7aef	43	*
12852b03 UH	44	* @param[in] di The driver instance to use. Must not be NULL.
12852b03 UH	45	* @param[in] sr_ctx The libsigrok context to assign. May be NULL.
063e7aef	46	*
12852b03 UH	47	* @retval SR_OK Success.
12852b03 UH	48	* @retval SR_ERR_ARG Invalid argument.
063e7aef	49	*/
c45c32ce	50	SR_PRIV int std_init(struct sr_dev_driver di, struct sr_context sr_ctx)
063e7aef UH	51	{
	52	struct drv_context *drvc;
	53
12852b03 UH	54	if (!di) {
	55	sr_err("%s: Invalid argument.", __func__);
	56	return SR_ERR_ARG;
	57	}
	58
91219afc	59	drvc = g_malloc0(sizeof(struct drv_context));
063e7aef	60	drvc->sr_ctx = sr_ctx;
c2523f22	61	drvc->instances = NULL;
41812aca	62	di->context = drvc;
063e7aef UH	63
	64	return SR_OK;
	65	}
4afdfd46	66
700d6b64	67	/**
12852b03	68	* Standard driver cleanup() callback API helper.
700d6b64	69	*
12852b03	70	* This function can be used to simplify most driver's cleanup() API callback.
700d6b64	71	*
12852b03	72	* Free all device instances by calling sr_dev_clear() and then release any
700d6b64 LPC	73	* resources allocated by std_init().
700d6b64 LPC	74	*
12852b03	75	* @param[in] di The driver instance to use. Must not be NULL.
700d6b64	76	*
12852b03 UH	77	* @retval SR_OK Success.
	78	* @retval SR_ERR_ARG Invalid argument.
	79	* @retval other Other error.
	80	*/
700d6b64 LPC	81	SR_PRIV int std_cleanup(const struct sr_dev_driver *di)
	82	{
	83	int ret;
	84
12852b03 UH	85	if (!di) {
	86	sr_err("%s: Invalid argument.", __func__);
	87	return SR_ERR_ARG;
	88	}
	89
700d6b64 LPC	90	ret = sr_dev_clear(di);
	91	g_free(di->context);
	92
	93	return ret;
	94	}
	95
4d67b9d9 UH	96	/**
	97	* Dummmy driver dev_open() callback API helper.
	98	*
	99	* @param[in] sdi The device instance to use. May be NULL (unused).
	100	*
	101	* @retval SR_OK Success.
	102	*/
	103	SR_PRIV int std_dummy_dev_open(struct sr_dev_inst *sdi)
	104	{
	105	(void)sdi;
	106
	107	return SR_OK;
	108	}
	109
	110	/**
	111	* Dummmy driver dev_close() callback API helper.
	112	*
	113	* @param[in] sdi The device instance to use. May be NULL (unused).
	114	*
	115	* @retval SR_OK Success.
	116	*/
	117	SR_PRIV int std_dummy_dev_close(struct sr_dev_inst *sdi)
	118	{
	119	(void)sdi;
	120
	121	return SR_OK;
	122	}
	123
	124	/**
	125	* Dummmy driver dev_acquisition_start() callback API helper.
	126	*
	127	* @param[in] sdi The device instance to use. May be NULL (unused).
	128	*
	129	* @retval SR_OK Success.
	130	*/
	131	SR_PRIV int std_dummy_dev_acquisition_start(const struct sr_dev_inst *sdi)
	132	{
	133	(void)sdi;
	134
	135	return SR_OK;
	136	}
	137
	138	/**
	139	* Dummmy driver dev_acquisition_stop() callback API helper.
	140	*
	141	* @param[in] sdi The device instance to use. May be NULL (unused).
	142	*
	143	* @retval SR_OK Success.
	144	*/
	145	SR_PRIV int std_dummy_dev_acquisition_stop(struct sr_dev_inst *sdi)
	146	{
	147	(void)sdi;
	148
	149	return SR_OK;
	150	}
	151
4afdfd46 UH	152	/**
	153	* Standard API helper for sending an SR_DF_HEADER packet.
	154	*
12852b03	155	* This function can be used to simplify most drivers'
6078d2c9	156	* dev_acquisition_start() API callback.
4afdfd46	157	*
12852b03	158	* @param[in] sdi The device instance to use. Must not be NULL.
4afdfd46	159	*
12852b03 UH	160	* @retval SR_OK Success.
	161	* @retval SR_ERR_ARG Invalid argument.
	162	* @retval other Other error.
4afdfd46	163	*/
bee2b016	164	SR_PRIV int std_session_send_df_header(const struct sr_dev_inst *sdi)
4afdfd46	165	{
12852b03	166	const char *prefix;
4afdfd46 UH	167	int ret;
	168	struct sr_datafeed_packet packet;
	169	struct sr_datafeed_header header;
	170
12852b03 UH	171	if (!sdi) {
	172	sr_err("%s: Invalid argument.", __func__);
	173	return SR_ERR_ARG;
	174	}
	175
	176	prefix = (sdi->driver) ? sdi->driver->name : "unknown";
	177
4afdfd46	178	/* Send header packet to the session bus. */
ac2926b3	179	sr_dbg("%s: Sending SR_DF_HEADER packet.", prefix);
4afdfd46 UH	180	packet.type = SR_DF_HEADER;
	181	packet.payload = (uint8_t *)&header;
	182	header.feed_version = 1;
	183	gettimeofday(&header.starttime, NULL);
	184
	185	if ((ret = sr_session_send(sdi, &packet)) < 0) {
12852b03	186	sr_err("%s: Failed to send SR_DF_HEADER packet: %d.", prefix, ret);
4afdfd46 UH	187	return ret;
	188	}
	189
	190	return SR_OK;
	191	}
cd2f0fe2	192
3be42bc2 UH	193	/**
	194	* Standard API helper for sending an SR_DF_END packet.
	195	*
12852b03 UH	196	* This function can be used to simplify most drivers'
	197	* dev_acquisition_stop() API callback.
	198	*
	199	* @param[in] sdi The device instance to use. Must not be NULL.
3be42bc2	200	*
12852b03 UH	201	* @retval SR_OK Success.
	202	* @retval SR_ERR_ARG Invalid argument.
	203	* @retval other Other error.
3be42bc2	204	*/
bee2b016	205	SR_PRIV int std_session_send_df_end(const struct sr_dev_inst *sdi)
3be42bc2	206	{
12852b03	207	const char *prefix;
3be42bc2 UH	208	int ret;
	209	struct sr_datafeed_packet packet;
	210
12852b03 UH	211	if (!sdi) {
12852b03 UH	212	sr_err("%s: Invalid argument.", __func__);
3be42bc2	213	return SR_ERR_ARG;
12852b03 UH	214	}
	215
	216	prefix = (sdi->driver) ? sdi->driver->name : "unknown";
3be42bc2 UH	217
	218	sr_dbg("%s: Sending SR_DF_END packet.", prefix);
	219
	220	packet.type = SR_DF_END;
	221	packet.payload = NULL;
	222
	223	if ((ret = sr_session_send(sdi, &packet)) < 0) {
	224	sr_err("%s: Failed to send SR_DF_END packet: %d.", prefix, ret);
	225	return ret;
	226	}
	227
	228	return SR_OK;
	229	}
	230
c4f2dfd0 UH	231	#ifdef HAVE_LIBSERIALPORT
c4f2dfd0 UH	232
813aab69	233	/**
12852b03	234	* Standard serial driver dev_open() callback API helper.
23dc6661 BV	235	*
	236	* This function can be used to implement the dev_open() driver API
	237	* callback in drivers that use a serial port. The port is opened
6c592ece	238	* with the SERIAL_RDWR flag.
23dc6661	239	*
12852b03 UH	240	* @param[in] sdi The device instance to use. Must not be NULL.
12852b03 UH	241	*
23dc6661	242	* @retval SR_OK Success.
12852b03 UH	243	* @retval SR_ERR_ARG Invalid argument.
12852b03 UH	244	* @retval other Serial port open failed.
23dc6661 BV	245	*/
	246	SR_PRIV int std_serial_dev_open(struct sr_dev_inst *sdi)
	247	{
	248	struct sr_serial_dev_inst *serial;
	249
12852b03 UH	250	if (!sdi) {
12852b03 UH	251	sr_err("%s: Invalid argument.", __func__);
7e463623	252	return SR_ERR_ARG;
12852b03	253	}
23dc6661	254
7e463623	255	serial = sdi->conn;
23dc6661	256
7e463623	257	return serial_open(serial, SERIAL_RDWR);
23dc6661 BV	258	}
23dc6661 BV	259
813aab69	260	/**
12852b03	261	* Standard serial driver dev_close() callback API helper.
1e7134dc BV	262	*
	263	* This function can be used to implement the dev_close() driver API
	264	* callback in drivers that use a serial port.
	265	*
12852b03 UH	266	* @param[in] sdi The device instance to use. Must not be NULL.
12852b03 UH	267	*
1e7134dc	268	* @retval SR_OK Success.
12852b03 UH	269	* @retval SR_ERR_ARG Invalid argument.
12852b03 UH	270	* @retval other Serial port close failed.
1e7134dc BV	271	*/
	272	SR_PRIV int std_serial_dev_close(struct sr_dev_inst *sdi)
	273	{
	274	struct sr_serial_dev_inst *serial;
	275
12852b03 UH	276	if (!sdi) {
12852b03 UH	277	sr_err("%s: Invalid argument.", __func__);
093e1cba	278	return SR_ERR_ARG;
12852b03	279	}
1e7134dc	280
f1ba6b4b	281	serial = sdi->conn;
093e1cba	282
f1ba6b4b	283	return serial_close(serial);
1e7134dc BV	284	}
1e7134dc BV	285
813aab69	286	/**
12852b03	287	* Standard serial driver dev_acquisition_stop() callback API helper.
cd2f0fe2	288	*
12852b03	289	* This function can be used to simplify most (serial port based) drivers'
6078d2c9	290	* dev_acquisition_stop() API callback.
cd2f0fe2	291	*
12852b03 UH	292	* @param[in] sdi The device instance for which acquisition should stop.
12852b03 UH	293	* Must not be NULL.
cd2f0fe2	294	*
1477a9a6	295	* @retval SR_OK Success.
12852b03 UH	296	* @retval SR_ERR_ARG Invalid argument.
12852b03 UH	297	* @retval other Other error.
cd2f0fe2	298	*/
1b38775b	299	SR_PRIV int std_serial_dev_acquisition_stop(struct sr_dev_inst *sdi)
cd2f0fe2	300	{
12852b03 UH	301	struct sr_serial_dev_inst *serial;
12852b03 UH	302	const char *prefix;
cd2f0fe2	303	int ret;
cd2f0fe2	304
12852b03 UH	305	if (!sdi) {
	306	sr_err("%s: Invalid argument.", __func__);
	307	return SR_ERR_ARG;
	308	}
	309
	310	serial = sdi->conn;
	311	prefix = sdi->driver->name;
	312
102f1239	313	if ((ret = serial_source_remove(sdi->session, serial)) < 0) {
ac2926b3	314	sr_err("%s: Failed to remove source: %d.", prefix, ret);
cd2f0fe2 UH	315	return ret;
	316	}
	317
093e1cba	318	if ((ret = sr_dev_close(sdi)) < 0) {
ac2926b3	319	sr_err("%s: Failed to close device: %d.", prefix, ret);
cd2f0fe2 UH	320	return ret;
	321	}
	322
12852b03	323	return std_session_send_df_end(sdi);
cd2f0fe2	324	}
49f00e13	325
c4f2dfd0 UH	326	#endif
c4f2dfd0 UH	327
813aab69	328	/**
12852b03	329	* Standard driver dev_clear() callback API helper.
49f00e13	330	*
813aab69 MH	331	* Clear driver, this means, close all instances.
813aab69 MH	332	*
49f00e13 BV	333	* This function can be used to implement the dev_clear() driver API
	334	* callback. dev_close() is called before every sr_dev_inst is cleared.
	335	*
8bf18daa	336	* The only limitation is driver-specific device contexts (sdi->priv / devc).
49f00e13 BV	337	* These are freed, but any dynamic allocation within structs stored
	338	* there cannot be freed.
	339	*
12852b03 UH	340	* @param[in] driver The driver which will have its instances released.
	341	* Must not be NULL.
	342	* @param[in] clear_private If not NULL, this points to a function called
8bf18daa	343	* with sdi->priv (devc) as argument. The function can then clear
12852b03	344	* any device instance-specific resources kept there.
8bf18daa UH	345	* It must NOT clear the struct pointed to by sdi->priv (devc),
	346	* since this function will always free it after clear_private()
	347	* has run.
49f00e13	348	*
12852b03 UH	349	* @retval SR_OK Success.
	350	* @retval SR_ERR_ARG Invalid argument.
	351	* @retval SR_ERR_BUG Implementation bug.
	352	* @retval other Other error.
49f00e13	353	*/
6e43c3d5	354	SR_PRIV int std_dev_clear_with_callback(const struct sr_dev_driver *driver,
144f6660	355	std_dev_clear_callback clear_private)
49f00e13	356	{
49f00e13	357	struct drv_context *drvc;
12a33563	358	struct sr_dev_inst *sdi;
7aebe22d	359	GSList *l;
49f00e13 BV	360	int ret;
49f00e13 BV	361
12852b03 UH	362	if (!driver) {
	363	sr_err("%s: Invalid argument.", __func__);
	364	return SR_ERR_ARG;
	365	}
	366
	367	drvc = driver->context; /* Caller checked for context != NULL. */
3a277f3b	368
49f00e13 BV	369	ret = SR_OK;
49f00e13 BV	370	for (l = drvc->instances; l; l = l->next) {
49f00e13	371	if (!(sdi = l->data)) {
12852b03	372	sr_err("%s: Invalid device instance.", __func__);
49f00e13 BV	373	ret = SR_ERR_BUG;
	374	continue;
	375	}
49f00e13 BV	376	if (driver->dev_close)
	377	driver->dev_close(sdi);
	378
	379	if (sdi->conn) {
45357ce6	380	#ifdef HAVE_LIBSERIALPORT
c4f2dfd0	381	if (sdi->inst_type == SR_INST_SERIAL)
12a33563	382	sr_serial_dev_inst_free(sdi->conn);
c4f2dfd0	383	#endif
45357ce6	384	#ifdef HAVE_LIBUSB_1_0
c4f2dfd0	385	if (sdi->inst_type == SR_INST_USB)
49f00e13	386	sr_usb_dev_inst_free(sdi->conn);
a0c7e23a	387	#endif
23f43dff ML	388	if (sdi->inst_type == SR_INST_SCPI)
23f43dff ML	389	sr_scpi_free(sdi->conn);
daa39012 AJ	390	if (sdi->inst_type == SR_INST_MODBUS)
daa39012 AJ	391	sr_modbus_free(sdi->conn);
49f00e13	392	}
8bf18daa UH	393
8bf18daa UH	394	/* Clear driver-specific stuff, if any. */
ae5859ff BV	395	if (clear_private)
ae5859ff BV	396	clear_private(sdi->priv);
8bf18daa UH	397
	398	/* Clear sdi->priv (devc). */
	399	g_free(sdi->priv);
886413b6	400
49f00e13 BV	401	sr_dev_inst_free(sdi);
	402	}
	403
	404	g_slist_free(drvc->instances);
	405	drvc->instances = NULL;
	406
	407	return ret;
	408	}
c01bf34c	409
f778bf02 UH	410	SR_PRIV int std_dev_clear(const struct sr_dev_driver *driver)
	411	{
	412	return std_dev_clear_with_callback(driver, NULL);
	413	}
	414
c01bf34c	415	/**
12852b03	416	* Standard driver dev_list() callback API helper.
c01bf34c	417	*
12852b03	418	* This function can be used as the dev_list() callback by most drivers.
c01bf34c	419	*
12852b03	420	* Return the devices contained in the driver context instances list.
c01bf34c	421	*
12852b03 UH	422	* @param[in] di The driver instance to use. Must not be NULL.
	423	*
	424	* @retval NULL Error, or the list is empty.
	425	* @retval other The list of device instances of this driver.
c01bf34c LPC	426	*/
	427	SR_PRIV GSList std_dev_list(const struct sr_dev_driver di)
	428	{
12852b03 UH	429	struct drv_context *drvc;
	430
	431	if (!di) {
	432	sr_err("%s: Invalid argument.", __func__);
	433	return NULL;
	434	}
	435
	436	drvc = di->context;
c01bf34c LPC	437
	438	return drvc->instances;
	439	}
15a5bfe4 LPC	440
15a5bfe4 LPC	441	/**
12852b03	442	* Standard driver scan() callback API helper.
15a5bfe4 LPC	443	*
	444	* This function can be used to perform common tasks required by a driver's
	445	* scan() callback. It will initialize the driver for each device on the list
	446	* and add the devices on the list to the driver's device instance list.
	447	* Usually it should be used as the last step in the scan() callback, right
	448	* before returning.
	449	*
	450	* Note: This function can only be used if std_init() has been called
	451	* previously by the driver.
	452	*
	453	* Example:
	454	* @code{c}
	455	* static GSList scan(struct sr_dev_driver di, GSList *options)
	456	* {
	457	* struct GSList *device;
	458	* struct sr_dev_inst *sdi;
	459	*
	460	* sdi = g_new0(sr_dev_inst, 1);
	461	* sdi->vendor = ...;
	462	* ...
	463	* devices = g_slist_append(devices, sdi);
	464	* ...
	465	* return std_scan_complete(di, devices);
	466	* }
	467	* @endcode
	468	*
12852b03 UH	469	* @param[in] di The driver instance to use. Must not be NULL.
	470	* @param[in] devices List of newly discovered devices (struct sr_dev_inst).
	471	* May be NULL.
15a5bfe4 LPC	472	*
	473	* @return The @p devices list.
	474	*/
	475	SR_PRIV GSList std_scan_complete(struct sr_dev_driver di, GSList *devices)
	476	{
39fcfdc9	477	struct drv_context *drvc;
15a5bfe4 LPC	478	GSList *l;
15a5bfe4 LPC	479
39fcfdc9 UH	480	if (!di) {
	481	sr_err("Invalid driver instance (di), cannot complete scan.");
	482	return NULL;
	483	}
	484
	485	drvc = di->context;
	486
15a5bfe4 LPC	487	for (l = devices; l; l = l->next) {
15a5bfe4 LPC	488	struct sr_dev_inst *sdi = l->data;
39fcfdc9	489	if (!sdi) {
12852b03	490	sr_err("Invalid device instance, cannot complete scan.");
39fcfdc9 UH	491	return NULL;
39fcfdc9 UH	492	}
15a5bfe4 LPC	493	sdi->driver = di;
	494	}
	495
	496	drvc->instances = g_slist_concat(drvc->instances, g_slist_copy(devices));
	497
	498	return devices;
	499	}